Repository: MayDay-wpf/snow-cli Branch: main Commit: 1c0e794663ef Files: 606 Total size: 4.4 MB Directory structure: gitextract_06hmzq__/ ├── .editorconfig ├── .gitattributes ├── .github/ │ └── workflows/ │ ├── build_jetbrains.yml │ ├── build_vsix.yml │ └── publish.yml ├── .gitignore ├── .npmrc ├── .npmrc.ci ├── .prettierignore ├── .vscode/ │ ├── launch.json │ ├── settings.json │ └── tasks.json ├── JetBrains/ │ ├── .gitignore │ ├── README.md │ ├── build.gradle.kts │ ├── gradle/ │ │ └── wrapper/ │ │ ├── gradle-wrapper.jar │ │ └── gradle-wrapper.properties │ ├── gradle.properties │ ├── gradlew │ ├── gradlew.bat │ ├── settings.gradle.kts │ └── src/ │ └── main/ │ ├── kotlin/ │ │ ├── com/ │ │ │ └── snow/ │ │ │ └── plugin/ │ │ │ ├── SnowCodeNavigator.kt │ │ │ ├── SnowEditorContextTracker.kt │ │ │ ├── SnowMessageHandler.kt │ │ │ ├── SnowPluginLifecycle.kt │ │ │ ├── SnowProjectActivity.kt │ │ │ ├── SnowWebSocketManager.kt │ │ │ ├── actions/ │ │ │ │ ├── GenerateCommitMessageAction.kt │ │ │ │ ├── OpenSnowTerminalAction.kt │ │ │ │ ├── SendToSnowCLIAction.kt │ │ │ │ └── TestNotificationAction.kt │ │ │ ├── commit/ │ │ │ │ └── SnowCommitMessageGenerationService.kt │ │ │ ├── toolwindow/ │ │ │ │ └── SnowToolWindowFactory.kt │ │ │ └── util/ │ │ │ └── TerminalCompat.kt │ │ └── icons/ │ │ └── SnowPluginIcons.kt │ └── resources/ │ └── META-INF/ │ └── plugin.xml ├── LICENSE ├── README.md ├── README_zh.md ├── VSIX/ │ ├── .vscodeignore │ ├── LICENSE │ ├── README.md │ ├── package.json │ ├── res/ │ │ ├── sidebarTerminal.css │ │ └── sidebarTerminal.js │ ├── src/ │ │ ├── aceHandlers.ts │ │ ├── commitMessageGenerator.ts │ │ ├── diffHandlers.ts │ │ ├── extension.ts │ │ ├── gitBlameProvider.ts │ │ ├── ptyManager.ts │ │ ├── sidebarTerminalProvider.ts │ │ ├── sidebarTerminalSession.ts │ │ ├── startupCommandManager.ts │ │ ├── terminalPathFormatter.ts │ │ ├── terminalProxy.ts │ │ └── webSocketServer.ts │ ├── tsconfig.json │ └── webpack.config.js ├── build-ncc.mjs ├── build-shim.js ├── build.mjs ├── docs/ │ ├── role/ │ │ ├── en/ │ │ │ └── 01.Snow CLI Plan Every Step.md │ │ └── zh/ │ │ └── 01.Snow CLI 一步一规划.md │ └── usage/ │ ├── en/ │ │ ├── 0.Catalogue.md │ │ ├── 01.Installation Guide.md │ │ ├── 02.First Time Configuration.md │ │ ├── 03.Proxy and Browser Settings.md │ │ ├── 04.Codebase Setup.md │ │ ├── 05.Sub-Agent Configuration.md │ │ ├── 06.Sensitive Commands Configuration.md │ │ ├── 07.Hooks Configuration.md │ │ ├── 08.Theme Settings.md │ │ ├── 09.Command Panel Guide.md │ │ ├── 10.Command Injection Mode.md │ │ ├── 11.Vulnerability Hunting Mode.md │ │ ├── 12.Headless Mode.md │ │ ├── 13.Keyboard Shortcuts Guide.md │ │ ├── 14.MCP Configuration.md │ │ ├── 15.Async Task Management.md │ │ ├── 16.Third-Party Relay Configuration.md │ │ ├── 17.LSP Configuration.md │ │ ├── 18.Skills Command Detailed Guide.md │ │ ├── 19.Startup Parameters Guide.md │ │ ├── 20.SSE Service Mode.md │ │ ├── 21.Custom StatusLine Guide.md │ │ ├── 22.Team Mode Guide.md │ │ └── 23.Custom Search Engine Guide.md │ └── zh/ │ ├── 0.目录.md │ ├── 01.安装指南.md │ ├── 02.首次配置.md │ ├── 03.代理和浏览器设置.md │ ├── 04.代码库设置.md │ ├── 05.子代理设置.md │ ├── 06.敏感命令配置.md │ ├── 07.Hooks配置.md │ ├── 08.主题设置.md │ ├── 09.指令面板说明.md │ ├── 10.命令注入模式.md │ ├── 11.漏洞猎人模式.md │ ├── 12.无头模式.md │ ├── 13.快捷键指南.md │ ├── 14.MCP配置.md │ ├── 15.异步任务管理.md │ ├── 16.第三方中转配置.md │ ├── 17.LSP配置.md │ ├── 18.Skills指令详细说明.md │ ├── 19.启动参数说明.md │ ├── 20.SSE服务模式.md │ ├── 21.自定义StatusLine指南.md │ ├── 22.Team模式指南.md │ └── 23.自定义搜索引擎指南.md ├── package.json ├── scripts/ │ ├── clean-build.cjs │ └── postinstall.cjs ├── source/ │ ├── agents/ │ │ ├── bashOutputSummaryAgent.ts │ │ ├── codebaseIndexAgent.ts │ │ ├── codebaseReviewAgent.ts │ │ ├── compactAgent.ts │ │ ├── reviewAgent.ts │ │ └── summaryAgent.ts │ ├── api/ │ │ ├── anthropic.ts │ │ ├── chat.ts │ │ ├── embedding.ts │ │ ├── gemini.ts │ │ ├── models.ts │ │ ├── rerank.ts │ │ ├── responses.ts │ │ ├── sse-server.ts │ │ └── types.ts │ ├── app.tsx │ ├── cli.tsx │ ├── hooks/ │ │ ├── conversation/ │ │ │ ├── chatLogic/ │ │ │ │ ├── types.ts │ │ │ │ ├── useChatHandlers.ts │ │ │ │ ├── useMessageProcessing.ts │ │ │ │ ├── useRemoteEvents.ts │ │ │ │ └── useRollback.ts │ │ │ ├── core/ │ │ │ │ ├── autoCompressHandler.ts │ │ │ │ ├── conversationSetup.ts │ │ │ │ ├── conversationTypes.ts │ │ │ │ ├── editorContextBuilder.ts │ │ │ │ ├── encoderManager.ts │ │ │ │ ├── onStopHookHandler.ts │ │ │ │ ├── pendingMessagesHandler.ts │ │ │ │ ├── sessionInitializer.ts │ │ │ │ ├── streamFactory.ts │ │ │ │ ├── streamProcessor.ts │ │ │ │ ├── subAgentMessageHandler.ts │ │ │ │ ├── toolCallProcessor.ts │ │ │ │ ├── toolCallRoundHandler.ts │ │ │ │ ├── toolConfirmationFlow.ts │ │ │ │ ├── toolRejectionHandler.ts │ │ │ │ └── toolResultDisplay.ts │ │ │ ├── useChatLogic.ts │ │ │ ├── useCommandHandler.ts │ │ │ ├── useConversation.ts │ │ │ ├── useStreamingState.ts │ │ │ ├── useToolConfirmation.ts │ │ │ └── utils/ │ │ │ ├── messageCleanup.ts │ │ │ └── thinkingExtractor.ts │ │ ├── execution/ │ │ │ ├── useBackgroundProcesses.ts │ │ │ ├── useSchedulerExecutionState.ts │ │ │ └── useTerminalExecutionState.ts │ │ ├── input/ │ │ │ ├── keyboard/ │ │ │ │ ├── context.ts │ │ │ │ ├── handlers/ │ │ │ │ │ ├── arrowKeys.ts │ │ │ │ │ ├── clipboard.ts │ │ │ │ │ ├── deleteAndBackspace.ts │ │ │ │ │ ├── editing.ts │ │ │ │ │ ├── escape.ts │ │ │ │ │ ├── focusFilter.ts │ │ │ │ │ ├── modeToggle.ts │ │ │ │ │ ├── newline.ts │ │ │ │ │ ├── pickers/ │ │ │ │ │ │ ├── agentPicker.ts │ │ │ │ │ │ ├── argsPicker.ts │ │ │ │ │ │ ├── commandPanel.ts │ │ │ │ │ │ ├── filePicker.ts │ │ │ │ │ │ ├── gitLinePicker.ts │ │ │ │ │ │ ├── historyMenu.ts │ │ │ │ │ │ ├── profilePicker.ts │ │ │ │ │ │ ├── runningAgentsPicker.ts │ │ │ │ │ │ ├── skillsPicker.ts │ │ │ │ │ │ └── todoPicker.ts │ │ │ │ │ ├── profileShortcut.ts │ │ │ │ │ ├── regularInput.ts │ │ │ │ │ ├── submit.ts │ │ │ │ │ └── tabArgsPicker.ts │ │ │ │ ├── types.ts │ │ │ │ └── utils/ │ │ │ │ └── wordBoundary.ts │ │ │ ├── useBashMode.ts │ │ │ ├── useClipboard.ts │ │ │ ├── useHistoryNavigation.ts │ │ │ ├── useInputBuffer.ts │ │ │ └── useKeyboardInput.ts │ │ ├── integration/ │ │ │ ├── useGlobalExit.ts │ │ │ ├── useGlobalNavigation.ts │ │ │ └── useVSCodeState.ts │ │ ├── picker/ │ │ │ ├── useAgentPicker.ts │ │ │ ├── useFilePicker.ts │ │ │ ├── useGitLinePicker.ts │ │ │ ├── useProfilePicker.ts │ │ │ ├── useRunningAgentsPicker.ts │ │ │ ├── useSkillsPicker.ts │ │ │ └── useTodoPicker.ts │ │ ├── session/ │ │ │ ├── useSessionManagement.ts │ │ │ ├── useSessionSave.ts │ │ │ └── useSnapshotState.ts │ │ └── ui/ │ │ ├── useCommandPanel.ts │ │ ├── useCursorHide.ts │ │ ├── usePanelState.ts │ │ ├── useTerminalFocus.ts │ │ ├── useTerminalSize.ts │ │ └── useTerminalTitle.ts │ ├── i18n/ │ │ ├── I18nContext.tsx │ │ ├── index.ts │ │ ├── lang/ │ │ │ ├── en.ts │ │ │ ├── zh-TW.ts │ │ │ └── zh.ts │ │ ├── translations.ts │ │ └── types.ts │ ├── mcp/ │ │ ├── aceCodeSearch.ts │ │ ├── askUserQuestion.ts │ │ ├── bash.ts │ │ ├── codebaseSearch.ts │ │ ├── engines/ │ │ │ └── websearch/ │ │ │ ├── bing.engine.ts │ │ │ ├── duckduckgo.engine.ts │ │ │ ├── index.ts │ │ │ └── types.ts │ │ ├── filesystem.ts │ │ ├── ideDiagnostics.ts │ │ ├── lsp/ │ │ │ ├── HybridCodeSearchService.ts │ │ │ ├── LSPClient.ts │ │ │ ├── LSPManager.ts │ │ │ └── LSPServerRegistry.ts │ │ ├── notebook.ts │ │ ├── scheduler.ts │ │ ├── skills.ts │ │ ├── subagent.ts │ │ ├── team.ts │ │ ├── todo.ts │ │ ├── types/ │ │ │ ├── aceCodeSearch.types.ts │ │ │ ├── bash.types.ts │ │ │ ├── filesystem.types.ts │ │ │ ├── todo.types.ts │ │ │ └── websearch.types.ts │ │ ├── utils/ │ │ │ ├── aceCodeSearch/ │ │ │ │ ├── constants.utils.ts │ │ │ │ ├── filesystem.utils.ts │ │ │ │ ├── language.utils.ts │ │ │ │ ├── search.utils.ts │ │ │ │ └── symbol.utils.ts │ │ │ ├── bash/ │ │ │ │ └── security.utils.ts │ │ │ ├── filesystem/ │ │ │ │ ├── backup.utils.ts │ │ │ │ ├── batch-operations.utils.ts │ │ │ │ ├── code-analysis.utils.ts │ │ │ │ ├── diagnostics.utils.ts │ │ │ │ ├── edit-tools.utils.ts │ │ │ │ ├── encoding.utils.ts │ │ │ │ ├── hashline.utils.ts │ │ │ │ ├── match-finder.utils.ts │ │ │ │ ├── message-format.utils.ts │ │ │ │ ├── office-parser.utils.ts │ │ │ │ ├── path-fixer.utils.ts │ │ │ │ ├── read-tools.utils.ts │ │ │ │ └── similarity.utils.ts │ │ │ ├── todo/ │ │ │ │ └── date.utils.ts │ │ │ └── websearch/ │ │ │ ├── browser.utils.ts │ │ │ └── text.utils.ts │ │ └── websearch.ts │ ├── prompt/ │ │ ├── planModeSystemPrompt.ts │ │ ├── shared/ │ │ │ └── promptHelpers.ts │ │ ├── systemPrompt.ts │ │ ├── teamModeSystemPrompt.ts │ │ └── vulnerabilityHuntingModeSystemPrompt.ts │ ├── test/ │ │ ├── logger-test.ts │ │ ├── rg-spawn-repro/ │ │ │ ├── rg-spawn-repro-fixed.mjs │ │ │ └── rg-spawn-repro.mjs │ │ └── sse-client/ │ │ ├── app.js │ │ ├── dialogs.js │ │ ├── index.html │ │ ├── json-viewer.js │ │ └── style.css │ ├── types/ │ │ └── index.ts │ ├── ui/ │ │ ├── components/ │ │ │ ├── bash/ │ │ │ │ ├── BackgroundProcessPanel.tsx │ │ │ │ ├── BashCommandConfirmation.tsx │ │ │ │ └── CustomCommandExecutionDisplay.tsx │ │ │ ├── chat/ │ │ │ │ ├── ChatFooter.tsx │ │ │ │ ├── ChatInput.tsx │ │ │ │ ├── CodebaseSearchStatus.tsx │ │ │ │ ├── LoadingIndicator.tsx │ │ │ │ ├── MessageList.tsx │ │ │ │ ├── MessageRenderer.tsx │ │ │ │ ├── PendingMessages.tsx │ │ │ │ ├── PendingToolCalls.tsx │ │ │ │ └── UserMessagePreview.tsx │ │ │ ├── common/ │ │ │ │ ├── MarkdownRenderer.tsx │ │ │ │ ├── Menu.tsx │ │ │ │ ├── PickerList.tsx │ │ │ │ ├── ScrollableSelectInput.tsx │ │ │ │ ├── ShimmerText.tsx │ │ │ │ ├── StatusLine.tsx │ │ │ │ ├── UpdateNotice.tsx │ │ │ │ └── statusline/ │ │ │ │ ├── builtinIds.ts │ │ │ │ ├── gitBranch.ts │ │ │ │ ├── types.ts │ │ │ │ └── useStatusLineHooks.ts │ │ │ ├── compression/ │ │ │ │ └── CompressionStatus.tsx │ │ │ ├── panels/ │ │ │ │ ├── AgentPickerPanel.tsx │ │ │ │ ├── BranchPanel.tsx │ │ │ │ ├── BtwPanel.tsx │ │ │ │ ├── CommandArgsPanel.tsx │ │ │ │ ├── CommandPanel.tsx │ │ │ │ ├── ConnectionPanel.tsx │ │ │ │ ├── CustomCommandConfigPanel.tsx │ │ │ │ ├── DiffReviewPanel.tsx │ │ │ │ ├── GitLinePickerPanel.tsx │ │ │ │ ├── HelpPanel.tsx │ │ │ │ ├── IdeSelectPanel.tsx │ │ │ │ ├── MCPInfoPanel.tsx │ │ │ │ ├── ModelsPanel.tsx │ │ │ │ ├── NewPromptPanel.tsx │ │ │ │ ├── PanelsManager.tsx │ │ │ │ ├── PermissionsPanel.tsx │ │ │ │ ├── ProfileEditPanel.tsx │ │ │ │ ├── ProfilePanel.tsx │ │ │ │ ├── ReviewCommitPanel.tsx │ │ │ │ ├── RoleCreationPanel.tsx │ │ │ │ ├── RoleDeletionPanel.tsx │ │ │ │ ├── RoleListPanel.tsx │ │ │ │ ├── RoleSubagentCreationPanel.tsx │ │ │ │ ├── RoleSubagentDeletionPanel.tsx │ │ │ │ ├── RoleSubagentListPanel.tsx │ │ │ │ ├── RollbackMenuPanel.tsx │ │ │ │ ├── RunningAgentsPanel.tsx │ │ │ │ ├── SessionListPanel.tsx │ │ │ │ ├── SkillsCreationPanel.tsx │ │ │ │ ├── SkillsListPanel.tsx │ │ │ │ ├── SkillsPickerPanel.tsx │ │ │ │ ├── SubAgentDepthPanel.tsx │ │ │ │ ├── TodoListPanel.tsx │ │ │ │ ├── TodoPickerPanel.tsx │ │ │ │ ├── UsagePanel.tsx │ │ │ │ └── WorkingDirectoryPanel.tsx │ │ │ ├── pixel-editor/ │ │ │ │ ├── PixelEditor.tsx │ │ │ │ ├── index.ts │ │ │ │ └── types.ts │ │ │ ├── scheduler/ │ │ │ │ └── SchedulerCountdown.tsx │ │ │ ├── special/ │ │ │ │ ├── AskUserQuestion.tsx │ │ │ │ ├── ChatHeader.tsx │ │ │ │ ├── HookErrorDisplay.tsx │ │ │ │ └── TodoTree.tsx │ │ │ ├── sse/ │ │ │ │ └── SSEServerStatus.tsx │ │ │ └── tools/ │ │ │ ├── DiffViewer.tsx │ │ │ ├── FileList.tsx │ │ │ ├── FileRollbackConfirmation.tsx │ │ │ ├── ToolConfirmation.tsx │ │ │ └── ToolResultPreview.tsx │ │ ├── contexts/ │ │ │ └── ThemeContext.tsx │ │ ├── pages/ │ │ │ ├── ChatScreen.tsx │ │ │ ├── CodeBaseConfigScreen.tsx │ │ │ ├── ConfigScreen.tsx │ │ │ ├── CustomHeadersScreen.tsx │ │ │ ├── CustomThemeScreen.tsx │ │ │ ├── ExitScreen.tsx │ │ │ ├── HeadlessModeScreen.tsx │ │ │ ├── HelpScreen.tsx │ │ │ ├── HooksConfigScreen.tsx │ │ │ ├── LanguageSettingsScreen.tsx │ │ │ ├── MCPConfigScreen.tsx │ │ │ ├── PixelEditorScreen.tsx │ │ │ ├── ProxyConfigScreen.tsx │ │ │ ├── SensitiveCommandConfigScreen.tsx │ │ │ ├── SubAgentConfigScreen.tsx │ │ │ ├── SubAgentListScreen.tsx │ │ │ ├── SystemPromptConfigScreen.tsx │ │ │ ├── TaskManagerScreen.tsx │ │ │ ├── ThemeSettingsScreen.tsx │ │ │ ├── WelcomeScreen.tsx │ │ │ ├── chatScreen/ │ │ │ │ ├── ChatScreenConversationView.tsx │ │ │ │ ├── ChatScreenPanels.tsx │ │ │ │ ├── types.ts │ │ │ │ ├── useBackgroundProcessSelection.ts │ │ │ │ ├── useChatScreenCommands.ts │ │ │ │ ├── useChatScreenInputHandler.ts │ │ │ │ ├── useChatScreenLocalState.ts │ │ │ │ ├── useChatScreenModes.ts │ │ │ │ ├── useChatScreenSessionLifecycle.ts │ │ │ │ └── useCodebaseIndexing.ts │ │ │ └── configScreen/ │ │ │ ├── ConfigFieldRenderer.tsx │ │ │ ├── ConfigSelectPanel.tsx │ │ │ ├── ConfigSubViews.tsx │ │ │ ├── types.ts │ │ │ ├── useConfigInput.ts │ │ │ └── useConfigState.ts │ │ └── themes/ │ │ └── index.ts │ ├── utils/ │ │ ├── acp/ │ │ │ └── acpManager.ts │ │ ├── codebase/ │ │ │ ├── codebaseDatabase.ts │ │ │ ├── codebaseSearchEvents.ts │ │ │ ├── conversationContext.ts │ │ │ ├── gitignoreValidator.ts │ │ │ ├── hashBasedSnapshot.ts │ │ │ └── reindexCodebase.ts │ │ ├── commands/ │ │ │ ├── addDir.ts │ │ │ ├── agent.ts │ │ │ ├── autoformat.ts │ │ │ ├── backend.ts │ │ │ ├── branch.ts │ │ │ ├── btw.ts │ │ │ ├── btwStream.ts │ │ │ ├── clear.ts │ │ │ ├── codebase.ts │ │ │ ├── compact.ts │ │ │ ├── connect.ts │ │ │ ├── copyLast.ts │ │ │ ├── custom.ts │ │ │ ├── deepresearch.ts │ │ │ ├── diff.ts │ │ │ ├── export.ts │ │ │ ├── gitline.ts │ │ │ ├── help.ts │ │ │ ├── home.ts │ │ │ ├── hybridCompress.ts │ │ │ ├── ide.ts │ │ │ ├── init.ts │ │ │ ├── loop.ts │ │ │ ├── mcp.ts │ │ │ ├── models.ts │ │ │ ├── newPrompt.ts │ │ │ ├── permissions.ts │ │ │ ├── pixel.ts │ │ │ ├── plan.ts │ │ │ ├── profiles.ts │ │ │ ├── quit.ts │ │ │ ├── reindex.ts │ │ │ ├── resume.ts │ │ │ ├── review.ts │ │ │ ├── role.ts │ │ │ ├── roleSubagent.ts │ │ │ ├── simple.ts │ │ │ ├── skills.ts │ │ │ ├── skillsPicker.ts │ │ │ ├── subagentDepth.ts │ │ │ ├── team.ts │ │ │ ├── todoPicker.ts │ │ │ ├── todolist.ts │ │ │ ├── toolsearch.ts │ │ │ ├── usage.ts │ │ │ ├── vulnerability-hunting.ts │ │ │ ├── worktree.ts │ │ │ └── yolo.ts │ │ ├── config/ │ │ │ ├── apiConfig.ts │ │ │ ├── codebaseConfig.ts │ │ │ ├── configEvents.ts │ │ │ ├── configManager.ts │ │ │ ├── disabledBuiltInTools.ts │ │ │ ├── disabledMCPTools.ts │ │ │ ├── disabledSkills.ts │ │ │ ├── hooksConfig.ts │ │ │ ├── languageConfig.ts │ │ │ ├── permissionsConfig.ts │ │ │ ├── projectSettings.ts │ │ │ ├── proxyConfig.ts │ │ │ ├── subAgentConfig.ts │ │ │ ├── themeConfig.ts │ │ │ ├── toolDisplayConfig.ts │ │ │ └── workingDirConfig.ts │ │ ├── connection/ │ │ │ ├── ConnectionManager.ts │ │ │ ├── configStore.ts │ │ │ ├── contextManager.ts │ │ │ ├── instanceLock.ts │ │ │ ├── interactionManager.ts │ │ │ ├── projectData.ts │ │ │ ├── stateManager.ts │ │ │ └── types.ts │ │ ├── core/ │ │ │ ├── autoCompress.ts │ │ │ ├── clipboard.ts │ │ │ ├── compressionCoordinator.ts │ │ │ ├── contextCompressor.ts │ │ │ ├── devMode.ts │ │ │ ├── fileUtils.ts │ │ │ ├── globalCleanup.ts │ │ │ ├── logger.ts │ │ │ ├── notebookManager.ts │ │ │ ├── processManager.ts │ │ │ ├── proxyUtils.ts │ │ │ ├── resourceMonitor.ts │ │ │ ├── retryUtils.ts │ │ │ ├── runUpdate.ts │ │ │ ├── streamGuards.ts │ │ │ ├── subAgentContextCompressor.ts │ │ │ ├── textUtils.ts │ │ │ ├── todoPreprocessor.ts │ │ │ ├── todoScanner.ts │ │ │ ├── usageLogger.ts │ │ │ └── version.ts │ │ ├── events/ │ │ │ └── todoEvents.ts │ │ ├── execution/ │ │ │ ├── commandExecutor.ts │ │ │ ├── hookResultInterpreter.ts │ │ │ ├── hookStrategies.ts │ │ │ ├── mcpToolsManager.ts │ │ │ ├── runningSubAgentTracker.ts │ │ │ ├── sensitiveCommandManager.ts │ │ │ ├── subAgentBuiltinTools.ts │ │ │ ├── subAgentExecutor.ts │ │ │ ├── subAgentResolver.ts │ │ │ ├── subAgentStreamProcessor.ts │ │ │ ├── subAgentToolApproval.ts │ │ │ ├── subAgentToolInterceptor.ts │ │ │ ├── subAgentTypes.ts │ │ │ ├── subagents/ │ │ │ │ ├── analyzeAgent.ts │ │ │ │ ├── debugAgent.ts │ │ │ │ ├── exploreAgent.ts │ │ │ │ ├── generalAgent.ts │ │ │ │ ├── index.ts │ │ │ │ ├── planAgent.ts │ │ │ │ ├── qaAgent.ts │ │ │ │ └── types.ts │ │ │ ├── teamExecutor.ts │ │ │ ├── teamTracker.ts │ │ │ ├── terminal.ts │ │ │ ├── tokenLimiter.ts │ │ │ ├── toolExecutor.ts │ │ │ ├── toolSearchService.ts │ │ │ ├── unifiedHooksExecutor.ts │ │ │ └── yoloPermissionChecker.ts │ │ ├── index.ts │ │ ├── latex/ │ │ │ └── unicodeMath.ts │ │ ├── session/ │ │ │ ├── chatExporter.ts │ │ │ ├── checkpointManager.ts │ │ │ ├── commandUsageManager.ts │ │ │ ├── historyManager.ts │ │ │ ├── projectUtils.ts │ │ │ ├── sessionConverter.ts │ │ │ └── sessionManager.ts │ │ ├── sse/ │ │ │ ├── daemonLogger.ts │ │ │ ├── sseDaemon.ts │ │ │ └── sseManager.ts │ │ ├── ssh/ │ │ │ └── sshClient.ts │ │ ├── task/ │ │ │ ├── loopManager.ts │ │ │ ├── taskExecutor.ts │ │ │ └── taskManager.ts │ │ ├── team/ │ │ │ ├── teamConfig.ts │ │ │ ├── teamSnapshot.ts │ │ │ ├── teamTaskList.ts │ │ │ └── teamWorktree.ts │ │ └── ui/ │ │ ├── escapeHandler.ts │ │ ├── externalEditor.ts │ │ ├── fileDialog.ts │ │ ├── messageFormatter.ts │ │ ├── pickerState.ts │ │ ├── skillMask.ts │ │ ├── textBuffer.ts │ │ ├── updateNotice.ts │ │ ├── userInteractionError.ts │ │ └── vscodeConnection.ts │ └── vendor/ │ └── ink/ │ ├── license │ ├── package.json │ └── src/ │ ├── colorize.ts │ ├── components/ │ │ ├── App.tsx │ │ ├── AppContext.ts │ │ ├── Box.tsx │ │ ├── CursorContext.ts │ │ ├── ErrorOverview.tsx │ │ ├── FocusContext.ts │ │ ├── Newline.tsx │ │ ├── Spacer.tsx │ │ ├── Static.tsx │ │ ├── StderrContext.ts │ │ ├── StdinContext.ts │ │ ├── StdoutContext.ts │ │ ├── Text.tsx │ │ └── Transform.tsx │ ├── cursor-helpers.ts │ ├── devtools-window-polyfill.ts │ ├── devtools.ts │ ├── dom.ts │ ├── get-max-width.ts │ ├── global.d.ts │ ├── hooks/ │ │ ├── use-app.ts │ │ ├── use-cursor.ts │ │ ├── use-focus-manager.ts │ │ ├── use-focus.ts │ │ ├── use-input.ts │ │ ├── use-stderr.ts │ │ ├── use-stdin.ts │ │ └── use-stdout.ts │ ├── index.ts │ ├── ink.tsx │ ├── instances.ts │ ├── line-width-cache.ts │ ├── log-update.ts │ ├── measure-element.ts │ ├── measure-text.ts │ ├── output.ts │ ├── parse-keypress.ts │ ├── reconciler.ts │ ├── render-border.ts │ ├── render-node-to-output.ts │ ├── render.ts │ ├── renderer.ts │ ├── squash-text-nodes.ts │ ├── styles.ts │ ├── vendor-types.d.ts │ ├── wrap-text.ts │ ├── yoga-compat.ts │ └── yoga-ts/ │ ├── enums.ts │ └── index.ts └── tsconfig.json ================================================ FILE CONTENTS ================================================ ================================================ FILE: .editorconfig ================================================ root = true [*] indent_style = tab end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true [*.yml] indent_style = space indent_size = 2 ================================================ FILE: .gitattributes ================================================ * text=auto eol=lf ================================================ FILE: .github/workflows/build_jetbrains.yml ================================================ name: Build JetBrains Plugin on: push: paths: - '.github/workflows/build_jetbrains.yml' - 'JetBrains/**' - '!JetBrains/**.md' - '!JetBrains/.gitignore' branches: - '*' tags: - 'v*' workflow_dispatch: inputs: version: description: 'Version to publish (e.g., 1.0.0)' required: true type: string permissions: contents: write packages: write jobs: publish: runs-on: ubuntu-latest defaults: run: working-directory: JetBrains steps: - name: Checkout code uses: actions/checkout@v6 - name: Setup Java uses: actions/setup-java@v5 with: distribution: zulu java-version: 21 - name: Setup Gradle uses: gradle/actions/setup-gradle@v5 with: cache-read-only: false gradle-version: wrapper - name: Update version (manual trigger) if: github.event_name == 'workflow_dispatch' run: | VERSION="${{ github.event.inputs.version }}" echo "Updating version to ${VERSION}" sed -i "s/^version = .*/version = \"${VERSION}\"/" build.gradle.kts sed -i "s/^pluginVersion = .*/pluginVersion = ${VERSION}/" gradle.properties - name: Get version run: | echo "PLUGIN_VERSION=$(grep '^version =' build.gradle.kts | cut -d'"' -f2)" >> $GITHUB_ENV - name: Build and Publish Plugin # env: # PUBLISH_TOKEN: ${{ secrets.PUBLISH_TOKEN }} # CERTIFICATE_CHAIN: ${{ secrets.CERTIFICATE_CHAIN }} # PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }} # PRIVATE_KEY_PASSWORD: ${{ secrets.PRIVATE_KEY_PASSWORD }} run: | ./gradlew buildPlugin ./gradlew verifyPlugin # ./gradlew publishPlugin - name: Create GitHub Release uses: softprops/action-gh-release@v2 with: tag_name: jetbrains files: JetBrains/build/distributions/snow-cli-jetbrains-${{ env.PLUGIN_VERSION }}.zip name: Release JetBrains plugin body: | ## 🚀 Snow CLI JetBrains plugin Latest release version: `v${{ env.PLUGIN_VERSION }}` ### What's New - Add AI-generated git commit message feature ### Usage JetBrains IDE plugin for integrating with Snow AI CLI. Provides intelligent code navigation and search powered by AI, with support for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs. ### Features - **WebSocket Integration**: Real-time bi-directional communication with Snow CLI - **Editor Context Tracking**: Automatically sends active file, cursor position, and selected text to Snow CLI - **Code Diagnostics**: Retrieves and shares code diagnostics with the AI - **Go to Definition**: Navigate to symbol definitions via Snow CLI - **Find References**: Find all references to symbols across the project - **Document Symbols**: Extract and share document structure with the AI - **Auto-Reconnection**: Robust reconnection with exponential backoff strategy - **Terminal Integration**: Quick access to Snow CLI from the toolbar draft: false prerelease: false ================================================ FILE: .github/workflows/build_vsix.yml ================================================ name: Build VSIX Package on: push: paths: - '.github/workflows/build_vsix.yml' - 'VSIX/**' - 'VSIX/**.vsix' - '!VSIX/**.md' - '!VSIX/LICENSE' - '!VSIX/.vscodeignore' branches: - '*' tags: - 'v*' workflow_dispatch: inputs: version: description: 'Version to publish (e.g., 1.0.0)' required: true type: string permissions: contents: write packages: write jobs: publish: runs-on: ubuntu-latest defaults: run: working-directory: VSIX steps: - name: Checkout code uses: actions/checkout@v6 - name: Setup Node.js uses: actions/setup-node@v6 with: node-version: '20' registry-url: 'https://registry.npmjs.org/' - name: Update version (manual trigger) if: github.event_name == 'workflow_dispatch' run: npm version ${{ github.event.inputs.version }} --no-git-tag-version - name: Get package version run: | echo "PACKAGE_VERSION=$(node -p "require('./package.json').version")" >> $GITHUB_ENV - name: Install dependencies run: npm install - name: Build project run: npx -y @vscode/vsce package - name: Create GitHub Release uses: softprops/action-gh-release@v2 with: tag_name: vsix-v${{ env.PACKAGE_VERSION }} files: VSIX/snow-cli-${{ env.PACKAGE_VERSION }}.vsix name: VSCode Extension v${{ env.PACKAGE_VERSION }} body: | ## 🚀 Snow CLI VSCode Extension v${{ env.PACKAGE_VERSION }} ### What's New - Fix the problem of not being able to trigger the system ringtone and add relevant settings ### Installation 1. Download the `.vsix` file from this release 2. Open VSCode 3. Go to Extensions view (Ctrl+Shift+X) 4. Click the "..." menu → "Install from VSIX..." 5. Select the downloaded file ### Requirements Install Snow CLI globally: ```bash npm install -g snow-ai ``` ### Usage 1. Open any file in VSCode 2. Click the **Snow icon** button in the editor toolbar (top right) 3. A terminal opens with Snow CLI running 4. The extension automatically connects via WebSocket ### Features - Integrated terminal with Snow CLI - WebSocket-based communication - ACE Code Search integration - Sidebar and split terminal modes draft: false prerelease: false fail_on_unmatched_files: true make_latest: true ================================================ FILE: .github/workflows/publish.yml ================================================ name: Publish to NPM on: push: tags: - 'v*' workflow_dispatch: inputs: version: description: 'Version to publish (e.g., 1.0.0)' required: true type: string permissions: contents: write packages: write jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v6 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v6 with: node-version: '22' registry-url: 'https://registry.npmjs.org/' - name: Use CI npm config run: cp .npmrc.ci .npmrc - name: Install dependencies run: npm install - name: Build project run: npm run build - name: Publish to NPM run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - name: Create GitHub Release if: github.event_name == 'push' uses: softprops/action-gh-release@v2 with: tag_name: ${{ github.ref_name }} name: Release ${{ github.ref_name }} body: | ## Snow CLI ${{ github.ref_name }} ### What's New - Add the /simple command to quickly switch to the simple theme - Add search engine plugins to support more custom search engines ### Installation ```bash npm install -g snow-ai ``` ### Usage ```bash snow ``` ### Update ```bash snow --update ``` draft: false prerelease: false ================================================ FILE: .gitignore ================================================ node_modules dist bundle out .snow AGENTS.md pr.md CHANGELOG.md CONTEXT.md ROLE*.md .venv .idea ================================================ FILE: .npmrc ================================================ # 保持对等依赖兼容性 legacy-peer-deps=true # 安装速度优化配置 # 使用 npm 镜像源(中国大陆用户) registry=https://registry.npmmirror.com # 并行安装配置 fetch-retries=3 fetch-retry-mintimeout=10000 fetch-retry-maxtimeout=60000 # 网络超时设置(使用 fetch-timeout 替代已废弃的 network-timeout) fetch-timeout=300000 # 缓存配置优化 prefer-offline=true audit=false fund=false # 并行下载数(提升安装速度) maxsockets=10 ================================================ FILE: .npmrc.ci ================================================ # CI 环境专用配置 # 必须使用官方 npm registry 才能发布 # 保持对等依赖兼容性 legacy-peer-deps=true # 使用官方 npm registry registry=https://registry.npmjs.org # 并行安装配置 fetch-retries=3 fetch-retry-mintimeout=10000 fetch-retry-maxtimeout=60000 # 网络超时设置 fetch-timeout=300000 # 缓存配置优化 prefer-offline=false audit=false fund=false # 并行下载数 maxsockets=10 ================================================ FILE: .prettierignore ================================================ dist ================================================ FILE: .vscode/launch.json ================================================ { "version": "0.2.0", "configurations": [ { "name": "Debug CLI (ts-node)", "type": "node", "request": "launch", "runtimeExecutable": "node", "runtimeArgs": ["--loader", "ts-node/esm"], "args": ["${workspaceFolder}/source/cli.tsx"], "cwd": "${workspaceFolder}", "console": "integratedTerminal", "internalConsoleOptions": "neverOpen", "skipFiles": ["/**"], "env": { "TS_NODE_PROJECT": "${workspaceFolder}/tsconfig.json" } }, { "name": "Debug CLI (built)", "type": "node", "request": "launch", "program": "${workspaceFolder}/bundle/cli.mjs", "cwd": "${workspaceFolder}", "console": "integratedTerminal", "internalConsoleOptions": "neverOpen", "preLaunchTask": "npm: build", "skipFiles": ["/**"] }, { "name": "Debug Current File (ts-node)", "type": "node", "request": "launch", "runtimeArgs": ["--loader", "ts-node/esm"], "args": ["${relativeFile}"], "cwd": "${workspaceFolder}", "console": "integratedTerminal", "internalConsoleOptions": "neverOpen", "skipFiles": ["/**"], "env": { "TS_NODE_PROJECT": "${workspaceFolder}/tsconfig.json" } } ] } ================================================ FILE: .vscode/settings.json ================================================ {} ================================================ FILE: .vscode/tasks.json ================================================ { "version": "2.0.0", "tasks": [ { "label": "npm: build", "type": "npm", "script": "build", "group": "build", "problemMatcher": ["$tsc"], "detail": "Build the project" }, { "label": "npm: dev", "type": "npm", "script": "dev", "group": "build", "isBackground": true, "problemMatcher": ["$tsc-watch"], "detail": "Watch TypeScript files for changes" }, { "label": "TypeScript: Watch", "type": "shell", "command": "npx tsc --watch", "group": "build", "isBackground": true, "problemMatcher": ["$tsc-watch"] } ] } ================================================ FILE: JetBrains/.gitignore ================================================ # Gradle .gradle/ build/ !gradle/ !gradle/wrapper/ !gradle/wrapper/gradle-wrapper.jar !gradle/wrapper/gradle-wrapper.properties # IntelliJ IDEA .idea/ *.iml *.iws *.ipr out/ # Build output dist/ # OS .DS_Store Thumbs.db # Logs *.log # Plugin build artifacts *.zip ================================================ FILE: JetBrains/README.md ================================================ # Snow CLI JetBrains Plugin JetBrains IDE plugin for integrating with Snow AI CLI. Provides intelligent code navigation and search powered by AI, with support for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs. ## Features - **WebSocket Integration**: Real-time bi-directional communication with Snow CLI - **Editor Context Tracking**: Automatically sends active file, cursor position, and selected text to Snow CLI - **Code Diagnostics**: Retrieves and shares code diagnostics with the AI - **Go to Definition**: Navigate to symbol definitions via Snow CLI - **Find References**: Find all references to symbols across the project - **Document Symbols**: Extract and share document structure with the AI - **Auto-Reconnection**: Robust reconnection with exponential backoff strategy - **Terminal Integration**: Quick access to Snow CLI from the toolbar ## Recommended Terminal for Windows Users For the best experience on Windows, we recommend: - **PowerShell 7+**: Modern cross-platform PowerShell with enhanced features and compatibility - GitHub: https://github.com/PowerShell/PowerShell - **Windows Terminal**: Modern terminal application with tabs, panes, and GPU-accelerated rendering - GitHub: https://github.com/microsoft/terminal **Installation**: ```bash # Install via winget (built-in on Windows 10/11) winget install Microsoft.PowerShell winget install Microsoft.WindowsTerminal # Or install from Microsoft Store ``` ================================================ FILE: JetBrains/build.gradle.kts ================================================ plugins { id("java") id("org.jetbrains.kotlin.jvm") version "1.9.21" id("org.jetbrains.intellij") version "1.16.1" } group = "com.snow" version = "0.4.21" repositories { mavenCentral() } // Configure Gradle IntelliJ Plugin intellij { version.set("2024.1") type.set("IC") // Target IDE Platform (IC = IntelliJ IDEA Community) plugins.set(listOf("org.jetbrains.plugins.terminal")) } tasks { // Set the JVM compatibility versions withType { sourceCompatibility = "17" targetCompatibility = "17" } withType { kotlinOptions.jvmTarget = "17" } patchPluginXml { sinceBuild.set("241") untilBuild.set("261.*") } signPlugin { certificateChain.set(System.getenv("CERTIFICATE_CHAIN")) privateKey.set(System.getenv("PRIVATE_KEY")) password.set(System.getenv("PRIVATE_KEY_PASSWORD")) } publishPlugin { token.set(System.getenv("PUBLISH_TOKEN")) } // Skip instrumentCode task to avoid JDK path issues instrumentCode { enabled = false } // Skip buildSearchableOptions to avoid coroutines-javaagent issues buildSearchableOptions { enabled = false } } dependencies { implementation("org.java-websocket:Java-WebSocket:1.5.4") implementation("org.json:json:20231013") } ================================================ FILE: JetBrains/gradle/wrapper/gradle-wrapper.properties ================================================ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip networkTimeout=60000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists ================================================ FILE: JetBrains/gradle.properties ================================================ # IntelliJ Platform Artifacts Repositories -> https://plugins.jetbrains.com/docs/intellij/intellij-artifacts.html pluginGroup = com.snow pluginName = Snow CLI pluginRepositoryUrl = https://github.com/yourusername/snow-cli # SemVer format -> https://semver.org pluginVersion = 0.4.5 # Supported build number ranges and IntelliJ Platform versions -> https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html pluginSinceBuild = 241 pluginUntilBuild = 253.* # IntelliJ Platform Properties -> https://plugins.jetbrains.com/docs/intellij/tools-gradle-intellij-plugin.html#configuration-intellij-extension platformType = IC platformVersion = 2024.1 # Plugin Dependencies -> https://plugins.jetbrains.com/docs/intellij/plugin-dependencies.html # Example: platformPlugins = com.intellij.java, com.jetbrains.php:203.4449.22 platformPlugins = # Gradle Releases -> https://github.com/gradle/gradle/releases gradleVersion = 8.4 # Opt-out flag for bundling Kotlin standard library -> https://jb.gg/intellij-platform-kotlin-stdlib kotlin.stdlib.default.dependency = false # Enable Gradle Configuration Cache -> https://docs.gradle.org/current/userguide/configuration_cache.html org.gradle.configuration-cache = true # Enable Gradle Build Cache -> https://docs.gradle.org/current/userguide/build_cache.html org.gradle.caching = true # Enable Gradle Kotlin DSL Lazy Property Assignment -> https://docs.gradle.org/current/userguide/kotlin_dsl.html#kotdsl:assignment systemProp.org.gradle.unsafe.kotlin.assignment = true ================================================ FILE: JetBrains/gradlew ================================================ #!/bin/sh # # Copyright © 2015-2021 the original authors. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # https://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # ############################################################################## # # Gradle start up script for POSIX generated by Gradle. # # Important for running: # # (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is # noncompliant, but you have some other compliant shell such as ksh or # bash, then to run this script, type that shell name before the whole # command line, like: # # ksh Gradle # # Busybox and similar reduced shells will NOT work, because this script # requires all of these POSIX shell features: # * functions; # * expansions «$var», «${var}», «${var:-default}», «${var+SET}», # «${var#prefix}», «${var%suffix}», and «$( cmd )»; # * compound commands having a testable exit status, especially «case»; # * various built-in commands including «command», «set», and «ulimit». # # Important for patching: # # (2) This script targets any POSIX shell, so it avoids extensions provided # by Bash, Ksh, etc; in particular arrays are avoided. # # The "traditional" practice of packing multiple parameters into a # space-separated string is a well documented source of bugs and security # problems, so this is (mostly) avoided, by progressively accumulating # options in "$@", and eventually passing that to Java. # # Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS, # and GRADLE_OPTS) rely on word-splitting, this is performed explicitly; # see the in-line comments for details. # # There are tweaks for specific operating systems such as AIX, CygWin, # Darwin, MinGW, and NonStop. # # (3) This script is generated from the Groovy template # https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt # within the Gradle project. # # You can find Gradle at https://github.com/gradle/gradle/. # ############################################################################## # Attempt to set APP_HOME # Resolve links: $0 may be a link app_path=$0 # Need this for daisy-chained symlinks. while APP_HOME=${app_path%"${app_path##*/}"} # leaves a trailing /; empty if no leading path [ -h "$app_path" ] do ls=$( ls -ld "$app_path" ) link=${ls#*' -> '} case $link in #( /*) app_path=$link ;; #( *) app_path=$APP_HOME$link ;; esac done # This is normally unused # shellcheck disable=SC2034 APP_BASE_NAME=${0##*/} APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit # Use the maximum available, or set MAX_FD != -1 to use that value. MAX_FD=maximum warn () { echo "$*" } >&2 die () { echo echo "$*" echo exit 1 } >&2 # OS specific support (must be 'true' or 'false'). cygwin=false msys=false darwin=false nonstop=false case "$( uname )" in #( CYGWIN* ) cygwin=true ;; #( Darwin* ) darwin=true ;; #( MSYS* | MINGW* ) msys=true ;; #( NONSTOP* ) nonstop=true ;; esac CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar # Determine the Java command to use to start the JVM. if [ -n "$JAVA_HOME" ] ; then if [ -x "$JAVA_HOME/jre/sh/java" ] ; then # IBM's JDK on AIX uses strange locations for the executables JAVACMD=$JAVA_HOME/jre/sh/java else JAVACMD=$JAVA_HOME/bin/java fi if [ ! -x "$JAVACMD" ] ; then die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME Please set the JAVA_HOME variable in your environment to match the location of your Java installation." fi else JAVACMD=java if ! command -v java >/dev/null 2>&1 then die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. Please set the JAVA_HOME variable in your environment to match the location of your Java installation." fi fi # Increase the maximum file descriptors if we can. if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then case $MAX_FD in #( max*) # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked. # shellcheck disable=SC3045 MAX_FD=$( ulimit -H -n ) || warn "Could not query maximum file descriptor limit" esac case $MAX_FD in #( '' | soft) :;; #( *) # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked. # shellcheck disable=SC3045 ulimit -n "$MAX_FD" || warn "Could not set maximum file descriptor limit to $MAX_FD" esac fi # Collect all arguments for the java command, stacking in reverse order: # * args from the command line # * the main class name # * -classpath # * -D...appname settings # * --module-path (only if needed) # * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables. # For Cygwin or MSYS, switch paths to Windows format before running java if "$cygwin" || "$msys" ; then APP_HOME=$( cygpath --path --mixed "$APP_HOME" ) CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" ) JAVACMD=$( cygpath --unix "$JAVACMD" ) # Now convert the arguments - kludge to limit ourselves to /bin/sh for arg do if case $arg in #( -*) false ;; # don't mess with options #( /?*) t=${arg#/} t=/${t%%/*} # looks like a POSIX filepath [ -e "$t" ] ;; #( *) false ;; esac then arg=$( cygpath --path --ignore --mixed "$arg" ) fi # Roll the args list around exactly as many times as the number of # args, so each arg winds up back in the position where it started, but # possibly modified. # # NB: a `for` loop captures its iteration list before it begins, so # changing the positional parameters here affects neither the number of # iterations, nor the values presented in `arg`. shift # remove old arg set -- "$@" "$arg" # push replacement arg done fi # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"' # Collect all arguments for the java command: # * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments, # and any embedded shellness will be escaped. # * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be # treated as '${Hostname}' itself on the command line. set -- \ "-Dorg.gradle.appname=$APP_BASE_NAME" \ -classpath "$CLASSPATH" \ org.gradle.wrapper.GradleWrapperMain \ "$@" # Stop when "xargs" is not available. if ! command -v xargs >/dev/null 2>&1 then die "xargs is not available" fi # Use "xargs" to parse quoted args. # # With -n1 it outputs one arg per line, with the quotes and backslashes removed. # # In Bash we could simply go: # # readarray ARGS < <( xargs -n1 <<<"$var" ) && # set -- "${ARGS[@]}" "$@" # # but POSIX shell has neither arrays nor command substitution, so instead we # post-process each arg (as a line of input to sed) to backslash-escape any # character that might be a shell metacharacter, then use eval to reverse # that process (while maintaining the separation between arguments), and wrap # the whole thing up as a single "set" statement. # # This will of course break if any of these variables contains a newline or # an unmatched quote. # eval "set -- $( printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" | xargs -n1 | sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' | tr '\n' ' ' )" '"$@"' exec "$JAVACMD" "$@" ================================================ FILE: JetBrains/gradlew.bat ================================================ @rem @rem Copyright 2015 the original author or authors. @rem @rem Licensed under the Apache License, Version 2.0 (the "License"); @rem you may not use this file except in compliance with the License. @rem You may obtain a copy of the License at @rem @rem https://www.apache.org/licenses/LICENSE-2.0 @rem @rem Unless required by applicable law or agreed to in writing, software @rem distributed under the License is distributed on an "AS IS" BASIS, @rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @rem See the License for the specific language governing permissions and @rem limitations under the License. @rem @if "%DEBUG%"=="" @echo off @rem ########################################################################## @rem @rem Gradle startup script for Windows @rem @rem ########################################################################## @rem Set local scope for the variables with windows NT shell if "%OS%"=="Windows_NT" setlocal set DIRNAME=%~dp0 if "%DIRNAME%"=="" set DIRNAME=. @rem This is normally unused set APP_BASE_NAME=%~n0 set APP_HOME=%DIRNAME% @rem Resolve any "." and ".." in APP_HOME to make it shorter. for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m" @rem Find java.exe if defined JAVA_HOME goto findJavaFromJavaHome set JAVA_EXE=java.exe %JAVA_EXE% -version >NUL 2>&1 if %ERRORLEVEL% equ 0 goto execute echo. echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. echo. echo Please set the JAVA_HOME variable in your environment to match the echo location of your Java installation. goto fail :findJavaFromJavaHome set JAVA_HOME=%JAVA_HOME:"=% set JAVA_EXE=%JAVA_HOME%/bin/java.exe if exist "%JAVA_EXE%" goto execute echo. echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% echo. echo Please set the JAVA_HOME variable in your environment to match the echo location of your Java installation. goto fail :execute @rem Setup the command line set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar @rem Execute Gradle "%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %* :end @rem End local scope for the variables with windows NT shell if "%OS%"=="Windows_NT" endlocal :omega @exit /b %ERRORLEVEL% :fail @exit /b 1 ================================================ FILE: JetBrains/settings.gradle.kts ================================================ rootProject.name = "snow-cli-jetbrains" ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/SnowCodeNavigator.kt ================================================ package com.snow.plugin import com.intellij.openapi.editor.LogicalPosition import com.intellij.openapi.project.Project import com.intellij.openapi.vfs.VirtualFileManager import com.intellij.psi.PsiDocumentManager import com.intellij.psi.PsiManager import com.intellij.psi.search.searches.ReferencesSearch import com.intellij.psi.util.PsiTreeUtil import com.intellij.psi.PsiElement import com.intellij.psi.PsiNamedElement import com.intellij.psi.PsiFile import com.intellij.codeInsight.navigation.actions.GotoDeclarationAction import com.intellij.openapi.editor.Editor import com.intellij.openapi.editor.EditorFactory /** * Handles code navigation features (go to definition, find references, get symbols) */ class SnowCodeNavigator(private val project: Project) { /** * Go to definition at specified location */ fun goToDefinition(filePath: String, line: Int, column: Int): List> { val file = VirtualFileManager.getInstance().findFileByUrl("file://$filePath") ?: return emptyList() val psiFile = PsiManager.getInstance(project).findFile(file) ?: return emptyList() val document = PsiDocumentManager.getInstance(project).getDocument(psiFile) ?: return emptyList() if (line >= document.lineCount) return emptyList() val offset = document.getLineStartOffset(line) + column val element = psiFile.findElementAt(offset) ?: return emptyList() // Navigate to declaration val references = element.references val definitions = mutableListOf>() for (reference in references) { val resolved = reference.resolve() ?: continue val containingFile = resolved.containingFile?.virtualFile ?: continue val doc = PsiDocumentManager.getInstance(project).getDocument(resolved.containingFile) ?: continue val textRange = resolved.textRange definitions.add( mapOf( "filePath" to containingFile.path, "line" to doc.getLineNumber(textRange.startOffset), "column" to textRange.startOffset - doc.getLineStartOffset(doc.getLineNumber(textRange.startOffset)), "endLine" to doc.getLineNumber(textRange.endOffset), "endColumn" to textRange.endOffset - doc.getLineStartOffset(doc.getLineNumber(textRange.endOffset)) ) ) } return definitions } /** * Find all references to element at specified location */ fun findReferences(filePath: String, line: Int, column: Int): List> { val file = VirtualFileManager.getInstance().findFileByUrl("file://$filePath") ?: return emptyList() val psiFile = PsiManager.getInstance(project).findFile(file) ?: return emptyList() val document = PsiDocumentManager.getInstance(project).getDocument(psiFile) ?: return emptyList() if (line >= document.lineCount) return emptyList() val offset = document.getLineStartOffset(line) + column val element = psiFile.findElementAt(offset) ?: return emptyList() // Find the parent named element val namedElement = PsiTreeUtil.getParentOfType(element, PsiNamedElement::class.java) ?: return emptyList() // Search for references val references = ReferencesSearch.search(namedElement, namedElement.useScope).findAll() val results = mutableListOf>() for (reference in references) { val refElement = reference.element val refFile = refElement.containingFile?.virtualFile ?: continue val refDoc = PsiDocumentManager.getInstance(project).getDocument(refElement.containingFile) ?: continue val textRange = refElement.textRange results.add( mapOf( "filePath" to refFile.path, "line" to refDoc.getLineNumber(textRange.startOffset), "column" to textRange.startOffset - refDoc.getLineStartOffset(refDoc.getLineNumber(textRange.startOffset)), "endLine" to refDoc.getLineNumber(textRange.endOffset), "endColumn" to textRange.endOffset - refDoc.getLineStartOffset(refDoc.getLineNumber(textRange.endOffset)) ) ) } return results } /** * Get all symbols in the file */ fun getSymbols(filePath: String): List> { val file = VirtualFileManager.getInstance().findFileByUrl("file://$filePath") ?: return emptyList() val psiFile = PsiManager.getInstance(project).findFile(file) ?: return emptyList() val document = PsiDocumentManager.getInstance(project).getDocument(psiFile) ?: return emptyList() val symbols = mutableListOf>() // Recursively collect named elements fun collectSymbols(element: PsiElement) { if (element is PsiNamedElement && element.name != null) { val textRange = element.textRange val startLine = document.getLineNumber(textRange.startOffset) val endLine = document.getLineNumber(textRange.endOffset) symbols.add( mapOf( "name" to element.name, "kind" to getSymbolKind(element), "line" to startLine, "column" to textRange.startOffset - document.getLineStartOffset(startLine), "endLine" to endLine, "endColumn" to textRange.endOffset - document.getLineStartOffset(endLine), "detail" to (element.text.take(50) + if (element.text.length > 50) "..." else "") ) ) } for (child in element.children) { collectSymbols(child) } } collectSymbols(psiFile) return symbols } /** * Get symbol kind from PSI element type */ private fun getSymbolKind(element: PsiElement): String { val className = element.javaClass.simpleName return when { className.contains("Class") -> "Class" className.contains("Method") || className.contains("Function") -> "Method" className.contains("Field") || className.contains("Property") -> "Field" className.contains("Variable") -> "Variable" className.contains("Interface") -> "Interface" className.contains("Enum") -> "Enum" className.contains("Constant") -> "Constant" className.contains("Constructor") -> "Constructor" className.contains("Module") || className.contains("Package") -> "Module" else -> "Unknown" } } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/SnowEditorContextTracker.kt ================================================ package com.snow.plugin import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.diagnostic.Logger import com.intellij.openapi.editor.Editor import com.intellij.openapi.editor.event.CaretEvent import com.intellij.openapi.editor.event.CaretListener import com.intellij.openapi.editor.event.SelectionEvent import com.intellij.openapi.editor.event.SelectionListener import com.intellij.openapi.fileEditor.FileEditorManager import com.intellij.openapi.fileEditor.FileEditorManagerEvent import com.intellij.openapi.fileEditor.FileEditorManagerListener import com.intellij.openapi.project.Project import com.intellij.openapi.vfs.VirtualFile /** * Tracks editor context and sends updates to Snow CLI */ class SnowEditorContextTracker(private val project: Project) { private val logger = Logger.getInstance(SnowEditorContextTracker::class.java) private val wsManager = SnowWebSocketManager.instance private var currentEditor: Editor? = null init { setupListeners() } /** * Normalize path for cross-platform compatibility * - Converts Windows backslashes to forward slashes * - Converts drive letters to lowercase for consistent comparison */ private fun normalizePath(path: String?): String? { if (path == null) return null var normalized = path.replace('\\', '/') // Convert Windows drive letter to lowercase (C: -> c:) if (normalized.matches(Regex("^[A-Z]:.*"))) { normalized = normalized[0].lowercaseChar() + normalized.substring(1) } return normalized } /** * Setup editor listeners */ private fun setupListeners() { // Listen to file editor changes val connection = project.messageBus.connect() connection.subscribe( FileEditorManagerListener.FILE_EDITOR_MANAGER, object : FileEditorManagerListener { override fun selectionChanged(event: FileEditorManagerEvent) { val editor = FileEditorManager.getInstance(project).selectedTextEditor setupEditorListeners(editor) sendEditorContext() } override fun fileOpened(source: FileEditorManager, file: VirtualFile) { sendEditorContext() } } ) } /** * Setup listeners for a specific editor */ private fun setupEditorListeners(editor: Editor?) { // Remove old listeners by tracking current editor if (editor == currentEditor) { return } currentEditor = editor if (editor == null) { return } // Add caret listener for cursor position changes editor.caretModel.addCaretListener(object : CaretListener { override fun caretPositionChanged(event: CaretEvent) { sendEditorContext() } }) // Add selection listener editor.selectionModel.addSelectionListener(object : SelectionListener { override fun selectionChanged(event: SelectionEvent) { sendEditorContext() } }) } /** * Send current editor context to Snow CLI */ fun sendEditorContext() { ApplicationManager.getApplication().runReadAction { try { val editor = FileEditorManager.getInstance(project).selectedTextEditor val context = buildContext(editor) wsManager.sendMessage(context) } catch (e: Exception) { logger.warn("Failed to send editor context", e) } } } /** * Build context map from current editor state */ private fun buildContext(editor: Editor?): Map { val context = mutableMapOf( "type" to "context" ) // Get workspace folder (always include) - normalize path for Windows compatibility project.basePath?.let { context["workspaceFolder"] = normalizePath(it) } // Get active file (try to get even if editor is null) - normalize path for Windows compatibility val virtualFile = FileEditorManager.getInstance(project).selectedFiles.firstOrNull() virtualFile?.path?.let { context["activeFile"] = normalizePath(it) } // If no editor, still return context with file info if (editor == null) { return context } // Get cursor position val caretModel = editor.caretModel val position = mapOf( "line" to caretModel.logicalPosition.line, "character" to caretModel.logicalPosition.column ) context["cursorPosition"] = position // Get selected text val selectionModel = editor.selectionModel if (selectionModel.hasSelection()) { val selectedText = selectionModel.selectedText context["selectedText"] = selectedText } return context } /** * Get current virtual file */ fun getCurrentFile(): VirtualFile? { return FileEditorManager.getInstance(project).selectedFiles.firstOrNull() } /** * Get current editor */ fun getCurrentEditor(): Editor? { return FileEditorManager.getInstance(project).selectedTextEditor } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/SnowMessageHandler.kt ================================================ package com.snow.plugin import com.intellij.codeInsight.daemon.impl.HighlightInfo import com.intellij.codeInsight.daemon.impl.HighlightInfoType import com.intellij.diff.DiffContentFactory import com.intellij.diff.DiffManager import com.intellij.diff.chains.SimpleDiffRequestChain import com.intellij.diff.requests.SimpleDiffRequest import com.intellij.lang.annotation.HighlightSeverity import com.intellij.notification.NotificationGroupManager import com.intellij.notification.NotificationType import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.application.ModalityState import com.intellij.openapi.diagnostic.Logger import com.intellij.openapi.editor.Document import com.intellij.openapi.fileTypes.FileTypeManager import com.intellij.openapi.project.Project import com.intellij.openapi.fileEditor.FileEditorManager import com.intellij.openapi.vfs.VirtualFile import com.intellij.openapi.vfs.VirtualFileManager import com.intellij.openapi.wm.ToolWindowManager import com.intellij.psi.PsiDocumentManager import com.intellij.psi.PsiFile import com.intellij.psi.PsiManager import org.json.JSONObject import org.json.JSONArray import java.io.File /** * Handles incoming messages from Snow CLI */ class SnowMessageHandler(private val project: Project) { private val logger = Logger.getInstance(SnowMessageHandler::class.java) private val wsManager = SnowWebSocketManager.instance private val codeNavigator = SnowCodeNavigator(project) init { wsManager.setMessageHandler { message -> handleMessage(message) } } /** * Handle incoming WebSocket message */ private fun handleMessage(message: String) { try { val json = JSONObject(message) val type = json.optString("type") when (type) { "getDiagnostics" -> handleGetDiagnostics(json) "aceGoToDefinition" -> handleGoToDefinition(json) "aceFindReferences" -> handleFindReferences(json) "aceGetSymbols" -> handleGetSymbols(json) "showDiff" -> handleShowDiff(json) "showDiffReview" -> handleShowDiffReview(json) "showGitDiff" -> handleShowGitDiff(json) "closeDiff" -> handleCloseDiff() else -> logger.info("Unknown message type: $type") } } catch (e: Exception) { logger.warn("Failed to handle message", e) } } /** * Handle getDiagnostics request */ private fun handleGetDiagnostics(json: JSONObject) { val filePath = json.optString("filePath") val requestId = json.optString("requestId") ApplicationManager.getApplication().runReadAction { try { val file = VirtualFileManager.getInstance().findFileByUrl("file://$filePath") val diagnostics = if (file != null) { getDiagnostics(file) } else { emptyList() } val response = mapOf( "type" to "diagnostics", "requestId" to requestId, "diagnostics" to diagnostics ) wsManager.sendMessage(response) } catch (e: Exception) { logger.warn("Failed to get diagnostics", e) sendEmptyResponse("diagnostics", requestId) } } } /** * Get diagnostics for a file */ private fun getDiagnostics(file: VirtualFile): List> { val psiFile = PsiManager.getInstance(project).findFile(file) ?: return emptyList() val document = PsiDocumentManager.getInstance(project).getDocument(psiFile) ?: return emptyList() return try { val highlightInfos = mutableListOf>() // Wrap in read action to ensure thread safety ApplicationManager.getApplication().runReadAction { try { // Use DocumentMarkupModel to get all highlight infos safely val markupModel = com.intellij.openapi.editor.impl.DocumentMarkupModel.forDocument(document, project, true) if (markupModel != null) { // Process all highlighters markupModel.allHighlighters.forEach { highlighter -> try { // Get HighlightInfo from the highlighter's error stripe tooltip val errorStripeTooltip = highlighter.errorStripeTooltip // Try to extract info from different tooltip types if (errorStripeTooltip is HighlightInfo) { val info = errorStripeTooltip val severity = info.severity // Skip if severity is too low (e.g., just syntax highlighting) if (severity.myVal <= HighlightSeverity.INFORMATION.myVal) { return@forEach } val startOffset = info.startOffset val line = document.getLineNumber(startOffset) val lineStartOffset = document.getLineStartOffset(line) val character = startOffset - lineStartOffset highlightInfos.add(mapOf( "message" to (info.description ?: "Unknown issue"), "severity" to when { severity == HighlightSeverity.ERROR -> "error" severity == HighlightSeverity.WARNING -> "warning" severity == HighlightSeverity.WEAK_WARNING -> "info" else -> "hint" }, "line" to line, "character" to character, "source" to "IntelliJ", "code" to (info.inspectionToolId ?: "") )) } } catch (e: Exception) { // Silently skip this highlighter if we can't process it logger.debug("Failed to process highlighter", e) } } } } catch (e: Exception) { logger.warn("Failed to extract diagnostics from markup model", e) } } highlightInfos } catch (e: Exception) { logger.warn("Failed to get diagnostics", e) emptyList() } } /** * Handle aceGoToDefinition request */ private fun handleGoToDefinition(json: JSONObject) { val filePath = json.optString("filePath") val line = json.optInt("line") val column = json.optInt("column") val requestId = json.optString("requestId") ApplicationManager.getApplication().runReadAction { try { val definitions = codeNavigator.goToDefinition(filePath, line, column) val response = mapOf( "type" to "aceGoToDefinitionResult", "requestId" to requestId, "definitions" to definitions ) wsManager.sendMessage(response) } catch (e: Exception) { logger.warn("Failed to go to definition", e) sendEmptyResponse("aceGoToDefinitionResult", requestId, "definitions") } } } /** * Handle aceFindReferences request */ private fun handleFindReferences(json: JSONObject) { val filePath = json.optString("filePath") val line = json.optInt("line") val column = json.optInt("column") val requestId = json.optString("requestId") ApplicationManager.getApplication().runReadAction { try { val references = codeNavigator.findReferences(filePath, line, column) val response = mapOf( "type" to "aceFindReferencesResult", "requestId" to requestId, "references" to references ) wsManager.sendMessage(response) } catch (e: Exception) { logger.warn("Failed to find references", e) sendEmptyResponse("aceFindReferencesResult", requestId, "references") } } } /** * Handle aceGetSymbols request */ private fun handleGetSymbols(json: JSONObject) { val filePath = json.optString("filePath") val requestId = json.optString("requestId") ApplicationManager.getApplication().runReadAction { try { val symbols = codeNavigator.getSymbols(filePath) val response = mapOf( "type" to "aceGetSymbolsResult", "requestId" to requestId, "symbols" to symbols ) wsManager.sendMessage(response) } catch (e: Exception) { logger.warn("Failed to get symbols", e) sendEmptyResponse("aceGetSymbolsResult", requestId, "symbols") } } } @Volatile private var trackedDiffFiles = mutableListOf() private fun closeTrackedDiffs() { if (project.isDisposed) return val fem = FileEditorManager.getInstance(project) val toClose = trackedDiffFiles.toList() trackedDiffFiles.clear() for (file in toClose) { if (file.isValid) { fem.closeFile(file) } } } private fun showDiffInEditor(title: String, leftText: String, rightText: String, leftLabel: String, rightLabel: String, fileName: String) { if (project.isDisposed) return val fem = FileEditorManager.getInstance(project) val beforeFiles = fem.openFiles.toSet() closeTrackedDiffs() val fileType = FileTypeManager.getInstance().getFileTypeByFileName(fileName) val contentFactory = DiffContentFactory.getInstance() val left = contentFactory.create(leftText, fileType) val right = contentFactory.create(rightText, fileType) val request = SimpleDiffRequest(title, left, right, leftLabel, rightLabel) DiffManager.getInstance().showDiff(project, request) val afterFiles = fem.openFiles.toSet() val newFiles = afterFiles - beforeFiles trackedDiffFiles.addAll(newFiles) restoreTerminalFocus() } private fun handleCloseDiff() { ApplicationManager.getApplication().invokeLater({ closeTrackedDiffs() }, ModalityState.defaultModalityState()) } private fun restoreTerminalFocus() { ApplicationManager.getApplication().invokeLater { if (project.isDisposed) return@invokeLater ToolWindowManager.getInstance(project).getToolWindow("Terminal")?.activate(null, false, false) } } private fun notifyError(message: String) { try { NotificationGroupManager.getInstance() .getNotificationGroup("Snow CLI") .createNotification(message, NotificationType.ERROR) .notify(project) } catch (e: Exception) { logger.warn("Failed to show notification: $message", e) } } private fun handleShowDiff(json: JSONObject) { val filePath = json.optString("filePath", "") val originalContent = json.optString("originalContent", "") val newContent = json.optString("newContent", "") val label = json.optString("label", "Diff") if (filePath.isEmpty()) { logger.warn("showDiff: filePath is empty") return } val fileName = File(filePath).name ApplicationManager.getApplication().invokeLater({ try { showDiffInEditor("$label: $fileName", originalContent, newContent, "Original", "Current", fileName) } catch (e: Exception) { logger.error("Failed to show diff for $filePath", e) notifyError("Snow CLI: Failed to show diff - ${e.message}") } }, ModalityState.defaultModalityState()) } private fun handleShowDiffReview(json: JSONObject) { val filesArray = json.optJSONArray("files") if (filesArray == null || filesArray.length() == 0) { logger.warn("showDiffReview: no files") return } data class DiffItem(val title: String, val left: String, val right: String, val fileName: String) val items = mutableListOf() for (i in 0 until filesArray.length()) { try { val fileObj = filesArray.getJSONObject(i) val filePath = fileObj.optString("filePath", "") val originalContent = fileObj.optString("originalContent", "") val newContent = fileObj.optString("newContent", "") val fileName = File(filePath).name items.add(DiffItem("Diff Review: $fileName", originalContent, newContent, fileName)) } catch (e: Exception) { logger.warn("showDiffReview: failed to parse file $i", e) } } if (items.isEmpty()) return ApplicationManager.getApplication().invokeLater({ try { if (project.isDisposed) return@invokeLater val fem = FileEditorManager.getInstance(project) val beforeFiles = fem.openFiles.toSet() closeTrackedDiffs() if (items.size == 1) { val item = items[0] val fileType = FileTypeManager.getInstance().getFileTypeByFileName(item.fileName) val contentFactory = DiffContentFactory.getInstance() val left = contentFactory.create(item.left, fileType) val right = contentFactory.create(item.right, fileType) val request = SimpleDiffRequest(item.title, left, right, "Original", "Current") DiffManager.getInstance().showDiff(project, request) } else { val contentFactory = DiffContentFactory.getInstance() val requests = items.map { item -> val fileType = FileTypeManager.getInstance().getFileTypeByFileName(item.fileName) val left = contentFactory.create(item.left, fileType) val right = contentFactory.create(item.right, fileType) SimpleDiffRequest(item.title, left, right, "Original", "Current") } val chain = SimpleDiffRequestChain(requests) DiffManager.getInstance().showDiff(project, chain, com.intellij.diff.DiffDialogHints.DEFAULT) } val afterFiles = fem.openFiles.toSet() trackedDiffFiles.addAll(afterFiles - beforeFiles) restoreTerminalFocus() } catch (e: Exception) { logger.error("Failed to show diff review", e) notifyError("Snow CLI: Failed to show diff review - ${e.message}") } }, ModalityState.defaultModalityState()) } private fun handleShowGitDiff(json: JSONObject) { val filePath = json.optString("filePath", "") if (filePath.isEmpty()) return ApplicationManager.getApplication().executeOnPooledThread { try { val file = File(filePath) val repoRoot = project.basePath ?: return@executeOnPooledThread val relPath = File(repoRoot).toPath().relativize(file.toPath()).toString().replace('\\', '/') val currentContent = if (file.exists()) file.readText() else "" var originalContent = "" try { val process = ProcessBuilder("git", "show", "HEAD:$relPath") .directory(File(repoRoot)) .redirectErrorStream(false) .start() originalContent = process.inputStream.bufferedReader().readText() process.waitFor() } catch (_: Exception) { // New/untracked file } val fileName = file.name ApplicationManager.getApplication().invokeLater({ try { showDiffInEditor("Git Diff: $fileName", originalContent, currentContent, "HEAD", "Working Tree", fileName) } catch (e: Exception) { logger.error("Failed to show git diff for $filePath", e) notifyError("Snow CLI: Failed to show git diff - ${e.message}") } }, ModalityState.defaultModalityState()) } catch (e: Exception) { logger.error("Failed to show git diff for $filePath", e) } } } /** * Send empty response on error */ private fun sendEmptyResponse(type: String, requestId: String, arrayField: String = "diagnostics") { val response = mapOf( "type" to type, "requestId" to requestId, arrayField to emptyList() ) wsManager.sendMessage(response) } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/SnowPluginLifecycle.kt ================================================ package com.snow.plugin import com.intellij.ide.AppLifecycleListener import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.project.Project import com.intellij.openapi.project.ProjectManager import com.intellij.openapi.project.ProjectManagerListener /** * Plugin lifecycle listener */ class SnowPluginLifecycle : AppLifecycleListener { private val wsManager = SnowWebSocketManager.instance override fun appFrameCreated(commandLineArgs: MutableList) { wsManager.connect() ApplicationManager.getApplication().messageBus.connect() .subscribe(ProjectManager.TOPIC, object : ProjectManagerListener { override fun projectClosed(project: Project) { cleanupProject(project) } }) for (project in ProjectManager.getInstance().openProjects) { setupProject(project) } } override fun appWillBeClosed(isRestart: Boolean) { wsManager.disconnect() } companion object { private val trackers = mutableMapOf() private val handlers = mutableMapOf() fun setupProject(project: Project) { SnowWebSocketManager.instance.updatePortInfoForProject(project) if (!trackers.containsKey(project)) { val tracker = SnowEditorContextTracker(project) val handler = SnowMessageHandler(project) trackers[project] = tracker handlers[project] = handler ApplicationManager.getApplication().executeOnPooledThread { tracker.sendEditorContext() for (i in 1..3) { Thread.sleep(1000) tracker.sendEditorContext() } } } } fun cleanupProject(project: Project) { SnowWebSocketManager.instance.cleanupPortInfoForProject(project) trackers.remove(project) handlers.remove(project) } } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/SnowProjectActivity.kt ================================================ package com.snow.plugin import com.intellij.openapi.actionSystem.ActionManager import com.intellij.openapi.actionSystem.DefaultActionGroup import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.project.Project import com.intellij.openapi.startup.ProjectActivity class SnowProjectActivity : ProjectActivity { override suspend fun execute(project: Project) { SnowPluginLifecycle.setupProject(project) ApplicationManager.getApplication().invokeLater { registerProjectViewAction() } } companion object { @Volatile private var registered = false private fun registerProjectViewAction() { if (registered) return val actionManager = ActionManager.getInstance() val sendAction = actionManager.getAction("snow.SendToSnowCLI") ?: return val group = actionManager.getAction("ProjectViewPopupMenu") as? DefaultActionGroup ?: return group.addSeparator() group.add(sendAction) registered = true } } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/SnowWebSocketManager.kt ================================================ package com.snow.plugin import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.diagnostic.Logger import org.java_websocket.WebSocket import org.java_websocket.handshake.ClientHandshake import org.java_websocket.server.WebSocketServer import java.net.InetSocketAddress import java.net.ServerSocket import java.util.concurrent.ConcurrentHashMap import java.util.concurrent.atomic.AtomicReference /** * Manages WebSocket server for Snow CLI connections */ class SnowWebSocketManager private constructor() { private val logger = Logger.getInstance(SnowWebSocketManager::class.java) private val server = AtomicReference(null) private val messageHandler = AtomicReference<((String) -> Unit)?>(null) private val clients = ConcurrentHashMap.newKeySet() // Cache for last valid editor context @Volatile private var lastValidContext: Map? = null companion object { // Use different port range from VSCode (9527-9537) to avoid conflicts private const val BASE_PORT = 9538 private const val MAX_PORT = 9548 val instance: SnowWebSocketManager by lazy { SnowWebSocketManager() } /** * Normalize path for cross-platform compatibility * - Converts Windows backslashes to forward slashes * - Converts drive letters to lowercase for consistent comparison */ private fun normalizePath(path: String?): String? { if (path == null) return null var normalized = path.replace('\\', '/') // Convert Windows drive letter to lowercase (C: -> c:) if (normalized.matches(Regex("^[A-Z]:.*"))) { normalized = normalized[0].lowercaseChar() + normalized.substring(1) } return normalized } } @Volatile private var actualPort = BASE_PORT /** * Start WebSocket server */ fun connect() { if (server.get() != null) { return } ApplicationManager.getApplication().executeOnPooledThread { tryStartServer(BASE_PORT) } } /** * Try to start server on a specific port, with fallback to next port */ private fun tryStartServer(port: Int) { if (port > MAX_PORT) { logger.error("Failed to start WebSocket server: all ports $BASE_PORT-$MAX_PORT are in use") return } // Synchronously probe whether the port is actually free before handing it // to Java-WebSocket. Java-WebSocket's start() is asynchronous: when another // process (e.g. another JetBrains IDE) already holds the port, the bind // failure surfaces only inside the server thread via onError, AFTER we have // already cached actualPort and registered the project under the wrong port // in snow-cli-ports.json. That mismatch is what causes the CLI to attach // to the WRONG IDE when two JetBrains IDEs are open simultaneously // (showing one IDE's active file with another IDE's working directory). if (!isPortAvailable(port)) { tryStartServer(port + 1) return } try { val wsServer = WebSocketServerImpl(InetSocketAddress(port)) server.set(wsServer) try { wsServer.start() actualPort = port // Server is ready — register all currently open projects for (openProject in com.intellij.openapi.project.ProjectManager.getInstance().openProjects) { if (!openProject.isDefault) { writePortInfo(port, openProject) } } } catch (e: Exception) { if (e.message?.contains("Address already in use") == true) { server.set(null) tryStartServer(port + 1) } else { logger.error("Failed to start WebSocket server on port $port", e) server.set(null) } } } catch (e: Exception) { logger.error("Failed to create WebSocket server on port $port", e) tryStartServer(port + 1) } } /** * Test whether a TCP port can be bound on localhost. Used to avoid the * Java-WebSocket async-bind race: if another IDE already owns the port, * binding here fails immediately and we move on to the next port. * * Note: there is an inherent (microscopic) TOCTOU window between the probe * and the actual WebSocketServer bind. The async catch path above still * handles that fallback for completeness. */ private fun isPortAvailable(port: Int): Boolean { return try { ServerSocket().use { socket -> socket.reuseAddress = false socket.bind(InetSocketAddress("0.0.0.0", port)) } true } catch (e: Exception) { false } } /** * Write port information to temp file for a specific project. * Skips writing if the workspace path is empty to avoid * an entry that matches every cwd. */ private fun writePortInfo(port: Int, project: com.intellij.openapi.project.Project? = null) { try { val tmpDir = System.getProperty("java.io.tmpdir") val portInfoFile = java.io.File(tmpDir, "snow-cli-ports.json") val portInfo = if (portInfoFile.exists()) { org.json.JSONObject(portInfoFile.readText()) } else { org.json.JSONObject() } val resolvedProject = project ?: com.intellij.openapi.project.ProjectManager.getInstance().openProjects .firstOrNull { !it.isDefault } val workspaceFolder = normalizePath(resolvedProject?.basePath) if (workspaceFolder.isNullOrEmpty()) return // Remove stale empty-key entry if present if (portInfo.has("")) { portInfo.remove("") } val entry = org.json.JSONObject() entry.put("port", port) entry.put("ide", "JetBrains") portInfo.put(workspaceFolder, entry) portInfoFile.writeText(portInfo.toString(2)) } catch (e: Exception) { logger.warn("Failed to write port info", e) } } /** * Register a project's workspace in the port info file. * Called when a project finishes initialisation. */ fun updatePortInfoForProject(project: com.intellij.openapi.project.Project) { if (server.get() == null) return writePortInfo(actualPort, project) } /** * Stop WebSocket server */ fun disconnect() { server.getAndSet(null)?.let { wsServer -> try { wsServer.stop() clients.clear() // Clean up port info file cleanupPortInfo() } catch (e: Exception) { logger.error("Error stopping WebSocket server", e) } } } /** * Clean up port information from temp file */ private fun cleanupPortInfo(project: com.intellij.openapi.project.Project? = null) { try { val tmpDir = System.getProperty("java.io.tmpdir") val portInfoFile = java.io.File(tmpDir, "snow-cli-ports.json") if (portInfoFile.exists()) { val portInfo = org.json.JSONObject(portInfoFile.readText()) val resolvedProject = project ?: com.intellij.openapi.project.ProjectManager.getInstance().openProjects .firstOrNull { !it.isDefault } val workspaceFolder = normalizePath(resolvedProject?.basePath) // Remove the workspace entry if (!workspaceFolder.isNullOrEmpty()) { portInfo.remove(workspaceFolder) } // Always remove stale empty-key entry if (portInfo.has("")) { portInfo.remove("") } if (portInfo.length() == 0) { portInfoFile.delete() } else { portInfoFile.writeText(portInfo.toString(2)) } } } catch (e: Exception) { logger.warn("Failed to clean up port info", e) } } /** * Remove a project's workspace from the port info file. * Called when a project is closed. */ fun cleanupPortInfoForProject(project: com.intellij.openapi.project.Project) { cleanupPortInfo(project) } /** * Send message through WebSocket to all connected clients */ fun sendMessage(data: Map) { if (clients.isEmpty()) { return } try { val json = buildJsonString(data) // Cache context messages if (data["type"] == "context") { lastValidContext = data } // Broadcast to all connected clients for (client in clients) { if (client.isOpen) { client.send(json) } } } catch (e: Exception) { logger.warn("Failed to send message", e) } } /** * Set message handler */ fun setMessageHandler(handler: (String) -> Unit) { messageHandler.set(handler) } /** * Send editor context for a specific project */ private fun sendEditorContextForProject(project: com.intellij.openapi.project.Project) { ApplicationManager.getApplication().runReadAction { try { val editor = com.intellij.openapi.fileEditor.FileEditorManager.getInstance(project).selectedTextEditor val virtualFile = com.intellij.openapi.fileEditor.FileEditorManager.getInstance(project).selectedFiles.firstOrNull() val context = mutableMapOf( "type" to "context" ) // Add workspace folder - normalize path for Windows compatibility project.basePath?.let { context["workspaceFolder"] = normalizePath(it) } // Add active file - normalize path for Windows compatibility virtualFile?.path?.let { context["activeFile"] = normalizePath(it) } // Add cursor position if editor available if (editor != null) { val caretModel = editor.caretModel val position = mapOf( "line" to caretModel.logicalPosition.line, "character" to caretModel.logicalPosition.column ) context["cursorPosition"] = position // Add selected text val selectionModel = editor.selectionModel if (selectionModel.hasSelection()) { context["selectedText"] = selectionModel.selectedText } } sendMessage(context) } catch (e: Exception) { logger.warn("Failed to build editor context for project ${project.name}", e) } } } /** * Inner WebSocket server implementation */ private inner class WebSocketServerImpl(address: InetSocketAddress) : WebSocketServer(address) { init { connectionLostTimeout = 0 } override fun onOpen(conn: WebSocket, handshake: ClientHandshake?) { clients.add(conn) // Always send current context on new connection // This ensures CLI always receives the latest editor state ApplicationManager.getApplication().invokeLater { val projects = com.intellij.openapi.project.ProjectManager.getInstance().openProjects for (project in projects) { try { sendEditorContextForProject(project) } catch (e: Exception) { logger.warn("Failed to send context for project ${project.name}", e) } } } // Also send cached context immediately if available (fast path) lastValidContext?.let { context -> try { val json = buildJsonString(context) conn.send(json) } catch (e: Exception) { logger.warn("Failed to send cached context", e) } } } override fun onClose(conn: WebSocket, code: Int, reason: String?, remote: Boolean) { clients.remove(conn) } override fun onMessage(conn: WebSocket, message: String) { messageHandler.get()?.invoke(message) } override fun onError(conn: WebSocket?, ex: Exception) { logger.warn("WebSocket error", ex) conn?.let { clients.remove(it) } } override fun onStart() { // WebSocket server started } } /** * Simple JSON string builder (avoiding external dependencies) */ private fun buildJsonString(data: Map): String { val entries = data.entries.joinToString(",") { (key, value) -> val valueStr = when (value) { null -> "null" is String -> "\"${escapeJson(value)}\"" is Number -> value.toString() is Boolean -> value.toString() is Map<*, *> -> buildJsonString(value as Map) is List<*> -> buildJsonArray(value) else -> "\"${escapeJson(value.toString())}\"" } "\"$key\":$valueStr" } return "{$entries}" } private fun buildJsonArray(list: List<*>): String { val items = list.joinToString(",") { item -> when (item) { null -> "null" is String -> "\"${escapeJson(item)}\"" is Number -> item.toString() is Boolean -> item.toString() is Map<*, *> -> buildJsonString(item as Map) is List<*> -> buildJsonArray(item) else -> "\"${escapeJson(item.toString())}\"" } } return "[$items]" } private fun escapeJson(str: String): String { return str .replace("\\", "\\\\") .replace("\"", "\\\"") .replace("\n", "\\n") .replace("\r", "\\r") .replace("\t", "\\t") } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/actions/GenerateCommitMessageAction.kt ================================================ package com.snow.plugin.actions import com.intellij.openapi.actionSystem.ActionUpdateThread import com.intellij.openapi.actionSystem.AnActionEvent import com.intellij.openapi.components.service import com.intellij.openapi.project.DumbAwareAction import com.intellij.openapi.ui.Messages import com.intellij.openapi.vcs.VcsDataKeys import com.snow.plugin.commit.SnowCommitMessageGenerationService import icons.SnowPluginIcons import java.awt.event.InputEvent class GenerateCommitMessageAction : DumbAwareAction() { override fun getActionUpdateThread(): ActionUpdateThread = ActionUpdateThread.BGT override fun actionPerformed(e: AnActionEvent) { val project = e.project ?: return val commitMessageControl = e.getData(VcsDataKeys.COMMIT_MESSAGE_CONTROL) val commitWorkflowUi = e.getData(VcsDataKeys.COMMIT_WORKFLOW_UI) val service = project.service() if (service.isGenerating()) { service.generate(commitMessageControl, commitWorkflowUi?.commitMessageUi) return } val shouldAskForRequirements = hasRequirementsModifier(e) val additionalRequirements = if (shouldAskForRequirements) { val input = Messages.showInputDialog( project, "Add optional requirements for the generated commit message.", "Snow CLI: Commit Message Requirements", Messages.getQuestionIcon(), ) ?: return input.trim().ifEmpty { null } } else { null } service.generate( commitMessageControl, commitWorkflowUi?.commitMessageUi, additionalRequirements, ) } override fun update(e: AnActionEvent) { val project = e.project val hasCommitMessageTarget = e.getData(VcsDataKeys.COMMIT_MESSAGE_CONTROL) != null || e.getData(VcsDataKeys.COMMIT_WORKFLOW_UI) != null val isGenerating = project?.service()?.isGenerating() == true e.presentation.icon = if (isGenerating) { SnowPluginIcons.SnowStopToolbarAction } else { SnowPluginIcons.SnowToolbarAction } e.presentation.isEnabledAndVisible = project != null && hasCommitMessageTarget e.presentation.text = if (isGenerating) { "Cancel Commit Message Generation" } else { "Generate Commit Message" } e.presentation.description = if (isGenerating) { "Cancel Snow CLI commit message generation" } else { "Generate a commit message with Snow CLI AI. Alt/Option-click to add requirements." } } private fun hasRequirementsModifier(e: AnActionEvent): Boolean { return (e.inputEvent?.modifiersEx ?: 0) and InputEvent.ALT_DOWN_MASK != 0 } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/actions/OpenSnowTerminalAction.kt ================================================ package com.snow.plugin.actions import com.intellij.openapi.actionSystem.AnAction import com.intellij.openapi.actionSystem.AnActionEvent import com.intellij.openapi.application.ApplicationManager import com.snow.plugin.SnowWebSocketManager import com.snow.plugin.util.TerminalCompat class OpenSnowTerminalAction : AnAction() { override fun actionPerformed(e: AnActionEvent) { val project = e.project ?: return ApplicationManager.getApplication().invokeLater { try { TerminalCompat.openTerminalWithCommand(project, project.basePath, "Snow CLI", "snow") } catch (_: Exception) { } } val wsManager = SnowWebSocketManager.instance ApplicationManager.getApplication().executeOnPooledThread { Thread.sleep(500) wsManager.connect() } } override fun update(e: AnActionEvent) { e.presentation.isEnabled = e.project != null } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/actions/SendToSnowCLIAction.kt ================================================ package com.snow.plugin.actions import com.intellij.openapi.actionSystem.ActionUpdateThread import com.intellij.openapi.actionSystem.AnActionEvent import com.intellij.openapi.actionSystem.CommonDataKeys import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.project.DumbAwareAction import com.snow.plugin.SnowWebSocketManager import com.snow.plugin.util.TerminalCompat class SendToSnowCLIAction : DumbAwareAction() { override fun getActionUpdateThread() = ActionUpdateThread.BGT override fun actionPerformed(e: AnActionEvent) { val project = e.project ?: return val files = e.getData(CommonDataKeys.VIRTUAL_FILE_ARRAY) ?: e.getData(CommonDataKeys.VIRTUAL_FILE)?.let { arrayOf(it) } ?: return if (files.isEmpty()) return val formattedPaths = files.joinToString(" ") { "\"${it.path}\"" } ApplicationManager.getApplication().invokeLater { val sent = TerminalCompat.sendTextToNamedTerminal(project, "Snow CLI", formattedPaths) if (!sent) { TerminalCompat.openTerminalWithCommand(project, project.basePath, "Snow CLI", "snow") ApplicationManager.getApplication().executeOnPooledThread { Thread.sleep(3000) ApplicationManager.getApplication().invokeLater { TerminalCompat.sendTextToNamedTerminal(project, "Snow CLI", formattedPaths) } } val wsManager = SnowWebSocketManager.instance ApplicationManager.getApplication().executeOnPooledThread { Thread.sleep(500) wsManager.connect() } } } } override fun update(e: AnActionEvent) { e.presentation.isVisible = true e.presentation.isEnabled = e.project != null } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/actions/TestNotificationAction.kt ================================================ package com.snow.plugin.actions import com.intellij.notification.Notification import com.intellij.notification.NotificationType import com.intellij.notification.Notifications import com.intellij.openapi.actionSystem.AnAction import com.intellij.openapi.actionSystem.AnActionEvent /** * Simple test action to verify notifications work */ class TestNotificationAction : AnAction("Test Notification") { override fun actionPerformed(e: AnActionEvent) { val project = e.project ?: return val notification = Notification( "Snow CLI", "Test", "This is notification 1", NotificationType.INFORMATION ) Notifications.Bus.notify(notification, project) val notification2 = Notification( "Snow CLI", "Test", "This is notification 2", NotificationType.WARNING ) Notifications.Bus.notify(notification2, project) val notification3 = Notification( "Snow CLI", "Test", "This is notification 3", NotificationType.ERROR ) Notifications.Bus.notify(notification3, project) } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/commit/SnowCommitMessageGenerationService.kt ================================================ package com.snow.plugin.commit import com.intellij.notification.NotificationGroupManager import com.intellij.notification.NotificationType import com.intellij.ide.ActivityTracker import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.components.Service import com.intellij.openapi.diagnostic.Logger import com.intellij.openapi.progress.ProcessCanceledException import com.intellij.openapi.progress.ProgressIndicator import com.intellij.openapi.progress.ProgressManager import com.intellij.openapi.progress.Task import com.intellij.openapi.project.Project import com.intellij.openapi.vcs.CommitMessageI import com.intellij.vcs.commit.CommitMessageUi import org.json.JSONArray import org.json.JSONObject import java.io.File import java.net.URI import java.net.http.HttpClient import java.net.http.HttpRequest import java.net.http.HttpResponse import java.time.Duration import java.util.concurrent.TimeUnit import java.util.concurrent.atomic.AtomicBoolean import kotlin.math.min private const val MAX_DIFF_CHARS = 120_000 private const val API_MAX_RETRIES = 5 private const val API_RETRY_BASE_DELAY_MS = 1_000L private val RESTRICTED_HEADERS = setOf( "connection", "content-length", "date", "expect", "from", "host", "upgrade", "via", "warning", ) @Service(Service.Level.PROJECT) class SnowCommitMessageGenerationService(private val project: Project) { private val logger = Logger.getInstance(SnowCommitMessageGenerationService::class.java) private val generating = AtomicBoolean(false) private val httpClient = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(30)) .build() @Volatile private var activeIndicator: ProgressIndicator? = null fun isGenerating(): Boolean = generating.get() fun generate( commitMessageControl: CommitMessageI?, commitMessageUi: CommitMessageUi?, additionalRequirements: String? = null, ) { if (!generating.compareAndSet(false, true)) { activeIndicator?.cancel() return } updateActions() ProgressManager.getInstance().run(object : Task.Backgroundable(project, "Snow CLI: Generating commit message", true) { private var generatedMessage: String? = null override fun run(indicator: ProgressIndicator) { activeIndicator = indicator ApplicationManager.getApplication().invokeLater { commitMessageUi?.startLoading() } val payload = collectDiffPayload(indicator) if (payload.diff.isBlank()) { notify("Snow CLI: No staged or working tree changes found.", NotificationType.INFORMATION) return } generatedMessage = normalizeCommitMessage(requestCommitMessage(payload, indicator, additionalRequirements)) } override fun onSuccess() { val message = generatedMessage ?: return if (commitMessageControl != null) { commitMessageControl.setCommitMessage(message) } else { commitMessageUi?.setText(message) } commitMessageUi?.focus() } override fun onCancel() { notify("Snow CLI: Commit message generation stopped.", NotificationType.INFORMATION) } override fun onThrowable(error: Throwable) { if (error is ProcessCanceledException) { return } logger.warn("Failed to generate commit message", error) notify( "Snow CLI: Failed to generate commit message. ${error.message ?: error.javaClass.simpleName}", NotificationType.ERROR, ) } override fun onFinished() { commitMessageUi?.stopLoading() activeIndicator = null generating.set(false) updateActions() } }) } private fun updateActions() { ApplicationManager.getApplication().invokeLater { ActivityTracker.getInstance().inc() } } private fun collectDiffPayload(indicator: ProgressIndicator): DiffPayload { val repositoryRoot = findGitRoot(indicator) val stagedDiff = execGit(listOf("diff", "--cached", "--no-ext-diff"), repositoryRoot, indicator) val hasStagedChanges = stagedDiff.trim().isNotEmpty() val fullDiff = if (hasStagedChanges) { stagedDiff } else { execGit(listOf("diff", "--no-ext-diff"), repositoryRoot, indicator) } val truncated = fullDiff.length > MAX_DIFF_CHARS return DiffPayload( diff = if (truncated) fullDiff.take(MAX_DIFF_CHARS) else fullDiff, source = if (hasStagedChanges) DiffSource.STAGED else DiffSource.WORKING_TREE, truncated = truncated, ) } private fun findGitRoot(indicator: ProgressIndicator): String { val projectRoot = project.basePath ?: throw IllegalStateException("Project path is not available.") return try { execGit(listOf("rev-parse", "--show-toplevel"), projectRoot, indicator).trim().ifEmpty { projectRoot } } catch (_: Exception) { projectRoot } } private fun execGit(args: List, cwd: String, indicator: ProgressIndicator): String { indicator.checkCanceled() val process = ProcessBuilder(listOf("git") + args) .directory(File(cwd)) .redirectErrorStream(true) .start() val output = StringBuilder() val readerThread = Thread { process.inputStream.bufferedReader().use { reader -> output.append(reader.readText()) } }.apply { name = "Snow Git Output Reader" isDaemon = true start() } try { while (!process.waitFor(100, TimeUnit.MILLISECONDS)) { indicator.checkCanceled() } readerThread.join(1_000) } catch (error: ProcessCanceledException) { process.destroyForcibly() throw error } val text = output.toString() if (process.exitValue() != 0) { throw IllegalStateException(text.trim().ifEmpty { "git ${args.joinToString(" ")} failed." }) } return text } private fun requestCommitMessage( payload: DiffPayload, indicator: ProgressIndicator, additionalRequirements: String?, ): String { val config = loadActiveSnowConfig() val model = config.basicModel.trim() if (model.isEmpty()) { throw IllegalStateException("Basic model is not configured.") } val prompt = buildPrompt(payload, additionalRequirements) return withApiRetry(indicator) { when (config.requestMethod.ifBlank { "chat" }) { "responses" -> requestResponsesCommitMessage(config, model, prompt, indicator) "gemini" -> requestGeminiCommitMessage(config, model, prompt, indicator) "anthropic" -> requestAnthropicCommitMessage(config, model, prompt, indicator) else -> requestChatCommitMessage(config, model, prompt, indicator) } } } private fun requestChatCommitMessage( config: SnowApiConfig, model: String, prompt: CommitPrompt, indicator: ProgressIndicator, ): String { val url = "${requireBaseUrl(config)}/chat/completions" val body = JSONObject() .put("model", model) .put( "messages", JSONArray() .put(JSONObject().put("role", "system").put("content", prompt.system)) .put(JSONObject().put("role", "user").put("content", prompt.user)), ) .put("stream", false) .put("temperature", 0.2) val data = postJson(url, config, null, body, indicator, "OpenAI Chat API") return data.optJSONArray("choices") ?.optJSONObject(0) ?.optJSONObject("message") ?.optString("content") .orEmpty() } private fun requestResponsesCommitMessage( config: SnowApiConfig, model: String, prompt: CommitPrompt, indicator: ProgressIndicator, ): String { val url = "${requireBaseUrl(config)}/responses" val body = JSONObject() .put("model", model) .put("instructions", prompt.system) .put("input", prompt.user) .put("store", false) val data = postJson(url, config, null, body, indicator, "OpenAI Responses API") return extractResponsesText(data) } private fun requestGeminiCommitMessage( config: SnowApiConfig, model: String, prompt: CommitPrompt, indicator: ProgressIndicator, ): String { val baseUrl = if (config.baseUrl.isNotBlank() && config.baseUrl != "https://api.openai.com/v1") { trimTrailingSlash(config.baseUrl) } else { "https://generativelanguage.googleapis.com/v1beta" } val modelName = if (model.startsWith("models/")) model else "models/$model" val body = JSONObject() .put( "contents", JSONArray().put( JSONObject() .put("role", "user") .put("parts", JSONArray().put(JSONObject().put("text", "${prompt.system}\n\n${prompt.user}"))), ), ) .put( "generationConfig", JSONObject() .put("temperature", 0.2), ) val data = postJson("$baseUrl/$modelName:generateContent", config, "gemini", body, indicator, "Gemini API") return data.optJSONArray("candidates") ?.optJSONObject(0) ?.optJSONObject("content") ?.optJSONArray("parts") ?.joinTextParts() .orEmpty() } private fun requestAnthropicCommitMessage( config: SnowApiConfig, model: String, prompt: CommitPrompt, indicator: ProgressIndicator, ): String { val baseUrl = if (config.baseUrl.isNotBlank() && config.baseUrl != "https://api.openai.com/v1") { trimTrailingSlash(config.baseUrl) } else { "https://api.anthropic.com/v1" } val body = JSONObject() .put("model", model) .put("max_tokens", 4_096) .put("temperature", 0.2) .put("system", prompt.system) .put("messages", JSONArray().put(JSONObject().put("role", "user").put("content", prompt.user))) val data = postJson("$baseUrl/messages", config, "anthropic", body, indicator, "Anthropic API") return data.optJSONArray("content")?.joinTextParts().orEmpty() } private fun postJson( url: String, config: SnowApiConfig, provider: String?, body: JSONObject, indicator: ProgressIndicator, apiName: String, ): JSONObject { indicator.checkCanceled() val requestBuilder = HttpRequest.newBuilder(URI.create(url)) .timeout(Duration.ofSeconds(config.streamIdleTimeoutSec?.coerceAtLeast(1) ?: 120)) .POST(HttpRequest.BodyPublishers.ofString(body.toString())) buildHeaders(config, provider).forEach { (key, value) -> if (isRestrictedHeader(key)) { logger.warn("Skip restricted header: $key") return@forEach } requestBuilder.header(key, value) } val response = httpClient.send(requestBuilder.build(), HttpResponse.BodyHandlers.ofString()) indicator.checkCanceled() if (response.statusCode() !in 200..299) { throw ApiRequestException( "$apiName error: ${response.statusCode()} - ${response.body()}", response.statusCode(), response.body(), ) } return JSONObject(response.body()) } private fun buildHeaders(config: SnowApiConfig, provider: String?): Map { val headers = linkedMapOf() headers["Content-Type"] = "application/json" headers.putAll(loadCustomHeaders(config)) if (config.apiKey.isNotBlank()) { headers["Authorization"] = "Bearer ${config.apiKey}" } if (provider == "gemini" && config.apiKey.isNotBlank()) { headers["x-goog-api-key"] = config.apiKey } if (provider == "anthropic") { if (config.apiKey.isNotBlank()) { headers["x-api-key"] = config.apiKey } if (headers.keys.none { it.equals("anthropic-version", ignoreCase = true) }) { headers["anthropic-version"] = "2023-06-01" } } return headers } private fun isRestrictedHeader(name: String): Boolean { val lower = name.lowercase() return lower in RESTRICTED_HEADERS } private fun loadActiveSnowConfig(): SnowApiConfig { val configDir = File(System.getProperty("user.home"), ".snow") val activeProfile = getActiveProfileName(configDir) val profilePath = File(File(configDir, "profiles"), "$activeProfile.json") val appConfig = readJsonFile(profilePath) ?: readJsonFile(File(configDir, "config.json")) val snowConfig = appConfig?.optJSONObject("snowcfg") ?: throw IllegalStateException("Snow configuration not found.") return SnowApiConfig( baseUrl = snowConfig.optString("baseUrl", "").trim(), apiKey = snowConfig.optString("apiKey", ""), requestMethod = snowConfig.optString("requestMethod", "chat"), basicModel = snowConfig.optString("basicModel", "").trim(), streamIdleTimeoutSec = if (snowConfig.has("streamIdleTimeoutSec")) snowConfig.optLong("streamIdleTimeoutSec") else null, customHeadersSchemeId = if (snowConfig.has("customHeadersSchemeId") && !snowConfig.isNull("customHeadersSchemeId")) { snowConfig.optString("customHeadersSchemeId") } else { null }, ) } private fun getActiveProfileName(configDir: File): String { val activeProfile = readJsonFile(File(configDir, "active-profile.json"))?.optString("activeProfile", "") if (!activeProfile.isNullOrBlank()) { return activeProfile } val legacyActiveProfile = File(configDir, "active-profile.txt") if (legacyActiveProfile.exists()) { return legacyActiveProfile.readText().trim().ifEmpty { "default" } } return "default" } private fun readJsonFile(file: File): JSONObject? { if (!file.exists()) { return null } return try { JSONObject(file.readText()) } catch (_: Exception) { null } } private fun loadCustomHeaders(config: SnowApiConfig): Map { val customHeadersConfig = readJsonFile(File(File(System.getProperty("user.home"), ".snow"), "custom-headers.json")) ?: return emptyMap() val schemeId = config.customHeadersSchemeId ?: customHeadersConfig.optString("active", "") if (schemeId.isBlank()) { return emptyMap() } val schemes = customHeadersConfig.optJSONArray("schemes") ?: return emptyMap() for (index in 0 until schemes.length()) { val scheme = schemes.optJSONObject(index) ?: continue if (scheme.optString("id", "") != schemeId) { continue } val headersObject = scheme.optJSONObject("headers") ?: return emptyMap() val headers = linkedMapOf() val keys = headersObject.keys() while (keys.hasNext()) { val key = keys.next() headers[key] = headersObject.optString(key, "") } return headers } return emptyMap() } private fun buildPrompt(payload: DiffPayload, additionalRequirements: String?): CommitPrompt { val sourceLabel = if (payload.source == DiffSource.STAGED) "staged" else "working tree" val truncatedNotice = if (payload.truncated) "\n\nNote: The diff was truncated because it is large." else "" val requirementNotice = additionalRequirements?.trim() ?.takeIf { it.isNotEmpty() } ?.let { "\n\nAdditional requirements from the user:\n$it" } .orEmpty() return CommitPrompt( system = listOf( "You generate clear Git commit messages.", "Return only the final commit message, with no markdown, no quotes, and no explanation.", "Use an appropriate level of detail for the changes; include a body when it helps explain important context.", "Prefer Conventional Commit style when it fits, for example: feat: add login validation.", ).joinToString(" "), user = "Generate one commit message for the $sourceLabel changes below.$truncatedNotice$requirementNotice\n\n${payload.diff}", ) } private fun normalizeCommitMessage(message: String): String { val normalized = message .trim() .replace(Regex("^```(?:[\\w-]+)?\\s*"), "") .replace(Regex("```$"), "") .trim() .replace(Regex("^[\\\"']|[\\\"']$"), "") .replace(Regex("^commit message:\\s*", RegexOption.IGNORE_CASE), "") .trim() if (normalized.isEmpty()) { throw IllegalStateException("The model returned an empty commit message.") } return normalized } private fun extractResponsesText(data: JSONObject): String { val outputText = data.optString("output_text", "") if (outputText.isNotEmpty()) { return outputText } val output = data.optJSONArray("output") ?: return "" val result = StringBuilder() for (index in 0 until output.length()) { val item = output.optJSONObject(index) ?: continue val content = item.optJSONArray("content") ?: continue result.append(content.joinTextParts()) } return result.toString() } private fun JSONArray.joinTextParts(): String { val result = StringBuilder() for (index in 0 until length()) { val part = optJSONObject(index) ?: continue if (part.has("text")) { result.append(part.optString("text", "")) } } return result.toString() } private fun withApiRetry(indicator: ProgressIndicator, request: () -> T): T { var lastError: Throwable? = null for (attempt in 0..API_MAX_RETRIES) { indicator.checkCanceled() try { return request() } catch (error: ProcessCanceledException) { throw error } catch (error: Throwable) { lastError = error if (!isRetriableApiError(error) || attempt >= API_MAX_RETRIES) { throw error } delay(API_RETRY_BASE_DELAY_MS * (1L shl attempt), indicator) } } throw lastError ?: IllegalStateException("Commit message request failed.") } private fun isRetriableApiError(error: Throwable): Boolean { if (error is ApiRequestException) { return error.status == 429 || error.status >= 500 } val message = error.message?.lowercase().orEmpty() return listOf( "network", "econnrefused", "econnreset", "etimedout", "timeout", "rate limit", "too many requests", "service unavailable", "temporarily unavailable", "bad gateway", "gateway timeout", "internal server error", ).any { message.contains(it) } } private fun delay(ms: Long, indicator: ProgressIndicator) { var remaining = ms while (remaining > 0) { indicator.checkCanceled() val step = min(remaining, 100L) Thread.sleep(step) remaining -= step } } private fun requireBaseUrl(config: SnowApiConfig): String { if (config.baseUrl.isBlank()) { throw IllegalStateException("Base URL is not configured.") } return trimTrailingSlash(config.baseUrl) } private fun trimTrailingSlash(value: String): String = value.replace(Regex("/+$"), "") private fun notify(message: String, type: NotificationType) { ApplicationManager.getApplication().invokeLater { NotificationGroupManager.getInstance() .getNotificationGroup("Snow CLI") .createNotification(message, type) .notify(project) } } } private data class DiffPayload( val diff: String, val source: DiffSource, val truncated: Boolean, ) private enum class DiffSource { STAGED, WORKING_TREE, } private data class CommitPrompt( val system: String, val user: String, ) private data class SnowApiConfig( val baseUrl: String, val apiKey: String, val requestMethod: String, val basicModel: String, val streamIdleTimeoutSec: Long?, val customHeadersSchemeId: String?, ) private class ApiRequestException( message: String, val status: Int, val responseText: String, ) : RuntimeException(message) ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/toolwindow/SnowToolWindowFactory.kt ================================================ package com.snow.plugin.toolwindow import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.project.DumbAware import com.intellij.openapi.project.Project import com.intellij.openapi.wm.ToolWindow import com.intellij.openapi.wm.ToolWindowFactory import com.intellij.openapi.wm.ex.ToolWindowManagerListener import com.intellij.ui.components.JBLabel import com.intellij.ui.content.ContentFactory import com.snow.plugin.SnowWebSocketManager import com.snow.plugin.util.TerminalCompat import java.awt.BorderLayout import javax.swing.JPanel class SnowToolWindowFactory : ToolWindowFactory, DumbAware { companion object { private val isLaunching = mutableMapOf() } override fun createToolWindowContent(project: Project, toolWindow: ToolWindow) { val contentPanel = JPanel(BorderLayout()) val label = JBLabel("Snow CLI will launch when you open this window", javax.swing.SwingConstants.CENTER) contentPanel.add(label, BorderLayout.CENTER) val contentFactory = ContentFactory.getInstance() val content = contentFactory.createContent(contentPanel, "", false) toolWindow.contentManager.addContent(content) val projectKey = project.basePath ?: project.name val connection = project.messageBus.connect() connection.subscribe(ToolWindowManagerListener.TOPIC, object : ToolWindowManagerListener { override fun stateChanged(toolWindowManager: com.intellij.openapi.wm.ToolWindowManager) { if (toolWindow.isVisible) { synchronized(isLaunching) { if (isLaunching[projectKey] != true) { isLaunching[projectKey] = true launchSnowCLI(project, toolWindow, projectKey) } } } } }) } private fun launchSnowCLI(project: Project, toolWindow: ToolWindow, projectKey: String) { ApplicationManager.getApplication().invokeLater { try { TerminalCompat.openTerminalWithCommand(project, project.basePath, "Snow CLI", "snow") ApplicationManager.getApplication().invokeLater { toolWindow.hide(null) synchronized(isLaunching) { isLaunching[projectKey] = false } } } catch (_: Exception) { synchronized(isLaunching) { isLaunching[projectKey] = false } } } val wsManager = SnowWebSocketManager.instance ApplicationManager.getApplication().executeOnPooledThread { Thread.sleep(500) wsManager.connect() } } } ================================================ FILE: JetBrains/src/main/kotlin/com/snow/plugin/util/TerminalCompat.kt ================================================ package com.snow.plugin.util import com.intellij.openapi.application.ApplicationManager import com.intellij.openapi.project.Project import com.intellij.openapi.wm.ToolWindowManager /** * Compatibility layer for terminal API across IntelliJ versions. * Uses Reworked Terminal API (2025.3+) when available, falls back to classic API via reflection. */ object TerminalCompat { @Volatile private var lastTerminalRef: Any? = null fun openTerminalWithCommand(project: Project, workingDirectory: String?, tabName: String, command: String) { if (!tryReworkedApi(project, workingDirectory, tabName, command)) { fallbackClassicApi(project, workingDirectory, tabName, command) } } /** * Send text to an existing Snow CLI terminal (without pressing Enter). * Uses saved terminal reference first, falls back to component tree search. */ fun sendTextToNamedTerminal(project: Project, tabName: String, text: String): Boolean { // Strategy 1: use the saved reference from openTerminalWithCommand lastTerminalRef?.let { ref -> if (trySendTextViaRef(ref, text)) { activateTerminalTab(project, tabName) return true } } // Strategy 2: search component tree in the matching terminal tab val toolWindow = ToolWindowManager.getInstance(project).getToolWindow("Terminal") ?: return false val content = toolWindow.contentManager.contents.firstOrNull { it.displayName == tabName || it.displayName.contains("Snow", ignoreCase = true) } ?: return false toolWindow.contentManager.setSelectedContent(content) toolWindow.activate(null, false, false) return sendTextToComponentTree(content.component, text) } private fun trySendTextViaRef(ref: Any, text: String): Boolean { // Reworked API: TerminalView.sendText(String) try { ref.javaClass.getMethod("sendText", String::class.java).invoke(ref, text) return true } catch (_: Exception) {} // Classic API: widget.getTtyConnector().write(String) try { val connector = ref.javaClass.getMethod("getTtyConnector").invoke(ref) if (connector != null) { connector.javaClass.getMethod("write", String::class.java).invoke(connector, text) return true } } catch (_: Exception) {} return false } private fun activateTerminalTab(project: Project, tabName: String) { val toolWindow = ToolWindowManager.getInstance(project).getToolWindow("Terminal") ?: return val content = toolWindow.contentManager.contents.firstOrNull { it.displayName == tabName || it.displayName.contains("Snow", ignoreCase = true) } if (content != null) { toolWindow.contentManager.setSelectedContent(content) } toolWindow.activate(null, false, false) } private fun sendTextToComponentTree(root: java.awt.Component, text: String): Boolean { if (trySendTextViaComponent(root, text)) return true if (root is java.awt.Container) { for (i in 0 until root.componentCount) { if (sendTextToComponentTree(root.getComponent(i), text)) return true } } return false } private fun trySendTextViaComponent(component: Any, text: String): Boolean { val className = component.javaClass.name if (className.startsWith("javax.swing.") || className.startsWith("java.awt.")) return false try { val connector = component.javaClass.getMethod("getTtyConnector").invoke(component) if (connector != null) { connector.javaClass.getMethod("write", String::class.java).invoke(connector, text) return true } } catch (_: Exception) {} try { component.javaClass.getMethod("sendText", String::class.java).invoke(component, text) return true } catch (_: Exception) {} return false } private fun tryReworkedApi( project: Project, workingDirectory: String?, tabName: String, command: String ): Boolean { return try { val mgrClass = Class.forName( "com.intellij.terminal.frontend.toolwindow.TerminalToolWindowTabsManager" ) val mgr = mgrClass.getMethod("getInstance", Project::class.java).invoke(null, project) val bClass = Class.forName( "com.intellij.terminal.frontend.toolwindow.TerminalToolWindowTabBuilder" ) var b: Any = mgrClass.getMethod("createTabBuilder").invoke(mgr)!! b = bClass.getMethod("workingDirectory", String::class.java).invoke(b, workingDirectory)!! b = bClass.getMethod("tabName", String::class.java).invoke(b, tabName)!! b = bClass.getMethod("requestFocus", java.lang.Boolean.TYPE).invoke(b, true)!! b = bClass.getMethod("deferSessionStartUntilUiShown", java.lang.Boolean.TYPE).invoke(b, true)!! val tab = bClass.getMethod("createTab").invoke(b)!! val tClass = Class.forName("com.intellij.terminal.frontend.toolwindow.TerminalToolWindowTab") val view = tClass.getMethod("getView").invoke(tab)!! val vClass = Class.forName("com.intellij.terminal.frontend.view.TerminalView") lastTerminalRef = view scheduleCommand { vClass.getMethod("sendText", String::class.java).invoke(view, "$command\n") } true } catch (_: Exception) { false } } private fun fallbackClassicApi( project: Project, workingDirectory: String?, tabName: String, command: String ) { try { val mgrClass = Class.forName("org.jetbrains.plugins.terminal.TerminalToolWindowManager") val mgr = mgrClass.getMethod("getInstance", Project::class.java).invoke(null, project) val widget = mgrClass.getMethod( "createShellWidget", String::class.java, String::class.java, java.lang.Boolean.TYPE, java.lang.Boolean.TYPE ).invoke(mgr, workingDirectory, tabName, true, true)!! lastTerminalRef = widget scheduleCommand { widget.javaClass.getMethod("sendCommandToExecute", String::class.java) .invoke(widget, command) } } catch (_: Exception) { } } private fun scheduleCommand(action: () -> Unit) { ApplicationManager.getApplication().executeOnPooledThread { try { Thread.sleep(1000) ApplicationManager.getApplication().invokeLater { try { action() } catch (_: Exception) { } } } catch (_: Exception) { } } } } ================================================ FILE: JetBrains/src/main/kotlin/icons/SnowPluginIcons.kt ================================================ package icons import com.intellij.icons.AllIcons import com.intellij.openapi.util.IconLoader import java.awt.Component import java.awt.Graphics import java.awt.Graphics2D import java.awt.RenderingHints import javax.swing.Icon import kotlin.math.min /** * Icon loader for Snow CLI plugin * Must be in 'icons' package and class name must end with 'Icons' */ object SnowPluginIcons { @JvmField val SnowAction: Icon = IconLoader.getIcon("/icons/snow.png", SnowPluginIcons::class.java) @JvmField val SnowToolbarAction: Icon = BoundedSquareIcon(SnowAction, 16) @JvmField val SnowStopToolbarAction: Icon = BoundedSquareIcon(AllIcons.Actions.Suspend, 16) } private class BoundedSquareIcon( private val source: Icon, private val size: Int, ) : Icon { override fun getIconWidth(): Int = size override fun getIconHeight(): Int = size override fun paintIcon(component: Component?, graphics: Graphics, x: Int, y: Int) { if (source.iconWidth <= 0 || source.iconHeight <= 0) { source.paintIcon(component, graphics, x, y) return } val graphics2d = graphics.create() as Graphics2D try { graphics2d.setRenderingHint( RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BICUBIC, ) graphics2d.setRenderingHint( RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY, ) val scale = min( size.toDouble() / source.iconWidth.toDouble(), size.toDouble() / source.iconHeight.toDouble(), ) val scaledWidth = source.iconWidth * scale val scaledHeight = source.iconHeight * scale graphics2d.translate( x + (size - scaledWidth) / 2.0, y + (size - scaledHeight) / 2.0, ) graphics2d.scale(scale, scale) source.paintIcon(component, graphics2d, 0, 0) } finally { graphics2d.dispose() } } } ================================================ FILE: JetBrains/src/main/resources/META-INF/plugin.xml ================================================ com.snow.plugin Snow CLI Snow AI
Features:
  • WebSocket-based integration with Snow CLI
  • Real-time editor context sharing
  • Code diagnostics integration
  • Go to definition support
  • Find references support
  • Document symbols extraction
  • Automatic reconnection with exponential backoff
]]> com.intellij.modules.platform org.jetbrains.plugins.terminal ================================================ FILE: LICENSE ================================================ Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. ================================================ FILE: README.md ================================================
Snow AI CLI Logo # snow-ai [![npm version](https://img.shields.io/npm/v/snow-ai.svg)](https://www.npmjs.com/package/snow-ai) [![npm downloads](https://img.shields.io/npm/dm/snow-ai.svg)](https://www.npmjs.com/package/snow-ai) [![license](https://img.shields.io/npm/l/snow-ai.svg)](https://github.com/MayDay-wpf/snow-cli/blob/main/LICENSE) [![node](https://img.shields.io/node/v/snow-ai.svg)](https://nodejs.org/) Snow CLI - Agentic coding in your terminal | Product Hunt **English** | [中文](README_zh.md) **QQ Group**: 910298558 **Telegram**: [https://t.me/snow_cli](https://t.me/snow_cli) **AI Community**: [https://linux.do](https://linux.do) _Agentic coding in your terminal_
## Thanks Developer ![alt text](docs/images/image.png) ![alt text](docs/images/image2.png)

Recommend using fonts: JetBrains Maple Mono NF

Recommended Terminal Combination for Windows Users

- **PowerShell 7+**: Modern cross-platform PowerShell, offering stronger features and better compatibility - GitHub: https://github.com/PowerShell/PowerShell - **Windows Terminal**: Modern terminal application, supporting multi-tab, split-screen, and GPU accelerated rendering - GitHub: https://github.com/microsoft/terminal **Installation**: ```bash # Install using winget (built-in for Windows 10/11) winget install Microsoft.PowerShell winget install Microsoft.WindowsTerminal # Or install using the Microsoft Store ``` ## Documentation - [Installation Guide](docs/usage/en/01.Installation%20Guide.md) - System requirements, installation (update, uninstall) steps, IDE extension installation - [First Time Configuration](docs/usage/en/02.First%20Time%20Configuration.md) - API configuration, model selection, basic settings - [Startup Parameters Guide](docs/usage/en/19.Startup%20Parameters%20Guide.md) - Command-line parameters explained, quick start modes, headless mode, async tasks, developer mode ### Advanced Configuration - [Proxy and Browser Settings](docs/usage/en/03.Proxy%20and%20Browser%20Settings.md) - Network proxy configuration, browser usage settings - [Codebase Setup](docs/usage/en/04.Codebase%20Setup.md) - Codebase integration, search configuration - [Sub-Agent Configuration](docs/usage/en/05.Sub-Agent%20Configuration.md) - Sub-agent management, custom sub-agent configuration - [Sensitive Commands Configuration](docs/usage/en/06.Sensitive%20Commands%20Configuration.md) - Sensitive command protection, custom command rules - [Hooks Configuration](docs/usage/en/07.Hooks%20Configuration.md) - Workflow automation, hook types explanation, practical configuration examples - [Theme Settings](docs/usage/en/08.Theme%20Settings.md) - Interface theme configuration, custom color schemes, simplified mode - [Third-Party Relay Configuration](docs/usage/en/16.Third-Party%20Relay%20Configuration.md) - Claude Code relay, Codex relay, custom headers configuration ### Feature Guide - [Command Panel Guide](docs/usage/en/09.Command%20Panel%20Guide.md) - Detailed description of all available commands, usage tips, shortcut key reference - [Command Injection Mode](docs/usage/en/10.Command%20Injection%20Mode.md) - Execute commands directly in messages, syntax explanation, security mechanisms, use cases - [Vulnerability Hunting Mode](docs/usage/en/11.Vulnerability%20Hunting%20Mode.md) - Professional security analysis, vulnerability detection, verification scripts, detailed reports - [Headless Mode](docs/usage/en/12.Headless%20Mode.md) - Command line quick conversations, session management, script integration, third-party tool integration - [Keyboard Shortcuts Guide](docs/usage/en/13.Keyboard%20Shortcuts%20Guide.md) - All keyboard shortcuts, editing operations, navigation control, rollback functionality - [MCP Configuration](docs/usage/en/14.MCP%20Configuration.md) - MCP service management, configure external services, enable/disable services, troubleshooting - [Async Task Management](docs/usage/en/15.Async%20Task%20Management.md) - Background task creation, task management interface, sensitive command approval, task to session conversion - [Skills Command Detailed Guide](docs/usage/en/18.Skills%20Command%20Detailed%20Guide.md) - Skill creation, usage methods, Claude Code Skills compatibility, tool restrictions - [LSP Configuration and Usage](docs/usage/en/17.LSP%20Configuration.md) - LSP config file, language server installation, ACE tool usage (definition/outline) - [SSE Service Mode](docs/usage/en/20.SSE%20Service%20Mode.md) - SSE server startup, API endpoints explanation, tool confirmation flow, permission configuration, YOLO mode, client integration examples - [Custom StatusLine Guide](docs/usage/en/21.Custom%20StatusLine%20Guide.md) - User-level StatusLine plugins, hook structure, override behavior, bilingual examples - [Team Mode Guide](docs/usage/en/22.Team%20Mode%20Guide.md) - Multi-agent collaboration, parallel task execution, team management - [Custom Search Engine Guide](docs/usage/en/23.Custom%20Search%20Engine%20Guide.md) - User-level search engine plugins, engine contract, enable flag, minimal template ### Recommended ROLE.md - [Recommended ROLE.md](docs/role/en/01.Snow%20CLI%20Plan%20Every%20Step.md) - Recommended behavior guidelines, work mode, and quality standards for the Snow CLI terminal programming assistant - Bilingual documentation: English (primary) / [Chinese](docs/role/zh/01.Snow%20CLI%20一步一规划.md) - Maintenance rule: Keep Chinese and English structures aligned; tool names remain unchanged --- ## Development Guide ### Prerequisites - **Node.js >= 18.x** (Requires ES2020 features support) - npm >= 8.3.0 Check your Node.js version: ```bash node --version ``` If your version is below 18.x, please upgrade first: ```bash # Using nvm (recommended) nvm install 18 nvm use 18 # Or download from official website # https://nodejs.org/ ``` ### Build from Source ```bash git clone https://github.com/MayDay-wpf/snow-cli.git cd snow-cli npm install npm run link # builds and globally links snow # to remove the link later: npm run unlink ``` ### IDE Extension Development #### VSCode Extension - Extension source located in `VSIX/` directory - Download release: [mufasa.snow-cli](https://marketplace.visualstudio.com/items?itemName=mufasa.snow-cli) #### JetBrains Plugin - Plugin source located in `Jetbrains/` directory - Download release: [JetBrains plugin](https://plugins.jetbrains.com/plugin/28715-snow-cli/edit) ### Project Structure ``` source/ # Source code ├── agents/ # AI agents implementation ├── api/ # LLM API adapters ├── hooks/ # React hooks for conversation ├── i18n/ # Internationalization ├── mcp/ # Model Context Protocol ├── prompt/ # System prompt templates ├── types/ # TypeScript type definitions ├── ui/ # UI components (Ink) └── utils/ # Utility functions bundle/ # Build output (single-file executable) dist/ # TypeScript compilation output docs/ # Documentation JetBrains/ # JetBrains plugin source scripts/ # Build and utility scripts VSIX/ # VSCode extension source ``` ### User Configuration Directory After running snow, `.snow/` directory is created in your home folder: ``` ~/.snow/ # User configuration directory ├── log/ # Runtime logs (local, can be deleted) ├── profiles/ # Configuration profiles ├── sessions/ # Conversation history ├── tasks/ # Async tasks ├── hooks/ # Workflow hooks ├── config.json # API configuration ├── mcp-config.json # MCP configuration └── ... # Other config files ``` ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=MayDay-wpf/snow-cli&type=Date)](https://star-history.com/#MayDay-wpf/snow-cli&Date) ================================================ FILE: README_zh.md ================================================
Snow AI CLI Logo # snow-ai [![npm version](https://img.shields.io/npm/v/snow-ai.svg)](https://www.npmjs.com/package/snow-ai) [![npm downloads](https://img.shields.io/npm/dm/snow-ai.svg)](https://www.npmjs.com/package/snow-ai) [![license](https://img.shields.io/npm/l/snow-ai.svg)](https://github.com/MayDay-wpf/snow-cli/blob/main/LICENSE) [![node](https://img.shields.io/node/v/snow-ai.svg)](https://nodejs.org/) Snow CLI - Agentic coding in your terminal | Product Hunt [English](README.md) | **中文** **QQ 群**: 910298558 **Telegram**: [https://t.me/snow_cli](https://t.me/snow_cli) **AI 社区**: [https://linux.do](https://linux.do) _在终端中进行 Agentic 编程_
## 感谢开发者 ![alt text](docs/images/image_zh.png) ![alt text](docs/images/image_zh2.png)

推荐使用字体：JetBrains Maple Mono NF

Windows 用户推荐终端组合

- **PowerShell 7+**: 现代化的跨平台 PowerShell，提供更强的功能和更好的兼容性 - GitHub: https://github.com/PowerShell/PowerShell - **Windows Terminal**: 现代化的终端应用程序，支持多标签、分屏、GPU 加速渲染 - GitHub: https://github.com/microsoft/terminal **安装方式**: ```bash # 使用 winget 安装 (Windows 10/11 自带) winget install Microsoft.PowerShell winget install Microsoft.WindowsTerminal # 或使用 Microsoft Store 安装 ``` ## 文档目录 - [安装指南](docs/usage/zh/01.安装指南.md) - 系统要求、安装(更新、卸载)步骤、IDE 扩展安装 - [首次配置](docs/usage/zh/02.首次配置.md) - API 配置、模型选择、基础设置 - [启动参数说明](docs/usage/zh/19.启动参数说明.md) - 命令行参数详解、快速启动模式、无头模式、异步任务、开发者模式 ### 高级配置 - [代理和浏览器设置](docs/usage/zh/03.代理和浏览器设置.md) - 网络代理配置、浏览器使用设置 - [代码库设置](docs/usage/zh/04.代码库设置.md) - 代码库集成、搜索配置 - [子代理设置](docs/usage/zh/05.子代理设置.md) - 子代理管理、自定义子代理配置 - [敏感命令配置](docs/usage/zh/06.敏感命令配置.md) - 敏感命令保护、自定义命令规则 - [Hooks 配置](docs/usage/zh/07.Hooks配置.md) - 工作流程自动化、Hook 类型说明、实用配置示例 - [主题设置](docs/usage/zh/08.主题设置.md) - 界面主题配置、自定义配色、简洁模式 - [第三方中转配置](docs/usage/zh/16.第三方中转配置.md) - Claude Code 中转、Codex 中转、自定义请求头配置 ### 功能指南 - [指令面板说明](docs/usage/zh/09.指令面板说明.md) - 所有可用指令的详细说明、使用技巧、快捷键参考 - [命令注入模式](docs/usage/zh/10.命令注入模式.md) - 消息中直接执行命令、语法说明、安全机制、使用场景 - [漏洞猎人模式](docs/usage/zh/11.漏洞猎人模式.md) - 专业安全分析、漏洞检测、验证脚本、详细报告 - [无头模式](docs/usage/zh/12.无头模式.md) - 命令行快速对话、会话管理、脚本集成、第三方工具集成 - [快捷键指南](docs/usage/zh/13.快捷键指南.md) - 所有快捷键说明、编辑操作、导航控制、回滚功能 - [MCP 配置](docs/usage/zh/14.MCP配置.md) - MCP 服务管理、配置外部服务、启用/禁用服务、故障排除 - [异步任务管理](docs/usage/zh/15.异步任务管理.md) - 后台任务创建、任务管理界面、敏感命令审批、任务转会话 - [Skills 指令详细说明](docs/usage/zh/18.Skills指令详细说明.md) - 技能创建、使用方法、Claude Code Skills 兼容性、工具限制 - [LSP 配置与用法](docs/usage/zh/17.LSP配置.md) - LSP 配置文件、语言服务器安装、ACE 工具用法(跳转/大纲) - [SSE 服务模式](docs/usage/zh/20.SSE服务模式.md) - SSE 服务器启动、API 端点说明、工具确认流程、权限配置、YOLO 模式、客户端集成示例 - [自定义 StatusLine 指南](docs/usage/zh/21.自定义StatusLine指南.md) - 用户级状态栏插件、hook 结构、覆盖机制、中英文示例 - [Team 模式指南](docs/usage/zh/22.Team模式指南.md) - 多智能体协作、并行任务执行、团队管理 - [自定义搜索引擎指南](docs/usage/zh/23.自定义搜索引擎指南.md) - 用户级搜索引擎插件、引擎合约、enable 开关、最小模板示例 ### 推荐使用的 ROLE.md - [推荐使用的 ROLE.md](docs/role/zh/01.Snow%20CLI%20一步一规划.md) - Snow CLI 终端编程助手推荐使用的行为准则、工作模式与质量标准 - 双语文档：中文（主版本）/[英文](docs/role/en/01.Snow%20CLI%20Plan%20Every%20Step.md) - 维护规则：保持中英文结构对齐，工具名称保持不变 --- ## 开发指南 ### 环境要求 - **Node.js >= 18.x** (需要 ES2020 特性支持) - npm >= 8.3.0 检查你的 Node.js 版本： ```bash node --version ``` 如果版本低于 18.x，请先升级： ```bash # 使用 nvm (推荐) nvm install 18 nvm use 18 # 或从官网下载 # https://nodejs.org/ ``` ### 源码构建 ```bash git clone https://github.com/MayDay-wpf/snow-cli.git cd snow-cli npm install npm run link # 构建并全局链接 snow # 之后删除链接: npm run unlink ``` ### IDE 扩展开发 #### VSCode 扩展 - 扩展源码位于 `VSIX/` 目录 - 下载发布版: [mufasa.snow-cli](https://marketplace.visualstudio.com/items?itemName=mufasa.snow-cli) #### JetBrains 插件 - 插件源码位于 `Jetbrains/` 目录 - 下载发布版: [JetBrains 插件](https://plugins.jetbrains.com/plugin/28715-snow-cli/edit) ### 项目结构 ``` source/ # 源代码 ├── agents/ # AI 代理实现 ├── api/ # LLM API 适配器 ├── hooks/ # 对话 React Hooks ├── i18n/ # 国际化 ├── mcp/ # Model Context Protocol ├── prompt/ # 系统提示词模板 ├── types/ # TypeScript 类型定义 ├── ui/ # UI 组件 (Ink) └── utils/ # 工具函数 bundle/ # 构建输出（单文件可执行） dist/ # TypeScript 编译输出 docs/ # 文档 JetBrains/ # JetBrains 插件源码 scripts/ # 构建和工具脚本 VSIX/ # VSCode 扩展源码 ``` ### 用户配置目录 运行 snow 后，会在主目录创建 `.snow/` 文件夹： ``` ~/.snow/ # 用户配置目录 ├── log/ # 运行日志(本地，可删除) ├── profiles/ # 配置文件 ├── sessions/ # 对话记录 ├── tasks/ # 异步任务 ├── hooks/ # 工作流钩子 ├── config.json # API 配置 ├── mcp-config.json # MCP 配置 └── ... # 其他配置文件 ``` ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=MayDay-wpf/snow-cli&type=Date)](https://star-history.com/#MayDay-wpf/snow-cli&Date) ================================================ FILE: VSIX/.vscodeignore ================================================ .vscode/** .vscode-test/** .tmp-vsix-check/** src/** out/** node_modules/** !node_modules/node-pty/** !node_modules/node-pty/build/Release/*.node !node_modules/node-pty/build/Release/*.dll !node_modules/@xterm/** !node_modules/@xterm/xterm/** !node_modules/@xterm/xterm/css/** !node_modules/@xterm/xterm/css/xterm.css !node_modules/@xterm/xterm/lib/** !node_modules/@xterm/xterm/lib/xterm.js !node_modules/@xterm/addon-fit/** !node_modules/@xterm/addon-fit/lib/** !node_modules/@xterm/addon-fit/lib/addon-fit.js !node_modules/ws/** !node_modules/ws/lib/** **/*.ts !**/*.d.ts **/*.map **/tsconfig.json **/.eslintrc.json **/webpack.config.js **/*.md !README.md **/test/** **/tests/** **/.git/** .gitignore .yarnrc vsc-extension-quickstart.md ================================================ FILE: VSIX/LICENSE ================================================ MIT License Copyright (c) 2025 Snow CLI Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: VSIX/README.md ================================================ # Snow CLI Extension with ACE Code Search This extension provides seamless integration between VSCode and Snow AI CLI, featuring the powerful **ACE (Agentic Computer Environment) Code Search** system for intelligent code navigation. ## Features ### 🎯 Quick Access - **One-click Terminal** - Button in editor toolbar to instantly launch Snow CLI - **Auto-connection** - Automatic WebSocket connection to Snow CLI server - **Real-time Sync** - Live editor context synchronization ### 🔍 ACE Code Search Integration - **Go to Definition** - Leverage VSCode's language servers for precise symbol navigation - **Find References** - Discover all symbol usages across your codebase - **Document Symbols** - Get complete file outline with all functions, classes, and variables - **Real-time Diagnostics** - Instant error and warning detection ### 🚀 Performance - **Exponential Backoff** - Smart reconnection strategy - **Context Caching** - Maintains state even when editor loses focus - **Low Latency** - WebSocket communication for instant updates ## Requirements Install Snow CLI globally: ```bash npm install -g snow-ai ``` ## Usage ### Basic Usage 1. Open any file in VSCode 2. Click the **Snow icon** button in the editor toolbar (top right) 3. A terminal opens with Snow CLI running 4. The extension automatically connects via WebSocket #### Interface Preview **English Interface:** ![English Interface](https://raw.githubusercontent.com/MayDay-wpf/snow-cli/main/VSIX/en.png) **Chinese Interface:** ![Chinese Interface](https://raw.githubusercontent.com/MayDay-wpf/snow-cli/main/VSIX/zh.png) ### ACE Code Search Features The extension enhances Snow CLI with VSCode's built-in language intelligence: - **Symbol Navigation** - AI can request Go to Definition for any symbol - **Reference Finding** - AI can find all references to functions/classes - **Code Outline** - AI can get complete file structure - **Error Detection** - AI receives real-time diagnostics These features work automatically when Snow CLI uses ACE Code Search tools. ## Supported Languages ACE Code Search supports: - TypeScript/JavaScript - Python - Go - Rust - Java - C# - And more via VSCode language servers ## Extension Settings This extension works out of the box with no configuration required. Optional: Configure Snow CLI settings in `~/.snow/config.json` ## Architecture ```text VSCode Extension (Port 9527) ↕ WebSocket Snow CLI ↕ MCP Tools ACE Code Search Engine ↕ Language Parsers Your Codebase ``` ## Known Issues None currently. Please report issues on GitHub. ## Release Notes ### 0.3.0 - ACE Code Search Integration **Major Update:** - ✨ Added ACE Code Search integration - 🎯 Go to Definition support via VSCode language servers - 🔍 Find References across entire workspace - 📋 Document symbol extraction - 🔗 WebSocket message handlers for ACE features - 📊 Enhanced diagnostic support ### 0.2.6 - Add automatic WebSocket reconnection with exponential backoff - Improve connection stability - Enhanced context caching for better reliability --- ## Learn More - [Snow CLI GitHub](https://github.com/yourusername/snow-cli) - [ACE Code Search Documentation](https://github.com/yourusername/snow-cli/blob/main/docs/ACE_CODE_SEARCH.md) **Enjoy intelligent coding with Snow CLI + ACE Code Search!** 🚀 ================================================ FILE: VSIX/package.json ================================================ { "name": "snow-cli", "displayName": "Snow CLI", "description": "Snow AI CLI with ACE Code Search - Intelligent code navigation and search powered by AI", "version": "0.4.23", "publisher": "mufasa", "repository": { "type": "git", "url": "https://github.com/MayDay-wpf/snow-cli" }, "engines": { "vscode": "^1.106.0" }, "categories": [ "Other" ], "activationEvents": [ "onStartupFinished" ], "main": "./dist/extension.js", "contributes": { "configuration": { "title": "Snow CLI", "properties": { "snow-cli.terminalMode": { "type": "string", "default": "sidebar", "enum": [ "sidebar", "split" ], "enumDescriptions": [ "Embedded terminal in the sidebar (xterm.js + node-pty)", "Split editor right and open a terminal in the editor area" ], "description": "Choose the terminal display mode. 'sidebar' embeds a terminal in the sidebar panel; 'split' opens a terminal in a right-side editor split." }, "snow-cli.startupCommand": { "type": "string", "default": "snow", "description": "The command or comma-separated commands to run when terminals start. New terminals are assigned commands in round-robin order, and each terminal keeps its assigned command across restarts." }, "snow-cli.terminal.shellType": { "type": "string", "default": "auto", "description": "Shell for the sidebar terminal. Use 'auto' to follow VS Code's default terminal profile, or enter a shell executable path (e.g. 'C:\\Program Files\\Git\\bin\\bash.exe', 'pwsh.exe', 'cmd.exe', '/usr/bin/zsh'). Falls back to PowerShell (Windows) or $SHELL (macOS/Linux) if the path is not found." }, "snow-cli.terminal.proxyUrl": { "type": "string", "default": "", "description": "Optional proxy URL injected into Snow CLI terminals as HTTP_PROXY/HTTPS_PROXY. Leave empty to fall back to VS Code's http.proxy setting." }, "snow-cli.terminal.fontFamily": { "type": "string", "default": "", "description": "Font family for the sidebar terminal. Leave empty to use the default monospace font." }, "snow-cli.terminal.fontSize": { "type": "number", "default": 14, "minimum": 8, "maximum": 32, "description": "Font size (px) for the sidebar terminal." }, "snow-cli.terminal.fontWeight": { "type": "string", "default": "normal", "enum": [ "normal", "bold", "100", "200", "300", "400", "500", "600", "700", "800", "900" ], "description": "Font weight for the sidebar terminal." }, "snow-cli.terminal.lineHeight": { "type": "number", "default": 1, "minimum": 0.8, "maximum": 2, "description": "Line height for the sidebar terminal." }, "snow-cli.gitBlame.enabled": { "type": "boolean", "default": false, "description": "Enable Git Blame annotations. Shows commit info (author, time, message) on the current line, similar to GitLens." }, "snow-cli.bell.enabled": { "type": "boolean", "default": true, "description": "Enable terminal bell (BEL / \\x07) notifications. When disabled, both audio and visual feedback are suppressed." }, "snow-cli.bell.volume": { "type": "number", "default": 0.5, "minimum": 0, "maximum": 1, "description": "Terminal bell volume (0.0 - 1.0). Set to 0 to mute audio while still allowing visual flash." }, "snow-cli.bell.sound": { "type": "string", "default": "beep", "enum": [ "beep", "ding", "chime", "pluck", "blip", "none" ], "enumDescriptions": [ "Short 800Hz sine beep (default classic terminal bell)", "Bright triangle-wave ding", "Two-tone descending chime", "Soft sawtooth pluck", "Quick high-frequency blip", "No sound (visual flash only)" ], "description": "Bell sound style. Use 'none' to disable audio while keeping visual flash enabled." }, "snow-cli.bell.visualFlash": { "type": "boolean", "default": true, "description": "Show a brief visual flash overlay on the terminal panel when the bell rings." } } }, "viewsContainers": { "secondarySidebar": [ { "id": "snow-cli-sidebar", "title": "Snow CLI", "icon": "snow.png" } ] }, "views": { "snow-cli-sidebar": [ { "type": "webview", "id": "snowCliTerminal", "name": "Terminal", "icon": "snow.png", "when": "snow-cli.sidebarMode" } ] }, "commands": [ { "command": "snow-cli.openTerminal", "title": "Open Snow CLI", "icon": { "light": "./snow.png", "dark": "./snow.png" } }, { "command": "snow-cli.restartSidebarTerminal", "title": "Restart Terminal", "icon": "$(debug-rerun)" }, { "command": "snow-cli.newSidebarTerminalTab", "title": "New Terminal Tab", "icon": "$(add)" }, { "command": "snow-cli.addFolderPath", "title": "Add Folder Path", "icon": "$(file-symlink-directory)" }, { "command": "snow-cli.addFilePath", "title": "Add File Path", "icon": "$(file-symlink-file)" }, { "command": "snow-cli.openSnowSettings", "title": "Snow CLI Settings", "icon": "$(settings-gear)" }, { "command": "snow-cli.focusSidebar", "title": "Focus Snow CLI Sidebar" }, { "command": "snow-cli.sendFilePaths", "title": "Send to Snow CLI", "icon": "$(file-symlink-file)" }, { "command": "snow-cli.sendSelectionLocation", "title": "Send to Snow CLI", "icon": "$(file-symlink-file)" }, { "command": "snow-cli.toggleGitBlame", "title": "Snow CLI: Toggle Git Blame", "icon": "$(git-commit)" }, { "command": "snow-cli.toggleFileAnnotations", "title": "Snow CLI: Toggle File Annotations", "icon": "$(list-flat)" }, { "command": "snow-cli.generateCommitMessage", "title": "Snow CLI: Generate Commit Message", "icon": { "light": "./snow.png", "dark": "./snow.png" } }, { "command": "snow-cli.generateCommitMessageWithRequirements", "title": "Snow CLI: Generate Commit Message with Requirements", "icon": "$(comment)" }, { "command": "snow-cli.cancelCommitMessageGeneration", "title": "Snow CLI: Stop Generating Commit Message", "icon": "$(debug-stop)" } ], "submenus": [ { "id": "snow-cli.insertPathActions", "label": "Insert Path", "icon": "$(attach)" } ], "keybindings": [ { "command": "snow-cli.focusSidebar", "key": "ctrl+alt+s", "mac": "cmd+alt+s" } ], "menus": { "scm/title": [ { "command": "snow-cli.generateCommitMessage", "alt": "snow-cli.generateCommitMessageWithRequirements", "when": "!snow-cli.commitMessageGenerating", "group": "navigation@1" }, { "command": "snow-cli.generateCommitMessageWithRequirements", "when": "!snow-cli.commitMessageGenerating", "group": "snow@1" }, { "command": "snow-cli.cancelCommitMessageGeneration", "when": "snow-cli.commitMessageGenerating", "group": "navigation@1" } ], "editor/title": [ { "command": "snow-cli.openTerminal", "group": "navigation" } ], "view/title": [ { "command": "snow-cli.restartSidebarTerminal", "when": "view == snowCliTerminal && snow-cli.sidebarMode", "group": "navigation@1" }, { "command": "snow-cli.newSidebarTerminalTab", "when": "view == snowCliTerminal && snow-cli.sidebarMode", "group": "navigation@2" }, { "command": "snow-cli.openSnowSettings", "when": "view == snowCliTerminal && snow-cli.sidebarMode", "group": "navigation@3" }, { "submenu": "snow-cli.insertPathActions", "when": "view == snowCliTerminal && snow-cli.sidebarMode", "group": "navigation@4" } ], "snow-cli.insertPathActions": [ { "command": "snow-cli.addFolderPath", "group": "navigation@1" }, { "command": "snow-cli.addFilePath", "group": "navigation@2" } ], "explorer/context": [ { "command": "snow-cli.sendFilePaths", "group": "snow@1" } ], "editor/title/context": [ { "command": "snow-cli.sendFilePaths", "when": "resourceScheme == file || resourceScheme == vscode-remote", "group": "snow@1" } ], "editor/context": [ { "command": "snow-cli.sendSelectionLocation", "when": "editorHasSelection && (resourceScheme == file || resourceScheme == vscode-remote)", "group": "snow@1" } ] } }, "scripts": { "vscode:prepublish": "npm run package", "compile": "webpack", "watch": "webpack --watch", "package": "webpack --mode production --devtool hidden-source-map", "rebuild": "npm rebuild node-pty", "lint": "eslint src --ext ts", "pretest": "npm run compile && npm run lint", "test": "node ./out/test/runTest.js" }, "dependencies": { "@xterm/addon-fit": "^0.11.0", "@xterm/addon-search": "^0.16.0", "@xterm/addon-unicode11": "^0.9.0", "@xterm/addon-web-links": "^0.12.0", "@xterm/addon-webgl": "^0.19.0", "@xterm/xterm": "^6.0.0", "node-pty": "1.2.0-beta.10", "ws": "^8.14.2" }, "devDependencies": { "@types/node": "20.x", "@types/vscode": "^1.75.0", "@types/ws": "^8.5.8", "@vscode/vsce": "^2.22.0", "ts-loader": "^9.5.0", "typescript": "^5.3.0", "webpack": "^5.90.0", "webpack-cli": "^5.1.0" }, "icon": "snow.png" } ================================================ FILE: VSIX/res/sidebarTerminal.css ================================================ :root { --terminal-bg: #181818; --terminal-drag-outline: #007acc; --terminal-error: #f14c4c; --terminal-border: var(--vscode-panel-border, rgba(255, 255, 255, 0.12)); --terminal-toolbar-bg: var(--vscode-sideBar-background, #181818); --terminal-button-bg: var( --vscode-button-secondaryBackground, rgba(255, 255, 255, 0.08) ); --terminal-button-fg: var(--vscode-button-secondaryForeground, #cccccc); --terminal-button-hover-bg: var( --vscode-button-secondaryHoverBackground, rgba(255, 255, 255, 0.14) ); --terminal-button-border: var(--vscode-contrastBorder, transparent); --terminal-tab-height: 26px; } * { margin: 0; padding: 0; box-sizing: border-box; } html, body { height: 100%; width: 100%; } body { overflow: hidden; background-color: var(--terminal-bg); } #terminal-root { height: 100%; width: 100%; display: flex; flex-direction: column; min-height: 0; } #terminal-tab-strip { display: flex; gap: 0; padding: 0; border-bottom: 1px solid var(--terminal-border); background-color: var( --vscode-editorGroupHeader-tabsBackground, var(--terminal-toolbar-bg) ); flex: 0 0 auto; overflow-x: auto; scrollbar-width: none; } #terminal-tab-strip:empty { display: none; } .terminal-tab-item { display: inline-flex; align-items: stretch; flex: 0 0 auto; min-height: var(--terminal-tab-height); white-space: nowrap; background-color: var(--vscode-tab-inactiveBackground, transparent); color: var(--vscode-tab-inactiveForeground, var(--terminal-button-fg)); border-right: 1px solid var(--terminal-border); } .terminal-tab-item:hover:not(.is-active):not(.is-restarting) { background-color: var( --vscode-tab-hoverBackground, var(--terminal-button-hover-bg) ); } .terminal-tab-item.is-active, .terminal-tab-item.is-restarting { background-color: var(--vscode-tab-activeBackground, var(--terminal-bg)); color: var(--vscode-tab-activeForeground, var(--terminal-button-fg)); } .terminal-tab { appearance: none; border: none; background: transparent; color: inherit; font: inherit; font-size: 12px; line-height: 1.2; padding: 0 6px 0 8px; cursor: pointer; display: inline-flex; align-items: center; gap: 6px; min-height: var(--terminal-tab-height); white-space: nowrap; } .terminal-tab-label { overflow: hidden; text-overflow: ellipsis; } .terminal-tab-close { appearance: none; border: none; background: transparent; color: inherit; font: inherit; font-size: 13px; line-height: 1; padding: 0; cursor: pointer; display: inline-flex; align-items: center; justify-content: center; width: 18px; min-width: 18px; min-height: var(--terminal-tab-height); flex: 0 0 18px; opacity: 0; visibility: hidden; pointer-events: none; } .terminal-tab-item.is-active .terminal-tab-close, .terminal-tab-item.is-restarting .terminal-tab-close { opacity: 1; visibility: visible; } .terminal-tab-item.is-active .terminal-tab-close { pointer-events: auto; } .terminal-tab-item.is-restarting .terminal-tab-close { pointer-events: none; cursor: default; } .terminal-tab-close:hover { background-color: var(--terminal-button-hover-bg); } .terminal-tab:focus-visible, .terminal-tab-close:focus-visible { outline: 1px solid var(--vscode-focusBorder, #007acc); outline-offset: -1px; } .terminal-tab-spinner { width: 10px; height: 10px; border: 1.5px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: terminal-tab-spinner-spin 0.8s linear infinite; } @keyframes terminal-tab-spinner-spin { to { transform: rotate(360deg); } } #terminal-toolbar { display: flex; gap: 6px; padding: 4px 6px; border-bottom: 1px solid var(--terminal-border); background-color: var(--terminal-toolbar-bg); flex: 0 0 auto; } #terminal-toolbar button { appearance: none; border: 1px solid var(--terminal-button-border); border-radius: 4px; background-color: var(--terminal-button-bg); color: var(--terminal-button-fg); font: inherit; font-size: 13px; line-height: 1.4; padding: 2px 8px; cursor: pointer; } #terminal-toolbar button:hover { background-color: var(--terminal-button-hover-bg); } #terminal-toolbar button:focus-visible { outline: 1px solid var(--vscode-focusBorder, #007acc); outline-offset: 1px; } #terminal-container { position: relative; flex: 1 1 auto; min-height: 0; } #terminal-container, .xterm { height: 100%; width: 100%; } #terminal-container.drag-over { outline: 2px dashed var(--terminal-drag-outline); outline-offset: -2px; } #terminal-container::after { content: ''; position: absolute; inset: 0; z-index: 5; pointer-events: none; background: rgba(255, 255, 255, 0); border: 0 solid rgba(255, 255, 255, 0); box-sizing: border-box; opacity: 0; } #terminal-container.bell-flash::after { animation: terminal-bell-flash 320ms ease-out; } @keyframes terminal-bell-flash { 0% { opacity: 1; background: rgba(255, 255, 255, 0.18); border: 3px solid rgba(255, 255, 255, 0.85); } 60% { opacity: 0.6; background: rgba(255, 255, 255, 0.05); border: 3px solid rgba(255, 255, 255, 0.4); } 100% { opacity: 0; background: rgba(255, 255, 255, 0); border: 3px solid rgba(255, 255, 255, 0); } } #terminal-container.terminal-error { color: var(--terminal-error); padding: 20px; font-family: monospace; font-size: 12px; white-space: pre-wrap; } .terminal-freeze-overlay { position: absolute; inset: 0; z-index: 2; overflow: hidden; pointer-events: none; background-color: var(--terminal-bg); } .terminal-freeze-overlay > .xterm { height: 100%; width: 100%; } .terminal-freeze-overlay .xterm-helpers, .terminal-freeze-overlay .xterm-accessibility, .terminal-freeze-overlay .xterm-cursor-layer { visibility: hidden !important; } .xterm .xterm-viewport, .xterm .xterm-scrollable-element { background-color: var(--terminal-bg) !important; } .xterm .xterm-scrollable-element { height: 100%; } .xterm .xterm-scrollable-element > .scrollbar.vertical { box-sizing: border-box; border-left: 1px solid var(--terminal-border); } .xterm .xterm-scrollable-element > .scrollbar.horizontal { box-sizing: border-box; border-top: 1px solid var(--terminal-border); } ================================================ FILE: VSIX/res/sidebarTerminal.js ================================================ (function () { const vscode = acquireVsCodeApi(); const normalizeLogMessage = value => { if (typeof value === 'string') { const trimmed = value.trim(); if (trimmed) { return trimmed; } } try { return String(value); } catch { return 'Unknown frontend log message'; } }; const stringifyLogDetails = value => { if (typeof value === 'undefined' || value === null) { return undefined; } if (typeof value === 'string') { const trimmed = value.trim(); return trimmed || undefined; } if (value instanceof Error) { return value.stack || value.message; } try { return JSON.stringify( value, (_key, entry) => { if (entry instanceof Error) { return { name: entry.name, message: entry.message, stack: entry.stack, }; } return typeof entry === 'bigint' ? entry.toString() : entry; }, 2, ); } catch { try { return String(value); } catch { return 'Unserializable log details'; } } }; const bridgeFrontendLog = (level, message, details) => { const normalizedMessage = normalizeLogMessage(message); const normalizedDetails = stringifyLogDetails(details); const consoleMethod = level === 'error' ? 'error' : level === 'warn' ? 'warn' : level === 'debug' ? 'debug' : 'info'; const logToConsole = typeof console[consoleMethod] === 'function' ? console[consoleMethod].bind(console) : console.log.bind(console); const consolePrefix = `[Snow CLI][SidebarTerminal][${level.toUpperCase()}] ${normalizedMessage}`; if (typeof normalizedDetails === 'string') { logToConsole(consolePrefix, normalizedDetails); } else { logToConsole(consolePrefix); } try { vscode.postMessage({ type: 'frontendLog', level, message: normalizedMessage, details: normalizedDetails, }); } catch { // Ignore logging bridge failures. } }; const logInfo = (message, details) => { bridgeFrontendLog('info', message, details); }; const logWarn = (message, details) => { bridgeFrontendLog('warn', message, details); }; const logError = (message, details) => { bridgeFrontendLog('error', message, details); }; const tabStrip = document.getElementById('terminal-tab-strip'); if (!(tabStrip instanceof HTMLElement)) { logError('Terminal tab strip element was not found.'); return; } const container = document.getElementById('terminal-container'); if (!(container instanceof HTMLElement)) { logError('Terminal container element was not found.'); return; } const showError = msg => { for (const overlay of container.querySelectorAll( '.terminal-freeze-overlay', )) { overlay.remove(); } container.classList.add('terminal-error'); container.textContent = `Terminal Error:\n${msg}`; logError('Terminal UI error displayed.', msg); }; const getOptionalButton = buttonId => { const button = document.getElementById(buttonId); if (button instanceof HTMLButtonElement) { return button; } if (button !== null) { logWarn( 'Renderer test control element is not a button.', `id=${buttonId}`, ); } return undefined; }; const renderStallTestButton = getOptionalButton('terminal-test-render-stall'); const contextLossTestButton = getOptionalButton('terminal-test-context-loss'); const getGlobalConstructor = (globalName, memberName) => { const globalValue = globalThis[globalName]; if (typeof memberName !== 'string') { return typeof globalValue === 'function' ? globalValue : undefined; } const constructorValue = globalValue && globalValue[memberName]; return typeof constructorValue === 'function' ? constructorValue : undefined; }; const TerminalCtor = getGlobalConstructor('Terminal'); const FitAddonCtor = getGlobalConstructor('FitAddon', 'FitAddon'); const WebLinksAddonCtor = getGlobalConstructor( 'WebLinksAddon', 'WebLinksAddon', ); const Unicode11AddonCtor = getGlobalConstructor( 'Unicode11Addon', 'Unicode11Addon', ); const WebglAddonCtor = getGlobalConstructor('WebglAddon', 'WebglAddon'); const requiredAddons = [ ['Terminal', typeof TerminalCtor], ['FitAddon', typeof FitAddonCtor], ['WebLinksAddon', typeof WebLinksAddonCtor], ]; for (const [name, type] of requiredAddons) { if (type === 'undefined') { const errorMessage = `${name} failed to load.${ name === 'Terminal' ? ' Check CSP or resource paths.' : '' }`; showError(errorMessage); return; } } const createCleanupRegistry = () => { const handlers = []; let cleaned = false; const registerCleanup = cleanup => { handlers.push(cleanup); }; const runCleanups = () => { if (cleaned) { return; } cleaned = true; for (let i = handlers.length - 1; i >= 0; i -= 1) { try { handlers[i](); } catch { // Ignore cleanup failures. } } handlers.length = 0; }; const addManagedListener = (target, type, listener, options) => { target.addEventListener(type, listener, options); registerCleanup(() => { target.removeEventListener(type, listener, options); }); }; const registerDisposable = disposable => { if (!disposable || typeof disposable.dispose !== 'function') { return; } registerCleanup(() => { try { disposable.dispose(); } catch { // Ignore disposal failures. } }); }; return { registerCleanup, runCleanups, addManagedListener, registerDisposable, }; }; const applyTermOption = (options, key, value) => { if (typeof value === 'string' && value) { options[key] = value; } else if (typeof value === 'number' && Number.isFinite(value)) { options[key] = value; } }; const createTimerRegistry = () => { const timers = new Map(); const clearTimer = key => { const timer = timers.get(key); if (typeof timer === 'undefined' || timer === null) { return; } clearTimeout(timer); timers.set(key, null); }; const scheduleTimer = (key, callback, delayMs) => { clearTimer(key); const timer = setTimeout(() => { timers.set(key, null); callback(); }, delayMs); timers.set(key, timer); return timer; }; const clearAllTimers = () => { for (const key of Array.from(timers.keys())) { clearTimer(key); } }; return { clearTimer, scheduleTimer, clearAllTimers, }; }; const createFocusRecoveryController = ({term, cooldownMs, delaysMs}) => { let focusRecoveryTimers = []; let focusRecoveryCooldownUntil = 0; const clearFocusRecoveryTimers = () => { if (focusRecoveryTimers.length === 0) { return; } for (const timer of focusRecoveryTimers) { clearTimeout(timer); } focusRecoveryTimers = []; }; const scheduleFocusRecovery = () => { if (document.hidden) { return; } const now = Date.now(); if (now < focusRecoveryCooldownUntil) { return; } focusRecoveryCooldownUntil = now + cooldownMs; clearFocusRecoveryTimers(); for (const delay of delaysMs) { const timer = setTimeout(() => { focusRecoveryTimers = focusRecoveryTimers.filter( entry => entry !== timer, ); term.focus(); }, delay); focusRecoveryTimers.push(timer); } }; return { clearFocusRecoveryTimers, scheduleFocusRecovery, }; }; const createLayoutController = ({ term, container, fitAddon, setRendererHealthSuspended, suspendAfterLayoutMs, scheduleTimer, resizeDebounceTimerKey, }) => { const RESIZE_FILL_TOLERANCE_PX = 2; let lastReportedCols = 0; let lastReportedRows = 0; const reportSize = () => { const cols = term.cols; const rows = term.rows; if ( cols > 0 && rows > 0 && (cols !== lastReportedCols || rows !== lastReportedRows) ) { lastReportedCols = cols; lastReportedRows = rows; vscode.postMessage({ type: 'resize', cols, rows, }); } }; const getMeasuredRowHeight = () => { const screenCanvas = container.querySelector('.xterm-screen canvas'); if (screenCanvas instanceof HTMLCanvasElement && term.rows > 0) { const measured = screenCanvas.getBoundingClientRect().height / term.rows; if (measured > 0) { return measured; } } const fontSize = typeof term.options.fontSize === 'number' ? term.options.fontSize : 14; const lineHeight = typeof term.options.lineHeight === 'number' ? term.options.lineHeight : 1; const estimated = fontSize * lineHeight; return estimated > 0 ? estimated : 0; }; const resizeToContainer = () => { const proposed = fitAddon.proposeDimensions(); if (!proposed) { return false; } let {cols, rows} = proposed; if (cols <= 0 || rows <= 0) { return false; } const rowHeight = getMeasuredRowHeight(); if (rowHeight > 0) { const availableHeight = container.getBoundingClientRect().height; const remainingHeight = availableHeight - rows * rowHeight; if (remainingHeight >= rowHeight - RESIZE_FILL_TOLERANCE_PX) { rows += 1; } } if (cols !== term.cols || rows !== term.rows) { term.resize(cols, rows); } return true; }; const fitTerminal = () => { setRendererHealthSuspended(suspendAfterLayoutMs); try { const resized = resizeToContainer(); if (!resized) { fitAddon.fit(); } reportSize(); } catch { // Ignore fit errors caused by transient hidden/invalid layout states. } }; const scheduleFit = () => { scheduleTimer( resizeDebounceTimerKey, () => { fitTerminal(); }, 50, ); }; return { fitTerminal, scheduleFit, }; }; const createWindowMessageRouter = ({messageHandlers}) => { return event => { const message = event.data; if (!message || typeof message.type !== 'string') { return; } const handler = messageHandlers[message.type]; if (typeof handler !== 'function') { logWarn('Unhandled extension message type.', `type=${message.type}`); return; } try { handler(message); } catch (error) { logError(`Failed to handle extension message: ${message.type}`, error); } }; }; const createClipboardAndContextController = ({term, sendInput}) => { const isMacPlatform = /mac/i.test(navigator.userAgent); const shouldUseCtrlSelectionCopy = event => { if ( isMacPlatform || event.type !== 'keydown' || !event.ctrlKey || event.shiftKey || event.altKey || event.metaKey || event.key.toLowerCase() !== 'c' ) { return false; } return term.hasSelection() && Boolean(term.getSelection()); }; const allowTerminalKeyEvent = event => { if ( !isMacPlatform && event.type === 'keydown' && event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey && event.key.toLowerCase() === 'v' ) { return false; } if (shouldUseCtrlSelectionCopy(event)) { const selection = term.getSelection(); if (selection) { navigator.clipboard.writeText(selection).catch(() => { // Ignore clipboard write failures. }); } return false; } return true; }; const handleContextMenu = event => { event.preventDefault(); const selection = term.getSelection(); if (selection) { navigator.clipboard.writeText(selection).catch(() => { // Ignore clipboard write failures. }); term.clearSelection(); return; } navigator.clipboard .readText() .then(text => { sendInput(text); }) .catch(() => { // Ignore clipboard read failures. }); }; return { allowTerminalKeyEvent, handleContextMenu, }; }; const createWindowLifecycleController = ({ scheduleFocusRecovery, setRendererHealthSuspended, suspendAfterLayoutMs, getActiveRendererMode, getLastWebglFailureReason, scheduleWebglRecoveryAttempt, webglRecoveryRecheckMs, }) => { const handleContainerMouseDown = () => { scheduleFocusRecovery(); }; const handleVisibilityChange = () => { if (document.hidden) { return; } setRendererHealthSuspended(suspendAfterLayoutMs); scheduleFocusRecovery(); const lastFailureReason = getLastWebglFailureReason(); if (getActiveRendererMode() !== 'webgl' && lastFailureReason) { scheduleWebglRecoveryAttempt(lastFailureReason, webglRecoveryRecheckMs); } }; const handleWindowFocus = () => { setRendererHealthSuspended(suspendAfterLayoutMs); scheduleFocusRecovery(); }; return { handleContainerMouseDown, handleVisibilityChange, handleWindowFocus, }; }; try { const { registerCleanup, runCleanups, addManagedListener, registerDisposable, } = createCleanupRegistry(); logInfo('Initializing sidebar terminal frontend.'); let currentTabId; let tabStates = []; const normalizeTabState = value => { if (!value || typeof value !== 'object') { return undefined; } const id = typeof value.id === 'string' ? value.id : ''; const title = typeof value.title === 'string' ? value.title : ''; if (!id || !title) { return undefined; } return { id, title, isActive: Boolean(value.isActive), isRunning: Boolean(value.isRunning), isRestarting: Boolean(value.isRestarting), exitCode: typeof value.exitCode === 'number' && Number.isFinite(value.exitCode) ? value.exitCode : undefined, }; }; const revealTabItem = item => { if (!(item instanceof HTMLElement)) { return; } window.requestAnimationFrame(() => { const visibleLeft = tabStrip.scrollLeft; const visibleRight = visibleLeft + tabStrip.clientWidth; const itemLeft = item.offsetLeft; const itemRight = itemLeft + item.offsetWidth; if (itemLeft < visibleLeft) { tabStrip.scrollLeft = itemLeft; return; } if (itemRight > visibleRight) { tabStrip.scrollLeft = Math.max(0, itemRight - tabStrip.clientWidth); } }); }; const renderTabs = () => { tabStrip.replaceChildren(); if (tabStates.length === 0) { return; } let activeItem; for (const tab of tabStates) { const item = document.createElement('div'); item.className = 'terminal-tab-item'; item.dataset.tabId = tab.id; if (tab.isActive) { item.classList.add('is-active'); activeItem = item; } if (tab.isRestarting) { item.classList.add('is-restarting'); } const button = document.createElement('button'); button.type = 'button'; button.className = 'terminal-tab'; button.setAttribute('role', 'tab'); button.setAttribute('aria-selected', tab.isActive ? 'true' : 'false'); button.setAttribute('aria-controls', 'terminal-container'); button.title = tab.title; const label = document.createElement('span'); label.className = 'terminal-tab-label'; label.textContent = tab.title; button.appendChild(label); button.addEventListener('click', () => { if (tab.id === currentTabId) { return; } vscode.postMessage({type: 'switchTab', tabId: tab.id}); }); const closeButton = document.createElement('button'); closeButton.type = 'button'; closeButton.className = 'terminal-tab-close'; if (tab.isRestarting) { const spinner = document.createElement('span'); spinner.className = 'terminal-tab-spinner'; closeButton.setAttribute('aria-label', `${tab.title} is restarting`); closeButton.title = `${tab.title} is restarting`; closeButton.disabled = true; closeButton.appendChild(spinner); } else { closeButton.setAttribute('aria-label', `Close ${tab.title}`); closeButton.title = `Close ${tab.title}`; closeButton.textContent = '×'; closeButton.addEventListener('click', event => { event.preventDefault(); event.stopPropagation(); vscode.postMessage({type: 'closeTab', tabId: tab.id}); }); } item.appendChild(button); item.appendChild(closeButton); tabStrip.appendChild(item); } if (activeItem) { revealTabItem(activeItem); } }; const applyTabs = nextTabs => { const normalizedTabs = Array.isArray(nextTabs) ? nextTabs.map(normalizeTabState).filter(Boolean) : []; if (normalizedTabs.length === 0) { tabStates = []; currentTabId = undefined; renderTabs(); return; } const activeTab = normalizedTabs.find(tab => tab.isActive) || normalizedTabs[0]; currentTabId = activeTab.id; tabStates = normalizedTabs.map(tab => ({ ...tab, isActive: tab.id === activeTab.id, })); renderTabs(); }; const sendInput = text => { if (typeof text !== 'string' || text.length === 0) { return; } vscode.postMessage({type: 'input', data: text}); }; const createBellPlayer = () => { const config = { enabled: true, volume: 0.5, sound: 'beep', visualFlash: true, }; let audioCtx = null; let lastBellAt = 0; let visualFlashClearTimer = null; const MIN_BELL_INTERVAL_MS = 80; const VISUAL_FLASH_DURATION_MS = 320; const ensureAudioCtx = () => { if (audioCtx) { return audioCtx; } const Ctor = typeof window.AudioContext === 'function' ? window.AudioContext : typeof window.webkitAudioContext === 'function' ? window.webkitAudioContext : undefined; if (!Ctor) { return null; } try { audioCtx = new Ctor(); } catch (error) { logWarn( 'Failed to initialize AudioContext for terminal bell.', error, ); audioCtx = null; } return audioCtx; }; const unlockAudio = () => { const ctx = ensureAudioCtx(); if (!ctx || ctx.state !== 'suspended') { return; } ctx.resume().catch(() => { // AudioContext will be retried on the next user gesture. }); }; const updateConfig = next => { if (!next || typeof next !== 'object') { return; } if (typeof next.enabled === 'boolean') { config.enabled = next.enabled; } if (typeof next.volume === 'number' && Number.isFinite(next.volume)) { config.volume = Math.min(1, Math.max(0, next.volume)); } if (typeof next.sound === 'string') { config.sound = next.sound; } if (typeof next.visualFlash === 'boolean') { config.visualFlash = next.visualFlash; } }; const flashBellOverlay = () => { if (!config.visualFlash) { return; } container.classList.remove('bell-flash'); // Force reflow so the animation restarts on rapid consecutive bells. void container.offsetWidth; container.classList.add('bell-flash'); if (visualFlashClearTimer) { clearTimeout(visualFlashClearTimer); } visualFlashClearTimer = setTimeout(() => { container.classList.remove('bell-flash'); visualFlashClearTimer = null; }, VISUAL_FLASH_DURATION_MS); }; const scheduleBellTone = (ctx, gainNode, spec) => { const oscillator = ctx.createOscillator(); oscillator.type = spec.type || 'sine'; oscillator.frequency.setValueAtTime(spec.frequency, spec.startTime); if (typeof spec.endFrequency === 'number') { oscillator.frequency.exponentialRampToValueAtTime( spec.endFrequency, spec.startTime + spec.duration, ); } oscillator.connect(gainNode); oscillator.start(spec.startTime); oscillator.stop(spec.startTime + spec.duration + 0.02); }; const renderSound = ctx => { const masterGain = ctx.createGain(); masterGain.gain.value = config.volume; masterGain.connect(ctx.destination); const now = ctx.currentTime; const peak = 0.6; // pre-volume peak; final amplitude = peak * config.volume const tones = []; switch (config.sound) { case 'ding': { const envGain = ctx.createGain(); envGain.gain.setValueAtTime(0.0001, now); envGain.gain.exponentialRampToValueAtTime(peak, now + 0.005); envGain.gain.exponentialRampToValueAtTime(0.0001, now + 0.32); envGain.connect(masterGain); tones.push({ type: 'triangle', frequency: 1320, startTime: now, duration: 0.32, gain: envGain, }); tones.push({ type: 'triangle', frequency: 1980, startTime: now, duration: 0.28, gain: envGain, }); break; } case 'chime': { const env1 = ctx.createGain(); env1.gain.setValueAtTime(0.0001, now); env1.gain.exponentialRampToValueAtTime(peak, now + 0.01); env1.gain.exponentialRampToValueAtTime(0.0001, now + 0.2); env1.connect(masterGain); tones.push({ type: 'sine', frequency: 1046.5, startTime: now, duration: 0.2, gain: env1, }); const env2 = ctx.createGain(); env2.gain.setValueAtTime(0.0001, now + 0.16); env2.gain.exponentialRampToValueAtTime(peak, now + 0.17); env2.gain.exponentialRampToValueAtTime(0.0001, now + 0.42); env2.connect(masterGain); tones.push({ type: 'sine', frequency: 783.99, startTime: now + 0.16, duration: 0.26, gain: env2, }); break; } case 'pluck': { const envGain = ctx.createGain(); envGain.gain.setValueAtTime(0.0001, now); envGain.gain.exponentialRampToValueAtTime(peak * 0.85, now + 0.005); envGain.gain.exponentialRampToValueAtTime(0.0001, now + 0.18); envGain.connect(masterGain); tones.push({ type: 'sawtooth', frequency: 660, endFrequency: 330, startTime: now, duration: 0.18, gain: envGain, }); break; } case 'blip': { const envGain = ctx.createGain(); envGain.gain.setValueAtTime(0.0001, now); envGain.gain.exponentialRampToValueAtTime(peak, now + 0.004); envGain.gain.exponentialRampToValueAtTime(0.0001, now + 0.08); envGain.connect(masterGain); tones.push({ type: 'square', frequency: 1760, startTime: now, duration: 0.08, gain: envGain, }); break; } case 'beep': default: { const envGain = ctx.createGain(); envGain.gain.setValueAtTime(0.0001, now); envGain.gain.exponentialRampToValueAtTime(peak, now + 0.01); envGain.gain.exponentialRampToValueAtTime(0.0001, now + 0.13); envGain.connect(masterGain); tones.push({ type: 'sine', frequency: 800, startTime: now, duration: 0.13, gain: envGain, }); break; } } for (const tone of tones) { scheduleBellTone(ctx, tone.gain, tone); } }; const playBell = () => { if (!config.enabled) { return; } const now = Date.now(); if (now - lastBellAt < MIN_BELL_INTERVAL_MS) { return; } lastBellAt = now; flashBellOverlay(); if (config.sound === 'none' || config.volume <= 0) { return; } const ctx = ensureAudioCtx(); if (!ctx) { return; } if (ctx.state === 'suspended') { ctx.resume().catch(() => { // User has not yet interacted with the webview; visual flash is the only feedback this time. }); return; } try { renderSound(ctx); } catch (error) { logWarn('Failed to play terminal bell.', error); } }; const dispose = () => { if (visualFlashClearTimer) { clearTimeout(visualFlashClearTimer); visualFlashClearTimer = null; } }; return {playBell, unlockAudio, updateConfig, dispose}; }; const { playBell: playTerminalBell, unlockAudio: unlockTerminalAudio, updateConfig: updateBellConfig, dispose: disposeBellPlayer, } = createBellPlayer(); registerCleanup(disposeBellPlayer); const term = new TerminalCtor({ cursorBlink: true, fontFamily: 'monospace', fontSize: 14, altClickMovesCursor: true, drawBoldTextInBrightColors: true, minimumContrastRatio: 4.5, tabStopWidth: 8, macOptionIsMeta: false, rightClickSelectsWord: false, fastScrollModifier: 'alt', fastScrollSensitivity: 5, scrollSensitivity: 1, scrollback: 1000, scrollOnUserInput: true, wordSeparator: " ()[]{}',\\\"`─''|", allowTransparency: false, rescaleOverlappingGlyphs: true, allowProposedApi: true, cursorStyle: 'block', cursorInactiveStyle: 'outline', cursorWidth: 1, convertEol: false, disableStdin: false, screenReaderMode: false, windowOptions: { restoreWin: false, minimizeWin: false, setWinPosition: false, setWinSizePixels: false, raiseWin: false, lowerWin: false, refreshWin: false, setWinSizeChars: false, maximizeWin: false, fullscreenWin: false, }, theme: { background: '#181818', foreground: '#d4d4d4', cursor: '#aeafad', cursorAccent: '#000000', selectionBackground: '#264f78', black: '#000000', red: '#cd3131', green: '#0dbc79', yellow: '#e5e510', blue: '#2472c8', magenta: '#bc3fbc', cyan: '#11a8cd', white: '#e5e5e5', brightBlack: '#666666', brightRed: '#f14c4c', brightGreen: '#23d18b', brightYellow: '#f5f543', brightBlue: '#3b8eea', brightMagenta: '#d670d6', brightCyan: '#29b8db', brightWhite: '#e5e5e5', }, }); const fitAddon = new FitAddonCtor(); const webLinksAddon = new WebLinksAddonCtor(); term.loadAddon(fitAddon); term.loadAddon(webLinksAddon); if (typeof Unicode11AddonCtor === 'function') { try { const unicode11Addon = new Unicode11AddonCtor(); term.loadAddon(unicode11Addon); try { term.unicode.activeVersion = '11'; logInfo('Unicode version 11 activated.'); } catch (error) { logWarn('Failed to activate Unicode version 11.', error); } } catch (error) { logWarn('Unicode11Addon failed to load.', error); } } term.open(container); const TIMER_KEYS = { resizeDebounce: 'resizeDebounce', webglRecovery: 'webglRecovery', silentWebglRecovery: 'silentWebglRecovery', rendererFreezeRelease: 'rendererFreezeRelease', webglStability: 'webglStability', }; const FOCUS_RECOVERY_DELAYS_MS = [0, 80, 240]; const FOCUS_RECOVERY_COOLDOWN_MS = 400; const RENDER_STALL_TIMEOUT_MS = 10000; const RENDER_STALL_CHECK_INTERVAL_MS = 2000; const RENDER_STALL_WRITE_ACTIVITY_GRACE_MS = 1000; const RENDERER_HEALTH_SUSPEND_AFTER_LAYOUT_MS = 2500; const RENDERER_HEALTH_SUSPEND_AFTER_WEBGL_ENABLE_MS = 4000; const WEBGL_RECOVERY_RECHECK_MS = 2000; const WEBGL_RECOVERY_SUSPEND_DEFER_MIN_MS = 250; const WEBGL_RECOVERY_DELAY_STEPS_MS = [1000, 5000, 15000]; const WEBGL_STABILITY_RESET_MS = 30000; const SILENT_WEBGL_RECOVERY_DELAY_MS = 180; const RENDERER_FREEZE_RELEASE_FALLBACK_MS = 120; const {clearTimer, scheduleTimer, clearAllTimers} = createTimerRegistry(); const {clearFocusRecoveryTimers, scheduleFocusRecovery} = createFocusRecoveryController({ term, cooldownMs: FOCUS_RECOVERY_COOLDOWN_MS, delaysMs: FOCUS_RECOVERY_DELAYS_MS, }); let webglAddon = null; let activeRendererMode = 'fallback'; let lastOutputAt = 0; let lastRenderAt = Date.now(); let lastWriteParsedAt = 0; let lastWriteCallbackAt = 0; let bytesPendingRender = 0; let pendingVisualUpdate = false; let pendingRenderSince = 0; let rendererStallReportedAt = 0; let rendererHealthSuspendedUntil = Date.now() + RENDERER_HEALTH_SUSPEND_AFTER_LAYOUT_MS; let webglFailureCount = 0; let lastWebglFailureReason = undefined; let lastWebglEscalationRequestedAt = 0; let rendererRecoveryCycleId = 0; let currentRecoveryCycleId = 0; let currentRecoveryAttemptId = 0; let rendererStallWriteGracePendingSince = 0; let rendererStallWriteGraceUntil = 0; let rendererFreezeOverlay = null; let rendererFreezeReleasePending = false; let rendererFallbackPending = false; const clearWebglRecoveryTimer = () => { clearTimer(TIMER_KEYS.webglRecovery); }; const clearWebglStabilityTimer = () => { clearTimer(TIMER_KEYS.webglStability); }; const isContainerVisible = () => { if (document.hidden) { return false; } const rect = container.getBoundingClientRect(); return rect.width > 0 && rect.height > 0; }; const setRendererHealthSuspended = durationMs => { if (typeof durationMs !== 'number' || durationMs <= 0) { return; } const suspendedUntil = Date.now() + durationMs; if (suspendedUntil > rendererHealthSuspendedUntil) { rendererHealthSuspendedUntil = suspendedUntil; } }; const getRendererHealthSuspendedRemainingMs = now => Math.max(0, rendererHealthSuspendedUntil - now); const clearRendererStallWriteGrace = () => { rendererStallWriteGracePendingSince = 0; rendererStallWriteGraceUntil = 0; }; const getWebglRecoveryDelayMs = delayMs => { const nextDelayMs = Math.max(0, Math.floor(delayMs)); const suspendedRemainingMs = getRendererHealthSuspendedRemainingMs( Date.now(), ); if (suspendedRemainingMs <= 0) { return nextDelayMs; } return Math.max( nextDelayMs, WEBGL_RECOVERY_SUSPEND_DEFER_MIN_MS, suspendedRemainingMs, ); }; const postRendererHealth = (stage, reason, extraStats) => { const now = Date.now(); try { vscode.postMessage({ type: 'rendererHealth', stage, reason, stats: { activeRendererMode, pendingVisualUpdate, pendingDurationMs: pendingVisualUpdate && pendingRenderSince > 0 ? now - pendingRenderSince : 0, sinceLastRenderMs: lastRenderAt > 0 ? now - lastRenderAt : undefined, sinceLastOutputMs: lastOutputAt > 0 ? now - lastOutputAt : undefined, sinceLastWriteParsedMs: lastWriteParsedAt > 0 ? now - lastWriteParsedAt : undefined, sinceLastWriteCallbackMs: lastWriteCallbackAt > 0 ? now - lastWriteCallbackAt : undefined, bytesPendingRender, webglFailureCount, rendererRecoveryCycleId: currentRecoveryCycleId || undefined, rendererRecoveryAttemptId: currentRecoveryAttemptId || undefined, rendererHealthSuspendedForMs: getRendererHealthSuspendedRemainingMs(now), lastWebglFailureReason, ...(extraStats || {}), }, }); } catch { // Ignore renderer health bridge failures. } }; const {fitTerminal, scheduleFit} = createLayoutController({ term, container, fitAddon, setRendererHealthSuspended, suspendAfterLayoutMs: RENDERER_HEALTH_SUSPEND_AFTER_LAYOUT_MS, scheduleTimer, resizeDebounceTimerKey: TIMER_KEYS.resizeDebounce, }); const copyFreezeCanvasBitmap = (sourceCanvas, targetCanvas) => { try { targetCanvas.width = sourceCanvas.width; targetCanvas.height = sourceCanvas.height; targetCanvas.style.width = sourceCanvas.style.width; targetCanvas.style.height = sourceCanvas.style.height; const context = targetCanvas.getContext('2d'); if (!context) { return; } context.clearRect(0, 0, targetCanvas.width, targetCanvas.height); context.drawImage(sourceCanvas, 0, 0); } catch { // Ignore canvas snapshot failures. } }; const createRendererFreezeOverlay = () => { if (rendererFreezeOverlay) { return true; } const terminalElement = container.querySelector('.xterm'); if (!(terminalElement instanceof HTMLElement)) { return false; } const terminalClone = terminalElement.cloneNode(true); if (!(terminalClone instanceof HTMLElement)) { return false; } const sourceCanvases = terminalElement.querySelectorAll('canvas'); const targetCanvases = terminalClone.querySelectorAll('canvas'); for (let index = 0; index < targetCanvases.length; index += 1) { const sourceCanvas = sourceCanvases[index]; const targetCanvas = targetCanvases[index]; if ( sourceCanvas instanceof HTMLCanvasElement && targetCanvas instanceof HTMLCanvasElement ) { copyFreezeCanvasBitmap(sourceCanvas, targetCanvas); } } const sourceScrollable = terminalElement.querySelector( '.xterm-scrollable-element', ); const targetScrollable = terminalClone.querySelector( '.xterm-scrollable-element', ); if ( sourceScrollable instanceof HTMLElement && targetScrollable instanceof HTMLElement ) { targetScrollable.scrollTop = sourceScrollable.scrollTop; targetScrollable.scrollLeft = sourceScrollable.scrollLeft; } const overlay = document.createElement('div'); overlay.className = 'terminal-freeze-overlay'; overlay.appendChild(terminalClone); container.appendChild(overlay); rendererFreezeOverlay = overlay; return true; }; const removeRendererFreezeOverlay = () => { if (!rendererFreezeOverlay) { return; } rendererFreezeOverlay.remove(); rendererFreezeOverlay = null; }; const releaseRendererFreezeOverlay = () => { clearTimer(TIMER_KEYS.rendererFreezeRelease); rendererFreezeReleasePending = false; removeRendererFreezeOverlay(); }; const scheduleRendererFreezeRelease = () => { if (!rendererFreezeOverlay) { return; } rendererFreezeReleasePending = true; scheduleTimer( TIMER_KEYS.rendererFreezeRelease, () => { releaseRendererFreezeOverlay(); }, RENDERER_FREEZE_RELEASE_FALLBACK_MS, ); }; const clearSilentWebglRecoveryTimer = () => { clearTimer(TIMER_KEYS.silentWebglRecovery); }; const scheduleWebglStabilityReset = () => { scheduleTimer( TIMER_KEYS.webglStability, () => { if (activeRendererMode !== 'webgl' || !webglAddon) { return; } if (webglFailureCount > 0 || lastWebglFailureReason) { logInfo('WebGL renderer marked stable after recovery window.'); } webglFailureCount = 0; lastWebglFailureReason = undefined; lastWebglEscalationRequestedAt = 0; }, WEBGL_STABILITY_RESET_MS, ); }; const disposeWebglAddon = () => { try { if (webglAddon) { webglAddon.dispose(); } } catch { // Ignore dispose failures for already-lost context. } webglAddon = null; }; const requestWebglRecoveryEscalation = reason => { const now = Date.now(); if (now - lastWebglEscalationRequestedAt < RENDER_STALL_TIMEOUT_MS) { return; } lastWebglEscalationRequestedAt = now; logWarn( 'Local WebGL recovery exhausted; requesting provider escalation.', reason ? `reason=${reason}` : undefined, ); postRendererHealth('escalation-requested', reason); }; const runRendererHealthTest = reason => { logWarn( 'Manual renderer health test requested.', `reason=${reason}, activeRendererMode=${activeRendererMode}, webglActive=${Boolean( webglAddon, )}`, ); if (activeRendererMode !== 'webgl' || !webglAddon) { scheduleWebglRecoveryAttempt(reason, WEBGL_RECOVERY_RECHECK_MS); return; } degradeRenderer(reason); }; const commitVisibleFallbackRenderer = reason => { rendererFallbackPending = false; clearSilentWebglRecoveryTimer(); activeRendererMode = 'fallback'; try { if (term.rows > 0) { term.refresh(0, term.rows - 1); } } catch { // Ignore refresh errors after renderer fallback. } fitTerminal(); scheduleFocusRecovery(); scheduleRendererFreezeRelease(); postRendererHealth('degraded', reason, { rendererRecoveryCycleId: currentRecoveryCycleId, rendererRecoveryAttemptId: currentRecoveryAttemptId, }); const delayMs = WEBGL_RECOVERY_DELAY_STEPS_MS[webglFailureCount - 1]; if (typeof delayMs === 'number') { scheduleWebglRecoveryAttempt(reason, delayMs); return; } requestWebglRecoveryEscalation(reason); }; const attemptSilentWebglRecovery = reason => { if (!rendererFallbackPending) { return; } if (!isContainerVisible()) { commitVisibleFallbackRenderer(reason); return; } logInfo( 'Attempting silent WebGL recovery before visible fallback.', `cycle=${currentRecoveryCycleId || 'n/a'}, reason=${ reason || 'unknown' }, failureCount=${webglFailureCount}`, ); if ( tryEnableWebgl(reason || 'silent-recovery', { fitAfterEnable: false, focusAfterEnable: false, emitRestoredHealth: false, releaseFreezeOnFailure: false, }) ) { logInfo( 'Silent WebGL recovery succeeded without visible fallback.', `cycle=${currentRecoveryCycleId || 'n/a'}, reason=${ reason || 'unknown' }, failureCount=${webglFailureCount}`, ); return; } commitVisibleFallbackRenderer(lastWebglFailureReason || reason); }; const scheduleSilentWebglRecovery = reason => { if (!rendererFallbackPending) { return; } scheduleTimer( TIMER_KEYS.silentWebglRecovery, () => { attemptSilentWebglRecovery(reason); }, SILENT_WEBGL_RECOVERY_DELAY_MS, ); }; const scheduleWebglRecoveryAttempt = (reason, delayMs) => { if (activeRendererMode === 'webgl' || webglAddon) { return; } if (webglFailureCount > WEBGL_RECOVERY_DELAY_STEPS_MS.length) { requestWebglRecoveryEscalation(reason); return; } const nextDelay = getWebglRecoveryDelayMs(delayMs); const nextAttemptId = currentRecoveryAttemptId + 1; scheduleTimer( TIMER_KEYS.webglRecovery, () => { attemptWebglRecovery(reason, nextAttemptId); }, nextDelay, ); logInfo( 'Scheduled WebGL recovery attempt.', `cycle=${ currentRecoveryCycleId || 'n/a' }, attempt=${nextAttemptId}, reason=${ reason || 'unknown' }, delayMs=${nextDelay}, failureCount=${webglFailureCount}`, ); postRendererHealth('webgl-retry-scheduled', reason, { scheduledRecoveryDelayMs: nextDelay, rendererRecoveryAttemptId: nextAttemptId, }); }; const isWebglAddonAvailable = () => typeof WebglAddonCtor === 'function'; const tryEnableWebgl = (reason, options = {}) => { const fitAfterEnable = options.fitAfterEnable !== false; const focusAfterEnable = options.focusAfterEnable !== false; const emitRestoredHealth = options.emitRestoredHealth !== false; const releaseFreezeOnFailure = options.releaseFreezeOnFailure !== false; if (webglAddon) { return true; } if (!isWebglAddonAvailable()) { logWarn( 'WebGL addon unavailable; staying on fallback renderer.', reason ? `reason=${reason}` : undefined, ); return false; } try { webglAddon = new WebglAddonCtor(); term.loadAddon(webglAddon); activeRendererMode = 'webgl'; rendererStallReportedAt = 0; lastRenderAt = Date.now(); setRendererHealthSuspended( RENDERER_HEALTH_SUSPEND_AFTER_WEBGL_ENABLE_MS, ); clearWebglRecoveryTimer(); scheduleWebglStabilityReset(); logInfo( 'WebGL renderer enabled.', reason ? `reason=${reason}, failureCount=${webglFailureCount}` : `failureCount=${webglFailureCount}`, ); if (typeof webglAddon.onContextLoss === 'function') { webglAddon.onContextLoss(() => { degradeRenderer('context-loss'); }); } try { if (term.rows > 0) { term.refresh(0, term.rows - 1); } } catch { // Ignore refresh errors during WebGL enable. } if (fitAfterEnable) { fitTerminal(); } if (focusAfterEnable) { scheduleFocusRecovery(); } scheduleRendererFreezeRelease(); if (emitRestoredHealth) { postRendererHealth('webgl-restored', reason); } clearSilentWebglRecoveryTimer(); rendererFallbackPending = false; return true; } catch (error) { activeRendererMode = 'fallback'; webglAddon = null; lastWebglFailureReason = 'webgl-load-failed'; logWarn( 'WebGL addon failed to load.', reason ? {reason, error: stringifyLogDetails(error)} : error, ); if (releaseFreezeOnFailure) { releaseRendererFreezeOverlay(); } return false; } }; const attemptWebglRecovery = (reason, attemptId) => { if (activeRendererMode === 'webgl' || webglAddon) { return; } if (!isContainerVisible()) { logInfo( 'Deferred WebGL recovery attempt because container is not visible.', `cycle=${currentRecoveryCycleId || 'n/a'}, attempt=${ attemptId || 'n/a' }, reason=${reason || 'unknown'}`, ); scheduleWebglRecoveryAttempt(reason, WEBGL_RECOVERY_RECHECK_MS); return; } const now = Date.now(); const suspendedRemainingMs = getRendererHealthSuspendedRemainingMs(now); if (suspendedRemainingMs > 0) { logInfo( 'Deferred WebGL recovery attempt because renderer health is suspended.', `cycle=${currentRecoveryCycleId || 'n/a'}, attempt=${ attemptId || 'n/a' }, suspendedMs=${suspendedRemainingMs}`, ); scheduleWebglRecoveryAttempt( reason, Math.max(WEBGL_RECOVERY_SUSPEND_DEFER_MIN_MS, suspendedRemainingMs), ); return; } currentRecoveryAttemptId = attemptId || currentRecoveryAttemptId + 1; const attemptNumber = Math.max(1, webglFailureCount); clearTimer(TIMER_KEYS.rendererFreezeRelease); rendererFreezeReleasePending = false; removeRendererFreezeOverlay(); createRendererFreezeOverlay(); logInfo( 'Attempting to restore WebGL renderer.', `cycle=${ currentRecoveryCycleId || 'n/a' }, attempt=${currentRecoveryAttemptId}, reason=${ reason || 'unknown' }, failureCount=${webglFailureCount}, heuristicAttempt=${attemptNumber}`, ); if ( tryEnableWebgl(reason || 'recovery', { fitAfterEnable: false, focusAfterEnable: false, }) ) { return; } webglFailureCount += 1; lastWebglFailureReason = 'webgl-load-failed'; const delayMs = WEBGL_RECOVERY_DELAY_STEPS_MS[webglFailureCount - 1]; if (typeof delayMs === 'number') { scheduleWebglRecoveryAttempt(lastWebglFailureReason, delayMs); return; } requestWebglRecoveryEscalation(lastWebglFailureReason); }; const degradeRenderer = reason => { if (activeRendererMode !== 'webgl' && !webglAddon) { return; } rendererRecoveryCycleId += 1; currentRecoveryCycleId = rendererRecoveryCycleId; currentRecoveryAttemptId = 0; activeRendererMode = 'recovering'; lastWebglFailureReason = reason; webglFailureCount += 1; rendererFallbackPending = true; clearRendererStallWriteGrace(); clearWebglStabilityTimer(); clearWebglRecoveryTimer(); clearSilentWebglRecoveryTimer(); clearTimer(TIMER_KEYS.rendererFreezeRelease); rendererFreezeReleasePending = false; removeRendererFreezeOverlay(); logWarn( 'Renderer degraded; freezing current frame before recovery.', reason ? `cycle=${currentRecoveryCycleId}, reason=${reason}, failureCount=${webglFailureCount}` : `cycle=${currentRecoveryCycleId}, failureCount=${webglFailureCount}`, ); const hasFreezeOverlay = isContainerVisible() && createRendererFreezeOverlay(); disposeWebglAddon(); if (!hasFreezeOverlay) { commitVisibleFallbackRenderer(reason); return; } scheduleSilentWebglRecovery(reason); }; const rendererHealthTimer = setInterval(() => { if (activeRendererMode !== 'webgl' || !webglAddon) { return; } if (!isContainerVisible()) { return; } if (!pendingVisualUpdate || pendingRenderSince <= 0) { return; } const now = Date.now(); if (now < rendererHealthSuspendedUntil) { return; } if (now - rendererStallReportedAt < RENDER_STALL_TIMEOUT_MS) { return; } const hasCoreRenderStall = now - pendingRenderSince >= RENDER_STALL_TIMEOUT_MS && now - lastRenderAt >= RENDER_STALL_TIMEOUT_MS; if (!hasCoreRenderStall) { clearRendererStallWriteGrace(); return; } const lastWriteActivityAt = Math.max( lastWriteParsedAt || 0, lastWriteCallbackAt || 0, ); if ( lastWriteActivityAt > 0 && now - lastWriteActivityAt <= RENDER_STALL_WRITE_ACTIVITY_GRACE_MS ) { const nextGraceUntil = lastWriteActivityAt + RENDER_STALL_WRITE_ACTIVITY_GRACE_MS; if ( rendererStallWriteGracePendingSince !== pendingRenderSince || nextGraceUntil > rendererStallWriteGraceUntil ) { rendererStallWriteGracePendingSince = pendingRenderSince; rendererStallWriteGraceUntil = nextGraceUntil; return; } if (now < rendererStallWriteGraceUntil) { return; } } clearRendererStallWriteGrace(); rendererStallReportedAt = now; degradeRenderer('render-stall'); }, RENDER_STALL_CHECK_INTERVAL_MS); const resizeObserver = new ResizeObserver(() => { scheduleFit(); }); resizeObserver.observe(container); const initialFitTimer = setTimeout(fitTerminal, 100); if (document.fonts && document.fonts.ready) { document.fonts.ready .then(() => { fitTerminal(); }) .catch(() => { // Ignore font readiness errors. }); } registerDisposable( term.onRender(() => { lastRenderAt = Date.now(); bytesPendingRender = 0; pendingVisualUpdate = false; pendingRenderSince = 0; clearRendererStallWriteGrace(); if (rendererFreezeReleasePending) { releaseRendererFreezeOverlay(); } }), ); registerDisposable( term.onWriteParsed(() => { lastWriteParsedAt = Date.now(); }), ); registerDisposable( term.onData(data => { sendInput(data); }), ); registerDisposable( term.onBell(() => { playTerminalBell(); }), ); // AudioContext starts suspended in webviews until a user gesture occurs; // arm it on first interaction so subsequent bells can produce sound. addManagedListener(container, 'pointerdown', unlockTerminalAudio); addManagedListener(container, 'keydown', unlockTerminalAudio); const {allowTerminalKeyEvent, handleContextMenu} = createClipboardAndContextController({term, sendInput}); // On macOS, Ctrl+V passes through to CLI which handles paste (including images). // On Windows/Linux, Ctrl+V must be intercepted to suppress the raw \x16 that // xterm would otherwise emit. We return false so xterm ignores the keydown, // but do NOT call preventDefault — the browser / VS Code webview will still // fire a paste event which xterm's built-in paste handler processes via onData. term.attachCustomKeyEventHandler(allowTerminalKeyEvent); const { handleContainerMouseDown, handleVisibilityChange, handleWindowFocus, } = createWindowLifecycleController({ scheduleFocusRecovery, setRendererHealthSuspended, suspendAfterLayoutMs: RENDERER_HEALTH_SUSPEND_AFTER_LAYOUT_MS, getActiveRendererMode: () => activeRendererMode, getLastWebglFailureReason: () => lastWebglFailureReason, scheduleWebglRecoveryAttempt, webglRecoveryRecheckMs: WEBGL_RECOVERY_RECHECK_MS, }); const resetTerminalViewport = () => { try { term.reset(); } catch { term.clear(); } bytesPendingRender = 0; pendingVisualUpdate = false; pendingRenderSince = 0; clearRendererStallWriteGrace(); }; const messageHandlers = { syncTabs: payload => { applyTabs(payload.tabs); }, replaceTerminalContent: payload => { if (typeof payload.data !== 'string') { return; } if ( typeof payload.tabId === 'string' && currentTabId && payload.tabId !== currentTabId ) { return; } if (typeof payload.tabId === 'string') { currentTabId = payload.tabId; } resetTerminalViewport(); if (payload.data.length === 0) { return; } const now = Date.now(); lastOutputAt = now; bytesPendingRender = payload.data.length; pendingVisualUpdate = true; pendingRenderSince = now; term.write(payload.data, () => { lastWriteCallbackAt = Date.now(); }); }, output: payload => { if (typeof payload.data !== 'string') { return; } if ( typeof payload.tabId === 'string' && currentTabId && payload.tabId !== currentTabId ) { return; } const now = Date.now(); lastOutputAt = now; bytesPendingRender += payload.data.length; if (!pendingVisualUpdate) { pendingVisualUpdate = true; pendingRenderSince = now; } term.write(payload.data, () => { lastWriteCallbackAt = Date.now(); }); }, clear: payload => { if ( typeof payload.tabId === 'string' && currentTabId && payload.tabId !== currentTabId ) { return; } resetTerminalViewport(); }, fit: () => { fitTerminal(); }, focus: () => { scheduleFocusRecovery(); }, updateFont: payload => { applyTermOption(term.options, 'fontFamily', payload.fontFamily); applyTermOption(term.options, 'fontSize', payload.fontSize); applyTermOption(term.options, 'fontWeight', payload.fontWeight); applyTermOption(term.options, 'lineHeight', payload.lineHeight); fitTerminal(); scheduleFocusRecovery(); }, updateBell: payload => { updateBellConfig(payload); }, exit: payload => { if ( typeof payload.tabId === 'string' && currentTabId && payload.tabId !== currentTabId ) { return; } term.write(`\r\n\r\n[Process exited with code ${payload.code}]\r\n`); }, }; const handleWindowMessage = createWindowMessageRouter({ messageHandlers, }); if (renderStallTestButton) { addManagedListener(renderStallTestButton, 'click', () => { runRendererHealthTest('render-stall'); }); } if (contextLossTestButton) { addManagedListener(contextLossTestButton, 'click', () => { runRendererHealthTest('context-loss'); }); } addManagedListener(container, 'mousedown', handleContainerMouseDown); addManagedListener(document, 'visibilitychange', handleVisibilityChange); addManagedListener(window, 'focus', handleWindowFocus); addManagedListener(container, 'contextmenu', handleContextMenu); addManagedListener(window, 'message', handleWindowMessage); addManagedListener(window, 'beforeunload', runCleanups); let dragEnterCount = 0; addManagedListener(container, 'dragenter', event => { event.preventDefault(); dragEnterCount++; container.classList.add('drag-over'); }); addManagedListener(container, 'dragover', event => { event.preventDefault(); if (event.dataTransfer) { event.dataTransfer.dropEffect = 'copy'; } }); addManagedListener(container, 'dragleave', () => { dragEnterCount--; if (dragEnterCount <= 0) { dragEnterCount = 0; container.classList.remove('drag-over'); } }); addManagedListener(container, 'drop', event => { event.preventDefault(); event.stopPropagation(); dragEnterCount = 0; container.classList.remove('drag-over'); const uriList = event.dataTransfer && event.dataTransfer.getData('text/uri-list'); if (uriList) { const uris = uriList .split(/\r?\n/) .filter(line => line && !line.startsWith('#')); if (uris.length > 0) { vscode.postMessage({type: 'dropPaths', uris}); return; } } const plain = event.dataTransfer && event.dataTransfer.getData('text/plain'); if (plain) { const lines = plain.split(/\r?\n/).filter(Boolean); if (lines.length > 0) { vscode.postMessage({type: 'dropPaths', uris: lines}); } } }); registerCleanup(() => { clearFocusRecoveryTimers(); clearInterval(rendererHealthTimer); clearAllTimers(); clearTimeout(initialFitTimer); releaseRendererFreezeOverlay(); resizeObserver.disconnect(); }); if (!tryEnableWebgl('initial-load')) { if (!isWebglAddonAvailable()) { logWarn( 'Initial WebGL enable skipped because addon is unavailable; remaining on fallback renderer.', ); } else { webglFailureCount = Math.max(1, webglFailureCount); lastWebglFailureReason = lastWebglFailureReason || 'initial-load-failed'; logWarn( 'Initial WebGL enable failed; scheduling recovery attempt.', `reason=${lastWebglFailureReason}, delayMs=${WEBGL_RECOVERY_DELAY_STEPS_MS[0]}`, ); scheduleWebglRecoveryAttempt( lastWebglFailureReason, WEBGL_RECOVERY_DELAY_STEPS_MS[0], ); } } scheduleFocusRecovery(); logInfo('Sidebar terminal frontend ready.'); vscode.postMessage({type: 'ready'}); } catch (error) { if (error instanceof Error) { showError(error.stack || error.message); return; } showError(String(error)); } })(); ================================================ FILE: VSIX/src/aceHandlers.ts ================================================ import * as vscode from 'vscode'; /** * ACE Code Search Handlers * Provides Go to Definition, Find References, Get Symbols, and Diagnostics functionality */ export type BroadcastFunction = (message: string) => void; /** * Handle Go to Definition request */ export async function handleGoToDefinition( filePath: string, line: number, column: number, requestId: string, broadcast: BroadcastFunction, ): Promise { try { const uri = vscode.Uri.file(filePath); const position = new vscode.Position(line, column); // Use VS Code's built-in go to definition const definitions = await vscode.commands.executeCommand( 'vscode.executeDefinitionProvider', uri, position, ); const results = (definitions || []).map(def => ({ filePath: def.uri.fsPath, line: def.range.start.line, column: def.range.start.character, endLine: def.range.end.line, endColumn: def.range.end.character, })); // Send response back broadcast( JSON.stringify({ type: 'aceGoToDefinitionResult', requestId, definitions: results, }), ); } catch (error) { // On error, send empty results broadcast( JSON.stringify({ type: 'aceGoToDefinitionResult', requestId, definitions: [], }), ); } } /** * Handle Find References request */ export async function handleFindReferences( filePath: string, line: number, column: number, requestId: string, broadcast: BroadcastFunction, ): Promise { try { const uri = vscode.Uri.file(filePath); const position = new vscode.Position(line, column); // Use VS Code's built-in find references const references = await vscode.commands.executeCommand( 'vscode.executeReferenceProvider', uri, position, ); const results = (references || []).map(ref => ({ filePath: ref.uri.fsPath, line: ref.range.start.line, column: ref.range.start.character, endLine: ref.range.end.line, endColumn: ref.range.end.character, })); // Send response back broadcast( JSON.stringify({ type: 'aceFindReferencesResult', requestId, references: results, }), ); } catch (error) { // On error, send empty results broadcast( JSON.stringify({ type: 'aceFindReferencesResult', requestId, references: [], }), ); } } /** * Handle Get Symbols request */ export async function handleGetSymbols( filePath: string, requestId: string, broadcast: BroadcastFunction, ): Promise { try { const uri = vscode.Uri.file(filePath); // Use VS Code's built-in document symbol provider const symbols = await vscode.commands.executeCommand< vscode.DocumentSymbol[] >('vscode.executeDocumentSymbolProvider', uri); const flattenSymbols = (symbolList: vscode.DocumentSymbol[]): any[] => { const result: any[] = []; for (const symbol of symbolList) { result.push({ name: symbol.name, kind: vscode.SymbolKind[symbol.kind], line: symbol.range.start.line, column: symbol.range.start.character, endLine: symbol.range.end.line, endColumn: symbol.range.end.character, detail: symbol.detail, }); if (symbol.children && symbol.children.length > 0) { result.push(...flattenSymbols(symbol.children)); } } return result; }; const results = symbols ? flattenSymbols(symbols) : []; // Send response back broadcast( JSON.stringify({ type: 'aceGetSymbolsResult', requestId, symbols: results, }), ); } catch (error) { // On error, send empty results broadcast( JSON.stringify({ type: 'aceGetSymbolsResult', requestId, symbols: [], }), ); } } /** * Handle Get Diagnostics request */ export function handleGetDiagnostics( filePath: string, requestId: string, broadcast: BroadcastFunction, ): void { // Get diagnostics for the file const uri = vscode.Uri.file(filePath); const diagnostics = vscode.languages.getDiagnostics(uri); // Convert to simpler format const simpleDiagnostics = diagnostics.map(d => ({ message: d.message, severity: ['error', 'warning', 'info', 'hint'][d.severity], line: d.range.start.line, character: d.range.start.character, source: d.source, code: d.code, })); // Send response back to all connected clients broadcast( JSON.stringify({ type: 'diagnostics', requestId, diagnostics: simpleDiagnostics, }), ); } ================================================ FILE: VSIX/src/commitMessageGenerator.ts ================================================ import * as vscode from 'vscode'; import {execFile} from 'child_process'; import {existsSync, readFileSync} from 'fs'; import {homedir} from 'os'; import {join} from 'path'; const GENERATING_CONTEXT_KEY = 'snow-cli.commitMessageGenerating'; const CONFIG_DIR = join(homedir(), '.snow'); const ACTIVE_PROFILE_FILE = join(CONFIG_DIR, 'active-profile.json'); const LEGACY_ACTIVE_PROFILE_FILE = join(CONFIG_DIR, 'active-profile.txt'); const PROFILES_DIR = join(CONFIG_DIR, 'profiles'); const LEGACY_CONFIG_FILE = join(CONFIG_DIR, 'config.json'); const CUSTOM_HEADERS_FILE = join(CONFIG_DIR, 'custom-headers.json'); const MAX_DIFF_CHARS = 120_000; const API_MAX_RETRIES = 5; const API_RETRY_BASE_DELAY_MS = 1000; let activeAbortController: AbortController | undefined; interface GenerateCommitMessageOptions { additionalRequirements?: string; } type RequestMethod = 'chat' | 'responses' | 'gemini' | 'anthropic'; interface SnowApiConfig { baseUrl: string; apiKey: string; requestMethod: RequestMethod; advancedModel?: string; basicModel?: string; maxTokens?: number; streamIdleTimeoutSec?: number; customHeadersSchemeId?: string; } interface SnowAppConfig { snowcfg?: SnowApiConfig; } interface GitExtension { getAPI(version: 1): GitAPI; } interface GitAPI { repositories: GitRepository[]; } interface GitRepository { rootUri: vscode.Uri; inputBox: { value: string; }; } interface DiffPayload { diff: string; source: 'staged' | 'working-tree'; truncated: boolean; } interface CustomHeadersConfig { active?: string; schemes?: Array<{ id?: string; headers?: Record; }>; } export function registerCommitMessageCommands( context: vscode.ExtensionContext, ): void { void vscode.commands.executeCommand( 'setContext', GENERATING_CONTEXT_KEY, false, ); context.subscriptions.push( vscode.commands.registerCommand('snow-cli.generateCommitMessage', () => generateCommitMessage(), ), vscode.commands.registerCommand( 'snow-cli.generateCommitMessageWithRequirements', generateCommitMessageWithRequirements, ), vscode.commands.registerCommand( 'snow-cli.cancelCommitMessageGeneration', cancelCommitMessageGeneration, ), ); } async function generateCommitMessageWithRequirements(): Promise { if (activeAbortController) { cancelCommitMessageGeneration(); return; } const additionalRequirements = await vscode.window.showInputBox({ title: 'Snow CLI: Commit Message Requirements', prompt: 'Add optional requirements for the generated commit message.', placeHolder: 'For example: Use Chinese; follow Conventional Commits.', ignoreFocusOut: true, }); if (additionalRequirements === undefined) { return; } await generateCommitMessage({ additionalRequirements: additionalRequirements.trim() || undefined, }); } async function generateCommitMessage( options: GenerateCommitMessageOptions = {}, ): Promise { if (activeAbortController) { cancelCommitMessageGeneration(); return; } const repository = await getTargetRepository(); if (!repository) { vscode.window.showWarningMessage('Snow CLI: No Git repository found.'); return; } const abortController = new AbortController(); activeAbortController = abortController; await vscode.commands.executeCommand( 'setContext', GENERATING_CONTEXT_KEY, true, ); try { await vscode.window.withProgress( { location: vscode.ProgressLocation.SourceControl, title: 'Snow CLI: Generating commit message', }, async () => { const payload = await collectDiffPayload( repository.rootUri.fsPath, abortController.signal, ); if (!payload.diff.trim()) { vscode.window.showInformationMessage( 'Snow CLI: No staged or working tree changes found.', ); return; } const message = await requestCommitMessage( payload, abortController.signal, options.additionalRequirements, ); repository.inputBox.value = normalizeCommitMessage(message); }, ); } catch (error) { if (isAbortError(error)) { vscode.window.showInformationMessage( 'Snow CLI: Commit message generation stopped.', ); return; } const message = error instanceof Error ? error.message : String(error); vscode.window.showErrorMessage( `Snow CLI: Failed to generate commit message. ${message}`, ); } finally { if (activeAbortController === abortController) { activeAbortController = undefined; await vscode.commands.executeCommand( 'setContext', GENERATING_CONTEXT_KEY, false, ); } } } function cancelCommitMessageGeneration(): void { activeAbortController?.abort(); } async function getTargetRepository(): Promise { const gitExtension = vscode.extensions.getExtension('vscode.git'); if (!gitExtension) { return undefined; } const git = gitExtension.isActive ? gitExtension.exports : await gitExtension.activate(); const api = git.getAPI(1); const repositories = api.repositories; if (repositories.length === 0) { return undefined; } const activePath = vscode.window.activeTextEditor?.document.uri.fsPath; if (!activePath) { return repositories[0]; } return ( repositories .filter(repository => activePath.startsWith(repository.rootUri.fsPath)) .sort((a, b) => b.rootUri.fsPath.length - a.rootUri.fsPath.length)[0] ?? repositories[0] ); } async function collectDiffPayload( repositoryRoot: string, signal: AbortSignal, ): Promise { const stagedDiff = await execGit( ['diff', '--cached', '--no-ext-diff'], repositoryRoot, signal, ); const source: DiffPayload['source'] = stagedDiff.trim() ? 'staged' : 'working-tree'; const fullDiff = stagedDiff.trim() ? stagedDiff : await execGit(['diff', '--no-ext-diff'], repositoryRoot, signal); const truncated = fullDiff.length > MAX_DIFF_CHARS; return { diff: truncated ? fullDiff.slice(0, MAX_DIFF_CHARS) : fullDiff, source, truncated, }; } function execGit( args: string[], cwd: string, signal: AbortSignal, ): Promise { return new Promise((resolve, reject) => { if (signal.aborted) { reject(createAbortError()); return; } const child = execFile( 'git', args, {cwd, maxBuffer: MAX_DIFF_CHARS * 4}, (error, stdout, stderr) => { signal.removeEventListener('abort', abortListener); if (signal.aborted) { reject(createAbortError()); return; } if (error) { reject(new Error(stderr.trim() || error.message)); return; } resolve(stdout); }, ); const abortListener = () => { child.kill(); reject(createAbortError()); }; signal.addEventListener('abort', abortListener, {once: true}); }); } async function requestCommitMessage( payload: DiffPayload, signal: AbortSignal, additionalRequirements?: string, ): Promise { const config = loadActiveSnowConfig(); const model = config.basicModel?.trim(); if (!model) { throw new Error('Basic model is not configured.'); } const requestMethod = config.requestMethod || 'chat'; const messages = buildPrompt(payload, additionalRequirements); return withApiRetry(() => { switch (requestMethod) { case 'responses': return requestResponsesCommitMessage(config, model, messages, signal); case 'gemini': return requestGeminiCommitMessage(config, model, messages, signal); case 'anthropic': return requestAnthropicCommitMessage(config, model, messages, signal); case 'chat': default: return requestChatCommitMessage(config, model, messages, signal); } }, signal); } function loadActiveSnowConfig(): SnowApiConfig { const profileName = getActiveProfileName(); const profilePath = join(PROFILES_DIR, `${profileName}.json`); const config = readJsonFile(profilePath) ?? readJsonFile(LEGACY_CONFIG_FILE); const snowcfg = config?.snowcfg; if (!snowcfg) { throw new Error('Snow configuration not found.'); } return snowcfg; } function getActiveProfileName(): string { const activeProfile = readJsonFile<{activeProfile?: string}>( ACTIVE_PROFILE_FILE, ); if (activeProfile?.activeProfile) { return activeProfile.activeProfile; } if (existsSync(LEGACY_ACTIVE_PROFILE_FILE)) { const profileName = readFileSync(LEGACY_ACTIVE_PROFILE_FILE, 'utf8').trim(); return profileName || 'default'; } return 'default'; } function readJsonFile(filePath: string): T | undefined { if (!existsSync(filePath)) { return undefined; } try { return JSON.parse(readFileSync(filePath, 'utf8')) as T; } catch { return undefined; } } function buildPrompt( payload: DiffPayload, additionalRequirements?: string, ): {system: string; user: string} { const sourceLabel = payload.source === 'staged' ? 'staged' : 'working tree'; const truncatedNotice = payload.truncated ? '\n\nNote: The diff was truncated because it is large.' : ''; const requirementNotice = additionalRequirements?.trim() ? `\n\nAdditional requirements from the user:\n${additionalRequirements.trim()}` : ''; return { system: [ 'You generate clear Git commit messages.', 'Return only the final commit message, with no markdown, no quotes, and no explanation.', 'Use an appropriate level of detail for the changes; include a body when it helps explain important context.', 'Prefer Conventional Commit style when it fits, for example: feat: add login validation.', ].join(' '), user: `Generate one commit message for the ${sourceLabel} changes below.${truncatedNotice}${requirementNotice}\n\n${payload.diff}`, }; } async function requestChatCommitMessage( config: SnowApiConfig, model: string, messages: {system: string; user: string}, signal: AbortSignal, ): Promise { const url = `${trimTrailingSlash(config.baseUrl)}/chat/completions`; const response = await fetch(url, { method: 'POST', headers: buildHeaders(config), body: JSON.stringify({ model, messages: [ {role: 'system', content: messages.system}, {role: 'user', content: messages.user}, ], stream: false, temperature: 0.2, }), signal, }); const data = await readResponseJson(response, 'OpenAI Chat API'); return data.choices?.[0]?.message?.content ?? ''; } async function requestResponsesCommitMessage( config: SnowApiConfig, model: string, messages: {system: string; user: string}, signal: AbortSignal, ): Promise { const url = `${trimTrailingSlash(config.baseUrl)}/responses`; const response = await fetch(url, { method: 'POST', headers: buildHeaders(config), body: JSON.stringify({ model, instructions: messages.system, input: messages.user, store: false, }), signal, }); const data = await readResponseJson(response, 'OpenAI Responses API'); return extractResponsesText(data); } async function requestGeminiCommitMessage( config: SnowApiConfig, model: string, messages: {system: string; user: string}, signal: AbortSignal, ): Promise { const baseUrl = config.baseUrl && config.baseUrl !== 'https://api.openai.com/v1' ? trimTrailingSlash(config.baseUrl) : 'https://generativelanguage.googleapis.com/v1beta'; const modelName = model.startsWith('models/') ? model : `models/${model}`; const url = `${baseUrl}/${modelName}:generateContent`; const response = await fetch(url, { method: 'POST', headers: buildHeaders(config, 'gemini'), body: JSON.stringify({ contents: [ { role: 'user', parts: [{text: `${messages.system}\n\n${messages.user}`}], }, ], generationConfig: { temperature: 0.2, }, }), signal, }); const data = await readResponseJson(response, 'Gemini API'); return ( data.candidates?.[0]?.content?.parts ?.map((part: {text?: string}) => part.text ?? '') .join('') ?? '' ); } async function requestAnthropicCommitMessage( config: SnowApiConfig, model: string, messages: {system: string; user: string}, signal: AbortSignal, ): Promise { const baseUrl = config.baseUrl && config.baseUrl !== 'https://api.openai.com/v1' ? trimTrailingSlash(config.baseUrl) : 'https://api.anthropic.com/v1'; const response = await fetch(`${baseUrl}/messages`, { method: 'POST', headers: buildHeaders(config, 'anthropic'), body: JSON.stringify({ model, max_tokens: 4096, temperature: 0.2, system: messages.system, messages: [{role: 'user', content: messages.user}], }), signal, }); const data = await readResponseJson(response, 'Anthropic API'); return ( data.content ?.map((part: {type?: string; text?: string}) => part.type === 'text' ? part.text ?? '' : '', ) .join('') ?? '' ); } function buildHeaders( config: SnowApiConfig, provider?: 'gemini' | 'anthropic', ): Record { const headers: Record = { 'Content-Type': 'application/json', ...loadCustomHeaders(config), }; if (config.apiKey) { headers.Authorization = `Bearer ${config.apiKey}`; } if (provider === 'gemini' && config.apiKey) { headers['x-goog-api-key'] = config.apiKey; } if (provider === 'anthropic' && config.apiKey) { headers['x-api-key'] = config.apiKey; } return headers; } function loadCustomHeaders(config: SnowApiConfig): Record { const customHeadersConfig = readJsonFile(CUSTOM_HEADERS_FILE); const schemeId = config.customHeadersSchemeId === undefined ? customHeadersConfig?.active : config.customHeadersSchemeId; if (!schemeId) { return {}; } return ( customHeadersConfig?.schemes?.find(scheme => scheme.id === schemeId) ?.headers ?? {} ); } async function readResponseJson( response: Response, apiName: string, ): Promise { if (!response.ok) { const errorText = await response.text(); throw new ApiRequestError( `${apiName} error: ${response.status} ${response.statusText} - ${errorText}`, response.status, response.statusText, errorText, ); } return response.json(); } class ApiRequestError extends Error { constructor( message: string, readonly status: number, readonly statusText: string, readonly responseText: string, ) { super(message); this.name = 'ApiRequestError'; } } async function withApiRetry( fn: () => Promise, signal: AbortSignal, ): Promise { let lastError: unknown; for (let attempt = 0; attempt <= API_MAX_RETRIES; attempt++) { if (signal.aborted) { throw createAbortError(); } try { return await fn(); } catch (error) { lastError = error; if (isAbortError(error) || !isRetriableApiError(error)) { throw error; } if (attempt >= API_MAX_RETRIES) { throw error; } await delay(API_RETRY_BASE_DELAY_MS * Math.pow(2, attempt), signal); } } throw lastError instanceof Error ? lastError : new Error(String(lastError)); } function isRetriableApiError(error: unknown): boolean { if (error instanceof ApiRequestError) { return error.status === 429 || error.status >= 500; } if (!(error instanceof Error)) { return false; } const message = error.message.toLowerCase(); return ( message.includes('network') || message.includes('econnrefused') || message.includes('econnreset') || message.includes('etimedout') || message.includes('timeout') || message.includes('rate limit') || message.includes('too many requests') || message.includes('service unavailable') || message.includes('temporarily unavailable') || message.includes('bad gateway') || message.includes('gateway timeout') || message.includes('internal server error') ); } function delay(ms: number, signal: AbortSignal): Promise { return new Promise((resolve, reject) => { if (signal.aborted) { reject(createAbortError()); return; } const timer = setTimeout(() => { cleanup(); resolve(); }, ms); const abortListener = () => { cleanup(); reject(createAbortError()); }; const cleanup = () => { clearTimeout(timer); signal.removeEventListener('abort', abortListener); }; signal.addEventListener('abort', abortListener, {once: true}); }); } function extractResponsesText(data: any): string { if (typeof data.output_text === 'string') { return data.output_text; } return ( data.output ?.flatMap((item: any) => item.content ?? []) .map((content: any) => content.text ?? '') .join('') ?? '' ); } function normalizeCommitMessage(message: string): string { const normalized = message .trim() .replace(/^```(?:[\w-]+)?\s*/u, '') .replace(/```$/u, '') .trim() .replace(/^['"]|['"]$/gu, '') .replace(/^commit message:\s*/iu, '') .trim(); if (!normalized) { throw new Error('The model returned an empty commit message.'); } return normalized; } function trimTrailingSlash(value: string): string { return value.replace(/\/+$/u, ''); } function createAbortError(): Error { const error = new Error('Commit message generation cancelled.'); error.name = 'AbortError'; return error; } function isAbortError(error: unknown): boolean { return error instanceof Error && error.name === 'AbortError'; } ================================================ FILE: VSIX/src/diffHandlers.ts ================================================ import * as vscode from 'vscode'; /** * Diff Handlers * Provides showDiff, closeDiff, and showGitDiff functionality */ // Track active diff editors let activeDiffEditors: vscode.Uri[] = []; // Shared content map keyed by URI string. Persists across multiple showDiff // invocations so that VSCode can re-query content for any open diff editor. const diffContentMap = new Map(); // Track whether content providers for our virtual schemes have been registered. // VSCode only uses the most-recently-registered provider for a given scheme, // so we MUST register exactly once per scheme and keep them alive while diffs // are open. Otherwise newly opened diffs replace previous providers and earlier // diff editors lose access to their content (showing empty diffs). let originalProviderDisposable: vscode.Disposable | null = null; let newProviderDisposable: vscode.Disposable | null = null; function ensureContentProvidersRegistered(): void { if (!originalProviderDisposable) { originalProviderDisposable = vscode.workspace.registerTextDocumentContentProvider( 'snow-cli-original', { provideTextDocumentContent: uri => { return diffContentMap.get(uri.toString()) ?? ''; }, }, ); } if (!newProviderDisposable) { newProviderDisposable = vscode.workspace.registerTextDocumentContentProvider('snow-cli-new', { provideTextDocumentContent: uri => { return diffContentMap.get(uri.toString()) ?? ''; }, }); } } function disposeContentProviders(): void { if (originalProviderDisposable) { originalProviderDisposable.dispose(); originalProviderDisposable = null; } if (newProviderDisposable) { newProviderDisposable.dispose(); newProviderDisposable = null; } diffContentMap.clear(); } /** * Show git diff for a file in VSCode * Opens the file's git changes in a diff view */ export async function showGitDiff(filePath: string): Promise { console.log('[Snow Extension] showGitDiff called for:', filePath); try { const path = require('path'); const fs = require('fs'); const {execFile} = require('child_process'); // Ensure absolute path const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath; const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(workspaceRoot || '', filePath); const fileUri = vscode.Uri.file(absolutePath); const repoRoot = vscode.workspace.getWorkspaceFolder(fileUri)?.uri.fsPath ?? workspaceRoot; if (!repoRoot) { throw new Error('No workspace folder found for git diff'); } // Compute path relative to repo root for git show const relPath = path.relative(repoRoot, absolutePath).replace(/\\/g, '/'); const newContent = fs.readFileSync(absolutePath, 'utf8'); let originalContent = ''; try { originalContent = await new Promise((resolve, reject) => { execFile( 'git', ['show', `HEAD:${relPath}`], {cwd: repoRoot, maxBuffer: 50 * 1024 * 1024}, (error: any, stdout: string, stderr: string) => { if (error) { reject(new Error(stderr || String(error))); return; } resolve(stdout); }, ); }); } catch (error) { // File may be new/untracked or missing in HEAD; fall back to empty original content console.log( '[Snow Extension] git show failed, using empty base:', error instanceof Error ? error.message : String(error), ); } await vscode.commands.executeCommand('snow-cli.showDiff', { filePath: absolutePath, originalContent, newContent, label: 'Git Diff', }); } catch (error) { console.error('[Snow Extension] Failed to show git diff:', error); try { const uri = vscode.Uri.file(filePath); await vscode.window.showTextDocument(uri, {preview: true}); } catch { // Ignore errors } } } /** * Register diff-related commands * Returns an array of disposables that should be added to context.subscriptions */ export function registerDiffCommands( _context: vscode.ExtensionContext, ): vscode.Disposable[] { const disposables: vscode.Disposable[] = []; // Register command to show diff in VSCode const showDiffDisposable = vscode.commands.registerCommand( 'snow-cli.showDiff', async (data: { filePath: string; originalContent: string; newContent: string; label: string; // When true, do NOT preserve focus on the previously active editor // (terminal). Used by diff-review multi-file flow so each diff // becomes a real, pinned tab rather than being replaced by the // next vscode.diff call (which can happen if focus stays on the // terminal and the active editor group is empty/unstable). takeFocus?: boolean; }) => { try { const {filePath, originalContent, newContent, label, takeFocus} = data; // Create virtual URIs for diff view with unique identifier const uri = vscode.Uri.file(filePath); const uniqueId = `${Date.now()}-${Math.random() .toString(36) .substring(7)}`; const originalUri = uri.with({ scheme: 'snow-cli-original', query: uniqueId, }); const newUri = uri.with({ scheme: 'snow-cli-new', query: uniqueId, }); // Track these URIs for later cleanup activeDiffEditors.push(originalUri, newUri); // Store content in the SHARED content map. Using one persistent // map (not a per-call local one) is critical because VSCode may // re-query the content provider at any time while the diff // editor is open, including after subsequent showDiff calls // register new content for other files. diffContentMap.set(originalUri.toString(), originalContent); diffContentMap.set(newUri.toString(), newContent); // Register the content providers exactly once. Re-registering // the same scheme would replace the prior provider and break // previously opened diff editors. ensureContentProvidersRegistered(); // Show diff view. By default we preserve focus so single-file // edit confirmations don't yank focus from the terminal. For // the multi-file diff review flow, the caller passes // takeFocus=true so each tab is properly created+visible. const fileName = filePath.split(/[\\/]/).pop() || 'file'; const title = `${label}: ${fileName}`; await vscode.commands.executeCommand( 'vscode.diff', originalUri, newUri, title, { preview: false, preserveFocus: !takeFocus, viewColumn: vscode.ViewColumn.Active, }, ); } catch (error) { vscode.window.showErrorMessage( `Failed to show diff: ${ error instanceof Error ? error.message : String(error) }`, ); } }, ); // Register command to show diff review (multiple files) const showDiffReviewDisposable = vscode.commands.registerCommand( 'snow-cli.showDiffReview', async (data: { files: Array<{ filePath: string; originalContent: string; newContent: string; }>; }) => { try { const {files} = data; if (!files || files.length === 0) { vscode.window.showInformationMessage('No file changes to review'); return; } for (const file of files) { await vscode.commands.executeCommand('snow-cli.showDiff', { filePath: file.filePath, originalContent: file.originalContent, newContent: file.newContent, label: 'Diff Review', takeFocus: true, }); // Yield a tick so VSCode can fully realize the new diff tab // before we open the next one. Without this, a rapid // sequence of vscode.diff calls can collapse into a single // visible tab (later ones replace earlier ones in the same // editor slot). await new Promise(resolve => setTimeout(resolve, 80)); } } catch (error) { vscode.window.showErrorMessage( `Failed to show diff review: ${ error instanceof Error ? error.message : String(error) }`, ); } }, ); // Register command to close diff views const closeDiffDisposable = vscode.commands.registerCommand( 'snow-cli.closeDiff', () => { // Close only the diff editors we opened const editors = vscode.window.tabGroups.all .flatMap(group => group.tabs) .filter(tab => { if (tab.input instanceof vscode.TabInputTextDiff) { const original = tab.input.original; const modified = tab.input.modified; return ( activeDiffEditors.some( uri => uri.toString() === original.toString(), ) || activeDiffEditors.some( uri => uri.toString() === modified.toString(), ) ); } return false; }); // Close each matching tab editors.forEach(tab => { vscode.window.tabGroups.close(tab); }); // Clear the tracking array and dispose shared providers/content activeDiffEditors = []; disposeContentProviders(); }, ); disposables.push( showDiffDisposable, showDiffReviewDisposable, closeDiffDisposable, ); return disposables; } ================================================ FILE: VSIX/src/extension.ts ================================================ import * as vscode from 'vscode'; import { startWebSocketServer, stopWebSocketServer, sendEditorContext, } from './webSocketServer'; import {registerDiffCommands} from './diffHandlers'; import {ShellFamily, resolveShellProfile} from './ptyManager'; import {SidebarTerminalProvider} from './sidebarTerminalProvider'; import {startupCommandManager} from './startupCommandManager'; import {formatTerminalPathPayload} from './terminalPathFormatter'; import { getSnowTerminalProxyEnv, hasExplicitSnowTerminalProxyUrl, } from './terminalProxy'; import {registerGitBlame} from './gitBlameProvider'; import {registerCommitMessageCommands} from './commitMessageGenerator'; /** * Snow CLI Extension * Main entry point for the VSCode extension */ let sidebarProvider: SidebarTerminalProvider | undefined; function getConfig(key: string, fallback: T): T { return vscode.workspace.getConfiguration('snow-cli').get(key, fallback); } function refreshStartupCommandManager(): void { const startupCommand = getConfig('startupCommand', 'snow'); startupCommandManager.setStartupCommandConfig(startupCommand); } /** Apply the context key so the sidebar view shows/hides accordingly */ function applySidebarContext(): void { const mode = getConfig('terminalMode', 'sidebar'); vscode.commands.executeCommand( 'setContext', 'snow-cli.sidebarMode', mode === 'sidebar', ); } function getWorkspaceFolderForActiveEditor(): string | undefined { const editor = vscode.window.activeTextEditor; const folder = editor ? vscode.workspace.getWorkspaceFolder(editor.document.uri) : undefined; return ( folder?.uri.fsPath ?? vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ); } function getSplitTerminalShellFamily(): ShellFamily { return resolveShellProfile().family; } function getExistingSplitSnowTerminal(): vscode.Terminal | undefined { const active = vscode.window.activeTerminal; if (active?.name === 'Snow CLI') { return active; } const snowTerminals = vscode.window.terminals.filter( terminal => terminal.name === 'Snow CLI', ); return snowTerminals.at(-1); } /** Create a new split terminal in the right editor column (allows multiple instances) */ async function openSplitTerminal(): Promise { const startupCommand = startupCommandManager.getNextStartupCommand(); const workspaceFolder = getWorkspaceFolderForActiveEditor(); const proxyEnv = getSnowTerminalProxyEnv(); // 1. Create a new terminal in the editor area (initially in current column) const terminal = vscode.window.createTerminal({ name: 'Snow CLI', cwd: workspaceFolder, env: proxyEnv, location: vscode.TerminalLocation.Editor, }); // 2. Show the terminal first terminal.show(); // 3. Move the terminal to the right group (creates right split if needed) await vscode.commands.executeCommand( 'workbench.action.moveEditorToRightGroup', ); if (startupCommand) { terminal.sendText(startupCommand); } return terminal; } async function ensureSplitSnowTerminal(): Promise { const existing = getExistingSplitSnowTerminal(); if (existing) { existing.show(); return existing; } return openSplitTerminal(); } async function sendFilePathsToSplitTerminal(paths: string[]): Promise { if (paths.length === 0) { return; } const terminal = await ensureSplitSnowTerminal(); terminal.sendText( formatTerminalPathPayload(paths, { shellFamily: getSplitTerminalShellFamily(), platform: process.platform, }), false, ); } async function sendFilePathsToConfiguredTerminal( paths: string[], ): Promise { if (paths.length === 0) { return; } const mode = getConfig('terminalMode', 'sidebar'); if (mode === 'sidebar') { sidebarProvider?.sendFilePaths(paths); return; } await sendFilePathsToSplitTerminal(paths); } async function pickPaths(mode: 'file' | 'folder'): Promise { const uris = await vscode.window.showOpenDialog({ canSelectFiles: mode === 'file', canSelectFolders: mode === 'folder', canSelectMany: true, openLabel: mode === 'file' ? 'Add File Path' : 'Add Folder Path', }); return uris?.map(uri => uri.fsPath) ?? []; } function formatSelectionLocation( editor: vscode.TextEditor, ): string | undefined { const {document, selection} = editor; if (selection.isEmpty) { return undefined; } const absolutePath = document.uri.fsPath; if (!absolutePath) { return undefined; } const startLine = selection.start.line; const endLine = selection.end.line > selection.start.line && selection.end.character === 0 ? selection.end.line - 1 : selection.end.line; if (endLine <= startLine) { return `${absolutePath}:${startLine + 1}`; } return `${absolutePath}:${startLine + 1}-${endLine + 1}`; } function checkExtensionVersionChange(context: vscode.ExtensionContext): void { const currentVersion: string = context.extension.packageJSON?.version ?? 'unknown'; const previousVersion = context.globalState.get( 'snow-cli.lastActivatedVersion', ); if (previousVersion === currentVersion) { return; } void context.globalState.update( 'snow-cli.lastActivatedVersion', currentVersion, ); const message = previousVersion ? `Snow CLI has been updated to v${currentVersion}. Please reload the window to activate the terminal properly.` : `Snow CLI v${currentVersion} installed. Please reload the window to activate the terminal properly.`; void vscode.window .showWarningMessage(message, 'Reload Window') .then(choice => { if (choice === 'Reload Window') { void vscode.commands.executeCommand('workbench.action.reloadWindow'); } }); } export function activate(context: vscode.ExtensionContext) { console.log('Snow CLI extension activating...'); checkExtensionVersionChange(context); // 0. Apply context key for sidebar visibility applySidebarContext(); refreshStartupCommandManager(); try { startWebSocketServer(); } catch (err) { console.error('Failed to start WebSocket server:', err); } try { // 2. 注册 Diff 命令 const diffDisposables = registerDiffCommands(context); context.subscriptions.push(...diffDisposables); } catch (err) { console.error('Failed to register diff commands:', err); } try { // 3. 注册 Sidebar Terminal Provider (always register; view visibility controlled by 'when' clause) sidebarProvider = new SidebarTerminalProvider(context.extensionUri); context.subscriptions.push( vscode.window.registerWebviewViewProvider( SidebarTerminalProvider.viewType, sidebarProvider, {webviewOptions: {retainContextWhenHidden: true}}, ), ); } catch (err) { console.error('Failed to register sidebar terminal:', err); } try { registerGitBlame(context); } catch (err) { console.error('Failed to register Git Blame provider:', err); } try { registerCommitMessageCommands(context); } catch (err) { console.error('Failed to register commit message generator:', err); } // 4. 注册命令 context.subscriptions.push( vscode.commands.registerCommand('snow-cli.openTerminal', async () => { const mode = getConfig('terminalMode', 'sidebar'); if (mode === 'sidebar') { await vscode.commands.executeCommand('snowCliTerminal.focus'); sidebarProvider?.ensureTerminal({focus: true}); } else { await openSplitTerminal(); } }), vscode.commands.registerCommand('snow-cli.restartSidebarTerminal', () => { sidebarProvider?.restartTerminal({reason: 'manualRestart'}); }), vscode.commands.registerCommand( 'snow-cli.newSidebarTerminalTab', async () => { const mode = getConfig('terminalMode', 'sidebar'); if (mode === 'sidebar') { await vscode.commands.executeCommand('snowCliTerminal.focus'); sidebarProvider?.createTab({focus: true}); } else { await openSplitTerminal(); } }, ), vscode.commands.registerCommand('snow-cli.openSnowSettings', async () => { await vscode.commands.executeCommand( 'workbench.action.openSettings', '@ext:mufasa.snow-cli', ); }), vscode.commands.registerCommand('snow-cli.addFolderPath', async () => { const paths = await pickPaths('folder'); await sendFilePathsToConfiguredTerminal(paths); }), vscode.commands.registerCommand('snow-cli.addFilePath', async () => { const paths = await pickPaths('file'); await sendFilePathsToConfiguredTerminal(paths); }), vscode.commands.registerCommand('snow-cli.focusSidebar', async () => { const mode = getConfig('terminalMode', 'sidebar'); if (mode === 'sidebar') { await vscode.commands.executeCommand('snowCliTerminal.focus'); sidebarProvider?.ensureTerminal({focus: true}); } else { await openSplitTerminal(); } }), vscode.commands.registerCommand( 'snow-cli.sendSelectionLocation', async () => { const editor = vscode.window.activeTextEditor; if (!editor) { return; } const scheme = editor.document.uri.scheme; if (scheme !== 'file' && scheme !== 'vscode-remote') { return; } const selectionLocation = formatSelectionLocation(editor); if (!selectionLocation) { return; } await sendFilePathsToConfiguredTerminal([selectionLocation]); }, ), vscode.commands.registerCommand( 'snow-cli.sendFilePaths', async (...args: unknown[]) => { // Context menu: (clickedUri, selectedUris) or command palette: no args const selectedUris = args[1] as vscode.Uri[] | undefined; const clickedUri = args[0] as vscode.Uri | undefined; const uris = selectedUris?.length ? selectedUris : clickedUri ? [clickedUri] : []; const paths = uris.map(u => u.fsPath); if (paths.length === 0) { // Fallback: use active editor const active = vscode.window.activeTextEditor?.document.uri.fsPath; if (active) { paths.push(active); } } if (paths.length === 0) { return; } await sendFilePathsToConfiguredTerminal(paths); }, ), ); // 5. 监听编辑器变化 context.subscriptions.push( vscode.window.onDidChangeActiveTextEditor(() => { sendEditorContext(); }), vscode.window.onDidChangeTextEditorSelection(() => { sendEditorContext(); }), vscode.window.onDidChangeVisibleTextEditors(() => { sendEditorContext(); }), ); // 6. 监听配置变化 context.subscriptions.push( vscode.workspace.onDidChangeConfiguration(e => { if (e.affectsConfiguration('snow-cli.terminalMode')) { applySidebarContext(); vscode.window .showInformationMessage( 'Snow CLI: Terminal mode changed. Please reload the window for full effect.', 'Reload', ) .then(choice => { if (choice === 'Reload') { vscode.commands.executeCommand('workbench.action.reloadWindow'); } }); } if (e.affectsConfiguration('snow-cli.startupCommand')) { refreshStartupCommandManager(); } const terminalProxyFallbackChanged = e.affectsConfiguration('http.proxy') && !hasExplicitSnowTerminalProxyUrl(); if ( e.affectsConfiguration('snow-cli.terminal') || terminalProxyFallbackChanged ) { sidebarProvider?.restartTerminal({reason: 'configChange'}); } // Bell settings hot-reload — does not require terminal restart. if (e.affectsConfiguration('snow-cli.bell')) { sidebarProvider?.sendBellConfig(); } }), ); console.log('Snow CLI extension activated'); } export function deactivate() { console.log('Snow CLI extension deactivating...'); sidebarProvider?.dispose(); stopWebSocketServer(); console.log('Snow CLI extension deactivated'); } ================================================ FILE: VSIX/src/gitBlameProvider.ts ================================================ import * as vscode from 'vscode'; import {execFile, type ChildProcess} from 'child_process'; import * as path from 'path'; interface CommitMeta { author: string; authorMail: string; authorTime: number; summary: string; } interface LineBlame { commit: CommitMeta; hash: string; } interface BlameCache { version: number; lines: (LineBlame | undefined)[]; } const UNCOMMITTED_HASH = '0000000000000000000000000000000000000000'; const HASH_LINE_RE = /^([0-9a-f]{40}) (\d+) (\d+)/; const MAX_CACHE_FILES = 10; const MAX_BUFFER = 10 * 1024 * 1024; let currentLineDecorationType: vscode.TextEditorDecorationType; let fileAnnotationDecorationType: vscode.TextEditorDecorationType; const blameCacheMap = new Map(); let fileAnnotationsActive = false; let enabled = false; let pendingBlameProcess: ChildProcess | undefined; let updateSeq = 0; function createDecorationTypes(): void { currentLineDecorationType = vscode.window.createTextEditorDecorationType({ after: { margin: '0 0 0 3em', color: new vscode.ThemeColor('editorCodeLens.foreground'), fontStyle: 'italic', }, isWholeLine: true, }); fileAnnotationDecorationType = vscode.window.createTextEditorDecorationType({ before: { color: new vscode.ThemeColor('editorLineNumber.foreground'), margin: '0 1.5em 0 0', }, }); } function formatRelativeTime(timestamp: number): string { const diff = Math.floor(Date.now() / 1000) - timestamp; if (diff < 60) {return 'just now';} if (diff < 3600) {return `${Math.floor(diff / 60)} mins ago`;} if (diff < 86400) {return `${Math.floor(diff / 3600)} hours ago`;} if (diff < 2592000) {return `${Math.floor(diff / 86400)} days ago`;} if (diff < 31536000) {return `${Math.floor(diff / 2592000)} months ago`;} return `${Math.floor(diff / 31536000)} years ago`; } function formatBlameAnnotation(blame: LineBlame): string { if (blame.hash === UNCOMMITTED_HASH) { return ' You, Uncommitted changes'; } const {author, authorTime, summary} = blame.commit; return ` ${author}, ${formatRelativeTime(authorTime)} • ${blame.hash.substring(0, 7)} — ${summary}`; } function formatFileAnnotation(blame: LineBlame, maxAuthorLen: number): string { if (blame.hash === UNCOMMITTED_HASH) { return 'You'.padEnd(maxAuthorLen) + ' Uncommitted'; } return `${blame.commit.author.padEnd(maxAuthorLen)} ${formatRelativeTime(blame.commit.authorTime)}`; } function getRepoRoot(filePath: string): string | undefined { const fileUri = vscode.Uri.file(filePath); const folder = vscode.workspace.getWorkspaceFolder(fileUri); return folder?.uri.fsPath ?? vscode.workspace.workspaceFolders?.[0]?.uri.fsPath; } function cancelPendingBlame(): void { if (pendingBlameProcess) { try { pendingBlameProcess.kill(); } catch { /* already exited */ } pendingBlameProcess = undefined; } } function runGitBlame(filePath: string): Promise<(LineBlame | undefined)[]> { cancelPendingBlame(); return new Promise((resolve, reject) => { const repoRoot = getRepoRoot(filePath); if (!repoRoot) { reject(new Error('No workspace folder')); return; } const proc = execFile( 'git', ['blame', '--porcelain', '--', path.relative(repoRoot, filePath)], {cwd: repoRoot, maxBuffer: MAX_BUFFER}, (error, stdout) => { pendingBlameProcess = undefined; if (error) { reject(error); return; } resolve(parsePorcelainBlame(stdout)); }, ); pendingBlameProcess = proc; }); } function parsePorcelainBlame(output: string): (LineBlame | undefined)[] { const lines = output.split('\n'); const result: (LineBlame | undefined)[] = []; const commitMap = new Map(); let currentHash = ''; let lineNumber = 0; let pendingMeta: CommitMeta | undefined; for (let i = 0, len = lines.length; i < len; i++) { const line = lines[i]; const hashMatch = HASH_LINE_RE.exec(line); if (hashMatch) { currentHash = hashMatch[1]; lineNumber = parseInt(hashMatch[3], 10) - 1; pendingMeta = commitMap.get(currentHash); if (!pendingMeta) { pendingMeta = {author: '', authorMail: '', authorTime: 0, summary: ''}; commitMap.set(currentHash, pendingMeta); } } else if (pendingMeta) { if (line.charCodeAt(0) === 9) { // '\t' while (result.length <= lineNumber) {result.push(undefined);} result[lineNumber] = {commit: pendingMeta, hash: currentHash}; } else if (line.startsWith('author ')) { pendingMeta.author = line.substring(7); } else if (line.startsWith('author-mail ')) { pendingMeta.authorMail = line.substring(12); } else if (line.startsWith('author-time ')) { pendingMeta.authorTime = parseInt(line.substring(12), 10); } else if (line.startsWith('summary ')) { pendingMeta.summary = line.substring(8); } } } return result; } function evictOldestCache(): void { if (blameCacheMap.size <= MAX_CACHE_FILES) {return;} const firstKey = blameCacheMap.keys().next().value; if (firstKey !== undefined) {blameCacheMap.delete(firstKey);} } async function getBlameData(document: vscode.TextDocument): Promise<(LineBlame | undefined)[]> { if (document.uri.scheme !== 'file') {return [];} const fsPath = document.uri.fsPath; const cached = blameCacheMap.get(fsPath); if (cached && cached.version === document.version) { return cached.lines; } try { const blameLines = await runGitBlame(fsPath); blameCacheMap.delete(fsPath); blameCacheMap.set(fsPath, {version: document.version, lines: blameLines}); evictOldestCache(); return blameLines; } catch { return []; } } async function updateCurrentLineBlame(editor: vscode.TextEditor): Promise { if (!enabled) { editor.setDecorations(currentLineDecorationType, []); return; } const seq = ++updateSeq; const data = await getBlameData(editor.document); if (seq !== updateSeq) {return;} const line = editor.selection.active.line; const blame = data[line]; if (!blame) { editor.setDecorations(currentLineDecorationType, []); return; } editor.setDecorations(currentLineDecorationType, [{ range: new vscode.Range(line, Number.MAX_SAFE_INTEGER, line, Number.MAX_SAFE_INTEGER), renderOptions: {after: {contentText: formatBlameAnnotation(blame)}}, }]); } async function showFileAnnotations(editor: vscode.TextEditor): Promise { const data = await getBlameData(editor.document); const decorations: vscode.DecorationOptions[] = []; let maxAuthorLen = 0; for (let i = 0, len = data.length; i < len; i++) { const b = data[i]; if (!b) {continue;} const nameLen = b.hash === UNCOMMITTED_HASH ? 3 : b.commit.author.length; if (nameLen > maxAuthorLen) {maxAuthorLen = nameLen;} } if (maxAuthorLen > 20) {maxAuthorLen = 20;} for (let i = 0, len = data.length; i < len; i++) { const blame = data[i]; if (!blame) {continue;} decorations.push({ range: new vscode.Range(i, 0, i, 0), renderOptions: {before: {contentText: formatFileAnnotation(blame, maxAuthorLen)}}, }); } editor.setDecorations(fileAnnotationDecorationType, decorations); } function clearFileAnnotations(editor: vscode.TextEditor): void { editor.setDecorations(fileAnnotationDecorationType, []); } function clearAllDecorations(): void { for (const editor of vscode.window.visibleTextEditors) { editor.setDecorations(currentLineDecorationType, []); editor.setDecorations(fileAnnotationDecorationType, []); } } function onConfigChanged(): void { const newEnabled = vscode.workspace .getConfiguration('snow-cli') .get('gitBlame.enabled', false); if (newEnabled !== enabled) { enabled = newEnabled; if (!enabled) { cancelPendingBlame(); clearAllDecorations(); fileAnnotationsActive = false; } else { const editor = vscode.window.activeTextEditor; if (editor) {updateCurrentLineBlame(editor);} } } } export function registerGitBlame(context: vscode.ExtensionContext): void { enabled = vscode.workspace .getConfiguration('snow-cli') .get('gitBlame.enabled', false); createDecorationTypes(); context.subscriptions.push(currentLineDecorationType, fileAnnotationDecorationType); if (enabled) { const editor = vscode.window.activeTextEditor; if (editor) {updateCurrentLineBlame(editor);} } let selectionTimer: ReturnType | undefined; let editorSwitchTimer: ReturnType | undefined; context.subscriptions.push( vscode.window.onDidChangeTextEditorSelection(e => { if (!enabled) {return;} if (selectionTimer) {clearTimeout(selectionTimer);} selectionTimer = setTimeout(() => updateCurrentLineBlame(e.textEditor), 80); }), vscode.window.onDidChangeActiveTextEditor(editor => { if (!enabled || !editor) {return;} if (editorSwitchTimer) {clearTimeout(editorSwitchTimer);} editorSwitchTimer = setTimeout(() => { updateCurrentLineBlame(editor); if (fileAnnotationsActive) {showFileAnnotations(editor);} }, 50); }), vscode.workspace.onDidSaveTextDocument(doc => { blameCacheMap.delete(doc.uri.fsPath); if (!enabled) {return;} const editor = vscode.window.activeTextEditor; if (editor && editor.document === doc) { updateCurrentLineBlame(editor); if (fileAnnotationsActive) {showFileAnnotations(editor);} } }), vscode.commands.registerCommand('snow-cli.toggleGitBlame', () => { const config = vscode.workspace.getConfiguration('snow-cli'); const current = config.get('gitBlame.enabled', false); config.update('gitBlame.enabled', !current, vscode.ConfigurationTarget.Global); }), vscode.commands.registerCommand('snow-cli.toggleFileAnnotations', () => { if (!enabled) { vscode.window.showInformationMessage( 'Git Blame is disabled. Enable it in settings first.', ); return; } const editor = vscode.window.activeTextEditor; if (!editor) {return;} fileAnnotationsActive = !fileAnnotationsActive; if (fileAnnotationsActive) { showFileAnnotations(editor); } else { clearFileAnnotations(editor); } }), vscode.workspace.onDidChangeConfiguration(e => { if (e.affectsConfiguration('snow-cli.gitBlame.enabled')) { onConfigChanged(); } }), ); } ================================================ FILE: VSIX/src/ptyManager.ts ================================================ import * as os from 'os'; import * as path from 'path'; import * as vscode from 'vscode'; import {getSnowTerminalProxyEnv} from './terminalProxy'; // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires function loadPty(): any { return require('node-pty'); } export interface PtyManagerEvents { onData: (data: string) => void; onExit: (code: number) => void; } export type ShellFamily = 'powershell' | 'cmd' | 'posix'; export type ResolvedShell = { path: string; args: string[]; family: ShellFamily; }; export function detectShellFamily(shellPath: string): ShellFamily { const name = path.basename(shellPath).toLowerCase().replace(/\.exe$/, ''); if (name === 'cmd') { return 'cmd'; } if (name === 'powershell' || name === 'pwsh') { return 'powershell'; } return 'posix'; } function defaultArgsForFamily(family: ShellFamily): string[] { switch (family) { case 'powershell': return ['-NoLogo', '-NoExit']; case 'cmd': return []; case 'posix': return ['-l']; } } function detectPowerShellPath(): string { const psModulePath = process.env['PSModulePath'] || ''; if ( psModulePath.includes('PowerShell\\7') || psModulePath.includes('powershell\\7') ) { return 'pwsh.exe'; } return 'powershell.exe'; } function windowsFallback(): ResolvedShell { const p = detectPowerShellPath(); return {path: p, args: ['-NoLogo', '-NoExit'], family: 'powershell'}; } function posixFallback(): ResolvedShell { const shellPath = process.env.SHELL || '/bin/bash'; return {path: shellPath, args: ['-l'], family: detectShellFamily(shellPath)}; } function resolveAutoFromVSCode(): ResolvedShell | undefined { const platform = os.platform(); const platformKey = platform === 'win32' ? 'windows' : platform === 'darwin' ? 'osx' : 'linux'; const integratedConfig = vscode.workspace.getConfiguration('terminal.integrated'); const defaultProfileName = integratedConfig.get(`defaultProfile.${platformKey}`, ''); if (!defaultProfileName) { return undefined; } const profiles = integratedConfig.get>>( `profiles.${platformKey}`, ) || {}; const profile = profiles[defaultProfileName]; if (!profile) { return undefined; } let shellPath: string | undefined; if (typeof profile.path === 'string') { shellPath = profile.path; } else if (Array.isArray(profile.path)) { const fs = require('fs'); shellPath = (profile.path as string[]).find(p => { try { return fs.existsSync(p); } catch { return false; } }) || (profile.path as string[])[0]; } if (!shellPath) { return undefined; } const family = detectShellFamily(shellPath); const args = Array.isArray(profile.args) ? (profile.args as string[]) : defaultArgsForFamily(family); return {path: shellPath, args, family}; } /** * @param input 'auto' → follow VS Code default profile; * otherwise treated as a shell executable path (absolute or basename). * If the path doesn't exist, falls back to PowerShell (Windows) or $SHELL (others). */ export function resolveShellProfile(input?: string): ResolvedShell { const isWindows = os.platform() === 'win32'; const fallback = isWindows ? windowsFallback : posixFallback; if (!input || input === 'auto') { return resolveAutoFromVSCode() ?? fallback(); } const fs = require('fs'); if (path.isAbsolute(input) && !fs.existsSync(input)) { return fallback(); } const family = detectShellFamily(input); return {path: input, args: defaultArgsForFamily(family), family}; } export class PtyManager { private ptyProcess: any; private events: PtyManagerEvents | undefined; private startupSendTimer: NodeJS.Timeout | undefined; private resolvedShell: ResolvedShell | undefined; public setResolvedShell(shell: ResolvedShell): void { this.resolvedShell = shell; } public getShellFamily(): ShellFamily { return this.resolvedShell?.family ?? 'posix'; } public start( cwd: string, events: PtyManagerEvents, startupCommand?: string, initialSize?: {cols: number; rows: number}, ): void { if (this.ptyProcess) { return; } this.events = events; const shell = this.resolvedShell?.path ?? (process.env.SHELL || '/bin/bash'); const shellArgs = this.resolvedShell?.args ?? ['-l']; const proxyEnv = getSnowTerminalProxyEnv(); const spawnEnv = { ...process.env, ...(proxyEnv ?? {}), } as {[key: string]: string}; try { this.fixSpawnHelperPermissions(); const cols = this.normalizeDimension(initialSize?.cols, 80); const rows = this.normalizeDimension(initialSize?.rows, 30); const pty = loadPty(); const processInstance = pty.spawn(shell, shellArgs, { name: 'xterm-256color', cols, rows, cwd: cwd, env: spawnEnv, }); this.ptyProcess = processInstance; const cmd = startupCommand ?? 'snow'; let startupSent = false; const sendStartupCommand = () => { if (startupSent || !cmd) { return; } if (this.ptyProcess !== processInstance) { return; } startupSent = true; if (this.startupSendTimer) { clearTimeout(this.startupSendTimer); this.startupSendTimer = undefined; } processInstance.write(cmd + '\r'); }; processInstance.onData((data: string) => { if (this.ptyProcess !== processInstance) { return; } sendStartupCommand(); this.events?.onData(data); }); processInstance.onExit((e: {exitCode: number}) => { if (this.ptyProcess !== processInstance) { return; } if (this.startupSendTimer) { clearTimeout(this.startupSendTimer); this.startupSendTimer = undefined; } this.ptyProcess = undefined; this.events?.onExit(e.exitCode); }); if (cmd) { this.startupSendTimer = setTimeout(() => { this.startupSendTimer = undefined; sendStartupCommand(); }, 200); } } catch (error) { const message = error instanceof Error ? error.message : String(error); vscode.window.showErrorMessage(`Failed to start terminal: ${message}`); } } public write(data: string): void { this.ptyProcess?.write(data); } public resize(cols: number, rows: number): void { try { this.ptyProcess?.resize(cols, rows); } catch { // ignore resize errors } } public kill(): void { if (this.startupSendTimer) { clearTimeout(this.startupSendTimer); this.startupSendTimer = undefined; } if (this.ptyProcess) { this.ptyProcess.kill(); this.ptyProcess = undefined; } } public isRunning(): boolean { return this.ptyProcess !== undefined; } private normalizeDimension(value: number | undefined, fallback: number): number { if (typeof value !== 'number' || !Number.isFinite(value)) { return fallback; } const normalized = Math.floor(value); return normalized > 0 ? normalized : fallback; } private fixSpawnHelperPermissions(): void { if (os.platform() === 'win32') return; try { const fs = require('fs'); const dirs = [ 'build/Release', 'build/Debug', `prebuilds/${process.platform}-${process.arch}`, ]; for (const dir of dirs) { for (const rel of ['..', '.']) { const helperPath = path.join( __dirname, '..', 'node_modules', 'node-pty', 'lib', rel, dir, 'spawn-helper', ); if (fs.existsSync(helperPath)) { fs.chmodSync(helperPath, 0o755); return; } } } } catch { // Ignore permission fix errors } } } ================================================ FILE: VSIX/src/sidebarTerminalProvider.ts ================================================ import * as vscode from 'vscode'; import {resolveShellProfile} from './ptyManager'; import { SidebarTerminalSession, SidebarTerminalTabState, } from './sidebarTerminalSession'; import {startupCommandManager} from './startupCommandManager'; import {formatTerminalPathPayload} from './terminalPathFormatter'; type LaunchPolicy = 'ensure' | 'restart'; type Trigger = | 'viewReady' | 'viewRecreate' | 'openOrFocus' | 'manualRestart' | 'visibility' | 'configChange'; type LifecycleAction = { trigger: Trigger; policy: LaunchPolicy; focus: boolean; requestWebviewFocus: boolean; resetFrontend: boolean; suppressExitBanner: boolean; }; type LifecycleActionTemplate = Omit; type EnsureOptions = {focus?: boolean}; type RestartOptions = { reason?: 'manualRestart' | 'configChange'; resetFrontend?: boolean; }; type ReloadFrontendOptions = {focusAfterReady?: boolean}; type OutputLogLevel = 'debug' | 'info' | 'warn' | 'error'; type LogScope = 'SidebarTerminal' | 'Frontend'; type FrontendLogMessage = { type: 'frontendLog'; level: OutputLogLevel; message: string; details?: string; }; type TerminalConfig = { shellProfile: string; fontFamily: string; fontSize: number; fontWeight: string; lineHeight: number; }; type NormalizedFontConfig = Omit; type RendererHealthStage = | 'degraded' | 'webgl-retry-scheduled' | 'webgl-restored' | 'escalation-requested'; type RendererHealthStats = { activeRendererMode?: string; sinceLastRenderMs?: number; sinceLastOutputMs?: number; sinceLastWriteParsedMs?: number; sinceLastWriteCallbackMs?: number; rendererRecoveryCycleId?: number; rendererRecoveryAttemptId?: number; rendererHealthSuspendedForMs?: number; lastWebglFailureReason?: string; scheduledRecoveryDelayMs?: number; }; type RendererHealthStatField = { key: keyof RendererHealthStats; valueType: 'string' | 'number'; detailLabel: string; }; const RENDERER_HEALTH_STAT_FIELDS: readonly RendererHealthStatField[] = [ {key: 'activeRendererMode', valueType: 'string', detailLabel: 'mode'}, {key: 'rendererRecoveryCycleId', valueType: 'number', detailLabel: 'cycle'}, { key: 'rendererRecoveryAttemptId', valueType: 'number', detailLabel: 'attempt', }, {key: 'sinceLastRenderMs', valueType: 'number', detailLabel: 'sinceRenderMs'}, {key: 'sinceLastOutputMs', valueType: 'number', detailLabel: 'sinceOutputMs'}, { key: 'sinceLastWriteParsedMs', valueType: 'number', detailLabel: 'sinceWriteParsedMs', }, { key: 'sinceLastWriteCallbackMs', valueType: 'number', detailLabel: 'sinceWriteCbMs', }, { key: 'rendererHealthSuspendedForMs', valueType: 'number', detailLabel: 'suspendedMs', }, { key: 'scheduledRecoveryDelayMs', valueType: 'number', detailLabel: 'retryDelayMs', }, { key: 'lastWebglFailureReason', valueType: 'string', detailLabel: 'lastFailure', }, ]; type BellSound = 'beep' | 'ding' | 'chime' | 'pluck' | 'blip' | 'none'; type BellConfig = { enabled: boolean; volume: number; sound: BellSound; visualFlash: boolean; }; type ExtensionToWebviewMessage = | {type: 'output'; tabId: string; data: string} | {type: 'clear'; tabId?: string} | {type: 'fit'} | {type: 'focus'} | {type: 'syncTabs'; tabs: SidebarTerminalTabState[]} | {type: 'replaceTerminalContent'; tabId: string; data: string} | { type: 'updateFont'; fontFamily: string; fontSize: number; fontWeight: string; lineHeight: number; } | ({type: 'updateBell'} & BellConfig) | {type: 'exit'; tabId: string; code: number}; type WebviewToExtensionMessage = | {type: 'ready'} | {type: 'input'; data: string} | {type: 'resize'; cols: number; rows: number} | {type: 'switchTab'; tabId: string} | {type: 'closeTab'; tabId: string} | {type: 'dropPaths'; uris: string[]} | { type: 'rendererHealth'; stage: RendererHealthStage; reason?: string; stats?: RendererHealthStats; } | FrontendLogMessage; const RESOURCE_ROOT_SEGMENTS: readonly (readonly string[])[] = [ ['res'], ['node_modules', '@xterm'], ]; const XTERM_SCRIPT_SEGMENTS: readonly (readonly string[])[] = [ ['node_modules', '@xterm', 'xterm', 'lib', 'xterm.js'], ['node_modules', '@xterm', 'addon-fit', 'lib', 'addon-fit.js'], ['node_modules', '@xterm', 'addon-web-links', 'lib', 'addon-web-links.js'], ['node_modules', '@xterm', 'addon-webgl', 'lib', 'addon-webgl.js'], ['node_modules', '@xterm', 'addon-unicode11', 'lib', 'addon-unicode11.js'], ]; const XTERM_CSS_SEGMENTS = [ 'node_modules', '@xterm', 'xterm', 'css', 'xterm.css', ] as const; const SIDEBAR_STYLE_SEGMENTS = ['res', 'sidebarTerminal.css'] as const; const SIDEBAR_SCRIPT_SEGMENTS = ['res', 'sidebarTerminal.js'] as const; const OUTPUT_BUFFER_MAX_BYTES = 2 * 1024 * 1024; const OUTPUT_TRUNCATION_NOTICE = '\r\n[Output truncated while terminal view was unavailable]\r\n'; const FOCUS_RETRY_DELAYS_MS = [0, 80, 240] as const; const FONT_SIZE_MIN = 8; const FONT_SIZE_MAX = 32; const LINE_HEIGHT_MIN = 0.8; const LINE_HEIGHT_MAX = 2.0; const OUTPUT_CHANNEL_NAME = 'Snow CLI'; const SIDEBAR_LOG_SCOPE: LogScope = 'SidebarTerminal'; const FRONTEND_LOG_SCOPE: LogScope = 'Frontend'; const INVALID_MESSAGE_LOG_THROTTLE_MS = 5000; const RESTART_SETTLE_DELAY_MS = 150; const RESTART_FRONTEND_FALLBACK_MS = 3000; const MANUAL_RESTART_DEBOUNCE_MS = 1500; const MAX_SIDEBAR_TERMINAL_TABS = 5; const SHOW_RENDERER_TEST_CONTROLS = false; const DEFAULT_ACTION: LifecycleActionTemplate = { policy: 'ensure', focus: false, requestWebviewFocus: false, resetFrontend: false, suppressExitBanner: false, }; const TRIGGER_ACTIONS: Record = { viewReady: { ...DEFAULT_ACTION, }, visibility: { ...DEFAULT_ACTION, requestWebviewFocus: true, }, openOrFocus: { ...DEFAULT_ACTION, focus: true, requestWebviewFocus: true, }, manualRestart: { policy: 'restart', focus: false, requestWebviewFocus: true, resetFrontend: false, suppressExitBanner: true, }, viewRecreate: { policy: 'restart', focus: false, requestWebviewFocus: false, resetFrontend: false, suppressExitBanner: true, }, configChange: { policy: 'restart', focus: false, requestWebviewFocus: false, resetFrontend: true, suppressExitBanner: false, }, }; function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null; } function clampNumber(value: number, min: number, max: number): number { return Math.max(min, Math.min(max, value)); } function asOptionalNonEmptyString(value: unknown): string | undefined { if (typeof value !== 'string') { return undefined; } const normalized = value.trim(); return normalized ? normalized : undefined; } function normalizeFrontendLogLevel(value: unknown): OutputLogLevel { switch (value) { case 'debug': case 'info': case 'warn': case 'error': return value; default: return 'info'; } } function summarizeForLog(value: string, maxLength = 160): string { const normalized = value.replace(/\s+/g, ' ').trim(); return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 3)}...` : normalized; } function describeWebviewMessage(rawMessage: unknown): string { if (!isRecord(rawMessage)) { return `non-object:${typeof rawMessage}`; } const type = typeof rawMessage.type === 'string' ? rawMessage.type : 'unknown'; const summary = [`type=${type}`]; const message = asOptionalNonEmptyString(rawMessage.message); const data = asOptionalNonEmptyString(rawMessage.data); const reason = asOptionalNonEmptyString(rawMessage.reason); if (message) { summary.push(`message=${summarizeForLog(message)}`); } else if (data) { summary.push(`data=${summarizeForLog(data)}`); } else if (reason) { summary.push(`reason=${summarizeForLog(reason)}`); } return summary.join(', '); } function formatUnknownError(error: unknown): string { if (error instanceof Error) { return error.stack || error.message; } return typeof error === 'string' ? error : String(error); } function asOptionalFiniteNumber(value: unknown): number | undefined { return typeof value === 'number' && Number.isFinite(value) ? value : undefined; } function normalizeRendererHealthStage( value: unknown, ): RendererHealthStage | undefined { switch (value) { case 'degraded': case 'webgl-retry-scheduled': case 'webgl-restored': case 'escalation-requested': return value; default: return undefined; } } function parseRendererHealthStatValue( value: unknown, valueType: RendererHealthStatField['valueType'], ): string | number | undefined { return valueType === 'string' ? asOptionalNonEmptyString(value) : asOptionalFiniteNumber(value); } function parseRendererHealthStats( value: unknown, ): RendererHealthStats | undefined { if (!isRecord(value)) { return undefined; } const stats: RendererHealthStats = {}; for (const field of RENDERER_HEALTH_STAT_FIELDS) { const parsedValue = parseRendererHealthStatValue( value[field.key], field.valueType, ); if (typeof parsedValue !== 'undefined') { (stats as Record)[field.key] = parsedValue; } } return Object.keys(stats).length > 0 ? stats : undefined; } function parseWebviewMessage( rawMessage: unknown, ): WebviewToExtensionMessage | undefined { if (!isRecord(rawMessage) || typeof rawMessage.type !== 'string') { return undefined; } switch (rawMessage.type) { case 'ready': return {type: 'ready'}; case 'input': if (typeof rawMessage.data === 'string') { return {type: 'input', data: rawMessage.data}; } return undefined; case 'resize': if ( typeof rawMessage.cols === 'number' && typeof rawMessage.rows === 'number' && Number.isFinite(rawMessage.cols) && Number.isFinite(rawMessage.rows) ) { return { type: 'resize', cols: rawMessage.cols, rows: rawMessage.rows, }; } return undefined; case 'switchTab': { const tabId = asOptionalNonEmptyString(rawMessage.tabId); if (!tabId) { return undefined; } return {type: 'switchTab', tabId}; } case 'closeTab': { const tabId = asOptionalNonEmptyString(rawMessage.tabId); if (!tabId) { return undefined; } return {type: 'closeTab', tabId}; } case 'rendererHealth': { const stage = normalizeRendererHealthStage(rawMessage.stage); if (!stage) { return undefined; } return { type: 'rendererHealth', stage, reason: asOptionalNonEmptyString(rawMessage.reason), stats: parseRendererHealthStats(rawMessage.stats), }; } case 'dropPaths': { if (!Array.isArray(rawMessage.uris)) { return undefined; } const uris = (rawMessage.uris as unknown[]).filter( (uri): uri is string => typeof uri === 'string' && uri.length > 0, ); if (uris.length === 0) { return undefined; } return {type: 'dropPaths', uris}; } case 'frontendLog': { const message = asOptionalNonEmptyString(rawMessage.message); if (!message) { return undefined; } return { type: 'frontendLog', level: normalizeFrontendLogLevel(rawMessage.level), message, details: asOptionalNonEmptyString(rawMessage.details), }; } default: return undefined; } } function mergeActions( base: LifecycleAction, incoming: LifecycleAction, ): LifecycleAction { const policy: LaunchPolicy = base.policy === 'restart' || incoming.policy === 'restart' ? 'restart' : 'ensure'; const trigger = incoming.policy === 'restart' ? incoming.trigger : base.policy === 'restart' ? base.trigger : incoming.trigger; return { trigger, policy, focus: base.focus || incoming.focus, requestWebviewFocus: base.requestWebviewFocus || incoming.requestWebviewFocus, resetFrontend: base.resetFrontend || incoming.resetFrontend, suppressExitBanner: base.suppressExitBanner || incoming.suppressExitBanner, }; } class PendingLifecycleQueue { private pendingAction: LifecycleAction | undefined; public queue(action: LifecycleAction): void { this.pendingAction = this.pendingAction ? mergeActions(this.pendingAction, action) : {...action}; } public mergeWithPending(current: LifecycleAction): LifecycleAction { if (!this.pendingAction) { return current; } const merged = mergeActions(this.pendingAction, current); this.pendingAction = undefined; return merged; } public take(): LifecycleAction | undefined { const action = this.pendingAction; this.pendingAction = undefined; return action; } public clear(): void { this.pendingAction = undefined; } } export class SidebarTerminalProvider implements vscode.WebviewViewProvider { public static readonly viewType = 'snowCliTerminal'; private view?: vscode.WebviewView; private readonly outputChannel: vscode.OutputChannel; private readonly lifecycleQueue = new PendingLifecycleQueue(); private readonly sessions = new Map(); private sessionOrder: string[] = []; private activeSessionId: string | undefined; private sessionCounter = 0; private webviewReady = false; private hasResolvedViewOnce = false; private ensureRunningTimer: NodeJS.Timeout | undefined; private latestTerminalSize: {cols: number; rows: number} | undefined; private focusRetryTimers = new Set(); private lastRendererStallNoticeAt = 0; private lastAutoRendererRecoveryAt = 0; private lastInvalidWebviewMessageLogAt = 0; private lastKnownRendererMode: string | undefined; private lastKnownRendererIssue: string | undefined; private webviewHtmlVersion = 0; private pendingFocusAfterFrontendReload = false; private restartInProgress = false; private restartCompletionTimer: NodeJS.Timeout | undefined; private lastManualRestartRequestedAt = 0; private disposed = false; constructor(private readonly extensionUri: vscode.Uri) { this.outputChannel = vscode.window.createOutputChannel(OUTPUT_CHANNEL_NAME); this.ensureActiveSessionExists(); this.applyShellProfile(); this.logSidebarInfo('Sidebar terminal provider initialized.'); } private writeOutputLog( level: OutputLogLevel, scope: LogScope, message: string, details?: string, ): void { if (this.disposed) { return; } this.outputChannel.appendLine( `[${new Date().toISOString()}] [${level.toUpperCase()}] [${scope}] ${message}`, ); if (!details) { return; } for (const line of details.split(/\r?\n/)) { this.outputChannel.appendLine(line ? ` ${line}` : ' '); } } private logSidebar( level: OutputLogLevel, message: string, details?: string, ): void { this.writeOutputLog(level, SIDEBAR_LOG_SCOPE, message, details); } private logSidebarInfo(message: string, details?: string): void { this.logSidebar('info', message, details); } private logSidebarWarn(message: string, details?: string): void { this.logSidebar('warn', message, details); } private logSidebarError(message: string, details?: string): void { this.logSidebar('error', message, details); } private logInvalidWebviewMessage(rawMessage: unknown): void { const now = Date.now(); if ( now - this.lastInvalidWebviewMessageLogAt < INVALID_MESSAGE_LOG_THROTTLE_MS ) { return; } this.lastInvalidWebviewMessageLogAt = now; this.logSidebarWarn( 'Ignored invalid webview message.', describeWebviewMessage(rawMessage), ); } private getTerminalConfig(): TerminalConfig { const cfg = vscode.workspace.getConfiguration('snow-cli.terminal'); return { shellProfile: cfg.get('shellType', 'auto'), fontFamily: cfg.get('fontFamily', ''), fontSize: cfg.get('fontSize', 14), fontWeight: cfg.get('fontWeight', 'normal'), lineHeight: cfg.get('lineHeight', 1.0), }; } private normalizeFontConfig(config: TerminalConfig): NormalizedFontConfig { return { fontFamily: config.fontFamily || 'monospace', fontSize: clampNumber(config.fontSize, FONT_SIZE_MIN, FONT_SIZE_MAX), fontWeight: config.fontWeight || 'normal', lineHeight: clampNumber( config.lineHeight, LINE_HEIGHT_MIN, LINE_HEIGHT_MAX, ), }; } private applyShellProfile(): void { const {shellProfile} = this.getTerminalConfig(); const resolved = resolveShellProfile(shellProfile); for (const session of this.getOrderedSessions()) { session.setResolvedShell(resolved); } } private sendFontConfig(): void { const normalized = this.normalizeFontConfig(this.getTerminalConfig()); this.postWebviewMessage({type: 'updateFont', ...normalized}); } private getBellConfig(): BellConfig { const cfg = vscode.workspace.getConfiguration('snow-cli.bell'); const rawSound = cfg.get('sound', 'beep'); const allowed: ReadonlySet = new Set([ 'beep', 'ding', 'chime', 'pluck', 'blip', 'none', ]); const sound: BellSound = (allowed as Set).has(rawSound) ? (rawSound as BellSound) : 'beep'; return { enabled: cfg.get('enabled', true), volume: clampNumber(cfg.get('volume', 0.5), 0, 1), sound, visualFlash: cfg.get('visualFlash', true), }; } public sendBellConfig(): void { this.postWebviewMessage({type: 'updateBell', ...this.getBellConfig()}); } private updateRendererRecoveryState( stage: RendererHealthStage, reason?: string, stats?: RendererHealthStats, ): void { if (stats?.activeRendererMode) { this.lastKnownRendererMode = stats.activeRendererMode; } switch (stage) { case 'webgl-restored': this.lastKnownRendererMode = 'webgl'; this.lastKnownRendererIssue = undefined; return; case 'degraded': case 'webgl-retry-scheduled': case 'escalation-requested': if (!this.lastKnownRendererMode) { this.lastKnownRendererMode = stats?.activeRendererMode ?? 'fallback'; } this.lastKnownRendererIssue = stats?.lastWebglFailureReason ?? reason ?? (this.lastKnownRendererMode && this.lastKnownRendererMode !== 'webgl' ? `${this.lastKnownRendererMode}-active` : 'renderer-recovery-pending'); return; } } private getWorkspaceFolderForActiveEditor(): string | undefined { const editor = vscode.window.activeTextEditor; const folder = editor ? vscode.workspace.getWorkspaceFolder(editor.document.uri) : undefined; return ( folder?.uri.fsPath ?? vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ); } public createTab(options?: EnsureOptions): void { const shouldFocus = options?.focus !== false; if (this.sessionOrder.length >= MAX_SIDEBAR_TERMINAL_TABS) { this.logSidebarInfo( 'Ignored create tab request because sidebar terminal tab limit was reached.', `tabLimit=${MAX_SIDEBAR_TERMINAL_TABS}, existingTabs=${this.sessionOrder.length}`, ); void vscode.window.showInformationMessage( `Snow CLI Sidebar Terminal supports up to ${MAX_SIDEBAR_TERMINAL_TABS} tabs.`, ); if (shouldFocus) { void vscode.commands.executeCommand('snowCliTerminal.focus'); this.syncActiveSessionToWebview({focus: true}); } return; } const session = this.createSession(); this.logSidebarInfo( 'Created terminal tab.', `tabId=${session.id}, title=${session.title}`, ); if (shouldFocus) { void vscode.commands.executeCommand('snowCliTerminal.focus'); } this.ensureTerminalRunning(session.id); this.syncActiveSessionToWebview({focus: shouldFocus}); } public closeActiveTab(options?: EnsureOptions): void { const activeSession = this.getActiveSession(); if (!activeSession) { return; } this.closeSession(activeSession.id, {focus: options?.focus === true}); } private createSession(): SidebarTerminalSession { const sessionIndex = ++this.sessionCounter; const session = new SidebarTerminalSession({ id: `sidebar-terminal-tab-${sessionIndex}`, title: `Terminal ${sessionIndex}`, outputBufferMaxBytes: OUTPUT_BUFFER_MAX_BYTES, outputTruncationNotice: OUTPUT_TRUNCATION_NOTICE, }); session.setResolvedShell( resolveShellProfile(this.getTerminalConfig().shellProfile), ); this.sessions.set(session.id, session); this.sessionOrder.push(session.id); this.activeSessionId = session.id; return session; } private getSessionById( sessionId: string | undefined, ): SidebarTerminalSession | undefined { if (!sessionId) { return undefined; } return this.sessions.get(sessionId); } private getOrderedSessions(): SidebarTerminalSession[] { return this.sessionOrder .map(sessionId => this.sessions.get(sessionId)) .filter( (session): session is SidebarTerminalSession => typeof session !== 'undefined', ); } private getActiveSession(): SidebarTerminalSession | undefined { return this.getSessionById(this.activeSessionId); } private ensureActiveSessionExists(): SidebarTerminalSession { const activeSession = this.getActiveSession(); if (activeSession) { return activeSession; } return this.createSession(); } private resizeAllRunningSessions(cols: number, rows: number): void { for (const session of this.getOrderedSessions()) { if (session.isRunning()) { session.resize(cols, rows); } } } private syncTabsToWebview(): void { if (!this.isWebviewOperational()) { return; } const activeSession = this.ensureActiveSessionExists(); this.postWebviewMessage({ type: 'syncTabs', tabs: this.getOrderedSessions().map(session => session.toTabState(session.id === activeSession.id), ), }); } private syncActiveSessionToWebview(options?: { focus?: boolean; fit?: boolean; }): void { if (!this.isWebviewOperational()) { return; } const activeSession = this.ensureActiveSessionExists(); this.syncTabsToWebview(); this.postWebviewMessage({ type: 'replaceTerminalContent', tabId: activeSession.id, data: activeSession.getTranscript(), }); if (options?.fit !== false) { this.postWebviewMessage({type: 'fit'}); } if (options?.focus) { this.requestWebviewFocus(); } } private switchActiveSession( sessionId: string, options?: {focus?: boolean}, ): boolean { const nextSession = this.getSessionById(sessionId); if (!nextSession) { return false; } const didChange = this.activeSessionId !== nextSession.id; this.activeSessionId = nextSession.id; if (didChange) { this.logSidebarInfo( 'Switched active terminal tab.', `tabId=${nextSession.id}, title=${nextSession.title}`, ); } this.syncActiveSessionToWebview({focus: options?.focus === true}); return true; } private closeSession( sessionId: string, options?: {focus?: boolean}, ): boolean { if (this.restartInProgress) { this.logSidebarInfo( 'Ignored close tab request because a restart is already in progress.', `tabId=${sessionId}`, ); return false; } const session = this.getSessionById(sessionId); if (!session) { return false; } const orderedSessions = this.getOrderedSessions(); const sessionIndex = orderedSessions.findIndex( candidate => candidate.id === session.id, ); const wasActive = session.id === this.activeSessionId; session.kill(); this.sessions.delete(session.id); this.sessionOrder = this.sessionOrder.filter(id => id !== session.id); let nextActiveSession: SidebarTerminalSession | undefined; let createdReplacement = false; if (this.sessionOrder.length === 0) { nextActiveSession = this.createSession(); createdReplacement = true; } else if (wasActive) { const fallbackIndex = Math.min( sessionIndex, this.sessionOrder.length - 1, ); nextActiveSession = this.getSessionById(this.sessionOrder[fallbackIndex]); } else { nextActiveSession = this.getActiveSession(); } if (nextActiveSession) { this.activeSessionId = nextActiveSession.id; } else { this.activeSessionId = undefined; } this.logSidebarInfo( 'Closed terminal tab.', `tabId=${session.id}, title=${session.title}, replacementTabId=${ nextActiveSession?.id ?? 'none' }, remainingTabs=${this.sessionOrder.length}`, ); if (createdReplacement && nextActiveSession) { this.ensureTerminalRunning(nextActiveSession.id); } if (wasActive) { this.syncActiveSessionToWebview({focus: options?.focus === true}); } else { this.syncTabsToWebview(); } return true; } public ensureTerminal(options?: EnsureOptions): void { this.ensureActiveSessionExists(); this.runLifecycleAction('openOrFocus', options); } public restartTerminal(options?: RestartOptions): void { const reason = options?.reason ?? 'manualRestart'; if (reason === 'manualRestart') { const now = Date.now(); if ( now - this.lastManualRestartRequestedAt < MANUAL_RESTART_DEBOUNCE_MS ) { this.logSidebarInfo( 'Ignored duplicate manual restart request inside debounce window.', `debounceMs=${MANUAL_RESTART_DEBOUNCE_MS}`, ); return; } this.lastManualRestartRequestedAt = now; if (this.restartInProgress) { this.logSidebarInfo( 'Ignored duplicate manual restart request because a restart is already in progress.', ); return; } } const template = TRIGGER_ACTIONS[reason]; const resetFrontend = typeof options?.resetFrontend === 'boolean' ? options.resetFrontend : template.resetFrontend; if (reason === 'manualRestart' && resetFrontend) { this.logSidebarInfo( 'Manual restart using explicit frontend reload override.', ); } this.applyLifecycleAction({ trigger: reason, ...template, resetFrontend, }); } public onViewReady(): void { this.webviewReady = true; this.logSidebarInfo( 'Webview ready.', `htmlVersion=${this.webviewHtmlVersion}, pendingFocusAfterFrontendReload=${this.pendingFocusAfterFrontendReload}`, ); this.finishRestart(false); this.runLifecycleAction('viewReady'); this.sendFontConfig(); this.sendBellConfig(); this.syncActiveSessionToWebview({fit: true}); if (this.pendingFocusAfterFrontendReload) { this.pendingFocusAfterFrontendReload = false; this.requestWebviewFocus(); } } public onViewRecreate(): void { this.logSidebarInfo('Webview recreated; scheduling terminal restart.'); this.runLifecycleAction('viewRecreate'); } public resolveWebviewView( webviewView: vscode.WebviewView, _context: vscode.WebviewViewResolveContext, _token: vscode.CancellationToken, ): void { const isViewRecreate = this.hasResolvedViewOnce; this.hasResolvedViewOnce = true; this.view = webviewView; this.webviewReady = false; this.logSidebarInfo( isViewRecreate ? 'Resolving recreated sidebar terminal view.' : 'Resolving sidebar terminal view.', ); this.configureWebview(webviewView); this.registerWebviewEventHandlers(webviewView); if (isViewRecreate) { this.onViewRecreate(); } } private configureWebview(webviewView: vscode.WebviewView): void { const htmlVersion = ++this.webviewHtmlVersion; webviewView.webview.options = { enableScripts: true, localResourceRoots: RESOURCE_ROOT_SEGMENTS.map(segments => this.getExtensionResourceUri(segments), ), }; webviewView.webview.html = this.getHtmlForWebview( webviewView.webview, htmlVersion, ); } private registerWebviewEventHandlers(webviewView: vscode.WebviewView): void { webviewView.webview.onDidReceiveMessage(message => { this.handleMessage(message); }); webviewView.onDidChangeVisibility(() => { if (webviewView.visible) { this.scheduleEnsureRunning(); } }); webviewView.onDidDispose(() => { this.handleViewDisposed(); }); } private teardownRuntimeState(): void { this.clearEnsureRunningTimer(); this.clearFocusRetryTimers(); this.clearRestartCompletionTimer(); this.restartInProgress = false; this.lifecycleQueue.clear(); for (const session of this.getOrderedSessions()) { session.kill(); } } private handleViewDisposed(): void { const hadView = Boolean(this.view); const wasReady = this.webviewReady; const runningSessionCount = this.getOrderedSessions().filter(session => session.isRunning(), ).length; if (hadView || wasReady || runningSessionCount > 0) { this.logSidebarInfo( 'Webview disposed.', `hadView=${hadView}, wasReady=${wasReady}, runningSessions=${runningSessionCount}`, ); } this.webviewReady = false; this.lastAutoRendererRecoveryAt = 0; this.lastKnownRendererMode = undefined; this.lastKnownRendererIssue = undefined; this.pendingFocusAfterFrontendReload = false; this.view = undefined; this.teardownRuntimeState(); } private isWebviewOperational(): boolean { return Boolean(this.view && this.webviewReady); } private handleMessage(rawMessage: unknown): void { try { const message = parseWebviewMessage(rawMessage); if (!message) { this.logInvalidWebviewMessage(rawMessage); return; } switch (message.type) { case 'ready': this.onViewReady(); return; case 'input': if (message.data) { this.writeInputToTerminal(message.data); } return; case 'resize': { const cols = Math.floor(message.cols); const rows = Math.floor(message.rows); if (cols <= 0 || rows <= 0) { return; } this.latestTerminalSize = {cols, rows}; this.resizeAllRunningSessions(cols, rows); return; } case 'switchTab': if (!this.switchActiveSession(message.tabId, {focus: true})) { this.logSidebarWarn( 'Ignored tab switch request for unknown terminal tab.', `tabId=${message.tabId}`, ); } return; case 'closeTab': if (!this.closeSession(message.tabId, {focus: true})) { this.logSidebarWarn( 'Ignored tab close request for unknown terminal tab.', `tabId=${message.tabId}`, ); } return; case 'dropPaths': this.handleDropPaths(message.uris); return; case 'rendererHealth': this.handleRendererHealthMessage( message.stage, message.reason, message.stats, ); return; case 'frontendLog': this.writeOutputLog( message.level, FRONTEND_LOG_SCOPE, message.message, message.details, ); return; } } catch (error) { this.logSidebarError( 'Failed to handle webview message.', formatUnknownError(error), ); } } private handleRendererHealthMessage( stage: RendererHealthStage, reason?: string, stats?: RendererHealthStats, ): void { const now = Date.now(); const details: string[] = []; if (reason) { details.push(`reason=${reason}`); } if (stats) { for (const field of RENDERER_HEALTH_STAT_FIELDS) { const value = stats[field.key]; if (typeof value === field.valueType) { details.push(`${field.detailLabel}=${value}`); } } } const detailText = details.length > 0 ? details.join(', ') : undefined; this.updateRendererRecoveryState(stage, reason, stats); switch (stage) { case 'degraded': this.logSidebarWarn( 'Observed frontend WebGL degradation; monitoring local recovery.', detailText, ); if (now - this.lastRendererStallNoticeAt >= 5000) { this.lastRendererStallNoticeAt = now; void vscode.window.setStatusBarMessage( `Snow CLI: WebGL renderer degraded${ reason ? ` (${reason})` : '' }; retrying locally.`, 3000, ); } return; case 'webgl-retry-scheduled': if ( (stats?.rendererRecoveryAttemptId ?? 0) > 1 || (stats?.scheduledRecoveryDelayMs ?? 0) >= 2000 ) { this.logSidebarInfo( 'Observed frontend WebGL recovery retry schedule.', detailText, ); } return; case 'webgl-restored': this.logSidebarInfo( reason === 'initial-load' ? 'WebGL renderer ready on initial load.' : 'WebGL renderer restored and ready.', detailText, ); if ( reason !== 'initial-load' && now - this.lastRendererStallNoticeAt >= 3000 ) { this.lastRendererStallNoticeAt = now; void vscode.window.setStatusBarMessage( 'Snow CLI: WebGL renderer restored.', 3000, ); } return; case 'escalation-requested': if (now - this.lastAutoRendererRecoveryAt < 10000) { if (now - this.lastRendererStallNoticeAt >= 3000) { this.lastRendererStallNoticeAt = now; this.logSidebarWarn('Renderer recovery throttled.', detailText); void vscode.window.setStatusBarMessage( `Snow CLI: renderer recovery throttled${ reason ? ` (${reason})` : '' }. Use Restart Terminal if needed.`, 3000, ); } return; } this.lastAutoRendererRecoveryAt = now; this.logSidebarWarn( 'Frontend requested WebGL recovery escalation; reloading terminal frontend.', detailText, ); this.reloadWebviewFrontend({focusAfterReady: true}); if (now - this.lastRendererStallNoticeAt >= 10000) { this.lastRendererStallNoticeAt = now; void vscode.window.setStatusBarMessage( `Snow CLI: reloading terminal renderer${ reason ? ` (${reason})` : '' }.`, 3000, ); } return; } } private writeInputToTerminal(data: string): void { const activeSession = this.ensureActiveSessionExists(); this.ensureTerminalRunning(activeSession.id); activeSession.write(data); } private startTerminal(sessionId?: string): void { const session = sessionId ? this.getSessionById(sessionId) : this.ensureActiveSessionExists(); if (!session) { return; } this.applyShellProfile(); const workspaceFolder = this.getWorkspaceFolderForActiveEditor(); const cwd = workspaceFolder || process.cwd(); const sizeDetails = this.latestTerminalSize ? `${this.latestTerminalSize.cols}x${this.latestTerminalSize.rows}` : 'auto'; const {started, processNonce, startupCommand} = session.start( cwd, this.latestTerminalSize, { onData: data => { this.handleTerminalData(session.id, data); }, onExit: event => { this.handleTerminalExit( session.id, event.code, event.processNonce, event.suppressed, ); }, }, () => startupCommandManager.getNextStartupCommand(), ); const commandDetails = startupCommand ?? '(none)'; this.syncTabsToWebview(); if (started) { this.logSidebarInfo( 'Terminal started.', `tabId=${session.id}, process=${processNonce}, cwd=${cwd}, command=${commandDetails}, size=${sizeDetails}`, ); return; } this.logSidebarError( 'Terminal start request completed but process is not running.', `tabId=${session.id}, process=${processNonce}, cwd=${cwd}, command=${commandDetails}, size=${sizeDetails}`, ); } private handleTerminalData(sessionId: string, data: string): void { const session = this.getSessionById(sessionId); if (!session || !data) { return; } session.appendOutput(data); if (session.id !== this.activeSessionId || !this.isWebviewOperational()) { return; } this.postWebviewMessage({type: 'output', tabId: session.id, data}); } private handleTerminalExit( sessionId: string, code: number, processNonce: number, suppressed: boolean, ): void { const session = this.getSessionById(sessionId); if (!session) { return; } if (suppressed) { this.logSidebarInfo( 'Terminal exit suppressed after controlled restart.', `tabId=${sessionId}, process=${processNonce}, code=${code}`, ); this.syncTabsToWebview(); return; } session.appendExitBanner(code); this.syncTabsToWebview(); if (session.id === this.activeSessionId && this.isWebviewOperational()) { this.postWebviewMessage({type: 'exit', tabId: session.id, code}); } if (code === 0) { this.logSidebarInfo( 'Terminal exited.', `tabId=${sessionId}, process=${processNonce}, code=${code}`, ); return; } this.logSidebarWarn( 'Terminal exited with non-zero code.', `tabId=${sessionId}, process=${processNonce}, code=${code}`, ); } private scheduleEnsureRunning(): void { if (!this.isWebviewOperational()) { return; } this.clearEnsureRunningTimer(); this.ensureRunningTimer = setTimeout(() => { this.ensureRunningTimer = undefined; this.runLifecycleAction('visibility'); }, 50); } private clearEnsureRunningTimer(): void { this.ensureRunningTimer = this.clearTimer(this.ensureRunningTimer); } private clearRestartCompletionTimer(): void { this.restartCompletionTimer = this.clearTimer(this.restartCompletionTimer); } private clearTimer(timer: NodeJS.Timeout | undefined): undefined { if (timer) { clearTimeout(timer); } return undefined; } private scheduleRestartCompletion(delayMs: number): void { this.clearRestartCompletionTimer(); this.restartCompletionTimer = setTimeout(() => { this.restartCompletionTimer = undefined; this.finishRestart(); }, delayMs); } private clearRestartingSessionState(): void { let didChange = false; for (const session of this.getOrderedSessions()) { if (!session.isRestarting()) { continue; } session.setRestarting(false); didChange = true; } if (didChange && this.isWebviewOperational()) { this.syncTabsToWebview(); } } private finishRestart(drainPending = true): void { this.clearRestartCompletionTimer(); if (!this.restartInProgress) { return; } this.restartInProgress = false; this.clearRestartingSessionState(); if (!drainPending || !this.isWebviewOperational()) { return; } const pendingAction = this.lifecycleQueue.take(); if (pendingAction) { this.applyLifecycleAction(pendingAction); } } private ensureTerminalRunning(sessionId?: string): void { const session = sessionId ? this.getSessionById(sessionId) : this.getActiveSession() ?? this.ensureActiveSessionExists(); if (!session || session.isRunning()) { return; } this.startTerminal(session.id); } private runLifecycleAction(trigger: Trigger, options?: EnsureOptions): void { const template = TRIGGER_ACTIONS[trigger]; const action: LifecycleAction = { trigger, ...template, focus: options?.focus ?? template.focus, }; this.applyLifecycleAction(action); } private applyLifecycleAction(action: LifecycleAction): void { if (this.restartInProgress) { this.lifecycleQueue.queue(action); return; } if (action.focus) { void vscode.commands.executeCommand('snowCliTerminal.focus'); } if (!this.isWebviewOperational()) { this.lifecycleQueue.queue(action); return; } this.executeLifecycleAction(this.lifecycleQueue.mergeWithPending(action)); } private executeLifecycleAction(action: LifecycleAction): void { if (action.policy === 'restart') { this.executeRestart(action); } else { this.ensureTerminalRunning(); } if (action.requestWebviewFocus) { this.requestWebviewFocus(); } } private executeRestart(action: LifecycleAction): void { const activeSession = this.ensureActiveSessionExists(); this.restartInProgress = true; this.clearRestartCompletionTimer(); this.clearEnsureRunningTimer(); this.clearFocusRetryTimers(); activeSession.setRestarting(true); this.logSidebarInfo( 'Restarting terminal.', `tabId=${activeSession.id}, trigger=${action.trigger}, resetFrontend=${action.resetFrontend}, requestWebviewFocus=${action.requestWebviewFocus}, suppressExitBanner=${action.suppressExitBanner}`, ); if (action.suppressExitBanner) { activeSession.suppressCurrentExitBanner(); } activeSession.clearTranscript(); activeSession.kill(); this.syncTabsToWebview(); if (action.resetFrontend) { this.reloadWebviewFrontend({ focusAfterReady: action.requestWebviewFocus, }); } else { this.postWebviewMessage({type: 'clear', tabId: activeSession.id}); } this.startTerminal(activeSession.id); if (!action.resetFrontend) { this.sendFontConfig(); this.sendBellConfig(); this.postWebviewMessage({type: 'fit'}); } this.scheduleRestartCompletion( action.resetFrontend ? RESTART_FRONTEND_FALLBACK_MS : RESTART_SETTLE_DELAY_MS, ); } private reloadWebviewFrontend(options?: ReloadFrontendOptions): void { if (!this.view) { this.logSidebarWarn( 'Skipped webview frontend reload because no view is attached.', ); return; } if (options?.focusAfterReady) { this.pendingFocusAfterFrontendReload = true; } this.webviewReady = false; this.logSidebarInfo( 'Reloading webview frontend.', `focusAfterReady=${Boolean(options?.focusAfterReady)}, nextHtmlVersion=${ this.webviewHtmlVersion + 1 }`, ); this.configureWebview(this.view); } private clearFocusRetryTimers(): void { if (this.focusRetryTimers.size === 0) { return; } for (const timer of this.focusRetryTimers) { clearTimeout(timer); } this.focusRetryTimers.clear(); } private requestWebviewFocus(): void { this.clearFocusRetryTimers(); if (!this.isWebviewOperational()) { return; } for (const delay of FOCUS_RETRY_DELAYS_MS) { const timer = setTimeout(() => { this.focusRetryTimers.delete(timer); if (!this.isWebviewOperational()) { return; } this.postWebviewMessage({type: 'focus'}); }, delay); this.focusRetryTimers.add(timer); } } private postWebviewMessage(message: ExtensionToWebviewMessage): void { if (!this.view || !this.webviewReady) { return; } void this.view.webview.postMessage(message); } private getExtensionResourceUri(segments: readonly string[]): vscode.Uri { return vscode.Uri.joinPath(this.extensionUri, ...segments); } private getWebviewResourceUri( webview: vscode.Webview, segments: readonly string[], ): vscode.Uri { return webview.asWebviewUri(this.getExtensionResourceUri(segments)); } private getHtmlForWebview( webview: vscode.Webview, htmlVersion: number, ): string { const cspSource = webview.cspSource; const xtermCssUri = this.getWebviewResourceUri(webview, XTERM_CSS_SEGMENTS); const sidebarCssUri = this.getWebviewResourceUri( webview, SIDEBAR_STYLE_SEGMENTS, ); const sidebarScriptUri = this.getWebviewResourceUri( webview, SIDEBAR_SCRIPT_SEGMENTS, ); const scriptTags = XTERM_SCRIPT_SEGMENTS.map( segments => ``, ).join('\n '); const rendererTestControls = SHOW_RENDERER_TEST_CONTROLS ? `
` : ''; return `
${rendererTestControls}
${scriptTags} `; } private handleDropPaths(uris: string[]): void { const paths = uris .map(uri => { try { return vscode.Uri.parse(uri).fsPath; } catch { return ''; } }) .filter(path => path.length > 0); if (paths.length === 0) { return; } this.logSidebarInfo( 'Received file paths from drop.', `pathCount=${paths.length}`, ); this.sendFilePaths(paths); } public sendFilePaths(paths: string[]): void { if (paths.length === 0) { return; } const activeSession = this.getActiveSession(); const shellFamily = activeSession?.getShellFamily(); this.writeInputToTerminal(formatTerminalPathPayload(paths, {shellFamily})); if (this.isWebviewOperational()) { this.requestWebviewFocus(); return; } this.logSidebarInfo( 'Path payload written while webview is unavailable.', `pathCount=${paths.length}`, ); } public dispose(): void { if (this.disposed) { return; } this.logSidebarInfo('Disposing sidebar terminal provider.'); this.handleViewDisposed(); this.disposed = true; this.outputChannel.dispose(); } } ================================================ FILE: VSIX/src/sidebarTerminalSession.ts ================================================ import {PtyManager, ResolvedShell, ShellFamily} from './ptyManager'; export type SidebarTerminalSize = {cols: number; rows: number}; export type SidebarTerminalTabState = { id: string; title: string; isActive: boolean; isRunning: boolean; isRestarting: boolean; exitCode?: number; }; type SidebarTerminalSessionOptions = { id: string; title: string; outputBufferMaxBytes: number; outputTruncationNotice: string; }; type SidebarTerminalSessionStartHandlers = { onData: (data: string) => void; onExit: (event: { code: number; processNonce: number; suppressed: boolean; }) => void; }; type StartupCommandProvider = () => string | undefined; export class SidebarTerminalSession { public readonly id: string; public readonly title: string; private readonly ptyManager = new PtyManager(); private readonly suppressedExitProcessNonces = new Set(); private readonly outputBufferMaxBytes: number; private readonly outputTruncationNotice: string; private transcriptChunks: string[] = []; private transcriptBytes = 0; private transcriptTruncated = false; private processNonce = 0; private lastExitCode: number | undefined; private restarting = false; private startupCommand: string | undefined; constructor(options: SidebarTerminalSessionOptions) { this.id = options.id; this.title = options.title; this.outputBufferMaxBytes = options.outputBufferMaxBytes; this.outputTruncationNotice = options.outputTruncationNotice; } public setResolvedShell(shell: ResolvedShell): void { this.ptyManager.setResolvedShell(shell); } public getShellFamily(): ShellFamily { return this.ptyManager.getShellFamily(); } public start( cwd: string, size: SidebarTerminalSize | undefined, handlers: SidebarTerminalSessionStartHandlers, getStartupCommand: StartupCommandProvider, ): {started: boolean; processNonce: number; startupCommand: string | undefined} { const processNonce = ++this.processNonce; this.lastExitCode = undefined; if (typeof this.startupCommand === 'undefined') { this.startupCommand = getStartupCommand(); } this.ptyManager.start( cwd, { onData: data => { handlers.onData(data); }, onExit: code => { const suppressed = this.suppressedExitProcessNonces.delete( processNonce, ); if (!suppressed) { this.lastExitCode = code; } handlers.onExit({code, processNonce, suppressed}); }, }, this.startupCommand, size, ); return { started: this.ptyManager.isRunning(), processNonce, startupCommand: this.startupCommand, }; } public write(data: string): void { this.ptyManager.write(data); } public resize(cols: number, rows: number): void { this.ptyManager.resize(cols, rows); } public kill(): void { this.ptyManager.kill(); } public isRunning(): boolean { return this.ptyManager.isRunning(); } public isRestarting(): boolean { return this.restarting; } public setRestarting(restarting: boolean): void { this.restarting = restarting; if (restarting) { this.lastExitCode = undefined; } } public suppressCurrentExitBanner(): void { if (this.processNonce > 0) { this.suppressedExitProcessNonces.add(this.processNonce); } } public clearTranscript(): void { this.transcriptChunks = []; this.transcriptBytes = 0; this.transcriptTruncated = false; this.lastExitCode = undefined; } public appendOutput(data: string): void { if (!data) { return; } this.transcriptChunks.push(data); this.transcriptBytes += data.length; if (this.transcriptBytes <= this.outputBufferMaxBytes) { return; } const fullData = this.transcriptChunks.join(''); const tail = fullData.slice(-this.outputBufferMaxBytes); this.transcriptChunks = [tail]; this.transcriptBytes = tail.length; this.transcriptTruncated = true; } public appendExitBanner(code: number): void { this.lastExitCode = code; this.appendOutput(`\r\n\r\n[Process exited with code ${code}]\r\n`); } public getTranscript(): string { const transcript = this.transcriptChunks.join(''); return this.transcriptTruncated ? `${this.outputTruncationNotice}${transcript}` : transcript; } public toTabState(isActive: boolean): SidebarTerminalTabState { return { id: this.id, title: this.title, isActive, isRunning: this.isRunning(), isRestarting: this.restarting, exitCode: this.lastExitCode, }; } } ================================================ FILE: VSIX/src/startupCommandManager.ts ================================================ const DEFAULT_STARTUP_COMMAND = 'snow'; function normalizeStartupCommand(command: string): string | undefined { const trimmed = command.trim(); return trimmed ? trimmed : undefined; } function parseStartupCommands(rawConfig: string | undefined): string[] { if (typeof rawConfig !== 'string') { return [DEFAULT_STARTUP_COMMAND]; } return rawConfig .split(',') .map(normalizeStartupCommand) .filter((command): command is string => Boolean(command)); } class StartupCommandManager { private commands: string[] = [DEFAULT_STARTUP_COMMAND]; private nextCommandIndex = 0; public setStartupCommandConfig(rawConfig: string | undefined): void { this.commands = parseStartupCommands(rawConfig); this.nextCommandIndex = 0; } public getNextStartupCommand(): string | undefined { if (this.commands.length === 0) { return undefined; } const command = this.commands[this.nextCommandIndex]; this.nextCommandIndex = (this.nextCommandIndex + 1) % this.commands.length; return command; } } export const startupCommandManager = new StartupCommandManager(); ================================================ FILE: VSIX/src/terminalPathFormatter.ts ================================================ import {ShellFamily} from './ptyManager'; type TerminalPathFormatOptions = { shellFamily?: ShellFamily; platform?: NodeJS.Platform; }; function quoteForPowerShell(path: string): string { return `'${path.replace(/'/g, "''")}'`; } function quoteForCmd(path: string): string { return `"${path.replace(/[%!]/g, '^$&')}"`; } function quoteForBash(path: string): string { return `'${path.replace(/'/g, `"'"'`)}'`; } export function formatTerminalPathPayload( paths: readonly string[], options: TerminalPathFormatOptions = {}, ): string { const platform = options.platform ?? process.platform; const family = options.shellFamily ?? (platform === 'win32' ? 'powershell' : 'posix'); const quote = family === 'cmd' ? quoteForCmd : family === 'powershell' ? quoteForPowerShell : quoteForBash; return paths.map(quote).join(' '); } ================================================ FILE: VSIX/src/terminalProxy.ts ================================================ import * as vscode from 'vscode'; export type TerminalProxyEnv = Record; function asOptionalNonEmptyString(value: string | undefined): string | undefined { const normalized = value?.trim(); return normalized ? normalized : undefined; } function getConfiguredSnowTerminalProxyUrl(): string | undefined { const configuredProxy = vscode.workspace .getConfiguration('snow-cli.terminal') .get('proxyUrl', ''); return asOptionalNonEmptyString(configuredProxy); } function getVsCodeHttpProxyUrl(): string | undefined { const vscodeProxy = vscode.workspace.getConfiguration('http').get('proxy', ''); return asOptionalNonEmptyString(vscodeProxy); } export function hasExplicitSnowTerminalProxyUrl(): boolean { return typeof getConfiguredSnowTerminalProxyUrl() !== 'undefined'; } export function getSnowTerminalProxyUrl(): string | undefined { return getConfiguredSnowTerminalProxyUrl() ?? getVsCodeHttpProxyUrl(); } export function getSnowTerminalProxyEnv(): TerminalProxyEnv | undefined { const proxyUrl = getSnowTerminalProxyUrl(); if (!proxyUrl) { return undefined; } return { HTTP_PROXY: proxyUrl, HTTPS_PROXY: proxyUrl, http_proxy: proxyUrl, https_proxy: proxyUrl, }; } ================================================ FILE: VSIX/src/webSocketServer.ts ================================================ import * as vscode from 'vscode'; import {WebSocketServer, WebSocket} from 'ws'; import { handleGoToDefinition, handleFindReferences, handleGetSymbols, handleGetDiagnostics, } from './aceHandlers'; import {showGitDiff} from './diffHandlers'; /** * WebSocket Server Module * Handles WebSocket communication between VSCode extension and Snow CLI */ let wss: WebSocketServer | null = null; let clients: Set = new Set(); let actualPort = 9527; const BASE_PORT = 9527; const MAX_PORT = 9537; // Global cache for last valid editor context let lastValidContext: any = { type: 'context', workspaceFolder: undefined, activeFile: undefined, cursorPosition: undefined, selectedText: undefined, }; /** * Normalize file path for consistent comparison */ function normalizePath(filePath: string | undefined): string | undefined { if (!filePath) { return undefined; } // Convert Windows backslashes to forward slashes for consistent path comparison let normalized = filePath.replace(/\\/g, '/'); // Convert Windows drive letter to lowercase (C: -> c:) if (/^[A-Z]:/.test(normalized)) { normalized = normalized.charAt(0).toLowerCase() + normalized.slice(1); } return normalized; } /** * Get all workspace folder keys for port mapping */ function getWorkspaceFolderKeys(): string[] { const folders = vscode.workspace.workspaceFolders ?? []; const keys = folders .map(folder => normalizePath(folder.uri.fsPath)) .filter((p): p is string => Boolean(p)); // Preserve existing behavior for "single file" mode (no workspace folders). if (keys.length === 0) { return ['']; } // De-dupe in case VSCode reports duplicates. return Array.from(new Set(keys)); } /** * Get workspace folder for a given editor */ function getWorkspaceFolderForEditor( editor: vscode.TextEditor, ): string | undefined { const folder = vscode.workspace.getWorkspaceFolder(editor.document.uri); return ( normalizePath(folder?.uri.fsPath) ?? normalizePath(vscode.workspace.workspaceFolders?.[0]?.uri.fsPath) ); } /** * Broadcast message to all connected clients */ export function broadcast(message: string): void { for (const client of clients) { if (client.readyState === WebSocket.OPEN) { client.send(message); } } } function isTrackableEditor( editor: vscode.TextEditor | undefined, ): editor is vscode.TextEditor { return editor !== undefined && editor.document.uri.scheme !== 'output'; } function getTrackableVisibleEditors(): vscode.TextEditor[] { return vscode.window.visibleTextEditors.filter(isTrackableEditor); } function getFallbackEditor( visibleEditors: vscode.TextEditor[], ): vscode.TextEditor | undefined { if (lastValidContext.activeFile) { const cachedEditor = visibleEditors.find( editor => normalizePath(editor.document.uri.fsPath) === lastValidContext.activeFile, ); if (cachedEditor) { return cachedEditor; } } return visibleEditors[0]; } /** * Send current editor context to all connected clients */ export function sendEditorContext(): void { if (clients.size === 0) { return; } const activeEditor = vscode.window.activeTextEditor; const visibleEditors = getTrackableVisibleEditors(); const editor = isTrackableEditor(activeEditor) ? activeEditor : getFallbackEditor(visibleEditors); if (!editor) { // All editor-area files closed — clear cached context and notify clients lastValidContext = { type: 'context', workspaceFolder: normalizePath( vscode.workspace.workspaceFolders?.[0]?.uri.fsPath, ), activeFile: undefined, cursorPosition: undefined, selectedText: undefined, }; broadcast(JSON.stringify(lastValidContext)); return; } const context: any = { type: 'context', // In multi-root workspaces, tie context to the workspace folder owning the active file. workspaceFolder: getWorkspaceFolderForEditor(editor), activeFile: normalizePath(editor.document.uri.fsPath), cursorPosition: { line: editor.selection.active.line, character: editor.selection.active.character, }, }; // Capture selection if (!editor.selection.isEmpty) { context.selectedText = editor.document.getText(editor.selection); } // Always update cache with valid editor state lastValidContext = {...context}; broadcast(JSON.stringify(context)); } /** * Handle incoming WebSocket messages */ function handleMessage(message: string): void { try { const data = JSON.parse(message); if (data.type === 'getDiagnostics') { const filePath = data.filePath; const requestId = data.requestId; handleGetDiagnostics(filePath, requestId, broadcast); } else if (data.type === 'aceGoToDefinition') { // ACE Code Search: Go to definition const filePath = data.filePath; const line = data.line; const column = data.column; const requestId = data.requestId; handleGoToDefinition(filePath, line, column, requestId, broadcast); } else if (data.type === 'aceFindReferences') { // ACE Code Search: Find references const filePath = data.filePath; const line = data.line; const column = data.column; const requestId = data.requestId; handleFindReferences(filePath, line, column, requestId, broadcast); } else if (data.type === 'aceGetSymbols') { // ACE Code Search: Get document symbols const filePath = data.filePath; const requestId = data.requestId; handleGetSymbols(filePath, requestId, broadcast); } else if (data.type === 'showDiff') { // Show diff in VSCode const filePath = data.filePath; const originalContent = data.originalContent; const newContent = data.newContent; const label = data.label; // Execute the showDiff command vscode.commands.executeCommand('snow-cli.showDiff', { filePath, originalContent, newContent, label, }); } else if (data.type === 'closeDiff') { // Close diff view by calling the closeDiff command vscode.commands.executeCommand('snow-cli.closeDiff'); } else if (data.type === 'showDiffReview') { // Show multiple file diffs for diff review const files = data.files; if (Array.isArray(files)) { vscode.commands.executeCommand('snow-cli.showDiffReview', {files}); } } else if (data.type === 'showGitDiff') { // Show git diff for a file in VSCode const filePath = data.filePath; if (filePath) { showGitDiff(filePath); } } } catch (error) { // Ignore invalid messages } } /** * Start the WebSocket server */ export function startWebSocketServer(): void { if (wss) { return; // Server already running } // Try ports from BASE_PORT to MAX_PORT let port = BASE_PORT; const tryPort = (currentPort: number) => { if (currentPort > MAX_PORT) { console.error( `Failed to start WebSocket server: all ports ${BASE_PORT}-${MAX_PORT} are in use`, ); return; } try { const server = new WebSocketServer({port: currentPort}); server.on('error', (error: any) => { if (error.code === 'EADDRINUSE') { console.log(`Port ${currentPort} is in use, trying next port...`); tryPort(currentPort + 1); } else { console.error('WebSocket server error:', error); } }); server.on('listening', () => { actualPort = currentPort; console.log(`Snow CLI WebSocket server started on port ${actualPort}`); // Write port to a temp file so CLI can discover it const fs = require('fs'); const os = require('os'); const path = require('path'); const portInfoPath = path.join(os.tmpdir(), 'snow-cli-ports.json'); try { let portInfo: any = {}; if (fs.existsSync(portInfoPath)) { portInfo = JSON.parse(fs.readFileSync(portInfoPath, 'utf8')); } // Map *every* workspace folder in this VSCode window to the same port. // This keeps multi-root workspaces working regardless of which folder the terminal is bound to. for (const workspaceFolder of getWorkspaceFolderKeys()) { portInfo[workspaceFolder] = actualPort; } fs.writeFileSync(portInfoPath, JSON.stringify(portInfo, null, 2)); } catch (err) { console.error('Failed to write port info:', err); } }); server.on('connection', ws => { console.log('Snow CLI connected'); clients.add(ws); // Send current editor context immediately upon connection sendEditorContext(); ws.on('message', message => { handleMessage(message.toString()); }); ws.on('close', () => { console.log('Snow CLI disconnected'); clients.delete(ws); }); ws.on('error', error => { console.error('WebSocket error:', error); clients.delete(ws); }); }); wss = server; } catch (error) { console.error(`Failed to start server on port ${currentPort}:`, error); tryPort(currentPort + 1); } }; tryPort(port); } /** * Stop the WebSocket server */ export function stopWebSocketServer(): void { // Close all client connections for (const client of clients) { client.close(); } clients.clear(); // Close server if (wss) { wss.close(); wss = null; } // Clean up port info file try { const fs = require('fs'); const os = require('os'); const path = require('path'); const portInfoPath = path.join(os.tmpdir(), 'snow-cli-ports.json'); if (fs.existsSync(portInfoPath)) { const portInfo = JSON.parse(fs.readFileSync(portInfoPath, 'utf8')); for (const workspaceFolder of getWorkspaceFolderKeys()) { delete portInfo[workspaceFolder]; } if (Object.keys(portInfo).length === 0) { fs.unlinkSync(portInfoPath); } else { fs.writeFileSync(portInfoPath, JSON.stringify(portInfo, null, 2)); } } } catch (err) { console.error('Failed to clean up port info:', err); } } /** * Get the actual port the server is running on */ export function getActualPort(): number { return actualPort; } /** * Get the number of connected clients */ export function getClientCount(): number { return clients.size; } ================================================ FILE: VSIX/tsconfig.json ================================================ { "compilerOptions": { "module": "commonjs", "target": "ES2020", "outDir": "dist", "lib": ["ES2020"], "sourceMap": true, "rootDir": "src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "declaration": true, "moduleResolution": "node" }, "exclude": ["node_modules", ".vscode-test", "dist", "out"] } ================================================ FILE: VSIX/webpack.config.js ================================================ //@ts-check 'use strict'; const path = require('path'); /** @type {import('webpack').Configuration} */ const config = { target: 'node', mode: 'none', entry: './src/extension.ts', output: { path: path.resolve(__dirname, 'dist'), filename: 'extension.js', libraryTarget: 'commonjs2' }, externals: { vscode: 'commonjs vscode', 'node-pty': 'commonjs node-pty', bufferutil: 'commonjs bufferutil', 'utf-8-validate': 'commonjs utf-8-validate' }, resolve: { extensions: ['.ts', '.js'] }, module: { rules: [ { test: /\.ts$/, exclude: /node_modules/, use: [ { loader: 'ts-loader' } ] } ] }, devtool: 'nosources-source-map', infrastructureLogging: { level: 'log' } }; module.exports = config; ================================================ FILE: build-ncc.mjs ================================================ import {exec} from 'child_process'; import {promisify} from 'util'; import {copyFileSync, mkdirSync, existsSync} from 'fs'; import {join} from 'path'; const execAsync = promisify(exec); // Create bundle directory if (!existsSync('bundle')) { mkdirSync('bundle'); } // Run ncc console.log('Building with ncc...'); await execAsync('ncc build dist/cli.js -o bundle --minify'); // Copy WASM file copyFileSync( 'node_modules/sql.js/dist/sql-wasm.wasm', 'bundle/sql-wasm.wasm', ); // Rename index.js to cli.cjs if (existsSync('bundle/index.js')) { const {renameSync} = await import('fs'); renameSync('bundle/index.js', 'bundle/cli.cjs'); } console.log('✓ Bundle created successfully'); ================================================ FILE: build-shim.js ================================================ import { fileURLToPath as _fileURLToPath } from 'url'; import { dirname as _dirname } from 'path'; import { createRequire as _createRequire } from 'module'; export const __filename = _fileURLToPath(import.meta.url); export const __dirname = _dirname(__filename); export const require = _createRequire(import.meta.url); ================================================ FILE: build.mjs ================================================ import * as esbuild from 'esbuild'; import {copyFileSync, existsSync, mkdirSync} from 'fs'; import {builtinModules} from 'module'; import {resolve} from 'path'; // Plugin to stub out optional dependencies const stubPlugin = { name: 'stub', setup(build) { build.onResolve({filter: /^react-devtools-core$/}, () => ({ path: 'react-devtools-core', namespace: 'stub-ns', })); build.onResolve({filter: /^@napi-rs\/canvas$/}, () => ({ path: '@napi-rs/canvas', namespace: 'stub-ns', })); build.onLoad({filter: /.*/, namespace: 'stub-ns'}, () => ({ contents: 'export default {}', })); }, }; // Create bundle directory if (!existsSync('bundle')) { mkdirSync('bundle'); } await esbuild.build({ entryPoints: ['dist/cli.js'], bundle: true, platform: 'node', target: 'node16', format: 'esm', outfile: 'bundle/cli.mjs', banner: { js: `import { createRequire as _createRequire } from 'module'; import { fileURLToPath as _fileURLToPath } from 'url'; const __snow_raw_require = _createRequire(import.meta.url); const require = Object.assign((moduleName) => { const moduleValue = __snow_raw_require(moduleName); if (moduleName === 'fetch-cookie' && typeof moduleValue !== 'function' && typeof moduleValue?.default === 'function') { return moduleValue.default; } return moduleValue; }, __snow_raw_require); const __filename = _fileURLToPath(import.meta.url); const __dirname = _fileURLToPath(new URL('.', import.meta.url)); // Pre-load @microsoft/signalr runtime dependencies into require.cache. // SignalR uses dynamic require() which esbuild cannot bundle statically. // Avoid eager-loading node-fetch on Node 18+, because that triggers // DEP0040 through node-fetch -> whatwg-url -> tr46 -> punycode even though // SignalR will use the native fetch implementation when it already exists. const __signalr_deps = { 'abort-controller': require('abort-controller'), 'eventsource': require('eventsource'), 'fetch-cookie': require('fetch-cookie'), 'tough-cookie': require('tough-cookie'), 'ws': require('ws') }; if (typeof globalThis.fetch === 'undefined') { __signalr_deps['node-fetch'] = require('node-fetch'); } // Polyfill for @microsoft/signalr dynamic require // SignalR uses: const requireFunc = typeof __webpack_require__ === "function" ? __non_webpack_require__ : require; // Keep __non_webpack_require__ aligned with our wrapped require for both branches. const __non_webpack_require__ = require; if (typeof globalThis.__non_webpack_require__ === 'undefined') { globalThis.__non_webpack_require__ = require; } // Polyfill for undici's web API dependencies // undici uses File, Blob, etc. which are only available in Node.js 20+ // For Node.js 16-18, we provide minimal polyfills if (typeof globalThis.File === 'undefined') { globalThis.File = class File { constructor(bits, name, options) { this.bits = bits; this.name = name; this.options = options; } }; } if (typeof globalThis.FormData === 'undefined') { globalThis.FormData = class FormData { constructor() { this._data = new Map(); } append(key, value) { this._data.set(key, value); } get(key) { return this._data.get(key); } }; } // Polyfill browser APIs required by pdfjs-dist in Node.js environment. // pdfjs-dist uses DOMMatrix/ImageData/Path2D at module level, so these must // exist before any bundled pdfjs code executes. // Only stubs are needed — we only do text extraction, not rendering. if (typeof globalThis.DOMMatrix === 'undefined') { globalThis.DOMMatrix = class DOMMatrix { constructor(init) { this.a = 1; this.b = 0; this.c = 0; this.d = 1; this.e = 0; this.f = 0; this.m11 = 1; this.m12 = 0; this.m13 = 0; this.m14 = 0; this.m21 = 0; this.m22 = 1; this.m23 = 0; this.m24 = 0; this.m31 = 0; this.m32 = 0; this.m33 = 1; this.m34 = 0; this.m41 = 0; this.m42 = 0; this.m43 = 0; this.m44 = 1; this.is2D = true; this.isIdentity = true; if (Array.isArray(init) && init.length === 6) { this.a = init[0]; this.b = init[1]; this.c = init[2]; this.d = init[3]; this.e = init[4]; this.f = init[5]; this.m11 = this.a; this.m12 = this.b; this.m21 = this.c; this.m22 = this.d; this.m41 = this.e; this.m42 = this.f; } } inverse() { return new DOMMatrix(); } multiply() { return new DOMMatrix(); } translate() { return new DOMMatrix(); } scale() { return new DOMMatrix(); } rotate() { return new DOMMatrix(); } scaleSelf() { return this; } translateSelf() { return this; } transformPoint() { return { x: 0, y: 0, z: 0, w: 1 }; } }; } if (typeof globalThis.ImageData === 'undefined') { globalThis.ImageData = class ImageData { constructor(sw, sh) { if (sw instanceof Uint8ClampedArray) { this.data = sw; this.width = sh; this.height = sw.length / (4 * sh); } else { this.width = sw; this.height = sh; this.data = new Uint8ClampedArray(sw * sh * 4); } } }; } if (typeof globalThis.Path2D === 'undefined') { globalThis.Path2D = class Path2D { constructor() {} addPath() {} closePath() {} moveTo() {} lineTo() {} bezierCurveTo() {} quadraticCurveTo() {} arc() {} arcTo() {} ellipse() {} rect() {} }; }`, }, external: [ // Only Node.js built-in modules should be external ...builtinModules, ...builtinModules.map(m => `node:${m}`), // Optional native dependencies (dynamically imported in code) 'sharp', // SSH2 includes native .node addons that cannot be bundled by esbuild 'ssh2', 'cpu-features', // Note: katex and markdown-it-math are bundled (not external) // Note: @microsoft/signalr dependencies (abort-controller, eventsource, fetch-cookie, node-fetch, tough-cookie) are NOT bundled // They are dynamically required at runtime and must be in package.json dependencies ], alias: { 'ink': resolve('source/vendor/ink/src/index.ts'), }, plugins: [stubPlugin], minify: false, sourcemap: false, metafile: true, logLevel: 'info', }); // Copy WASM files copyFileSync( 'node_modules/sql.js/dist/sql-wasm.wasm', 'bundle/sql-wasm.wasm', ); copyFileSync( 'node_modules/tiktoken/tiktoken_bg.wasm', 'bundle/tiktoken_bg.wasm', ); // Copy PDF.js worker file for PDF parsing copyFileSync( 'node_modules/pdfjs-dist/build/pdf.worker.mjs', 'bundle/pdf.worker.mjs', ); // Copy package.json to bundle directory for version reading copyFileSync('package.json', 'bundle/package.json'); console.log('✓ Bundle created successfully'); ================================================ FILE: docs/role/en/01.Snow CLI Plan Every Step.md ================================================ # Snow CLI Plan Every Step > Note: This English version is being maintained incrementally. > For the latest complete content, refer to the Chinese version: `../zh/01.Snow CLI 一步一规划.md`. ## Role Positioning You are the Snow CLI terminal programming assistant. Your goal is to deliver high-quality code with the minimum necessary analysis: understand quickly, plan clearly, execute reliably, and verify strictly. ## Hard Constraints for Language and Communication 1. Always reply in Chinese in this project workflow. 2. Do not use emoji. 3. Keep output concise, actionable, and practical. 4. Ask questions only when necessary; if execution is clear, execute first and then report. ## Work Mode: Plan Every Step 1. Start with `Plan Agent` for an initial plan. 2. Create `TODO` items and split work into executable tasks. 3. Before each next task, run `Plan Agent` again for the next step. 4. For complex tasks, use multiple small plans instead of one coarse execution. ## Standard Execution Flow 1. Confirm requirements. 2. Locate code first, then read files. 3. Analyze impact and regression risks. 4. Create and maintain TODO tasks via **`todo-manage`** (`action`: `get` / `add` / `update` / `delete`) for the session list. 5. Implement with complete syntax units only. 6. Run build/tests before delivery. 7. Report changes, reasons, verification, and next steps. ## Tool usage guidelines 1. Locate before reading: prefer search tools, then `filesystem-read`. 2. On multi-file work, prefer batch read and batch edit to reduce round-trips. 3. Use `filesystem-edit` when changing existing code. 4. Keep TODOs in sync end-to-end: use **`todo-manage`** with `action` set to `get`, `add`, `update`, or `delete` for the session task list. 5. Record risky or fragile spots with **`notebook-add`** so you do not repeat the same mistakes. ## Notes - This file is the English-maintained counterpart. - Keep section structure aligned with `../zh/01.Snow CLI 一步一规划.md`. - If Chinese content changes, update this file in the same PR when possible. ================================================ FILE: docs/role/zh/01.Snow CLI 一步一规划.md ================================================ # Snow CLI 一步一规划 ## 角色定位 你是 Snow CLI 终端编程助手。你的目标是以最小必要分析完成高质量代码交付：快速理解需求、明确计划、可靠执行、严格验证。 ## 语言与沟通硬性约束 1. 必须始终使用中文回复。 2. 禁止使用 emoji。 3. 输出优先简洁、可执行、可落地，避免空话。 4. 仅在必要时提问；若可直接执行，应先执行再反馈。 ## 工作模式：一步一规划 1. 接收任务后，必须先使用 `Plan Agent` 生成初期规划。 2. 然后创建 `TODO`，将实施步骤拆分为可执行任务。 3. 每完成一项、进入下一项前，必须再次使用 `Plan Agent` 规划下一步。 4. 复杂任务保持多次小规划，禁止一次性粗放执行。 ### 核心原则 确保每一步都进行规划，以多次规划实现更高编码质量与更低返工率。 ## 标准执行流程 1. **需求确认**：提炼目标、约束、输入输出与验收标准。 2. **定位代码**：先搜索后读取；优先读取用户指定文件/路径。 3. **影响分析**：识别依赖、调用方、边界条件与潜在回归风险。 4. **制定步骤**：生成 TODO 并标注执行顺序。 5. **实施修改**：按完整语法单元修改，避免半段编辑。 6. **质量验证**：运行构建/测试，修复报错后再交付。 7. **结果汇报**：说明改动点、原因、验证结果与后续建议。 ## 工具使用规范 1. 读文件前先定位：优先使用搜索工具定位目标，再用 `filesystem-read` 读取。 2. 多文件场景使用批量操作：批量读取、批量编辑，减少往返。 3. 修改现有代码可用 `filesystem-edit`。 4. TODO 工具应贯穿全过程：使用 `todo-manage`，通过 `action` 为 `get` / `add` / `update` / `delete` 管理会话任务列表。 5. 重要风险或脆弱点使用 `notebook-add` 记录，避免反复踩坑。 ## 代码修改硬规则 1. 只修改完整语法单元：函数、代码块、标签必须成对闭合。 2. 修改前必须确认边界：`{}`、`()`、`[]` 与标签闭合完整。 3. 禁止凭猜测编辑：不清楚路径、参数、依赖时先查再改。 4. 优先复用已有实现，避免重复造轮子与硬编码捷径。 5. 保持代码可编译、可运行、可维护，不引入明显技术债。 ## 安全与 Git 规范 1. 未经用户明确要求，禁止执行回滚类操作（如 reset/checkout 还原）。 2. 执行 Git 相关高风险操作前，必须先征得用户确认。 3. 发现非本人造成的异常文件变更时，先暂停并向用户确认再继续。 ## 质量标准与验收清单 交付前必须满足： - [ ] 需求目标已覆盖，未偏离用户约束。 - [ ] 关键变更点已说明，影响范围已检查。 - [ ] 已执行构建或测试命令，结果可说明。 - [ ] 无新增语法错误、明显逻辑错误或未处理异常。 - [ ] TODO 状态已更新，遗留项有明确说明。 ## 输出格式要求 1. 先给结果，再给关键细节。 2. 改动说明应包含：修改文件、核心变更、原因、验证方式。 3. 引用文件时使用可定位路径与行号（如 `src/app.ts:42`）。 4. 若存在风险或未完成项，必须显式标注，不得隐瞒。 ### 标准回复模板（建议） 1. **结果**：一句话说明完成情况。 2. **改动**：按文件列出核心修改点。 3. **原因**：说明为什么这样改。 4. **验证**：列出执行命令与结果。 5. **风险/后续**：说明遗留风险与下一步建议。 ## 禁止事项（负面清单） 1. 禁止跳过规划直接多步并行改动。 2. 禁止只改局部导致语法不完整。 3. 禁止在未知上下文下做假设性修改。 4. 禁止为了“看起来完成”而省略验证步骤。 5. 禁止输出与仓库现状不一致的结论。 6. 禁止未定位文件就直接编辑。 7. 禁止修改后不更新 TODO 状态。 8. 禁止忽略构建/测试失败直接交付。 ================================================ FILE: docs/usage/en/0.Catalogue.md ================================================ # Snow CLI Usage Documentation - Catalogue Welcome to Snow CLI! Agentic coding in your terminal. ## Quick Start - [Installation Guide](./01.Installation%20Guide.md) - System requirements, installation (update, uninstall) steps, IDE extension installation - [First Time Configuration](./02.First%20Time%20Configuration.md) - API configuration, model selection, basic settings - [Startup Parameters Guide](./19.Startup%20Parameters%20Guide.md) - Command-line parameters explained, quick start modes, headless mode, async tasks, developer mode ## Advanced Configuration - [Proxy and Browser Settings](./03.Proxy%20and%20Browser%20Settings.md) - Network proxy configuration, browser usage settings - [Codebase Setup](./04.Codebase%20Setup.md) - Codebase integration, search configuration - [Sub-Agent Configuration](./05.Sub-Agent%20Configuration.md) - Sub-agent management, custom sub-agent configuration - [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Sensitive command protection, custom command rules - [Hooks Configuration](./07.Hooks%20Configuration.md) - Workflow automation, hook types explanation, practical configuration examples - [Theme Settings](./08.Theme%20Settings.md) - Interface theme configuration, custom color schemes, simplified mode - [Third-Party Relay Configuration](./16.Third-Party%20Relay%20Configuration.md) - Claude Code relay, Codex relay, custom headers configuration ## Feature Guide - [Command Panel Guide](./09.Command%20Panel%20Guide.md) - Detailed description of all available commands, usage tips, shortcut key reference - [Command Injection Mode](./10.Command%20Injection%20Mode.md) - Execute commands directly in messages, syntax explanation, security mechanisms, use cases - [Vulnerability Hunting Mode](./11.Vulnerability%20Hunting%20Mode.md) - Professional security analysis, vulnerability detection, verification scripts, detailed reports - [Headless Mode](./12.Headless%20Mode.md) - Command line quick conversations, session management, script integration, third-party tool integration - [Keyboard Shortcuts Guide](./13.Keyboard%20Shortcuts%20Guide.md) - All keyboard shortcuts, editing operations, navigation control, rollback functionality - [MCP Configuration](./14.MCP%20Configuration.md) - MCP service management, configure external services, enable/disable services, troubleshooting - [Async Task Management](./15.Async%20Task%20Management.md) - Background task creation, task management interface, sensitive command approval, task to session conversion - [Skills Command Detailed Guide](./18.Skills%20Command%20Detailed%20Guide.md) - Skill creation, usage methods, Claude Code Skills compatibility, tool restrictions - [LSP Configuration and Usage](./19.LSP%20Configuration.md) - LSP config file, language server installation, ACE tool usage (definition/outline) - [SSE Service Mode](./20.SSE%20Service%20Mode.md) - SSE server startup, API endpoints explanation, tool confirmation flow, permission configuration, YOLO mode, client integration examples - [Custom StatusLine Guide](./21.Custom%20StatusLine%20Guide.md) - User-level StatusLine plugins, hook structure, override behavior, bilingual examples - [Team Mode Guide](./22.Team%20Mode%20Guide.md) - Multi-agent collaboration, parallel task execution, team management - [Custom Search Engine Guide](./23.Custom%20Search%20Engine%20Guide.md) - User-level search engine plugins, engine contract, enable flag, minimal template ================================================ FILE: docs/usage/en/01.Installation Guide.md ================================================ # Snow CLI User Documentation - Installation Guide Welcome to Snow CLI! Agentic coding in your terminal. ## Installation Guide ### 1. System Requirements 1. Operating System: Windows 10+ / macOS 10.15+ / Ubuntu 18.04+ / CentOS 7+ 2. Node.js: v18.0.0+ 3. npm: >= 8.3.0 ### 2. Installing Node.js + npm 1. Windows: Download and install Node.js+npm from [https://nodejs.org/en/download/](https://nodejs.org/en/download/) 2. macOS: Install Node.js+npm via Homebrew ```bash brew install node ``` 3. Linux: Install Node.js+npm via apt-get ```bash sudo apt-get install nodejs sudo apt-get install npm ``` 4. Verify successful installation ```bash node -v npm -v ``` ### 3. Installing Snow CLI and IDE Plugins 1. Install Snow CLI using npm ```bash npm install -g snow-ai ``` 2. Install Snow CLI by compiling from source ```bash git clone https://github.com/MayDay-wpf/snow-cli cd snow-cli npm install npm run build npm run link ``` 3. Verify successful installation ```bash snow --version snow --help ``` 4. Install VSCode Plugin Search for `Snow CLI` in the Extensions Marketplace and install ![alt text](../images/image.png) After installation, a launch icon will appear in the top-right corner of VSCode ![alt text](../images/image1.png) 5. VSCode Extension Settings After installing the VSCode plugin, you can configure the following settings in `Settings` (search for `Snow CLI`): - **Terminal Mode** (`snow-cli.terminalMode`): Choose the terminal display mode. - `split` (default): Opens a terminal in a right-side editor split. - `sidebar`: Embeds a terminal in the sidebar panel. - **Startup Command** (`snow-cli.startupCommand`): The command to run when the terminal starts. Default is `snow`. Supports comma-separated commands for round-robin assignment across multiple terminals. - **Shell Type** (`snow-cli.terminal.shellType`): Shell for the sidebar terminal. Default is `auto` to follow VS Code's default terminal profile. You can also specify a custom shell path (e.g., `C:\Program Files\Git\bin\bash.exe`, `/usr/bin/zsh`). - **Proxy URL** (`snow-cli.terminal.proxyUrl`): Optional proxy URL injected into Snow CLI terminals as `HTTP_PROXY`/`HTTPS_PROXY`. Leave empty to fall back to VS Code's `http.proxy` setting. - **Font Family** (`snow-cli.terminal.fontFamily`): Font family for the sidebar terminal. Leave empty to use the default monospace font. - **Font Size** (`snow-cli.terminal.fontSize`): Font size (px) for the sidebar terminal. Default is `14` (range: 8–32). - **Font Weight** (`snow-cli.terminal.fontWeight`): Font weight for the sidebar terminal. Default is `normal`. - **Line Height** (`snow-cli.terminal.lineHeight`): Line height for the sidebar terminal. Default is `1` (range: 0.8–2). - **Git Blame** (`snow-cli.gitBlame.enabled`): Enable Git Blame annotations on the current line, similar to GitLens. Default is `false`. 6. Install JetBrains IDE Plugin Search for `Snow CLI` in the Plugin Marketplace and install After plugin installation, restart your IDE ![alt text](../images/image2.png) A launch icon will appear to the right of the `Tab` in the terminal ![alt text](../images/image3.png) ================================================ FILE: docs/usage/en/02.First Time Configuration.md ================================================ # Snow CLI User Documentation - First Time Configuration Welcome to Snow CLI! Agentic coding in your terminal. ## First Time Configuration ### 1. Launch from Any Directory 1. Type `snow` to start Snow CLI or click the launch icon in the IDE plugin 2. Snow CLI's default language is `English`. You can go to `Language Settings` to modify your language preference ![alt text](../images/image4.png) ### 2. Enter Configuration Interface After setting your language preference, go to `API and Model Settings` ![alt text](../images/image5.png) The configuration interface provides comprehensive AI service configuration capabilities, supporting multiple profile management and rich model parameter settings. ## Detailed Configuration Options ### Profile Management **Purpose**: Manage multiple configuration sets for quick switching between different scenarios **Operations**: - Press Enter to access the profile selection interface - Use up/down arrow keys to select profiles - The currently active profile will display a green ✓ mark **Quick Actions**: - Press `n` key: Create new profile (requires entering profile name) - Press `d` key: Delete current profile (the default profile cannot be deleted) **Important Notes**: - Each profile independently saves all settings - Switching profiles immediately loads all settings from that profile ### Basic Configuration #### Base URL (Required) **Purpose**: Base address of the API service **Configuration Method**: - Press Enter to enter edit mode - Input the complete API address - Press Enter again to confirm **Standard Addresses**: ![alt text](../images/image6.png) 1. **OpenAI Chat Completion** ``` https://api.openai.com/v1 ``` For OpenAI's standard chat completion API 2. **OpenAI Responses** ``` https://api.openai.com/v1 ``` For OpenAI's response API with reasoning capabilities 3. **Gemini** ``` https://generativelanguage.googleapis.com/v1beta ``` Google Gemini API service address 4. **Anthropic** ``` https://api.anthropic.com/v1 ``` API service address for Claude models **Important Notes**: - Supports proxy or third-party relay service addresses - Ensure the address format is correct, starting with `https://` - Address typically includes version number at the end (e.g., `/v1`) #### API Key (Required) **Purpose**: Access key for API service **Configuration Method**: - Press Enter to enter edit mode - Input the complete API Key - Input will be automatically hidden and displayed as `*` characters - Press Enter again to confirm **Important Notes**: - API Keys typically start with specific prefixes (e.g., `sk-` for OpenAI) - Keep your API Key secure to prevent disclosure - Will only display as asterisks, never in plain text #### Request Method **Purpose**: Select API calling method; different methods support different features **Available Options**: - **OpenAI Chat Completion**: Standard OpenAI chat API - **OpenAI Responses**: OpenAI API with reasoning mode support - **Gemini**: Google's Gemini model - **Anthropic**: Claude model **Configuration Method**: - Press Enter to open selection list - Use up/down arrow keys to select - Press Enter to confirm **Important Notes**: - Different request methods display different advanced configuration options - When switching request methods, specific feature configurations will automatically adjust #### System Prompt (Optional) **Purpose**: Select which system prompt to use for the current profile **Available Options**: - **Follow Global (None)**: Use global settings, no system prompt currently activated - **Follow Global (Name)**: Use the system prompt activated in global settings - **Not Use**: Explicitly disable system prompt, even if there's an activated global prompt - **Select Specific Prompt**: Choose from the list of configured system prompts **Configuration Method**: - Press Enter to open selection list - Use up/down arrow keys to select - Press Enter to confirm **Description**: - System prompts can be created and managed in the "System Prompt Management" interface - Profile-level settings override global settings - Selecting "Not Use" allows you to temporarily disable system prompts in specific scenarios #### Custom Headers (Optional) **Purpose**: Select which custom headers scheme to use for the current profile **Available Options**: - **Follow Global (None)**: Use global settings, no headers scheme currently activated - **Follow Global (Name)**: Use the headers scheme activated in global settings - **Not Use**: Explicitly disable custom headers, even if there's an activated global scheme - **Select Specific Scheme**: Choose from the list of configured headers schemes **Configuration Method**: - Press Enter to open selection list - Use up/down arrow keys to select - Press Enter to confirm **Description**: - Custom headers schemes can be created and managed in the "Custom Headers Management" interface - Profile-level settings override global settings - Selecting "Not Use" allows you to temporarily disable custom headers in specific scenarios ### Advanced Configuration #### Enable Auto Compress **Purpose**: Automatically compress long text content to reduce token consumption **Default**: Enabled **Configuration Method**: - Press Enter or Space key to toggle Enabled/Disabled status - Displays "Enabled" or "Disabled" **Recommendation**: Enabling can reduce API call costs but may lose some context details #### Show Thinking **Purpose**: Display AI's reasoning and thinking process in the interface **Default**: Enabled **Configuration Method**: - Press Enter or Space key to toggle Enabled/Disabled status - Displays "Enabled" or "Disabled" **Recommendation**: Enabling helps understand AI's reasoning process, useful for debugging and understanding results ### Anthropic-Specific Configuration When selecting the `Anthropic` request method, the following configuration options will appear: #### Anthropic Beta **Purpose**: Enable Anthropic's Beta version features **Default**: Disabled **Configuration Method**: - Press Enter or Space key to toggle Enabled/Disabled status **Important Notes**: Beta features may be unstable, use with caution #### Anthropic Cache TTL **Purpose**: Set the expiration time for prompt caching **Available Options**: - `5m`: 5 minutes - `1h`: 1 hour **Default**: 5 minutes **Configuration Method**: - Press Enter to open selection list - Select cache duration - Press Enter to confirm **Description**: Longer cache times can reduce token consumption for repeated content #### Thinking Enabled **Purpose**: Enable Claude's extended thinking feature **Default**: Disabled **Configuration Method**: - Press Enter or Space key to toggle Enabled/Disabled status **Description**: When enabled, AI will perform deeper reasoning #### Thinking Budget Tokens **Purpose**: Set the maximum token count for extended thinking mode **Default**: 10000 **Range**: Minimum value 1000 **Configuration Method**: - Press Enter to enter edit mode - Input number (supports backspace deletion) - Press Enter to confirm **Important Notes**: - Larger thinking budget enables deeper AI reasoning but consumes more tokens - If input value is below minimum, it will automatically adjust to minimum value when saved ### Gemini-Specific Configuration When selecting the `Gemini` request method, the following configuration options will appear: #### Gemini Thinking Enabled **Purpose**: Enable Gemini's thinking and reasoning feature **Default**: Disabled **Configuration Method**: - Press Enter or Space key to toggle Enabled/Disabled status #### Gemini Thinking Budget **Purpose**: Set the budget value for Gemini thinking mode **Default**: 1024 **Range**: Minimum value 1 **Configuration Method**: - Press Enter to enter edit mode - Input number (supports backspace deletion) - Press Enter to confirm ### OpenAI Responses-Specific Configuration When selecting the `OpenAI Responses` request method, the following configuration options will appear: #### Responses Reasoning Enabled **Purpose**: Enable OpenAI's reasoning feature **Default**: Disabled **Configuration Method**: - Press Enter or Space key to toggle Enabled/Disabled status #### Responses Reasoning Effort **Purpose**: Set the intensity level of reasoning mode **Available Options**: - `LOW`: Low-intensity reasoning - `MEDIUM`: Medium-intensity reasoning - `HIGH`: High-intensity reasoning - `XHIGH`: Ultra-high intensity reasoning (only supported in responses method) **Default**: HIGH **Configuration Method**: - Press Enter to open selection list - Use up/down arrow keys to select intensity - Press Enter to confirm **Important Notes**: Higher reasoning intensity provides deeper reasoning but increases time and token consumption ### Model Configuration #### Advanced Model **Purpose**: Primary model for complex tasks **Configuration Method**: 1. Press Enter to automatically fetch available model list (requires correct Base URL and API Key configuration) 2. If fetching fails, will automatically enter manual input mode 3. Can use alphanumeric input for fuzzy search filtering 4. Select "Manual Input" option to manually enter model name 5. Press `m` key to quickly enter manual input mode **Common Model Examples**: - OpenAI: `gpt-4`, `gpt-4-turbo`, `gpt-4o` - Claude: `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229` - Gemini: `gemini-2.0-flash-exp`, `gemini-pro` **Recommendation**: Choose more powerful models for complex programming tasks #### Basic Model **Purpose**: Auxiliary model for simple tasks **Configuration Method**: Same as Advanced Model **Common Model Examples**: - OpenAI: `gpt-3.5-turbo`, `gpt-4o-mini` - Claude: `claude-3-haiku-20240307` - Gemini: `gemini-flash` **Recommendation**: Choose models with fast response speed and lower cost #### Max Context Tokens **Purpose**: Maximum context window size supported by the model **Default**: 4000 **Range**: Minimum value 4000 **Configuration Method**: - Press Enter to enter edit mode - Input number (supports backspace deletion) - Press Enter to confirm **Common Model Context Capacities**: - Claude 3.5 Sonnet: 200000 - GPT-4 Turbo: 128000 - GPT-4: 8192 - Gemini 2.0 Flash: 1000000 - Gemini Pro: 32768 **Important Notes**: - Must be set to the actual context size supported by the model - Setting too high will cause API call failures - Setting too low will limit conversation length #### Max Tokens **Purpose**: Maximum token count allowed for single response generation **Default**: 4096 **Range**: Minimum value 100 **Configuration Method**: - Press Enter to enter edit mode - Input number (supports backspace deletion) - Press Enter to confirm **Common Model Output Capacities**: - Claude 3.5 Sonnet: 64000 - GPT-4 Turbo: 4096 - GPT-4: 8192 - Gemini 2.0 Flash: 8192 **Important Notes**: - Different models support different maximum output token counts - Setting too high will increase response time and cost - Recommend setting reasonably based on actual needs ## Configuration Interface Operations ### Basic Operations - **Up/Down Arrow Keys**: Move between configuration items - **Enter Key**: Enter edit mode or confirm input - **Esc Key**: Save configuration and exit - **Ctrl+S / Cmd+S**: Quick save configuration - **Space Key**: Toggle switch-type configuration items (e.g., Enable/Disable) ### Navigation Tips - Configuration interface displays current position at top: `(Current item/Total items)` - When configuration items exceed 8, will automatically scroll - Currently selected configuration item displays `❯` marker ### Enhanced Model Selection Features In the model selection interface: - **Alphanumeric Input**: Real-time filtering of model list - **Backspace**: Delete filter characters - **Esc Key**: Exit selection interface - **m Key**: Quick entry to manual input mode ### Enhanced Number Input When editing token-related configurations: - **Number Keys**: Append digits - **Backspace/Delete**: Delete last digit - **Enter Key**: Confirm and automatically validate minimum value ## Configuration Validation The system will automatically validate when saving configuration: 1. **Required Field Check**: Base URL and API Key must be filled 2. **Format Validation**: Check if Base URL format is correct 3. **Value Range**: Automatically adjust token configurations above minimum values 4. **Request Method Matching**: Validate compatibility between selected model and request method **Error Messages**: - Red error information will display at bottom of interface when validation fails - Can try saving again after fixing errors ## Configuration File Storage - **Main Configuration File**: `~/.snowcli/config.json` - **Profile Directory**: `~/.snowcli/profiles/` - **Auto Save**: Automatically saves to currently active profile when exiting configuration interface ## FAQ ### 1. Unable to fetch model list? **Solution**: - Check if Base URL and API Key are correct - Check network connection and proxy settings - If it continues to fail, use manual input mode (press `m` key) ### 2. Configuration doesn't take effect after saving? **Solution**: - Confirm you have saved configuration by pressing Esc or Ctrl+S - Restart Snow CLI to ensure configuration is loaded - Check if the correct profile is selected ### 3. Token limit exceeded error? **Solution**: - Check if Max Context Tokens is set correctly - Confirm it doesn't exceed the model's actual supported context size - Appropriately reduce Max Tokens setting ### 4. Configuration lost after switching request methods? **Explanation**: Specific configuration items for different request methods (such as Anthropic's Thinking feature) will automatically show/hide based on the current method. Configuration values are still saved and will be restored when switching back. ## Configuration Best Practices 1. **First-Time Configuration**: First set Basic configuration (Base URL, API Key, Request Method), then configure advanced features 2. **Multi-Scenario Usage**: Create different profiles for different projects 3. **Cost Optimization**: Reasonably set Max Tokens, enable Auto Compress feature 4. **Performance Optimization**: Choose appropriate models based on task complexity, use Basic Model for simple tasks 5. **Debugging Recommendation**: Enable Show Thinking to view AI reasoning process, helpful for understanding and optimizing prompts ================================================ FILE: docs/usage/en/03.Proxy and Browser Settings.md ================================================ # Snow CLI User Documentation - Proxy and Browser Settings Welcome to Snow CLI! Agentic coding in your terminal. ## Proxy and Browser Settings * When proxy is enabled, CLI traffic will be transmitted through the custom port * Browser Settings: The CLI's web search functionality will use a browser. By default, it selects the default browser for macOS and Windows. If the default browser's installation location has changed, please manually specify the browser path ================================================ FILE: docs/usage/en/04.Codebase Setup.md ================================================ # Snow CLI User Guide - Codebase Setup Welcome to Snow CLI! Agentic coding in your terminal. ## Codebase Setup Snow CLI supports enabling local codebase functionality. _The codebase is a vector search-based SQLite database used to store source code and comments from your codebase, with natural language query capabilities through vectorization._ ## Configuration Storage Codebase configuration is split into two parts: - **Project-level config** (`.snow/codebase.json`): Stored in project root, controls enable/disable status, indexing parameters, reranking config, etc. - **Global config** (`~/.snow/codebase.json`): Stores Embedding service configuration, shared across projects This allows each project to independently control codebase functionality, while Embedding settings only need to be configured once. ## Quick Toggle Use the `/codebase` command to quickly control codebase functionality for the current project: - `/codebase` - Toggle enable/disable - `/codebase on` - Enable codebase - `/codebase off` - Disable codebase - `/codebase status` - View current status When enabling for the first time, you need to configure the Embedding service in `/home` first. ## Configuration UI In `/home` → Codebase Config, settings are organized into collapsible groups to save screen space: ``` CodeBase Enabled: ← Master toggle Agent Review: ← AI review of search results (mutually exclusive with reranking) Result Reranking: ← Rerank search results (mutually exclusive with agent review) ▶ Embedding Model Config ← Press Enter to expand/collapse ▶ Reranking Model Config ← Press Enter to expand/collapse ▶ Batch Settings ← Press Enter to expand/collapse ``` Use ↑↓ to navigate, Enter to edit/toggle/expand, Ctrl+S or Esc to save. ## Search Result Optimization After codebase search returns results, there are two optimization modes available (**mutually exclusive, cannot be enabled simultaneously**): ### Agent Review Uses an AI model (basicModel) to semantically review search results, filtering out irrelevant items and potentially suggesting better search keywords. Best for scenarios requiring deep code semantic understanding. - Supports multi-round retry with keyword suggestions - Can identify high-confidence files for deep exploration - Depends on configured AI models (basicModel / advancedModel) ### Result Reranking Uses a dedicated Rerank model to reorder search results by relevance, returning the Top N most relevant items. More lightweight and efficient compared to Agent Review, best for speed-oriented scenarios. - Calls standard Rerank API (compatible with Jina Reranker, Cohere Rerank, etc.) - Built-in 3-attempt retry with exponential backoff - Built-in context length protection: uses tiktoken for precise token counting, auto-truncates or drops oversized documents to prevent context overflow - Graceful degradation to raw search results on failure **Mutual exclusivity**: Enabling "Result Reranking" automatically disables "Agent Review", and vice versa. The reranking model must be configured before it can be enabled. ## Embedding Service Configuration Expand under "▶ Embedding Model Config": - The codebase supports three request schemes: Jina (OpenAI-compatible), Ollama (local deployment, supports both OpenAI-compatible `/v1/embeddings` and native `/api/embed`), and Gemini. - Codebase BaseURL (multiple forms supported; Snow CLI will auto-normalize to the final endpoint): - Jina (OpenAI-compatible) supports: `https://api.jina.ai`, `https://api.jina.ai/v1`, `https://api.jina.ai/v1/embeddings` (final request: `.../v1/embeddings`). - Ollama supports: `http://localhost:11434`, `http://localhost:11434/v1`, `http://localhost:11434/v1/embeddings` (OpenAI-compatible); and `http://localhost:11434/api`, `http://localhost:11434/api/embed` (Ollama native). - Embedding Dimensions: Enter the dimensions supported by your embedding model. Some providers may ignore the `dimensions` parameter; Snow CLI will log a warning if the returned dimensions don't match. ## Reranking Model Configuration Expand under "▶ Reranking Model Config": | Setting | Description | Default | |---------|-------------|---------| | Model Name | Rerank model name, e.g. `jina-reranker-v2-base-multilingual` | — | | Base URL | Rerank API endpoint, e.g. `https://api.jina.ai` (auto-appends `/v1/rerank`) | — | | API Key | API authentication key (optional, can be left empty for local deployments) | — | | Model Context Length | Maximum context tokens the model supports, used to prevent request overflow | 4096 | | Top N | Number of top results to return after reranking | 5 | **Context length protection**: Before sending requests, tiktoken is used to precisely calculate the total token count of all documents. Individual documents exceeding 30% of the context window are truncated; documents that would exceed the total budget are dropped. This ensures requests never overflow the model's context limit. ## Indexing Parameters Expand under "▶ Batch Settings": - Chunking Configuration: Configure how code is split into chunks for indexing. These settings control the size and overlap of code segments: - `maxLinesPerChunk`: Maximum lines per chunk (default: 200) - `minLinesPerChunk`: Minimum lines per chunk (default: 10) - `minCharsPerChunk`: Minimum characters per chunk (default: 20) - `overlapLines`: Lines overlapping between consecutive chunks (default: 20) These settings affect search accuracy and indexing performance. - Batch Processing: Control how files are processed in batches for efficient indexing: - `maxLines`: Maximum lines per batch request (default: 10) - `concurrency`: Number of concurrent batch operations (default: 3) This controls the number of `input` items sent to the embedding API per request. **Note: Maximum batch lines refers to the number of `input` items in the request body, not the number of lines in code slices** ## Related Features After enabling codebase indexing, the following features will be significantly enhanced: - [Vulnerability Hunting Mode](./11.Vulnerability%20Hunting%20Mode.md) - Codebase indexing can greatly improve accuracy and efficiency of security analysis - [Command Panel Guide](./9.Command%20Panel%20Guide.md) - Use `/reindex` to rebuild codebase index, use `/codebase` to toggle enable/disable ================================================ FILE: docs/usage/en/05.Sub-Agent Configuration.md ================================================ # Snow CLI User Guide - Sub-Agent Configuration Welcome to Snow CLI! Agentic coding in your terminal. ## What are Sub-Agents Sub-agents are branches of the main workflow in Snow CLI, designed to handle specific individual tasks to save context usage in the main workflow. ## Three Built-in System Sub-Agents - Explore Agent - An exploration agent for searching code functionality for the main workflow, focusing on locating code positions. - Plan Agent - A planning agent for developing comprehensive coding plans and guidance for the main workflow. - General Purpose Agent - A general-purpose agent that provides common coding functionality for the main workflow, suitable for completing tasks that are singular but involve many files (e.g., internationalization). ## Sub-Agent Workflow ```mermaid graph TB Start([User Initiates Task]) --> MainProcess[Main Workflow Main Agent] MainProcess --> Check{Does it need
a sub-agent?} Check -->|No| DirectHandle[Main workflow handles directly] DirectHandle --> End([Return Result]) Check -->|Yes| SelectAgent{Select sub-agent type} SelectAgent -->|Code exploration| ExploreAgent[Explore Agent
Exploration Agent] SelectAgent -->|Make plan| PlanAgent[Plan Agent
Planning Agent] SelectAgent -->|General coding| GeneralAgent[General Purpose Agent
General-Purpose Agent] ExploreAgent --> SendTask[Main workflow sends task prompt] PlanAgent --> SendTask GeneralAgent --> SendTask SendTask --> SubProcess[Sub-agent receives task] SubProcess --> Isolate[Independent context environment
Isolated from main workflow] Isolate --> SpecializedWork{Specialized direction processing} SpecializedWork -->|Explore agent| SearchCode[Search code positions
Analyze code structure] SpecializedWork -->|Plan agent| MakePlan[Develop coding plan
Provide guidance] SpecializedWork -->|General agent| GeneralWork[Execute general coding
Process batch files] SearchCode --> Complete[Processing complete] MakePlan --> Complete GeneralWork --> Complete Complete --> Return[Send results back to main workflow] Return --> MainReceive[Main workflow receives results] MainReceive --> End style MainProcess fill:#e1f5ff style ExploreAgent fill:#fff4e1 style PlanAgent fill:#ffe1f5 style GeneralAgent fill:#e1ffe1 style Isolate fill:#ffe1e1 style SubProcess fill:#f0f0f0 style Return fill:#e1ffe1 ``` ### Workflow Description 1. **Main Workflow Assessment**: After receiving a user task, the main workflow first evaluates whether a sub-agent is needed. 2. **Sub-Agent Selection**: Select an appropriate sub-agent based on the task type: - **Explore Agent**: Deep code exploration (5+ files), complex dependency tracing - **Plan Agent**: Breaking down complex features, major refactoring planning - **General Purpose Agent**: Batch modifications (5+ files), systematic refactoring 3. **Task Dispatch**: The main workflow sends a task prompt containing complete context to the sub-agent. 4. **Independent Processing**: The sub-agent processes the task in an independent context environment, completely isolated from the main workflow. 5. **Specialized Processing**: Each sub-agent performs targeted processing according to its specialized direction. 6. **Return Results**: After processing is complete, the sub-agent sends the results back to the main workflow. 7. **Main Workflow Continues**: The main workflow receives the results and continues with subsequent work. ### Key Features - **Context Isolation**: Sub-agents have independent context that does not affect the main workflow's conversation history. - **One-Way Communication**: Main workflow → Send task → Sub-agent → Return results → Main workflow - **Specialized Division of Labor**: Each sub-agent focuses on a specific domain, improving processing efficiency. - **Resource Conservation**: Prevents the main workflow context from being occupied by extensive exploration or planning information. ## Sub-Agent Configuration Management ### Adding a Sub-Agent You can create custom sub-agents through the configuration interface to meet specific business needs. #### Operation Steps 1. **Enter Configuration Interface** - Select "Sub-Agent Configuration" in the main menu - Select "Add Sub-Agent" 2. **Basic Information Configuration** Fill in the following fields as prompted by the interface: - **Agent Name** (Required) - Enter the name of the sub-agent - Suggest using descriptive names like "Code Review Agent", "Testing Agent", etc. - Press Enter to confirm and move to the next field - **Description** (Required) - Enter the function description of the sub-agent - Describe in detail the purpose and application scenarios of this sub-agent - **Role Definition** (Required) - Define the role and behavioral norms of the sub-agent - This is the sub-agent's own role instructions. At runtime it is appended to the prompt sent to the sub-agent. - Example: ``` You are a professional code review assistant. Your responsibilities are: 1. Check code quality and compliance 2. Discover potential bugs and security issues 3. Provide improvement suggestions and best practices ``` - Press Enter to confirm and move to the next field 3. **Advanced Configuration Options** **Important Reminder**: Sub-agents no longer select **System Prompt** or **Custom Request Headers** separately. Both are taken from the selected **Configuration Profile** (Profile), because the profile already contains these settings. - **Configuration Profile** (Optional) - Specify a dedicated API configuration profile for the sub-agent - Purpose: Allow the sub-agent to use different API endpoints, different models, and the system prompt + request headers defined in that profile - Operation: - Use ↑/↓ arrow keys to browse available profiles - Press Space to select/deselect - Use ←/→ arrow keys to quickly switch between configuration options - Marker description: `❯` indicates cursor position, `[✓]` indicates selected - Application scenarios: - Let the sub-agent use more powerful models - Let the sub-agent use different API providers - Allocate different billing accounts for different sub-agents - Bind different system prompts/request headers via different profiles - Set different request priorities 4. **Tool Permission Configuration** Select the tools that the sub-agent can use: - Use ↑/↓ arrow keys to navigate between tool categories - Use ←/→ arrow keys to switch between tool categories - Press Space to select/deselect tools - Tool categories include: - Filesystem tools (filesystem-read, filesystem-create, filesystem-edit, etc.) - ACE code search tool (`ace-search` with action: find_definition / find_references / semantic_search / file_outline / text_search) - Codebase tools (codebase-search) - Terminal tools (terminal-execute) - TODO management tools - Web search tools - MCP tools (if configured) **Suggestion**: Only grant the minimum set of permissions needed for the sub-agent to complete its tasks. 5. **Save Configuration** - Press Ctrl+S to save the configuration - The system will automatically validate the configuration's completeness - Return to the main menu after successful save #### Configuration Inheritance Explanation When creating a new sub-agent, if no **Configuration Profile** (Profile) is specified, the sub-agent will follow the currently active profile of the main workflow. This means: - The sub-agent will use the same API configuration and model as the main workflow - The sub-agent will use the system prompt and request headers defined in that profile (and then apply its own role definition on top) ### Editing a Sub-Agent You can edit existing sub-agent configurations, including the three built-in system agents. #### Operation Steps 1. **Enter Edit Interface** - Select "Sub-Agent Configuration" in the main menu - Select the sub-agent to edit 2. **Edit Restrictions Explanation** **System Built-in Agents** (Explore Agent, Plan Agent, General Purpose Agent): - Name, description, and role definition are read-only and cannot be modified - The interface will display "(System Built-in - Not Modifiable)" prompt - Can modify: Tool permissions, configuration profile **Custom Agents**: - All fields can be modified 3. **Modify Configuration** Navigation and operation methods are the same as adding an agent: - Use ↑/↓ arrow keys to navigate between fields - Use ←/→ arrow keys to switch between configuration options - Press Space to select/deselect - Directly input modification content in text fields 4. **Save Changes** - Press Ctrl+S to save changes - The system will validate the modified configuration - Return to the main menu after successful save #### Edit Configuration Inheritance Explanation When editing an existing sub-agent: - If the sub-agent already has custom configurations, the interface will display and load these configurations - If the sub-agent does not have custom configurations: - When editing a copy of a system built-in agent, it will automatically inherit the current main workflow's configuration as default values - When editing an existing custom agent, configurations will not be automatically filled (remain unselected) ### Configuration Best Practices 1. **Clear Role Definition** - Clearly describe the scope of responsibilities of the sub-agent - Provide specific work steps or checklists - Specify output format and quality standards 2. **Reasonable Tool Permission Allocation** - Follow the principle of least privilege - Read-only tasks do not grant write tools - Exploration tasks do not grant execution tools 3. **Good Use of Configuration Isolation** - Configure different sub-agents for different types of tasks - Use different configuration profiles (Profile) to control cost and model selection - Use different configuration profiles (Profile) to bind different system prompts and request headers 4. **Test Configuration Effects** - Perform small-scale testing after creation - Observe whether the sub-agent's behavior meets expectations - Adjust role definition and tool permissions based on actual effects ### Keyboard Shortcuts - **↑/↓**: Navigate between options or scroll lists - **←/→**: Switch between fields (configuration options, tool categories) - **Space**: Select/deselect (tools, configuration options) - **Enter**: Confirm input and move to next field - **Ctrl+S**: Save configuration - **Ctrl+C** or **ESC**: Cancel and return ## Quick Sub-Agent Selection In addition to using the `/agent-` command to open the sub-agent selection panel, you can also use the `#` symbol in the input box to quickly trigger the sub-agent picker: ### How to Use 1. **Trigger the picker**: Type `#` in the input box to automatically pop up the sub-agent selection panel 2. **Search and filter**: Type `#keyword` to filter sub-agents by ID, name, or description 3. **Select sub-agent**: Use arrow keys to select a sub-agent, press Enter to confirm. The system will automatically insert `#subAgentID ` into the input box ### Examples ``` #explore → Select explore sub-agent #plan → Select plan sub-agent #general → Select general sub-agent ``` ### Notes - The `#` symbol must not be preceded by `@` (e.g., `@#` or `@@#` will not trigger the sub-agent picker, but the file picker) - If you type a space or newline after `#`, the picker will automatically close - Press ESC to close the sub-agent selection panel ## Sending Messages to Running Sub-Agents When a sub-agent is running, you can use the `>>` command to send messages to specific running sub-agents, enabling real-time interaction with the main workflow. ### How to Use 1. **Trigger the picker**: Type `>>` at the beginning of the input box (leading whitespace is allowed) to pop up the list of currently running sub-agents 2. **Select sub-agents**: - Use `↑/↓` arrow keys to navigate - Use `Space` to select/deselect sub-agents (supports multi-select) - If no sub-agent is explicitly selected, the currently highlighted item will be auto-selected when you press Enter 3. **Send message**: Press `Enter` to confirm selection, then type your message and send ### Visual Tag Explanation After selecting sub-agents, a visual tag will appear in the input box: ``` [»Explore Agent#abcd: Investigating project architecture...] Please continue analyzing ``` - `»` symbol (U+00BB): Used to avoid re-triggering the picker - `Explore Agent`: Sub-agent name - `#abcd`: Last 4 characters of instance ID (ensures uniqueness) - `Investigating project architecture...`: Short summary of the task prompt ### Message Routing Mechanism The actual sent message contains a special marker: ``` # SubAgentTarget:instanceId:agentName Your message content ``` The system routes the message to the corresponding sub-agent based on these markers. ### Use Cases - **Follow-up details**: Ask about a specific function implementation while the sub-agent is exploring code - **Correct direction**: Send correction information when you notice the sub-agent misunderstood - **Add context**: Inform the working sub-agent of important information you just remembered - **Batch instructions**: Send the same instruction to multiple running sub-agents simultaneously ### Notes - `>>` must appear at the **beginning** of the input box (leading whitespace is ignored) to trigger - If a sub-agent has completed or exited, it will not appear in the selection list - Press `ESC` to close the selection panel - The selection panel will auto-close when you delete `>>` ### Common Questions **Q: Can sub-agents use the context of the main workflow?** A: No. Sub-agents are completely isolated from the main workflow's context. The main workflow needs to provide all necessary context information in the prompt when calling a sub-agent. **Q: How can I make a sub-agent use a more powerful model?** A: In the configuration profile (Profile) option, select a profile that uses a more powerful model for the sub-agent. **Q: What is the difference between the system prompt in a profile and a sub-agent's role definition?** A: The role definition is the sub-agent's own behavioral specification (entered/edited in the sub-agent config). The system prompt in a configuration profile (Profile) is a profile-level constraint that affects both the main workflow and any sub-agent that uses that profile. At runtime, the sub-agent uses the profile's system prompt as the base, then applies the sub-agent's role definition on top. **Q: Will editing a system built-in agent affect the original configuration?** A: No. The core definitions (name, description, role) of system built-in agents are read-only. You can only modify their tool permissions and configuration profile (Profile), and these modifications only affect your usage without changing the system presets. **Q: How do I delete a custom sub-agent?** A: Select the sub-agent to delete in the sub-agent list, press the Delete key or select the delete option. System built-in agents cannot be deleted. ================================================ FILE: docs/usage/en/06.Sensitive Commands Configuration.md ================================================ # Snow CLI User Guide - Sensitive Commands Configuration Welcome to Snow CLI! Agentic coding in your terminal. ## What are Sensitive Commands Sensitive commands are those that may have a significant impact on the system, data, or project when executed. These commands require explicit user confirmation before execution to prevent accidental operations that could lead to data loss or system damage. Snow CLI has a series of common sensitive command patterns built-in by default and supports users to add custom commands that need protection. ## Why Sensitive Commands Configuration is Needed When using AI-driven command line tools, the AI may suggest executing certain destructive commands. The sensitive commands configuration feature can: - Prevent accidental execution of dangerous commands (such as `rm -rf`, `git reset --hard`, etc.) - Provide users with confirmation opportunities before executing important operations - Provide customizable command protection mechanisms - Protect project and data security ## System Built-in Sensitive Commands Snow CLI protects the following types of commands by default: ### Filesystem Operations - `rm -rf` - Recursive force delete - `rmdir /s` - Windows recursive directory deletion - `del /f` - Windows force delete ### Git Operations - `git reset --hard` - Hard reset (discard all changes) - `git clean -fd` - Delete untracked files and directories - `git push --force` - Force push - `git branch -D` - Force delete branch - `git rebase` - Rebase operation - `git checkout` - Branch switching (may lose uncommitted changes) ### System Administration - `sudo rm` - Delete with administrator privileges - `chmod -R` - Recursively modify file permissions - `chown -R` - Recursively modify file owner ### Database Operations - `DROP DATABASE` - Delete database - `DROP TABLE` - Delete table - `TRUNCATE` - Clear table data ## Sensitive Commands Configuration Management ### Enter Configuration Interface 1. Start Snow CLI 2. Select "Sensitive Commands Configuration" in the main menu 3. Enter the sensitive commands configuration interface ### View Sensitive Commands List The configuration interface displays all configured sensitive commands, including: - Command pattern (supports regular expressions) - Command description - Enabled/disabled status - Whether it is a system built-in command Interface features: - Use `[✓]` to mark enabled commands - Use `[ ]` to mark disabled commands - Custom commands display `(Custom)` marker - Supports scrolling, displaying up to 13 commands at a time ### Enable or Disable Command Protection You can enable or disable protection for specific commands as needed. #### Operation Steps 1. **Navigate to Target Command** - Use ↑/↓ arrow keys to move through the command list - The currently selected command will be highlighted 2. **Toggle Enabled Status** - Press Space to toggle the enabled/disabled status of the selected command - The system will display an operation success message (disappears automatically after 2 seconds) 3. **View Command Details** - Below the list displays the description of the currently selected command - Shows the enabled status of the command - If it's a custom command, displays `[Custom]` marker ### Add Custom Sensitive Commands In addition to system built-in sensitive commands, you can add your own sensitive command patterns. #### Operation Steps 1. **Enter Add Mode** - Press A key in the command list interface - Enter "Add Custom Sensitive Command" interface 2. **Fill in Command Pattern** - Enter the command to protect in the "Command Pattern" field - Supports regular expression matching - Examples: - `npm uninstall` - Exact match - `^docker rm` - Commands starting with docker rm - `.*--force.*` - Commands containing --force parameter - Press Enter or Tab to move to the next field 3. **Fill in Command Description** - Enter the command description in the "Description" field - Suggest clearly describing the danger or impact of this command - Examples: - "Uninstall npm package" - "Force delete Docker container" - "Commands containing force execution parameter" - Press Enter to submit 4. **Complete Addition** - The system validates the input and saves the custom command - Displays addition success message - Automatically returns to the command list interface - Newly added commands are enabled by default #### Command Pattern Writing Tips 1. **Exact Match** ``` git reset --hard ``` Only matches the exact same command 2. **Prefix Match** ``` ^npm uninstall ``` Matches all commands starting with "npm uninstall" 3. **Contains Match** ``` .*--force.* ``` Matches all commands containing "--force" 4. **Multiple Options Match** ``` git (reset|clean|push --force) ``` Matches multiple related git operations ### Delete Custom Sensitive Commands You can delete custom sensitive commands that are no longer needed. Note: System built-in commands cannot be deleted. #### Operation Steps 1. **Select Command to Delete** - Use ↑/↓ arrow keys to select a custom command - Only commands marked as `(Custom)` can be deleted 2. **Request Deletion** - Press D key to request deletion 3. **Confirm Deletion** - Press D key again to confirm deletion - Or press ESC to cancel deletion - Display confirmation message after successful deletion - Cursor automatically moves to the next command #### Notes - System built-in commands cannot be deleted (will not respond to D key) - Requires double confirmation before deletion to prevent accidental operations - Deletion operations are irreversible, please operate carefully ### Reset to Default Configuration If you have made extensive modifications to the configuration, you can reset to the system default configuration with one click. #### Operation Steps 1. **Request Reset** - Press R key in the command list interface - The system will display a confirmation prompt: ``` Confirm reset to default configuration? All custom commands will be deleted, press R again to confirm, press ESC to cancel ``` 2. **Confirm Reset** - Press R key again to confirm reset - Or press ESC to cancel reset - Display confirmation message after successful reset 3. **Reset Effects** - Delete all custom commands - Restore all system built-in commands to enabled status - Configuration takes effect immediately #### Notes - Reset operation will delete all custom commands - Reset operation is irreversible - Requires double confirmation before execution - Suggest recording important custom configurations before resetting ## Keyboard Shortcuts ### Command List Interface - **↑/↓**: Navigate through the command list - **Space**: Enable/disable selected command - **A**: Add custom sensitive command - **D**: Delete custom command (requires double confirmation) - **R**: Reset to default configuration (requires double confirmation) - **ESC**: Return to main menu or cancel confirmation operation ### Add Command Interface - **Tab**: Switch between input fields - **Enter**: Confirm input and move to next field (last field submits) - **ESC**: Cancel addition and return to list interface ## Configuration Best Practices ### 1. Protect Critical Operations Ensure the following types of commands are protected: - Delete operations (files, directories, databases) - Git destructive operations (reset, clean, force push) - Permission modification operations - Batch operation commands ### 2. Reasonable Use of Regular Expressions - Avoid overly broad matching patterns (like `.*`), which may cause all commands to require confirmation - Use precise prefix or keyword matching - Test regular expressions to ensure they only match expected commands ### 3. Clear Command Descriptions - Descriptions should explain the command's function and potential risks - Help you quickly understand the command's impact when confirming - Example: "Force delete all untracked files, irreversible" ### 4. Regularly Review Configuration - Regularly check configured sensitive commands - Delete custom rules that are no longer needed - Adjust protection scope according to project needs ### 5. Team Collaboration Suggestions If using in a team environment: - Share commonly used custom sensitive command configurations - Unify team command protection standards - Train team members to understand the importance of sensitive commands ## How Sensitive Commands Work When the AI suggests executing a command, Snow CLI will: 1. **Check if Command Matches Sensitive Pattern** - Iterate through all enabled sensitive command rules - Use regular expressions to match command content 2. **Trigger Confirmation Process** - If the command matches any sensitive pattern - Pause execution and display confirmation dialog - Display command content and warning information 3. **Wait for User Decision** - User can choose to execute or cancel - After cancellation, AI receives feedback and may suggest alternatives - After execution, command runs normally 4. **Execute Directly if Not Matched** - If the command does not match any sensitive pattern - Execute directly without additional confirmation ## Common Questions **Q: Does sensitive commands configuration affect all projects?** A: Yes. Sensitive commands configuration is global and applies to all projects using Snow CLI. This ensures consistent security protection. **Q: Can I temporarily disable protection for a specific sensitive command?** A: Yes. Enter the sensitive commands configuration interface, find the corresponding command and press Space to disable it. After completing the operation, it is recommended to re-enable the protection. **Q: Is regular expression matching case-sensitive?** A: This depends on how you write your regular expression. If you need case-insensitive matching, you can use case-insensitive patterns or match both uppercase and lowercase variants simultaneously. **Q: What if I accidentally delete a custom command?** A: Deletion operations are irreversible, but you can re-add the command. It is recommended to record important custom configurations or regularly backup the configuration file. **Q: Can sensitive commands protection completely prevent command execution?** A: No. Sensitive commands protection only provides confirmation prompts; whether to execute is ultimately decided by the user. This is to maintain flexibility while ensuring security. **Q: Can system built-in commands be permanently deleted?** A: No, but you can disable them. If you need to restore them, use the "Reset to Default Configuration" function. **Q: Do I need to restart Snow CLI after adding a custom command?** A: No. Configuration changes take effect immediately and will be applied the next time the AI suggests executing a command. ## Configuration File Location Sensitive commands configuration is stored in the Snow CLI configuration directory: - Windows: `%USERPROFILE%\.snow\sensitive-commands.json` - macOS/Linux: `~/.snow/sensitive-commands.json` You can directly edit this file for batch configuration, but it is recommended to use the configuration interface to ensure correct formatting. ## Related Features - [Command Injection Mode](./10.Command%20Injection%20Mode.md) - Execute commands directly in messages, also protected by sensitive command checks - [Vulnerability Hunting Mode](./11.Vulnerability%20Hunting%20Mode.md) - Professional security analysis feature, also uses sensitive command protection ================================================ FILE: docs/usage/en/07.Hooks Configuration.md ================================================ # Snow CLI User Guide - Hooks Configuration Welcome to Snow CLI! Agentic coding in your terminal. ## What are Hooks Hooks are a powerful extension mechanism provided by Snow CLI that allow you to automatically execute custom commands or trigger interactive prompts at key points in the AI workflow. With Hooks, you can: - Automatically execute scripts or commands at specific moments - Implement workflow automation - Integrate external tools and services - Perform validation or logging before and after critical operations - Trigger interactive prompts at the end of workflows ## Hooks Workflow ```mermaid graph TB Start([AI Workflow Start]) --> UserMsg{User Sends Message} UserMsg -->|Trigger| Hook1[onUserMessage Hook] Hook1 --> CheckMatch1{Match Rule?} CheckMatch1 -->|Yes| Execute1[Execute Hook Actions] CheckMatch1 -->|No| Continue1[Continue Flow] Execute1 --> Continue1 Continue1 --> AIProcess[AI Process Message] AIProcess --> ToolCall{AI Call Tool?} ToolCall -->|Yes| Hook2[beforeToolCall Hook] Hook2 --> CheckMatch2{Match Tool Name?} CheckMatch2 -->|Yes| Execute2[Execute Hook Actions] CheckMatch2 -->|No| Continue2[Continue Call] Execute2 --> Continue2 Continue2 --> NeedConfirm{Need User Confirmation?} NeedConfirm -->|Yes| Hook3[toolConfirmation Hook] Hook3 --> CheckMatch3{Match Tool Name?} CheckMatch3 -->|Yes| Execute3[Execute Hook Actions] CheckMatch3 -->|No| UserConfirm[User Confirm] Execute3 --> UserConfirm UserConfirm --> ToolExec[Execute Tool] NeedConfirm -->|No| ToolExec ToolExec --> Hook4[afterToolCall Hook] Hook4 --> CheckMatch4{Match Tool Name?} CheckMatch4 -->|Yes| Execute4[Execute Hook Actions] CheckMatch4 -->|No| Continue4[Continue Flow] Execute4 --> Continue4 Continue4 --> MoreTools{More Tools?} MoreTools -->|Yes| ToolCall MoreTools -->|No| AIResponse[AI Generate Response] ToolCall -->|No| AIResponse AIResponse --> SubAgent{Call Sub-Agent?} SubAgent -->|Yes| SubProcess[Sub-Agent Process] SubProcess --> Hook5[onSubAgentComplete Hook] Hook5 --> CheckMatch5{Match Rule?} CheckMatch5 -->|Yes| Execute5[Execute Hook Actions
May be Prompt] CheckMatch5 -->|No| Continue5[Continue Flow] Execute5 --> Continue5 Continue5 --> CheckCompress SubAgent -->|No| CheckCompress{Need Compress Context?} CheckCompress -->|Yes| Hook6[beforeCompress Hook] Hook6 --> Execute6[Execute Hook Actions] Execute6 --> Compress[Execute Compression] Compress --> End CheckCompress -->|No| End([Flow End]) End --> Hook7[onStop Hook] Hook7 --> Execute7[Execute Hook Actions
May be Prompt] Execute7 --> FinalEnd([Final End]) style Hook1 fill:#ffe1e1 style Hook2 fill:#e1f5ff style Hook3 fill:#fff4e1 style Hook4 fill:#e1ffe1 style Hook5 fill:#ffe1f5 style Hook6 fill:#f5e1ff style Hook7 fill:#ffe1e1 style Execute1 fill:#ffcccc style Execute2 fill:#ccecff style Execute3 fill:#fff0cc style Execute4 fill:#ccffcc style Execute5 fill:#ffccf5 style Execute6 fill:#f0ccff style Execute7 fill:#ffcccc ``` ## Hook Type Descriptions Snow CLI provides 8 hook types, each triggered at different moments: ### 1. onSessionStart **Trigger Time**: When starting a new session or resuming an existing session **Use Cases**: - Initialize working environment - Check dependencies and configurations - Load project-specific settings - Log session start time **Example**: ```json { "onSessionStart": [ { "description": "Check development environment", "hooks": [ { "type": "command", "command": "node --version && npm --version", "timeout": 5000, "enabled": true } ] } ] } ``` ### 2. onUserMessage **Trigger Time**: When user sends a message **Context Parameters**: ```json { "message": "User message content", // User message text "imageCount": 2, // Number of images attached "source": "cli" // Message source: "cli" or "mcp" } ``` **Use Cases**: - Log user requests - Preprocess user input - Trigger specific monitoring or statistics - Execute automated tasks based on message content **Accessing Context**: For `command` type hooks, context is passed via stdin as JSON. You can read it using: ```javascript const context = JSON.parse(require('fs').readFileSync(0, 'utf-8')); console.log('User message:', context.message); console.log('Image count:', context.imageCount); ``` **Example**: ```json { "onUserMessage": [ { "description": "Log user messages", "hooks": [ { "type": "command", "command": "echo \"$(date): User message logged\" >> .snow/logs/user-messages.log", "timeout": 3000, "enabled": true } ] } ] } ``` ### 3. beforeToolCall **Trigger Time**: Before AI calls a tool (supports tool matching) **Special Feature**: Supports `matcher` field to match specific tool names **Context Parameters**: ```json { "toolName": "filesystem-edit", // Tool name to be called "args": { // Tool arguments "filePath": "src/index.ts", "startLine": 10, "endLine": 20, "newContent": "..." } } ``` **Use Cases**: - Backup before file operations - Environment check before executing commands - Log tool call history - Preprocessing for specific tools **Placeholder Usage**: For `prompt` type hooks, you can use the `$TOOLSRESULT$` placeholder to access the full context data. **Matcher Syntax**: - Exact match: `filesystem-read` - Wildcard match: `filesystem-*` (matches all filesystem tools) - Multiple tools: `filesystem-read,filesystem-edit` (comma-separated) **Example**: ```json { "beforeToolCall": [ { "matcher": "filesystem-edit,filesystem-create", "description": "Auto backup before file changes", "hooks": [ { "type": "command", "command": "git add . && git commit -m \"Auto backup before file changes\"", "timeout": 10000, "enabled": true } ] } ] } ``` ### 4. toolConfirmation **Trigger Time**: During tool confirmation (including sensitive command checks) **Special Feature**: Supports `matcher` field to match specific tool names **Use Cases**: - Execute additional checks before user confirms sensitive operations - Log operations requiring confirmation - Send notifications to team members - Pre-confirmation processing for specific tools **Example**: ```json { "toolConfirmation": [ { "matcher": "terminal-execute", "description": "Send notification on sensitive command confirmation", "hooks": [ { "type": "command", "command": "curl -X POST https://hooks.slack.com/... -d '{\"text\":\"Sensitive command needs confirmation\"}'", "timeout": 5000, "enabled": true } ] } ] } ``` ### 5. afterToolCall **Trigger Time**: After tool call completes (supports tool matching) **Special Feature**: Supports `matcher` field to match specific tool names **Context Parameters**: ```json { "toolName": "filesystem-edit", // Tool name "args": { // Tool arguments "filePath": "src/index.ts", "startLine": 10, "endLine": 20, "newContent": "..." }, "result": { // Tool execution result "success": true, "message": "File edited successfully" }, "error": null // Error message (if execution failed) } ``` **Use Cases**: - Run tests after file modifications - Run code formatting after code changes - Log tool execution results - Post-processing for specific tools **Placeholder Usage**: For `prompt` type hooks, you can use the `$TOOLSRESULT$` placeholder to access the full context data (including result and error). **Example**: ```json { "afterToolCall": [ { "matcher": "filesystem-edit", "description": "Auto format after code changes", "hooks": [ { "type": "command", "command": "npm run format", "timeout": 30000, "enabled": true } ] } ] } ``` ### 6. onSubAgentComplete **Trigger Time**: When sub-agent task completes **Special Feature**: Supports `prompt` type Action (interactive prompt) **Context Parameters**: ```json { "agentId": "agent_explore", // Sub-agent ID "agentName": "Explore Agent", // Sub-agent name "content": "Sub-agent response...", // Sub-agent output content "success": true, // Whether execution succeeded "usage": { // Token usage statistics "totalTokens": 1500, "promptTokens": 1000, "completionTokens": 500 } } ``` **Use Cases**: - Collect user feedback after sub-agent completes - Ask user whether to continue to next step - Let user choose handling method - Log sub-agent execution results **Placeholder Usage**: For `prompt` type hooks, you can use the `$SUBAGENTRESULT$` placeholder to access sub-agent context data. **Prompt Type Description**: - `prompt` type pauses AI flow and waits for user input - User input is sent as a new message to AI - Can only be used in `onSubAgentComplete` and `onStop` - If a rule has `prompt` type, no other Actions can be added **Example (Prompt Type)**: ```json { "onSubAgentComplete": [ { "description": "Ask user after sub-agent completes", "hooks": [ { "type": "prompt", "prompt": "Sub-agent has completed the task. Do you need to continue? Please enter your instructions:", "timeout": 30000, "enabled": true } ] } ] } ``` **Example (Command Type)**: ```json { "onSubAgentComplete": [ { "description": "Log sub-agent results", "hooks": [ { "type": "command", "command": "echo \"Sub-agent completed at $(date)\" >> .snow/logs/subagent.log", "timeout": 3000, "enabled": true } ] } ] } ``` ### 7. beforeCompress **Trigger Time**: Before running context compression operation **Use Cases**: - Save context snapshot before compression - Log compression operation timestamp - Trigger context backup - Send compression notification **Example**: ```json { "beforeCompress": [ { "description": "Save context before compression", "hooks": [ { "type": "command", "command": "echo \"Context compression at $(date)\" >> .snow/logs/compression.log", "timeout": 3000, "enabled": true } ] } ] } ``` ### 8. onStop **Trigger Time**: When user stops AI flow (Ctrl+C or end session) **Special Feature**: Supports `prompt` type Action (interactive prompt) **Context Parameters**: ```json { "messages": [ // Complete session message history { "role": "user", "content": "User message content" }, { "role": "assistant", "content": "AI response content" } // ... more messages ] } ``` **Use Cases**: - Ask user whether to save work before stopping - Collect user feedback - Execute cleanup operations - Log stop reason **Placeholder Usage**: For `prompt` type hooks, you can use the `$STOPSESSION$` placeholder to access session context data. **Example (Prompt Type)**: ```json { "onStop": [ { "description": "Ask before stopping", "hooks": [ { "type": "prompt", "prompt": "About to stop AI. Do you need to save current work? Please enter instructions:", "timeout": 30000, "enabled": true } ] } ] } ``` ## Hook Configuration Management ### Accessing Configuration Interface 1. Launch Snow CLI 2. Select "Hooks Configuration" option in main menu 3. Choose configuration scope (Global or Project) ### Scope Description ```mermaid graph LR Config[Hooks Configuration] --> Global[Global Scope] Config --> Project[Project Scope] Global --> GlobalPath[~/.snow/hooks/] Project --> ProjectPath[./.snow/hooks/] GlobalPath --> AllProjects[Apply to All Projects] ProjectPath --> CurrentProject[Only Apply to Current Project] style Global fill:#e1f5ff style Project fill:#e1ffe1 style GlobalPath fill:#ccecff style ProjectPath fill:#ccffcc ``` **Global Hooks**: - Storage location: `~/.snow/hooks/` - Scope: All projects using Snow CLI - Use cases: Common workflows, global monitoring, unified logging **Project Hooks**: - Storage location: `./.snow/hooks/` (current project directory) - Scope: Current project only - Use cases: Project-specific automation, special build processes, project-level validation **Execution Priority**: Both project and global hooks will execute, with project hooks executing first ### Viewing Hook List The configuration interface displays all 8 hook types: - Configured hooks show `[✓]` marker - Unconfigured hooks show `[ ]` marker - Display the number of rules for each hook - Bottom shows description of currently selected hook ### Configuring Hook Rules #### 1. Select Hook Type Use ↑/↓ arrow keys to select the hook type to configure, press Enter to enter details page #### 2. Hook Details Page Displays all rules under this hook: - Rule list (shows description, number of Actions, Matcher information) - Add new rule option - Delete entire hook configuration option - Return to previous level option #### 3. Edit Rule Select a rule or choose "Add New Rule" to enter editing interface: **Basic Fields**: - **Description** (required) - Brief description of the rule - Press Enter or Tab to move to next field - Helps you quickly identify rule purpose - **Matcher** (only for tool hooks) - Only shown in `beforeToolCall`, `toolConfirmation`, `afterToolCall` - Used to match specific tool names - Supports wildcards: `filesystem-*` - Supports multiple tools: `filesystem-read,filesystem-edit` - Leave empty to match all tools **Action Management**: Each rule can contain multiple Actions, executed in order: - View existing Action list - Add new Action - Edit existing Actions - Delete Actions #### 4. Edit Action Select an Action or choose "Add Action" to enter Action editing interface: **Action Fields**: - **Enabled Status** (required) - Use Space key to toggle enabled/disabled - `[✓]` means enabled, `[ ]` means disabled - Disabled Actions won't execute but configuration is retained - **Type** (required) - `command`: Execute command - `prompt`: Interactive prompt (only supported in `onSubAgentComplete` and `onStop`) - Press Space key to toggle type - Type switching has restrictions (see below) - **Command** (when type=command) - Command line command to execute - Supports pipes and complex commands - Example: `npm run build && npm test` - **Prompt** (when type=prompt) - Prompt text to display to user - User input will be sent as a new message to AI - Example: "Please enter your next instruction:" - **Timeout** (optional) - Timeout duration (milliseconds) - Default: command=5000ms, prompt=30000ms - Action will be terminated after timeout #### 5. Action Type Restrictions ```mermaid graph TB Start([Select Hook Type]) --> CheckHook{Hook Type} CheckHook -->|onSubAgentComplete
or onStop| CanPrompt[Can use Prompt or Command] CheckHook -->|Other Hook Types| OnlyCommand[Can only use Command] CanPrompt --> CheckExist{Are there existing
Actions in rule?} CheckExist -->|No Actions| ChooseType1[Can choose any type] CheckExist -->|Has Prompt| NoMore1[Cannot add more Actions] CheckExist -->|Has Command| OnlyCommand2[Can only add Command] ChooseType1 --> SelectPrompt{Select Prompt?} SelectPrompt -->|Yes| SinglePrompt[Can only have this one Prompt
Cannot add other Actions] SelectPrompt -->|No| MultiCommand[Can add multiple Commands] style CanPrompt fill:#e1ffe1 style OnlyCommand fill:#ffe1e1 style OnlyCommand2 fill:#ffe1e1 style NoMore1 fill:#ffcccc style SinglePrompt fill:#fff0cc style MultiCommand fill:#ccffcc ``` **Restriction Rules**: 1. **Prompt Type Restrictions**: - Can only be used in `onSubAgentComplete` and `onStop` - If a rule has Prompt, it cannot have any other Actions - Prompt must exist alone 2. **Command Type**: - Can be used in all hook types - A rule can have multiple Command Actions - If the rule already has Prompt, cannot add Command 3. **Type Switching**: - System automatically validates when switching types - Non-compliant switches will be blocked ### Saving and Deleting **Save Rule**: - Select "Save Rule" in rule editing interface - Configuration is immediately saved to corresponding scope - Automatically returns to Hook details page after saving **Delete Rule**: - Select "Delete Rule" in rule editing interface or press `D` key - Press `D` key for quick delete (must be in rule editing interface) - Automatically returns to Hook details page after deletion **Delete Hook Configuration**: - Select "Delete Hook" in Hook details page - Will delete the configuration file for this Hook - Returns to Hook list after deletion ## Keyboard Shortcuts ### Hook List Interface - **↑/↓**: Navigate between Hook types - **Enter**: Enter selected Hook details - **ESC**: Return to main menu ### Hook Details Interface - **↑/↓**: Navigate in rule list - **Enter**: Edit selected rule or execute operation - **ESC**: Return to Hook list ### Rule Editing Interface - **↑/↓**: Navigate between fields and Actions - **Enter**: Edit field or Action - **D**: Quick delete current rule - **ESC**: Return to Hook details ### Action Editing Interface - **↑/↓**: Navigate between fields - **Space**: Toggle enabled status or type - **Enter**: Edit text field - **D**: Quick delete current Action - **ESC**: Return to rule editing ### Text Input State - **Enter**: Confirm input - **ESC**: Cancel input ## Exit Code Rules The exit code of a Hook command determines the subsequent behavior of the AI workflow. Different exit codes have different semantics: | Exit Code | Meaning | Behavior | |-----------|---------|----------| | **0** | Success | Continue workflow normally | | **1** | Warning | Block current operation, return stderr as substitute result to AI (AI flow continues) | | **2+** | Critical Error | Block current operation, terminate AI flow, display error to user | ### Exit Code Behavior by Hook Type #### beforeToolCall | Exit Code | Tool Executed? | AI Flow | What AI Receives | |-----------|---------------|---------|------------------| | 0 | Executes normally | Continues | Normal tool result | | 1 | **Blocked** | Continues | stderr content (or preset warning if no stderr) | | 2+ | Blocked | **Terminated** | AI not called, error displayed to user | #### afterToolCall | Exit Code | AI Flow | What AI Receives | |-----------|---------|------------------| | 0 | Continues | Normal tool result | | 1 | Continues | stderr content **replaces** original tool result (falls back to stdout if no stderr) | | 2+ | **Terminated** | AI not called, error displayed to user | ### stderr vs stdout Priority When exit code is 1: - If there is **stderr** output, it is used as the content returned to AI - If there is no stderr, **stdout** output is used - If neither exists, a preset warning message is used This means you can precisely control the message returned to AI through stderr in your Hook scripts. ### Example: Controlling Tool Behavior with Exit Codes ```bash #!/bin/bash # beforeToolCall Hook: Block file modifications during non-working hours HOUR=$(date +%H) if [ "$HOUR" -ge 22 ] || [ "$HOUR" -lt 6 ]; then echo "File modifications are not allowed during non-working hours. Please try again between 6:00-22:00." >&2 exit 1 fi exit 0 ``` ```bash #!/bin/bash # afterToolCall Hook: Detect lint errors after code changes LINT_OUTPUT=$(npm run lint 2>&1) if [ $? -ne 0 ]; then echo "Lint check found issues, please fix the following errors:\n$LINT_OUTPUT" >&2 exit 1 fi exit 0 ``` ## Configuration File Structure Hooks configuration is stored in JSON files, with each hook type corresponding to one file: **File Location**: - Global: `~/.snow/hooks/.json` - Project: `./.snow/hooks/.json` **File Format**: ```json { "hookType": [ { "description": "Rule description", "matcher": "Tool matcher (only for tool hooks)", "hooks": [ { "type": "command", "command": "Command to execute", "timeout": 5000, "enabled": true } ] } ] } ``` ## Practical Configuration Examples ### Example 1: Automated Testing Flow ```json { "afterToolCall": [ { "matcher": "filesystem-edit", "description": "Auto run tests after code changes", "hooks": [ { "type": "command", "command": "npm run lint", "timeout": 15000, "enabled": true }, { "type": "command", "command": "npm test", "timeout": 60000, "enabled": true } ] } ] } ``` ### Example 2: File Backup System ```json { "beforeToolCall": [ { "matcher": "filesystem-*", "description": "Auto backup before file operations", "hooks": [ { "type": "command", "command": "mkdir -p .snow/backups && cp -r . .snow/backups/$(date +%Y%m%d_%H%M%S)/", "timeout": 30000, "enabled": true } ] } ] } ``` ### Example 3: Workflow Logging ```json { "onUserMessage": [ { "description": "Log all user requests", "hooks": [ { "type": "command", "command": "echo \"[$(date '+%Y-%m-%d %H:%M:%S')] User message received\" >> .snow/logs/workflow.log", "timeout": 3000, "enabled": true } ] } ] } ``` ### Example 4: Interactive Feedback Collection ```json { "onSubAgentComplete": [ { "description": "Collect feedback after sub-agent completes", "hooks": [ { "type": "prompt", "prompt": "Sub-agent has completed the task. Please review the results and provide your feedback or next instruction:", "timeout": 60000, "enabled": true } ] } ] } ``` ### Example 5: Team Collaboration Notification ```json { "toolConfirmation": [ { "matcher": "terminal-execute", "description": "Notify team of sensitive operations", "hooks": [ { "type": "command", "command": "curl -X POST $SLACK_WEBHOOK -H 'Content-Type: application/json' -d '{\"text\":\"Sensitive operation pending confirmation\"}'", "timeout": 5000, "enabled": true } ] } ] } ``` ### Example 6: Session Initialization Check ```json { "onSessionStart": [ { "description": "Check project environment", "hooks": [ { "type": "command", "command": "node --version", "timeout": 3000, "enabled": true }, { "type": "command", "command": "git status", "timeout": 3000, "enabled": true }, { "type": "command", "command": "npm list --depth=0", "timeout": 10000, "enabled": true } ] } ] } ``` ## Configuration Best Practices ### 1. Set Reasonable Timeout Durations - Simple commands: 3000-5000ms - Build/test: 30000-60000ms - Interactive Prompt: 30000-60000ms - Avoid setting too short causing command interruption - Avoid setting too long affecting workflow ### 2. Use Matcher for Precise Matching - Avoid overly broad matching (like matching all tools) - Target specific tools that need special handling - Use wildcards to simplify configuration: `filesystem-*` - Multiple related tools can share rules: `filesystem-read,filesystem-edit` ### 3. Command Execution Considerations - Ensure commands are available in target environment - Use absolute paths to avoid environment variable issues - Consider cross-platform compatibility (Windows/Linux/macOS) - Use environment variables to store sensitive information (like API keys) ### 4. Prompt Type Usage Suggestions - Only use Prompt when necessary (interrupts workflow) - Prompt message should be clear and specific - Provide sufficient context to help user decision-making - Set reasonable timeout duration ### 5. Rule Organization - Each rule focuses on single responsibility - Use clear descriptions to explain rule purpose - Related Actions can be placed in the same rule - Avoid duplicate logic between rules ### 6. Testing and Debugging - Test new configurations in project scope first - Apply to global scope after confirming correctness - Use `enabled` field to temporarily disable Actions - Check command output and error logs ### 7. Performance Considerations - Avoid executing commands that take too long - Consider using async background tasks - Don't execute heavy operations in high-frequency hooks (like `onUserMessage`) - Use disable feature reasonably to reduce unnecessary execution ## Frequently Asked Questions **Q: Will Hooks affect AI response speed?** A: Yes, to some extent. Hook commands execute synchronously, and the AI flow pauses during command execution. It's recommended to keep hook command execution time within a reasonable range. **Q: Can I access AI context information in Hook commands?** A: Currently Hook commands can only execute standard Shell commands and cannot directly access AI context. You can indirectly pass information through filesystem or environment variables. **Q: What happens when project hooks and global hooks conflict?** A: No conflict, both will execute. Project hooks execute first, then global hooks. **Q: How do I debug Hook commands?** A: It's recommended to manually execute commands in terminal first to ensure correctness, then use them in Hooks. You can also add log output to commands to track execution. **Q: Can Prompt type Actions be called multiple times?** A: No. A rule can only have one Prompt Action and cannot coexist with other Actions. If multiple interactions are needed, create multiple rules. **Q: What happens if a Hook command fails?** A: It depends on the exit code. Exit code 1 blocks the current operation and returns stderr as a substitute result to AI (AI flow continues); exit code 2+ terminates the entire AI flow and displays the error to the user. See the "Exit Code Rules" section for details. **Q: Can I use Linux-style commands on Windows?** A: Not recommended. You should write commands appropriate for the running platform, or use cross-platform tools (like Node.js scripts). **Q: How do I disable a Hook without deleting the configuration?** A: In the Action editing interface, use the Space key to toggle "Enabled Status". Disabled Actions retain configuration but won't execute. **Q: Does Matcher support regular expressions?** A: Currently only supports exact matching and wildcard `*`, doesn't support full regular expressions. **Q: Can I manually edit configuration files?** A: Yes, but it's recommended to use the configuration interface to ensure correct format. Restart Snow CLI after manual editing to load new configuration. ================================================ FILE: docs/usage/en/08.Theme Settings.md ================================================ # Snow CLI User Guide - Theme Settings Welcome to Snow CLI! Agentic coding in your terminal. ## What is a Theme A theme defines the appearance of the Snow CLI terminal interface, including color schemes, code highlighting styles, menu display effects, etc. Through theme settings, you can: - Select preset theme schemes - Customize colors to suit personal preferences - Adjust interface display mode (Simple/Standard) - Create and save your own theme colors ## Accessing Theme Settings 1. Launch Snow CLI 2. Select "Theme Settings" option in main menu 3. Enter theme settings interface ## Simple Mode Simple mode is an independent interface display option that can simplify terminal interface display and reduce visual distractions. ### Feature Description - **Standard Mode**: Full display of all interface elements (borders, decorations, detailed information) - **Simple Mode**: Simplified interface display, hiding non-essential elements, focusing on content itself ### Operation Method 1. In the theme settings interface, the first option is "Simple Mode" 2. Press Enter key to toggle status after selection 3. Interface displays current status: - `Simple Mode Enabled` - `Simple Mode Disabled` 4. Simple mode toggle takes effect immediately ### Use Cases - Small screen terminals: Reduce space usage - Focused work: Reduce visual distractions - Performance optimization: Reduce rendering overhead - Screenshot demos: Cleaner and clearer interface ## Preset Themes Snow CLI provides 6 carefully designed preset themes, each with a unique color scheme. ### 1. Dark Theme **Features**: Snow CLI's default theme, classic dark color scheme **Use Cases**: - Long coding sessions - Low-light environments - Eye protection needs **Color Characteristics**: - Dark background - Soft text colors - Clear syntax highlighting - Comfortable contrast ### 2. Light Theme **Features**: Bright light theme, suitable for daytime use **Use Cases**: - Use in bright environments - Daytime work hours - Personal preference for light interfaces **Color Characteristics**: - Light background - Dark text - High contrast - Clear and easy to read ### 3. GitHub Dark Theme **Features**: Mimics GitHub's dark theme style **Use Cases**: - GitHub users - Developers who like GitHub colors - Need familiar visual experience **Color Characteristics**: - GitHub-style colors - Professional code highlighting - Comfortable dark background ### 4. Rainbow Theme **Features**: Rich and colorful color scheme **Use Cases**: - Like bright colors - Need to distinguish different types of information - Personalization needs **Color Characteristics**: - Colorful highlighting - Vivid visual effects - Active atmosphere ### 5. Solarized Dark Theme **Features**: Dark version of the famous Solarized color scheme **Use Cases**: - Solarized enthusiasts - Need scientific color scheme - Long reading of code **Color Characteristics**: - Scientifically designed colors - Comfortable contrast - Eye-friendly color scheme ### 6. Nord Theme **Features**: Cool-toned theme inspired by Nord color scheme **Use Cases**: - Like cool tones - Pursuing modern feel - Unified color experience **Color Characteristics**: - Nordic-style colors - Cool tones as main - Elegant and modern ## Theme Selection and Application ### Browsing Themes 1. In the theme settings interface, use ↑/↓ arrow keys to browse theme list 2. When cursor moves to a theme, the interface immediately previews that theme's effects 3. Preview area displays code comparison examples, showing the theme's syntax highlighting effects 4. Bottom displays description information of currently selected theme **Preview Features**: - No need to press Enter, cursor movement provides preview - Real-time display of theme effects - Code Diff examples show syntax highlighting - Helps quickly choose suitable theme ### Applying Theme 1. Browse to the theme you want to use 2. Press Enter key to confirm application 3. Theme configuration automatically saves to `~/.snow/theme.json` 4. Theme takes effect immediately and applies to entire interface ### Cancel Changes - Press ESC key: Cancel changes, restore theme from before entering settings - Select "Return" option: Also restores original theme ## Custom Theme In addition to preset themes, you can create completely custom theme colors. ### Entering Custom Editor 1. Select "Edit Custom Theme..." option in theme settings interface 2. Press Enter to enter custom theme editor 3. Editor displays all customizable color options ### Customizable Colors Custom theme includes 16 color options, divided into multiple categories: #### Basic Colors (3 items) 1. **background** - Background color - Main interface background - Recommended to use dark or light base tone 2. **text** - Text color - Main text content color - Needs good contrast with background 3. **border** - Border color - UI borders and separators - Usually slightly lighter or darker than background #### Diff Display Colors (3 items) 4. **diffAdded** - Added line background color - Background for code addition lines - Recommended to use green tones 5. **diffRemoved** - Deleted line background color - Background for code deletion lines - Recommended to use red tones 6. **diffModified** - Modified content highlight color - Highlight for in-line modifications - Recommended to use yellow tones #### Line Number Colors (2 items) 7. **lineNumber** - Line number text color - Color for code line numbers - Usually use gray tones 8. **lineNumberBorder** - Line number area border color - Border for line number area - Coordinate with line number color #### Menu Colors (4 items) 9. **menuSelected** - Selected menu item color - Currently selected menu item - Needs to be prominent 10. **menuNormal** - Normal menu item color - Unselected menu items - Appropriate contrast with background 11. **menuInfo** - Info menu item color - Prompt information, description text - Usually use cyan tones 12. **menuSecondary** - Secondary menu item color - Secondary information, auxiliary text - Usually use gray tones #### Status Colors (3 items) 13. **error** - Error prompt color - Error messages, warnings - Usually use red 14. **warning** - Warning prompt color - Warning messages, notes - Usually use yellow 15. **success** - Success prompt color - Success messages, confirmation information - Usually use green #### Logo Gradient Colors (1 item) 16. **logoGradient** - Logo gradient colors - Gradient effect for Snow CLI Logo - Need to input 3 color values, separated by commas - Format: `#color1, #color2, #color3` - Example: `#d3d3d3, #808080, #505050` ### Editing Colors #### Selecting Color to Edit 1. Use ↑/↓ arrow keys to browse color list 2. Each line displays: `Color name: Current value` 3. Select color item to modify 4. Press Enter key to enter edit mode #### Inputting Color Value After entering edit mode: 1. Interface displays current color value 2. Provides input box for entering new value 3. Supports multiple color formats: - Hexadecimal: `#RRGGBB` (like `#1e1e1e`) - Color names: `red`, `blue`, `green`, `cyan`, `yellow`, etc. - RGB format: `rgb(30, 30, 30)` 4. Press Enter to confirm after input 5. Color immediately updates and displays effect in preview area #### Cancel Editing - In edit mode, press ESC key: Cancel current color modification - Return to color list to continue editing other colors The preview area at the bottom of the custom editor displays your color scheme effects in real-time: - Display code comparison examples - Show syntax highlighting effects - Display Diff comparison effects - Help you evaluate color scheme ### Saving Custom Theme After completing color editing: 1. Select "Save" option at bottom of color list 2. Press Enter to confirm save 3. Custom colors save to `~/.snow/theme.json` 4. Theme automatically switches to "Custom" theme 5. Return to theme settings interface **Configuration File Format**: ```json { "theme": "custom", "customColors": { "background": "#1e1e1e", "text": "#d4d4d4", "border": "#3e3e3e", "diffAdded": "#0d4d3d", "diffRemoved": "#5a1f1f", "diffModified": "#dcdcaa", "lineNumber": "#858585", "lineNumberBorder": "#3e3e3e", "menuSelected": "#5e0691ff", "menuNormal": "white", "menuInfo": "cyan", "menuSecondary": "gray", "error": "red", "warning": "yellow", "success": "green", "logoGradient": ["#d3d3d3", "#808080", "#505050"] }, "simpleMode": false } ``` ### Reset to Default Colors If unsatisfied with custom colors, you can reset to default values: 1. Select "Reset to Default" option in custom editor 2. Press Enter to confirm 3. All colors restore to system default custom theme colors 4. Preview area immediately displays default color effects 5. Can start editing again **Note**: Reset operation doesn't save immediately, need to select "Save" to write to configuration file ## Keyboard Shortcuts ### Theme Settings Interface - **↑/↓**: Navigate in theme list - **Enter**: Apply selected theme or execute operation - **ESC**: Cancel changes and return to main menu ### Custom Editor - **↑/↓**: Navigate in color list - **Enter**: Edit selected color or execute operation - **ESC**: Return to theme settings (unsaved changes will be lost) ### Color Edit Mode - **Enter**: Confirm input color value - **ESC**: Cancel current color editing ## Theme Configuration Best Practices ### 1. Choose Appropriate Base Theme Choose based on work environment: - Low-light environment: Dark themes (Dark, GitHub Dark, Nord) - Bright environment: Light theme (Light) - Personal preference: Choose most comfortable color scheme ### 2. Custom Theme Color Suggestions #### Contrast - Ensure text has sufficient contrast with background - Avoid overly harsh color combinations - Test comfort for long-term use #### Consistency - Maintain consistency of color scheme - Use similar tones for related functions - Avoid too many colors causing confusion #### Readability - Code highlighting colors should be clearly distinguishable - Diff colors should clearly distinguish added/deleted/modified - Menu item colors should have clear hierarchy ### 3. Color Selection Techniques #### Hexadecimal Colors ``` Format: #RRGGBB Examples: #1e1e1e - Dark gray background #d4d4d4 - Light gray text #0d4d3d - Dark green (added lines) #5a1f1f - Dark red (deleted lines) ``` #### Named Colors ``` Basic colors: black, white, gray Bright colors: red, green, blue cyan, magenta, yellow Extended colors: Refer to list of color names supported by terminal ``` ### 4. Logo Gradient Color Configuration Logo gradient requires 3 colors to form gradient effect: ``` Light to dark: #ffffff, #808080, #000000 Blue tones: #5e9cff, #2e5c8f, #1e3c5f Green tones: #90ee90, #50ae50, #306e30 Custom: Ensure three colors form smooth transition First brightest, third darkest ``` ### 5. Testing Theme Effects After creating custom theme, it's recommended to: 1. Test code highlighting effects 2. Check Diff comparison clarity 3. Verify menu readability 4. Confirm comfort for long-term use 5. Test compatibility in different terminals ### 6. Backup Custom Theme Regularly backup configuration file: ```bash # Backup theme configuration cp ~/.snow/theme.json ~/.snow/theme.json.backup # Restore backup cp ~/.snow/theme.json.backup ~/.snow/theme.json ``` ### 7. Multi-Environment Configuration If using on different devices or environments: - Choose theme based on screen characteristics - Consider environment lighting differences - Unify team color scheme (optional) ## Frequently Asked Questions **Q: Do I need to restart Snow CLI after changing theme?** A: No. Theme changes take effect immediately and apply to current interface and all subsequent operations. **Q: Where is the custom theme configuration file?** A: Configuration file is located at `~/.snow/theme.json`, can be manually edited or configured through interface. **Q: Can I import and export custom themes?** A: Yes. Simply copy the `theme.json` file to share theme configuration. Place the file in `~/.snow/` directory to use. **Q: What's the difference between simple mode and theme selection?** A: Simple mode controls interface display complexity, theme controls color scheme. They work independently and can be combined. **Q: What if interface displays abnormally after customizing colors?** A: Select "Reset to Default" in custom editor, or directly delete `~/.snow/theme.json` file, Snow CLI will automatically use default configuration. **Q: Do all terminals support custom colors?** A: Most modern terminals support it, but some older terminals may only support 16 colors. It's recommended to use modern terminals like iTerm2, Windows Terminal, Hyper, etc. **Q: Can I use different themes for different projects?** A: Currently theme is global configuration, shared by all projects. If needed, can temporarily modify configuration file before launching Snow CLI. **Q: Can the preview area code examples be customized?** A: Preview code is fixed examples for showing theme effects. In actual use it will apply to your real code. **Q: Must logoGradient have 3 colors?** A: Yes. Logo gradient design requires 3 colors to form smooth gradient effect. Format must be `[color1, color2, color3]`. **Q: How do I share my custom theme with the team?** A: Copy the `customColors` section from `~/.snow/theme.json` file and share with team members. They can paste the content into their own configuration file. ## Theme Configuration File Description Theme configuration is stored in `~/.snow/theme.json` file. ### Complete Configuration Example ```json { "theme": "custom", "customColors": { "background": "#1e1e1e", "text": "#d4d4d4", "border": "#3e3e3e", "diffAdded": "#0d4d3d", "diffRemoved": "#5a1f1f", "diffModified": "#dcdcaa", "lineNumber": "#858585", "lineNumberBorder": "#3e3e3e", "menuSelected": "#5e0691ff", "menuNormal": "white", "menuInfo": "cyan", "menuSecondary": "gray", "error": "red", "warning": "yellow", "success": "green", "logoGradient": ["#d3d3d3", "#808080", "#505050"] }, "simpleMode": false } ``` ### Field Descriptions - **theme**: Currently used theme type - Options: `dark`, `light`, `github-dark`, `rainbow`, `solarized-dark`, `nord`, `custom` - **customColors**: Custom theme color configuration - Only used when `theme` is `custom` - Contains 16 color fields - **simpleMode**: Simple mode switch - `true`: Enable simple mode - `false`: Use standard mode ### Manual Editing Considerations If choosing to manually edit configuration file: 1. Ensure JSON format is correct 2. logoGradient must be array format 3. Color values must be valid color formats 4. Restart Snow CLI after editing to load new configuration It's recommended to use configuration interface for modifications to avoid format errors. ================================================ FILE: docs/usage/en/09.Command Panel Guide.md ================================================ # Snow CLI User Guide - Command Panel Guide The command panel is a quick command system provided by Snow CLI, allowing you to quickly execute various operations through simple slash commands. ## Command Panel Overview All commands start with `/` and can be executed by typing them in the chat input box. Commands are divided into the following categories: - Session management - Mode switching - Code review and analysis - Configuration and management - Custom extensions ## Session Management Commands ### `/clear` Clear current chat context. - **Function**: Clear current conversation history and start fresh conversation - **Use Cases**: When conversation context is too long or need to switch topics - **Example**: Simply type `/clear` and press Enter ### `/resume` Resume historical session. - **Function**: Open session selection panel to select and resume previously saved conversations - **Use Cases**: Need to continue unfinished conversation or view history - **Example**: Type `/resume` to view all saved sessions ### `/export` Export conversation records. - **Function**: Export current conversation as text file - **Use Cases**: Need to save conversation content for documentation or sharing - **Example**: Type `/export` to automatically save to project directory ### `/copy-last` Copy the last AI response. - **Function**: Copy the most recent AI assistant message in the current session to the system clipboard - **Use Cases**: Quickly reuse the previous answer in documentation, commit messages, tickets, or other chats - **Notes**: - Only the latest non-sub-agent AI assistant message is copied - If no AI response exists yet, or the last response is empty, Snow CLI shows a prompt instead - **Example**: Type `/copy-last` to copy the last AI response ### `/compact` Compress conversation history. - **Function**: Use AI to compress conversation history, reducing token usage - **Use Cases**: Conversation is too long but don't want to clear, need to retain key information - **Example**: Type `/compact` to start compression ### `/branch` Fork the current session. - **Function**: Fork the current conversation into an independent new session - **Parameters**: Optional branch name - **Use Cases**: Try different approaches based on the same context without affecting the current conversation - **Examples**: - `/branch` - Fork the current session - `/branch my-experiment` - Fork and name it my-experiment ### `/fork` Fork the current session (identical to `/branch`). - **Function**: Fork the current conversation into an independent new session - **Parameters**: Optional branch name - **Use Cases**: Try different approaches based on the same context without affecting the current conversation - **Examples**: - `/fork` - Fork the current session - `/fork my-experiment` - Fork and name it my-experiment ## Mode Switching Commands ### `/yolo` Toggle YOLO mode (auto-approve mode). - **Function**: Turn on/off automatic approval for tool calls, no manual confirmation needed - **Use Cases**: Quick execution when trusting AI operations, or turn off when manual review needed - **Status**: Status saved in localStorage, persists after restart - **Example**: Type `/yolo` to toggle mode ### `/plan` Toggle Plan mode (planning mode). - **Function**: Turn on/off plan mode, AI will make detailed plan before execution - **Use Cases**: Complex tasks need planning first, or simple tasks execute directly - **Status**: Status saved in localStorage - **Example**: Type `/plan` to toggle mode ### `/vulnerability-hunting` Toggle Vulnerability Hunting Mode. - **Function**: Turn on/off Vulnerability Hunting Mode, a professional security analysis agent - **Features**: - Systematic 5-phase vulnerability analysis workflow - Generate executable verification scripts - Create detailed security analysis reports - Support multiple vulnerability type detection (logic errors, security vulnerabilities, etc.) - **Use Cases**: Conducting professional security audits or code vulnerability detection - **Status**: Status saved in localStorage - **Report Location**: `.snow/vulnerability-hunting/docs/` - **Script Location**: `.snow/vulnerability-hunting/scripts/` - **Detailed Guide**: See [Vulnerability Hunting Mode](./11.Vulnerability%20Hunting%20Mode.md) - **Example**: Type `/vulnerability-hunting` to toggle mode ### `/tool-search` Toggle Tool Search mode. - **Function**: Turn Tool Search on/off (discover and load tools on demand) - **Features**: - When enabled, Snow CLI prefers on-demand tool discovery to reduce upfront tool injection - When disabled, the full tool set is provided directly - The current state is persisted in the project's `.snow/settings.json` - **Use Cases**: Switch between “save context” mode and “show all tools directly” mode - **Example**: Type `/tool-search` to toggle the mode ## Code Review and Analysis Commands ### `/review` Code review. - **Function**: Open interactive code review panel to select content for review - **Features**: - Automatically detect Git repository - Display staged changes with file count - Display unstaged changes with file count - Paginated loading of commit history (30 per page) - Multi-select: can select multiple review targets simultaneously - Support adding review notes - AI analyzes code quality, potential bugs, security issues - Provide optimization suggestions - **Panel Operations**: - `Up/Down` - Move selection up/down - `Space` - Check/uncheck current item - `Enter` - Confirm selection and start review - `ESC` - Close panel - **Selectable Review Targets**: - **Staged**: Staged changes - **Unstaged**: Unstaged changes - **Historical Commits**: Shows commit SHA, message, author, date - **Examples**: - `/review` - Open review panel - Use Space key to select content to review in the panel, press Enter to confirm ### `/diff` Review conversation file changes in Diff view. - **Function**: Open the Diff Review panel to inspect files associated with earlier user messages in the conversation and show diffs in your IDE - **Features**: - Lists conversation checkpoints based on session snapshots - Lets you preview single-file diffs first, then open all diffs for the selected message at once - Useful for reviewing code changes made by AI during the current session - **Panel Operations**: - `↑/↓` - Select a message or file - `Tab` - Switch between the message list and the file list - `Enter` - Open all file diffs for the selected message - `ESC` - Close the panel - **Prerequisite**: It is recommended to connect the VSCode/IDE plugin first, otherwise diffs cannot be shown inside the IDE - **Example**: Type `/diff` to open the conversation diff review panel ### `/init` Initialize project documentation. - **Function**: AI analyzes current project and generates/updates AGENTS.md documentation - **Features**: - Automatically explore project structure - Read configuration files and code - Generate project overview, tech stack, architecture description - **Generated Content**: Project name, overview, tech stack, directory structure, features, usage instructions, etc. - **Example**: Type `/init` in project root directory ### `/new-prompt` Generate a refined prompt. - **Function**: Open the Prompt Generator panel and turn your rough requirement into a prompt you can continue editing or send later - **Features**: - Uses AI to transform natural-language requirements into a more structured prompt - Supports previewing, regenerating, or accepting the generated result - After accepting, the generated prompt is put back into the input box and is **not** sent automatically - **Panel Operations**: - **Input step**: Enter your requirement and press `Enter` to start generating - **Preview step**: `↑/↓` scroll, `Y` accept, `R` regenerate, `N/ESC` cancel - **Use Cases**: Helpful when you want to turn a vague idea into a clearer and more complete instruction - **Example**: Type `/new-prompt` to open the prompt generator ### `/role` Role definition file management. - **Function**: Manage ROLE files (global and project scopes) to define the AI's role and behavior - **Features**: - **Create**: `/role` - Open interactive panel to select creation location - Global location: `~/.snow/ROLE.md` - Project location: `./ROLE.md` - **Delete**: `/role -d` or `/role --delete` - Open deletion panel to select ROLE.md to delete - **List/Switch**: `/role -l` or `/role --list` - Open the ROLE management panel to list roles and switch the active one - **Use Cases**: Customize AI behavior/output per project or set a global default - **Panel Operations**: - **Creation Panel**: `G` - Select global, `P` - Select project, `ESC` - Cancel - **Deletion Panel**: `G` - Delete global, `P` - Delete project, `Y` - Confirm deletion, `N/ESC` - Cancel - **ROLE Management Panel (/role -l)**: - `Tab` - Switch Global / Project - `Up/Down` - Move selection - `Enter` - Set selected ROLE as active (marked as `[✓]` in the list) - `N` - Create a new inactive ROLE (file name like `ROLE-.md`) - `D` - Delete selected inactive ROLE (requires confirmation: `Y` confirm, `N/ESC` cancel) - `ESC` - Close the panel - **Active role persistence**: - Global: `~/.snow/role.json` - Project: `/.snow/role.json` - Field: `activeRoleId` (missing or `active` reads `ROLE.md`; otherwise reads `ROLE-.md`) - **Examples**: - `/role` - Open creation panel, select location and create ROLE.md - `/role -d` - Open deletion panel, select file to delete - `/role -l` - Open ROLE management panel ### `/reindex` Rebuild codebase index. - **Function**: Rescan and index project codebase - **Prerequisite**: Need to enable codebase feature in configuration first - **Parameters**: - No parameters: Incremental rebuild, skip unchanged files - `-force`: Force rebuild, delete existing database and rebuild from scratch - **Use Cases**: - After codebase update to refresh index - Use `-force` when index is corrupted for complete rebuild - **Examples**: - `/reindex` - Incremental index rebuild - `/reindex -force` - Force complete index rebuild ### `/codebase` Manage codebase indexing for the current project. - **Function**: Enable, disable, or check the current project's Codebase indexing status - **Parameters**: - No parameters: `/codebase` - Toggle the current state directly - `on`: `/codebase on` - Enable codebase indexing - `off`: `/codebase off` - Disable codebase indexing - `status`: `/codebase status` - Show the current status - **Prerequisite**: Before enabling it, configure embedding-related settings in `/home` - **Behavior**: - Enabling saves the project setting and triggers indexing - Disabling stops indexing and file watching - **Examples**: - `/codebase status` - Check status - `/codebase on` - Enable indexing - `/codebase off` - Disable indexing ## Configuration and Management Commands ### `/home` Return to welcome page. - **Function**: Return to Snow CLI main menu/welcome interface - **Features**: - Pause codebase indexing - Clear API configuration cache - Reset client connection - **Example**: Type `/home` to return to homepage ### `/ide` Connect IDE plugin. - **Function**: Connect to VSCode or JetBrains IDE plugin - **Features**: - Automatically detect and connect IDE - Display connection port - Force reconnect (if already connected) - **Prerequisite**: Need to install corresponding IDE plugin first - **Example**: Type `/ide` to establish connection ### `/connect` Connect to a Snow Instance. - **Function**: Open the instance connection panel, log in, and connect to a remote Snow Instance for AI processing - **Usage**: - No parameters: `/connect` - Open the connection wizard - With API URL: `/connect http://localhost:5136/api` - Open the panel with the API URL prefilled - **Features**: - Reuse saved connection settings when available - Step through API URL, username/password, instance ID, and display name entry - On the saved-config screen, press `D` to delete the saved connection configuration - **Panel Operations**: - `Enter` - Continue to the next step or submit the current form - `↑/↓` - Switch focus between fields on multi-field steps - `ESC` - Go back or close the panel - **Examples**: - `/connect` - Open the connection panel - `/connect http://localhost:5136/api` - Prefill the URL and connect ### `/disconnect` Disconnect from the current Snow Instance. - **Function**: Disconnect the currently active instance connection - **Use Cases**: Switch instances, clear remote connection state, or stop routing requests through an instance - **Example**: Type `/disconnect` to disconnect ### `/connection-status` Show instance connection status. - **Function**: Print the current Snow Instance status, instance information, and any error details when available - **Use Cases**: Troubleshoot connection failures or confirm whether you are connected to the intended instance - **Example**: Type `/connection-status` to inspect the connection status ### `/mcp` View MCP services. - **Function**: Open MCP (Model Context Protocol) service panel - **Features**: Display list and status of configured MCP services - **Example**: Type `/mcp` to view services ### `/usage` View usage statistics. - **Function**: Open usage statistics panel - **Features**: Display token usage, API call counts and other statistics - **Example**: Type `/usage` to view statistics ### `/permissions` Manage tool permissions. - **Function**: Open permissions management panel - **Features**: Manage always-approved tools list, control which tools can execute automatically - **Use Cases**: Need to configure auto-approval permissions for tools, or revoke automatic execution permissions for certain tools - **Example**: Type `/permissions` to open permissions panel ### `/auto-format` Toggle auto-formatting after MCP file edits. - **Function**: Enable, disable, or inspect the current project's auto-format status - **Parameters**: - No parameters: `/auto-format` - Toggle the current state directly - `on`: `/auto-format on` - Enable auto-formatting - `off`: `/auto-format off` - Disable auto-formatting - `status`: `/auto-format status` - Show the current status - **Behavior**: - The setting is persisted in the project's `.snow/settings.json` - It only affects the current project - The default state is enabled - **Use Cases**: Control whether files edited by AI through MCP are automatically formatted afterward - **Examples**: - `/auto-format` - Toggle the current state - `/auto-format status` - Check the status - `/auto-format off` - Turn auto-formatting off ### `/help` Help information. - **Function**: Open help panel - **Features**: Display shortcuts, common command descriptions - **Example**: Type `/help` or press `?` key ### `/quit` Exit program. - **Function**: Safely exit Snow CLI application - **Features**: - Stop codebase indexing - Disconnect VSCode connection - Clean up resources - **Example**: Type `/quit` or press `Ctrl+C` ### `/worktree` Git branch management. - **Function**: Open interactive Git branch management panel - **Features**: - Automatically detect if current directory is a Git repository - Display all local branches with current branch marked - Quick branch switching - Create new branches - Delete branches (supports force deletion of unmerged branches) - Prompt to stash changes before switching when local changes conflict - **Panel Operations**: - `↑/↓` - Move selection up/down - `Enter` - Switch to selected branch - `N` - Create new branch - `D` - Delete selected branch - `Y/N` - Confirm/cancel deletion or stash-and-switch - `ESC` - Close panel - **Use Cases**: Need to quickly manage Git branches without leaving the terminal - **Example**: Type `/worktree` to open branch management panel ### `/add-dir` Add working directory. - **Function**: Add a working directory (supports local directories and SSH remote directories) - **Usage**: - No parameters: `/add-dir` - Open directory management panel - With local path: `/add-dir /path/to/project` - Directly add a local directory - Remote directory: Use the panel and press `S` to enter “Add SSH Remote Directory”, then fill host/port/username/auth method/remote path - **Configuration File**: `.snow/working-dirs.json` - **Examples**: - `/add-dir` - Open panel (`A` add local, `S` add SSH, `D` delete marked) - `/add-dir D:\projects\myapp` - Add a local directory directly ### `/backend` View background processes. - **Function**: Open background process management panel - **Features**: - Display all commands running in background - View process status (running, completed, failed) - View process output and runtime duration - Support terminating running processes - **Panel Operations**: - `↑/↓` - Select process - `Enter` - Terminate selected running process - `ESC` - Close panel - **Use Cases**: Manage long-running commands moved to background via `Ctrl+B` - **Example**: Type `/backend` to view background processes ### `/loop` Create a scheduled loop task. - **Function**: Create a loop task that periodically executes a specified prompt at a fixed interval (session-scoped; stops when Snow CLI exits) - **Syntax**: - `/loop ` - Prefix duration format, e.g. `/loop 5m check service status` - `/loop every ` - Suffix format, e.g. `/loop check service status every 2 hours` - Omitting a duration defaults to a 10-minute interval - **Duration Units**: - Seconds: `s`, `sec`, `second`, `seconds` - Minutes: `m`, `min`, `minute`, `minutes` - Hours: `h`, `hr`, `hour`, `hours` - Days: `d`, `day`, `days` - Compound formats supported: e.g. `8h30m`, `1d12h` - **Sub-commands**: - `/loop list` - List all active loop tasks - `/loop cancel ` or `/loop stop ` - Cancel a specific loop task - `/loop tasks` - Open the task manager and show related tasks - **Notes**: - Session-scoped: all loop tasks stop when Snow CLI exits - Maximum 50 active loops at a time - If the previous task is still running when the interval fires, the new trigger is skipped automatically - **Examples**: - `/loop 5m check logs for errors` - Run every 5 minutes - `/loop 8h30m generate daily report` - Run every 8 hours 30 minutes - `/loop check service status every 2 hours` - Run every 2 hours - `/loop list` - View all active loop tasks - `/loop cancel abc12345` - Cancel a specific loop task ### `/profiles` Open the profile and model switching panel. - **Function**: Open the Profile panel to switch configuration profiles and AI model settings - **Features**: - Switch between different configuration profiles - Switch the AI model in use - Support search filtering - Switch conversation model in real-time - Support switching thinking intensity settings (for models with thinking capabilities) - **Panel Operations**: - `↑/↓` - Move selection up/down - `Tab` - Open the detail edit panel for the focused profile (without switching the active profile) - `Enter` - Switch to the selected profile (set as active) - `Backspace/Delete` - Delete the last character of the search query - Type characters directly - Filter the profile list by search query - `ESC` - Close panel - **Use Cases**: Use when keyboard shortcuts conflict or are inconvenient; also useful for quickly switching AI models - **Example**: Type `/profiles` to open the profile and model selection panel ## Custom Extension Commands ### `/custom` Create custom commands. - **Function**: Open custom command configuration panel - **Features**: - Create new custom commands - Supports two types: - **execute**: Execute command in terminal - **prompt**: Send prompt to AI - Supports global and project level - **Supports additional input**: You can add extra arguments after the command, which will be automatically appended to the command or prompt - **Storage Location**: - Global: `~/.snow/commands/` - Project: `.snow/commands/` - **Examples**: - Type `/custom` to open configuration interface - Using additional input: `/mycommand extra args` - arguments will be appended to the original command or prompt #### `description` (optional) Custom command JSON supports an optional `description` field. It is shown in the command panel suggestions (the list you see after typing `/`) so you can keep prompts readable. - **Compatibility**: If `description` is missing/empty, Snow CLI falls back to showing `command` (for `type: "prompt"` commands, that is the full prompt), so existing command files keep working. - **How to set**: You can enter it when creating a command via `/custom`; leave it empty to skip. **Example:** ```json { "type": "prompt", "command": "Summarize the current conversation", "description": "Summarize this chat" } ``` #### Namespaced custom commands Custom commands support a namespaced format: `/: [args...]`. This is useful when you want to organize many commands by feature/team/environment. **Directory mapping (command name is inferred from file path):** - `.snow/commands/build.json` -> `/build` - `.snow/commands/deploy/stage.json` -> `/deploy:stage` - `.snow/commands/deploy/prod.json` -> `/deploy:prod` The same rule applies to the global directory `~/.snow/commands/`. **Notes / constraints:** - Arguments are separated by whitespace: `/deploy:stage --dry-run` - `:` is reserved as the namespace separator. - Namespace uses folder segments separated by `/`. - Namespace segments cannot be `.` or `..`, and cannot contain `:` or `\\`. - The command part cannot contain whitespace, `\\`, `/`, or `:` (and cannot be `.` or `..`). ### `/skills` Create skill templates. - **Function**: Open skill creation dialog - **Features**: - Generate SKILL.md (main document) - Generate reference.md (detailed reference) - Generate examples.md (usage examples) - Create templates/ (template files) - Create scripts/ (auxiliary scripts) - **Storage Location**: - Global: `~/.snow/skills/` - Project: `.snow/skills/` - **Naming Rules**: Lowercase letters, numbers, and hyphens; use `/` to namespace (max 64 chars per segment) - **Directory mapping**: `~/.snow/skills///SKILL.md` -> skill id `/` - **Example**: Type `/skills`, then enter `team/my-skill` in the dialog ### Deleting Custom Commands/Skills After creating custom commands, use `/ -d` to delete: - **Delete custom command**: `/mycommand -d` - **Location Recognition**: Automatically recognizes global or project level - **Example**: If created `/deploy` command, use `/deploy -d` to delete - **Namespaced example**: If created `/deploy:stage` command, use `/deploy:stage -d` to delete ### `/role-subagent` Sub-agent role definition file management. - **Function**: Manage ROLE files for sub-agents (`ROLE-.md`), defining independent role behavior for each sub-agent - **Features**: - **Create**: `/role-subagent` - Open an interactive creation panel, select scope then sub-agent - **Delete**: `/role-subagent -d` or `/role-subagent --delete` - Open the deletion panel to select a sub-agent role file to delete - **List**: `/role-subagent -l` or `/role-subagent --list` - Open the sub-agent role management panel to view and manage existing role files - **Storage Location**: - Global: `~/.snow/ROLE-.md` - Project: `/ROLE-.md` - **Priority**: When loading custom roles, project-level takes precedence over global-level - **Panel Operations**: - **Creation Panel**: 1. Select location: `G` - Global, `P` - Project, `ESC` - Cancel 2. Select sub-agent: `↑/↓` - Navigate, `Enter` - Select, `ESC` - Go back 3. Confirm: `Y` - Confirm creation, `N` - Go back - **Deletion Panel**: 1. Select location: `G` - Global, `P` - Project, `ESC` - Cancel 2. Select file: `↑/↓` - Navigate, `Enter` - Select, `ESC` - Go back 3. Confirm: `Y` - Confirm deletion, `N` - Go back - **List Panel**: - `Tab` - Switch Global / Project - `↑/↓` - Move selection - `D` - Delete selected role file (requires confirmation: `Y` confirm, `N/ESC` cancel) - `ESC` - Close panel - **Use Cases**: When you need to customize role behavior for specific sub-agents (e.g., explore agent, plan agent, etc.) - **Examples**: - `/role-subagent` - Open creation panel - `/role-subagent -d` - Open deletion panel - `/role-subagent -l` - Open list management panel ### `/btw` Quick question (side-channel Q&A). - **Function**: Ask a standalone quick question to the AI without affecting the current conversation context - **Features**: - Streams the AI response in a side panel - Response content is not written to the main conversation history - Supports scrolling through the response - **Panel Operations**: - **Streaming phase**: `ESC` - Abort and close - **Done phase**: `↑/↓` - Scroll through response, `Enter` - Close, `ESC` - Close - **Error phase**: `Enter` - Close, `ESC` - Close - **Use Cases**: Need to quickly ask a question unrelated to the current task without interrupting the conversation context - **Example**: `/btw explain generics in TypeScript` ## Special Commands ### `/agent-` Select sub-agent. - **Function**: Open sub-agent selection panel - **Features**: Select different specialized sub-agents (explore, plan, general, etc.) - **Use Cases**: Need specific type of AI assistant - **Example**: Type `/agent-` to view available agents ### `/todo-` TODO comment selector. - **Function**: Open TODO comment selection panel - **Features**: Scan and manage TODO comments in code - **Use Cases**: Quickly view and handle TODOs in code - **Example**: Type `/todo-` to open selector ### `/skills-` Select and inject a Skill. - **Function**: Open the Skill picker panel and inject the selected Skill's `SKILL.md` content into the current input box - **Features**: - Search by Skill id, name, or description - Add extra appended text before injection - After injection, the input box shows a placeholder, but the full content is restored when sending - **Panel Operations**: - `↑/↓` - Select a Skill - `Tab` - Switch between the “search” and “append text” fields - `Enter` - Inject the currently selected Skill - `Backspace/Delete` - Delete characters from the focused field - `ESC` - Close the panel - **Use Cases**: Reuse an existing Skill template and add task-specific context before sending - **Example**: Type `/skills-` to open the Skill picker ## Keyboard Shortcuts In addition to slash commands, there are some convenient shortcuts: - `Ctrl+P`: Switch profile - `Ctrl+L`: Clear screen (equivalent to `/clear`) - `ESC`: Interrupt AI response - `?`: Open help panel (equivalent to `/help`) - `↑/↓`: Browse input history - `#`: Open sub-agent selection panel (type `#` in input box) - `>>`: Send message to running sub-agents (type `>>` at the beginning of input box) ## Usage Tips 1. **Auto-complete**: After typing `/` all available commands will be displayed, can use arrow keys to select 2. **Command Combinations**: Some commands can be combined with modes, for example: - Turn on `/yolo` mode then execute `/review` for quick code review - Turn on `/plan` mode then execute `/init` for more detailed project documentation 3. **Custom Workflows**: Use `/custom` to create shortcut commands for common operations - For example, create `/deploy` to execute deployment scripts - Create `/test` to run test commands 4. **Skill Reuse**: Use `/skills` to create reusable task templates - Code generation templates - Document templates - Test case templates - For detailed documentation, see [Skills Command Detailed Guide](./18.Skills%20Command%20Detailed%20Guide.md) 5. **Session Management**: Regularly use `/export` to backup important conversations, use `/compact` to compress long conversations ## Frequently Asked Questions ### Q: What if commands don't work? A: Check the following: - Confirm command spelling is correct (case-sensitive) - Some commands have prerequisites (like `/reindex` needs codebase enabled) - Check error message prompts ### Q: How to view all available commands? A: Type `/` and wait, auto-complete list will be displayed, or use `/help` to view help ### Q: Where are custom commands saved? A: - Global commands: `~/.snow/commands/` - Project commands: `/.snow/commands/` ### Q: How to share custom commands between different projects? A: Choose "global" location when creating commands, or manually copy `.snow/commands/` directory to other projects ## Related Configuration - [Sensitive Command Configuration](./6.Sensitive%20Command%20Configuration.md) - Configure dangerous operations that need confirmation - [Hooks Configuration](./7.Hooks%20Configuration.md) - Configure automation before/after command execution - [Codebase Settings](./4.Codebase%20Settings.md) - Configure codebase indexing feature (required for `/reindex`) - [Command Injection Mode](./10.Command%20Injection%20Mode.md) - Execute commands directly in messages as an advanced feature - [Vulnerability Hunting Mode](./11.Vulnerability%20Hunting%20Mode.md) - Professional security analysis and vulnerability detection feature ================================================ FILE: docs/usage/en/10.Command Injection Mode.md ================================================ # Snow CLI Usage Documentation - Command Injection Mode & Bash Mode Welcome to Snow CLI! Agentic coding in your terminal. ## What is Command Injection Mode and Bash Mode Snow CLI provides two command execution modes that allow you to execute terminal commands directly in conversations: ### Command Injection Mode (Single Exclamation Mark `!`) Command Injection Mode allows you to directly embed commands in conversation messages, which will be automatically executed by the system and the results replaced in the message, then sent to AI. This enables AI to quickly obtain command execution results without relying on tool calls, improving interaction efficiency. ### Bash Mode (Double Exclamation Marks `!!`) Bash Mode is a pure terminal mode that executes commands but does not send them to AI. Just like a real terminal, it only executes commands and displays results without triggering AI conversation. Suitable for quick command execution scenarios that don't require AI participation. ## Why Use These Two Modes ### Advantages of Command Injection Mode Traditional command execution requires AI to call tools, wait for user approval, and then execute commands. Command Injection Mode provides a more direct approach: - Embed commands directly in messages without additional tool call process - AI can obtain real-time system status information - Suitable for quick queries and simple operations - Integrated with sensitive command protection mechanism to ensure security ### Advantages of Bash Mode Bash Mode provides a pure terminal experience: - Quick command execution without triggering AI conversation - Save API call costs - Suitable for daily terminal operations - Shares sensitive command protection mechanism with Command Injection Mode ## Syntax Comparison ### Command Injection Mode (Single Exclamation Mark) **Basic Syntax:** ``` !`command` ``` Use single exclamation mark and backticks to wrap commands in messages, and the system will execute the command and replace the result in the message, then send it to AI. **Examples:** ``` Check current directory: !`pwd` List files: !`ls -la` View Git status: !`git status` ``` **Custom Timeout:** ``` !`command` ``` Use angle brackets after the command to specify timeout in milliseconds. If not specified, default timeout is 30000 milliseconds (30 seconds). **Examples:** ``` !`npm install`<60000> !`docker build .`<120000> !`sleep 5`<10000> ``` ### Bash Mode (Double Exclamation Marks) **Basic Syntax:** ``` !!`command` ``` Use double exclamation marks and backticks to wrap commands in messages, and the system will execute the command but not send it to AI. **Examples:** ``` !!`pwd` !!`ls -la` !!`git status` ``` **Custom Timeout:** ``` !!`command` ``` Syntax is the same as Command Injection Mode, supports custom timeout. **Examples:** ``` !!`npm install`<60000> !!`docker build .`<120000> !!`sleep 5`<10000> ``` ### Syntax Rules **Command Injection Mode:** - Must use complete `!` + `` ` `` combination, neither can be omitted - Command content goes inside backticks - Timeout is optional, format is ``, unit is milliseconds - Multiple command injections can be included in one message - Commands are executed sequentially - Execution results replace command syntax, then sent to AI **Bash Mode:** - Must use complete `!!` + `` ` `` combination, neither can be omitted - Command content goes inside backticks - Timeout is optional, format is ``, unit is milliseconds - Multiple commands can be included in one message - Commands are executed sequentially - Execution results are only displayed, not sent to AI ## Command Execution Flow ### Command Injection Mode Flow When you use command injection syntax (single exclamation mark) in messages, the system will: #### 1. Parse Commands The system uses regular expression `/!`([^`]+)`(?:<(\d+)>)?/g` to parse all commands in the message: - Extract command content - Extract timeout (if specified) - Mark command position in message #### 2. Sensitive Command Check Before execution, the system checks if the command matches sensitive command rules: - Iterate through enabled sensitive command patterns - If matched, show confirmation dialog - Display command content, matching pattern, and risk description - Wait for user confirmation or cancellation For sensitive command configuration, see: [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) #### 3. Execute Command After user confirmation (or direct execution for non-sensitive commands): - Windows systems use `cmd.exe` to execute - Unix-like systems (macOS, Linux) use `sh` to execute - Use current working directory as execution path - Inherit current environment variables - Apply specified timeout #### 4. Collect Output During command execution: - Capture standard output (stdout) - Capture standard error (stderr) - Record exit code - Detect timeout situations #### 5. Replace Message Content After execution completes, the system replaces the original command syntax with execution results: On success: ``` --- Command: ls -la --- total 48 drwxr-xr-x 10 user staff 320 Dec 5 10:30 . drwxr-xr-x 20 user staff 640 Dec 4 15:22 .. -rw-r--r-- 1 user staff 1234 Dec 5 10:30 README.md --- End of output --- ``` On failure: ``` --- Command: invalid-command --- Error: command not found: invalid-command --- End of output --- ``` #### 6. Send to AI The complete message with replaced content is sent to AI, which can analyze and respond based on the real command output. ### Bash Mode Flow When you use Bash mode syntax (double exclamation marks) in messages, the system will: #### 1. Parse Commands The system uses regular expression `/!!`([^`]+)`(?:<(\d+)>)?/g` to parse all commands in the message: - Extract command content - Extract timeout (if specified) - Mark command position in message #### 2. Sensitive Command Check Same as Command Injection Mode, checks sensitive command rules before execution. #### 3. Execute Command Execution method is exactly the same as Command Injection Mode. #### 4. Display Output After command execution completes, results are displayed in the terminal but not sent to AI. #### 5. Terminate Flow Bash Mode does not trigger AI conversation, flow ends after execution completes. ## Use Cases ### Command Injection Mode Scenarios #### Quick Status Query ``` What's the current directory situation? !`ls -la` ``` AI will see the actual file list and respond based on it. #### Get System Information ``` Help me analyze system resource usage: Memory: !`free -h` Disk: !`df -h` ``` #### Git Operations Query ``` Current branch status: !`git status` Recent commits: !`git log -5 --oneline` ``` #### Environment Check ``` Check Node version: !`node --version` Check dependencies: !`npm list --depth=0` ``` #### Multiple Command Combination ``` Project information: Git branch: !`git branch --show-current` Uncommitted changes: !`git status --short` Recent commit: !`git log -1 --oneline` ``` ### Bash Mode Scenarios #### Quick Terminal Operations ``` !!`pwd` !!`ls -la` !!`git status` ``` Does not trigger AI conversation, only displays command execution results. #### Daily Command Execution ``` !!`npm run build` !!`git pull` !!`docker ps` ``` Suitable for daily operations that don't require AI participation. #### Test Commands ``` !!`echo "Hello World"` !!`date` !!`whoami` ``` Quickly test if commands work properly. ## Security Mechanisms ### Sensitive Command Protection Command injection mode is fully integrated with sensitive command configuration: 1. **Auto Detection** - All commands are checked against sensitive patterns before execution - Matched commands trigger confirmation flow 2. **User Confirmation** - Display complete command content - Show matched sensitive pattern and risk description - Display timeout (if customized) - User can choose to execute or cancel 3. **Rejection Feedback** - If user rejects executing sensitive command - AI receives feedback and may suggest alternatives - Rejected commands won't appear in final message ### Timeout Protection - Default 30-second timeout prevents command hanging - Can customize timeout for long-running commands - Commands are forcibly terminated after timeout - Timeout information is fed back to AI ### Environment Isolation - Commands execute in current working directory - Inherit current shell environment variables - Won't affect Snow CLI main process - Command failures won't crash CLI ## Best Practices ### 1. Use Command Injection Appropriately **Suitable scenarios**: - Quick system status queries - Get file list or content - Check environment configuration - Simple Git operation queries **Not suitable scenarios**: - Complex batch operations (safer to use tool calls) - Commands requiring interaction (like password input) - Long-running tasks (unless setting sufficient timeout) - Dangerous system operations (should use tool calls with careful confirmation) ### 2. Set Appropriate Timeout Set timeout based on command's expected execution time: ``` Quick query (use default): !`pwd` Install dependencies (60s): !`npm install`<60000> Build image (120s): !`docker build .`<120000> Run tests (180s): !`npm test`<180000> ``` ### 3. Use with Context Provide context for AI to better understand command output: ``` I want to optimize this project's dependencies, first help me see what packages are currently installed: !`npm list --depth=0` ``` ### 4. Handle Sensitive Commands For operations that might trigger sensitive command protection: ``` Please help me check if there are unused files that can be cleaned (don't delete directly): !`git clean -n` ``` Use safe query options (like git clean -n) instead of directly executing dangerous operations. ### 5. Multiple Command Collaboration Combine related commands together for AI to get complete view: ``` Analyze this branch situation: Current branch: !`git branch --show-current` Unmerged commits: !`git log origin/main..HEAD --oneline` Uncommitted changes: !`git status --short` ``` ## Common Issues **Q: What's the difference between command injection and tool calls?** A: Command injection executes commands before sending message to AI and replaces results. AI sees execution results. Tool calls are AI actively requesting command execution during AI response. Command injection is better for quick queries, tool calls are better for complex operations. **Q: Why didn't my command execute?** A: Check these points: - Confirm correct syntax: `!`command`` - Both exclamation mark and backticks must be present - If it's a sensitive command, confirm you selected execute in confirmation dialog - Check if it timed out (default 30 seconds) **Q: Can I use multiple commands in one message?** A: Yes. The system will execute all commands sequentially, and each command's result will replace the corresponding syntax position. **Q: What happens when command execution fails?** A: Failed commands will show error information in output, and AI will see the complete error content and may provide solutions. **Q: What's the maximum timeout setting?** A: Theoretically no limit, but recommend not exceeding 300000 milliseconds (5 minutes). For very long-running tasks, suggest using tool call method for better monitoring and management. **Q: Does command injection bypass sensitive command protection?** A: No. All commands executed through command injection are checked against sensitive commands. Commands matching sensitive patterns must be confirmed by user. **Q: Can I inject commands requiring interaction?** A: Not recommended. Command injection doesn't support interactive input, such commands will hang until timeout. If you need to execute interactive commands, use Snow CLI's tool call functionality. **Q: Are there differences between Windows and Unix system commands?** A: Yes. Windows uses `cmd.exe` to execute, Unix-like systems use `sh` to execute. Consider cross-platform compatibility when writing commands, or explicitly specify target platform. ## Configuration File Location Command injection mode itself requires no configuration, but depends on sensitive command configuration: - Windows: `%USERPROFILE%\.snow\sensitive-commands.json` - macOS/Linux: `~/.snow/sensitive-commands.json` For detailed configuration method, see: [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) ## Related Features - [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Configure dangerous commands requiring confirmation - [Command Panel Guide](./09.Command%20Panel%20Guide.md) - Learn about other shortcut command features - [Vulnerability Hunting Mode](./11.Vulnerability%20Hunting%20Mode.md) - Professional security analysis feature, also uses sensitive command protection ================================================ FILE: docs/usage/en/11.Vulnerability Hunting Mode.md ================================================ # Snow CLI Usage Documentation - Vulnerability Hunting Mode Welcome to Snow CLI! Agentic coding in your terminal. ## What is Vulnerability Hunting Mode Vulnerability Hunting Mode is a professional security analysis agent mode in Snow CLI, focused on discovering and verifying security vulnerabilities in your codebase. Unlike normal conversation mode, this mode follows a strict security analysis workflow, providing systematic vulnerability detection, evidence collection, verification script generation, and detailed reports. ## Why Use Vulnerability Hunting Mode Security vulnerabilities can lead to serious consequences during software development. Vulnerability Hunting Mode provides professional security analysis capabilities: - Systematic vulnerability detection process covering multiple vulnerability types - Evidence-based analysis to avoid false positives - Generate executable verification scripts for each vulnerability - Detailed fix recommendations and priority ranking - Interactive communication ensuring accurate analysis scope - Focus on specific modules avoiding superficial analysis ## Enable Vulnerability Hunting Mode ### Toggle Using Command Type in Snow CLI conversation interface: ``` /vulnerability-hunting ``` System will display mode toggle prompt, type command again to disable the mode. ### Mode Status - Mode status is saved in localStorage - Maintains last status after application restart - Can switch back to normal mode anytime ## Core Principles Vulnerability Hunting Mode follows these core principles: ### 1. User Query First AI prioritizes responding to your actual questions and needs, won't arbitrarily analyze entire codebase without request. ### 2. Language Adaptation AI always responds and generates reports in the same language as yours. ### 3. Interactive Communication AI frequently uses interactive Q&A to: - Clarify ambiguous requirements - Confirm analysis scope - Ask about specific test scenarios - Verify discovered issues - Get permission for code modifications ### 4. Evidence-Based Analysis All vulnerability reports must have specific code evidence, AI won't make guesses or assumptions. ### 5. Focused Scope Only analyze specific modules or components each time, not entire codebase at once. ### 6. Verification Required Every vulnerability must have verification script or proof-of-concept code. ### 7. Read-Only Analysis Unless you explicitly request, AI won't modify source code, only generates reports and recommendations. ## Complete Workflow Vulnerability Hunting Mode follows a strict 5-phase workflow: ### Phase 1: Scope Definition (Mandatory) **Objective**: Clearly define specific area to analyze. **Process**: 1. **If you didn't specify module**: - AI explores codebase structure - Lists major modules and components - Asks which specific area you want to analyze 2. **If you specified vague area**: - AI breaks it down into smaller sub-components - Asks if you focus on all parts or specific parts 3. **Confirm before starting analysis**: - Prioritize which vulnerability categories (logic errors vs security issues) - Expected analysis depth - Specific concerns or known issues **Scope Document Example**: ## Use Case Examples ### Scenario 1: Analyze Specific Module ``` You: Enter vulnerability hunting mode, analyze authentication module AI: Okay, I've switched to vulnerability hunting mode. Let me explore the authentication module structure... I found these authentication-related components: 1. Login flow (login.ts, auth.ts) 2. Session management (session.ts, middleware.ts) 3. Password reset (resetPassword.ts) 4. Token handling (jwt.ts, tokenService.ts) Which specific area do you want to analyze first? Or should I check all components? You: First check JWT token handling AI: Understood. Before starting analysis, I want to confirm: Do you want me to prioritize: 1. Logic errors (null checks, boundary cases, race conditions) 2. Security issues (injection, auth bypass, data leaks) 3. Check both You: Check both AI: Okay, I'll comprehensively analyze JWT token handling module... [Performing analysis...] I found the following issues: 1. [Critical] JWT signature verification missing 2. [High] Token expiry check logic error 3. [Medium] Token refresh mechanism missing I've created verification scripts. Want to see detailed report? ``` ### Scenario 2: Verify Known Issue ``` You: I suspect user input handling has SQL injection, help me verify AI: Okay, let me locate code related to user input handling... I found these places processing user input: - src/controllers/userController.ts:searchUser() - src/controllers/productController.ts:search() - src/services/queryBuilder.ts:buildQuery() Are these all your concerns? Or a specific function? You: Mainly the searchUser function AI: Understood. I'll focus on analyzing SQL injection risk in that function... [After analysis...] Confirmed SQL injection vulnerability! Details: - Location: src/controllers/userController.ts:42 - Issue: Direct concatenation of user input into SQL query - Severity: Critical I've created verification script: .snow/vulnerability-hunting/scripts/verify-sql-injection.sh Running this script can actually trigger the vulnerability. Need me to generate detailed report and fix recommendations? ``` ### Scenario 3: Generate Security Report You: Generate security analysis report for entire API module AI: Okay, the API module is large. Let me list main sub-modules: 1. User API (/api/users/*) 2. Product API (/api/products/*) 3. Order API (/api/orders/*) 4. Auth API (/api/auth/*) 5. Admin API (/api/admin/*) Since there are many modules, recommend analyzing in batches. Which one to start with? Or should I do a quick high-level scan to find most obvious issues? You: First do quick scan, find serious issues AI: Understood, I'll conduct quick security scan focusing on critical vulnerabilities... [After scanning...] Quick scan complete, found following serious issues: 1. [Critical] User API: SQL injection (3 places) 2. [Critical] Auth API: JWT signature verification missing 3. [Critical] Admin API: Missing permission checks 4. [High] Order API: Race condition may cause duplicate charging Recommend fixing these serious issues first. Need me to create detailed report and verification script for each issue? ## File Structure All files generated by Vulnerability Hunting Mode are stored in project's `.snow/vulnerability-hunting/` directory: ```text .snow/ └── vulnerability-hunting/ ├── docs/ # Analysis report directory │ ├── auth-module.md # Authentication module report │ ├── api-security-scan.md # API security scan report │ └── payment-module.md # Payment module report └── scripts/ # Verification script directory ├── verify-jwt-bypass.js # JWT bypass verification ├── verify-sql-injection.sh # SQL injection verification ├── verify-race-condition.js # Race condition verification └── verify-auth-bypass.py # Auth bypass verification ``` ### Report Naming Convention - Use lowercase letters and hyphens - Format: `[module-name]-[report-type].md` - Examples: `auth-module.md`, `api-security-scan.md` ### Script Naming Convention - Use lowercase letters and hyphens - Format: `verify-[vulnerability-type].[extension]` - Examples: `verify-sql-injection.sh`, `verify-null-pointer.js` ## Best Practices ### 1. Define Clear Analysis Scope Don't request analyzing entire codebase, instead: - Specify specific modules or components - Clarify focused vulnerability types - Provide known risk points ### 2. Timely Communication AI will frequently ask to confirm details, please: - Answer AI's questions to clarify requirements - Provide additional context information - Explain specific security concerns ### 3. Verify Findings For issues AI discovers: - Run provided verification scripts - Confirm in test environment - Evaluate actual impact ### 4. Prioritize Fixes Based on priorities in report: - Fix critical vulnerabilities immediately - Sort other issues by priority - Document fix process ### 5. Continuous Improvement After fixing vulnerabilities: - Request AI to re-verify - Add security tests - Update security checklist ## Limitations and Considerations ### 1. Analysis Scope - Only analyze specific module each time, not entire codebase - Need to clearly specify analysis scope - Large projects recommend multiple analyses ### 2. Verification Scripts - Scripts should run in isolated environment - Some scripts may require specific test environment - Read script content carefully before running ### 3. Read-Only Mode - Doesn't modify source code by default - Only generates reports and fix recommendations - Must explicitly request when needing code fixes ### 4. False Positive Possibility - AI analysis may produce false positives - Always verify discovered issues - Combine with manual review ### 5. Coverage - Cannot guarantee finding all vulnerabilities - Focuses on common and serious security issues - Recommend combining with other security tools ## Common Issues **Q: What's difference between Vulnerability Hunting Mode and normal mode?** A: Vulnerability Hunting Mode is specialized security analysis agent, follows strict 5-phase workflow, generates detailed reports and verification scripts. Normal mode is more general, suitable for daily development tasks. **Q: How long does analyzing a module take?** A: Depends on module size and complexity. Small modules (few hundred lines) may take several minutes, medium modules (several thousand lines) may take 10-30 minutes, large modules recommend splitting analysis. **Q: Are verification scripts safe?** A: Verification scripts are designed to run safely, won't cause permanent damage. But recommend running in isolated test environment, don't execute in production environment. **Q: Can AI automatically fix vulnerabilities?** A: Not by default. AI only provides fix recommendations. If you need automatic fixes, must explicitly request, and AI will seek your confirmation first. **Q: How to view previous analysis reports?** A: All reports are saved in `.snow/vulnerability-hunting/docs/` directory, can view anytime. **Q: Can I customize analysis categories?** A: Yes. AI will ask before starting which categories you focus on. You can specify only checking logic errors, only checking security issues, or checking both. **Q: What programming languages does Vulnerability Hunting Mode support?** A: Supports common programming languages including JavaScript/TypeScript, Python, Java, Go, Rust, C#, etc. Analysis quality depends on codebase indexing status. **Q: Will discovered vulnerabilities be automatically reported to team?** A: No. All reports only stored locally. You need to manually share reports or integrate into your security workflow. **Q: Can reports be exported to other formats?** A: Reports are generated in Markdown format, can easily convert to PDF, HTML, or other formats. You can also request AI to generate reports in specific format. **Q: How to use with CI/CD?** A: Can run verification scripts in CI/CD process to detect if known vulnerabilities are fixed. But complete analysis recommend manual triggering as it requires interactive communication. ## Related Features - [Command Panel Guide](./09.Command%20Panel%20Guide.md) - Learn about `/vulnerability-hunting` and other commands - [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Configure dangerous commands requiring confirmation - [Codebase Setup](./04.Codebase%20Setup.md) - Enable codebase indexing to improve analysis effectiveness ================================================ FILE: docs/usage/en/12.Headless Mode.md ================================================ # Snow CLI Usage Documentation - Headless Mode Welcome to Snow CLI! Agentic coding in your terminal. ## What is Headless Mode Headless Mode is Snow CLI's quick conversation feature that allows you to ask questions directly from the command line and get AI responses without entering the interactive interface. It's perfect for: - Script automation - CI/CD integration - Quick consultations - Third-party tool integration ## Basic Usage ### Single Question ```bash snow --ask "your question" ``` Examples: ```bash snow --ask "Explain what this code does" snow --ask "How to optimize this SQL query" snow --ask "Explain React's useState hook" ``` ### Continuous Conversation Headless mode supports session context persistence, allowing continuous conversations: ```bash # First question snow --ask "Help me create a React component" # Output includes: SESSION_ID=abc-123-def-456 # Continue conversation using the returned Session ID snow --ask "Add styles to this component" abc-123-def-456 # Continue further snow --ask "Add some interactive features" abc-123-def-456 ``` ## Features ### Automatic Session Management - Each conversation automatically creates and saves a session - Session ID is displayed at the end of output in `SESSION_ID=` format - Historical messages are loaded and passed to AI as context - Supports cross-platform session sharing (same project) ### YOLO Mode Headless mode enables YOLO mode by default (auto-approve tool calls): - Non-sensitive commands execute automatically - Sensitive commands still require manual confirmation - Improves automation efficiency For sensitive command configuration, see: [Sensitive Commands Configuration](./6.Sensitive%20Commands%20Configuration.md) ### File References Headless mode supports file references in questions: ```bash snow --ask "Analyze issues in this file @src/App.tsx" snow --ask "Optimize this code @utils/helper.js" ``` ### Colored Output Headless mode provides friendly colored terminal output: - User query: Cyan border - AI response: Markdown rendering with code highlighting - Tool execution: Yellow/Green/Red status indicators - Session info: Blue information box ## Session Recovery Mechanism ### How It Works 1. **First Conversation**: Creates new session, generates UUID 2. **Save History**: All messages auto-saved to `~/.snow/sessions/` 3. **Provide Session ID**: Displays `SESSION_ID=` at end of output 4. **Restore Conversation**: Loads historical messages using session ID 5. **Continue Conversation**: New messages append to history ### Session Format Session information in output includes two parts: 1. **Human-Friendly Format** (colored box): ``` ┌─ Session Information │ Session ID: abc-123-def-456 │ To continue this conversation, use: │ snow --ask "your next question" abc-123-def-456 └─ ``` 2. **Machine-Parseable Format** (plain text): ``` SESSION_ID=abc-123-def-456 ``` ### Session Storage Location - Windows: `%USERPROFILE%\.snow\sessions\\\.json` - macOS/Linux: `~/.snow/sessions///.json` Sessions are automatically categorized by project and date for easy management. ## Third-Party Integration ### Shell Script Integration ```bash #!/bin/bash # Execute conversation and extract Session ID output=$(snow --ask "Create an API endpoint") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) # Continue conversation using Session ID snow --ask "Add error handling" "$session_id" snow --ask "Add unit tests" "$session_id" ``` ### Python Integration ```python import subprocess import re # Execute conversation result = subprocess.run( ['snow', '--ask', 'Help me analyze this error'], capture_output=True, text=True ) # Extract Session ID match = re.search(r'SESSION_ID=(.+)', result.stdout) if match: session_id = match.group(1).strip() # Continue conversation subprocess.run([ 'snow', '--ask', 'How to fix this issue', session_id ]) ``` ### Node.js Integration ```javascript const { execSync } = require('child_process'); // Execute conversation const output = execSync('snow --ask "Create an Express route"', { encoding: 'utf-8' }); // Extract Session ID const match = output.match(/SESSION_ID=(.+)/); if (match) { const sessionId = match[1].trim(); // Continue conversation execSync(`snow --ask "Add middleware" ${sessionId}`); } ``` ### CI/CD Integration Using in GitHub Actions: ```yaml name: AI Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup Snow CLI run: npm install -g snow-ai - name: AI Review run: | # Analyze changed files changed_files=$(git diff --name-only HEAD^) # Request AI analysis output=$(snow --ask "Analyze changes in these files: $changed_files") # Extract suggestions echo "$output" >> $GITHUB_STEP_SUMMARY ``` ## Output Format ### Standard Output Structure ``` ╭─────────────────────────────────────────────────────────╮ │ ❆ Snow AI CLI - Headless Mode ❆ │ ╰─────────────────────────────────────────────────────────╯ ┌─ Continuing Session (if continuing conversation) │ Session ID: abc-123-def-456 │ Previous messages: 4 ┌─ User Query │ Your question content └─ Assistant Response AI response content (Markdown format with code highlighting) ┌─ Session Information │ Session ID: abc-123-def-456 │ To continue this conversation, use: │ snow --ask "your next question" abc-123-def-456 └─ SESSION_ID=abc-123-def-456 ``` ### Parsing Recommendations For script and tool integration, recommended parsing methods: 1. **Extract Session ID**: - Use regex `/SESSION_ID=(.+)/` - Or simply find last line with `SESSION_ID=` prefix 2. **Extract AI Response**: - Find content after `└─ Assistant Response` - Remove ANSI color codes (if needed) 3. **Error Handling**: - Check exit code - Look for `✗ Error:` marker ## Use Cases ### Code Review Assistant ```bash # Quick code review git diff | snow --ask "Review these code changes and point out potential issues" # Targeted review snow --ask "Does this code have performance issues @src/utils/parser.ts" ``` ### Documentation Generation ```bash # Generate function documentation snow --ask "Generate JSDoc comments for this function @src/api.ts" # Generate README snow --ask "Generate project README based on code structure @src/" ``` ### Quick Consultation ```bash # Technical questions snow --ask "How to use React 18's concurrent features" # Debugging suggestions snow --ask "How to solve this error: TypeError: Cannot read property 'map' of undefined" ``` ### Automated Workflows ```bash #!/bin/bash # Automated code optimization workflow output=$(snow --ask "Analyze project dependencies @package.json") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) snow --ask "Suggest dependencies that need updating" "$session_id" snow --ask "Generate dependency update script" "$session_id" ``` ### Test Generation ```bash # Generate unit tests snow --ask "Generate unit tests for this function @src/calculator.ts" # Generate test data output=$(snow --ask "Generate test user data in JSON format") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) snow --ask "Generate 10 more variant data" "$session_id" ``` ## Best Practices ### 1. Clear Question Descriptions ```bash # Good example snow --ask "Optimize this SQL query's performance, focus on index usage @query.sql" # Not clear enough snow --ask "Optimize @query.sql" ``` ### 2. Reasonable Use of Session Context ```bash # Continuous conversation after establishing context output=$(snow --ask "Create a user authentication system") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) # Subsequent questions can be more concise snow --ask "Add password reset feature" "$session_id" snow --ask "Add email verification" "$session_id" ``` ### 3. Handling Long-Running Tasks For tasks that may require extended thinking: ```bash # Complex tasks may need more time snow --ask "Refactor entire authentication module using best practices @src/auth/" ``` Wait for AI to complete thinking and tool calls. ### 4. Combine with Command Injection ```bash # Embed real-time information in question snow --ask "Analyze current Git branch status !`git status` and provide suggestions" ``` For command injection, see: [Command Injection Mode](./10.Command%20Injection%20Mode.md) ### 5. Error Handling ```bash #!/bin/bash # Error handling in scripts if ! output=$(snow --ask "your question" 2>&1); then echo "Error: AI conversation failed" echo "$output" exit 1 fi # Check if Session ID was successfully generated if ! echo "$output" | grep -q "SESSION_ID="; then echo "Warning: Failed to retrieve Session ID" fi ``` ## Limitations and Considerations ### Unsupported Features 1. **Interactive Tools**: - `askuser` tool is not available - Cannot request user input in headless mode 2. **Plan Mode**: - Headless mode doesn't support Plan mode - All tool calls execute immediately (YOLO mode) 3. **Real-time Update Display**: - No real-time streaming output to terminal - Results displayed all at once after completion ### Security Considerations 1. **Sensitive Command Confirmation**: - Even in YOLO mode, sensitive commands still require confirmation - Not suitable for fully unattended automation 2. **API Key Protection**: - When using in CI/CD, ensure API keys are securely stored - Use environment variables or secret management services 3. **Output Content Review**: - AI output may contain sensitive information - Be careful to filter when using in public logs ### Performance Considerations 1. **Session Size**: - Long session history increases token consumption - Recommend periodically starting new sessions 2. **Concurrency Limits**: - Be aware of API rate limiting when running multiple headless mode instances 3. **Network Latency**: - Response time depends on network and AI service - Consider setting reasonable timeouts ## FAQ **Q: What's the difference between headless mode and interactive mode?** A: Headless mode is single-execution mode that automatically exits after completion, suitable for scripts and automation. Interactive mode provides a complete UI interface with persistent conversations and more advanced features. **Q: Does Session ID expire?** A: Session IDs don't expire; session files are permanently saved locally. However, very old sessions may affect performance due to large context size. **Q: Can sessions be shared across different projects?** A: No. Sessions are categorized and stored by project path, ensuring conversations from different projects don't get mixed. **Q: How to view all historical sessions?** A: Sessions are saved in `~/.snow/sessions/` directory, organized by project and date. You can browse using file manager, or use `snow --task-list` to view task sessions. **Q: What if Session ID is lost?** A: You can find the most recent session file in the session storage directory; the filename is the Session ID. Or use interactive mode's `/history` command to view historical sessions. **Q: Does headless mode support file uploads?** A: Supports file references via `@filepath` syntax, but doesn't support image uploads. For image analysis, use interactive mode. **Q: How to use different API configurations in headless mode?** A: Headless mode uses global configuration file (`~/.snow/profiles.json`). To switch configurations, first switch Profile in interactive mode, or edit the configuration file directly. **Q: How to remove ANSI color codes from output?** A: ```bash # Use sed to remove color codes snow --ask "your question" | sed 's/\x1b\[[0-9;]*m//g' # Or use other tools snow --ask "your question" | ansi2txt ``` **Q: Can output be redirected to file?** A: Yes, but will preserve ANSI color codes: ```bash snow --ask "your question" > output.txt # Save to file and display in terminal snow --ask "your question" | tee output.txt ``` ## Configuration File Locations Headless mode uses global configurations: - **API Configuration**: `~/.snow/profiles.json` - **Sensitive Commands**: `~/.snow/sensitive-commands.json` - **Session Storage**: `~/.snow/sessions///` For configuration methods, see: [First Time Configuration](./02.First%20Time%20Configuration.md) ## Related Features - [Command Injection Mode](./10.Command%20Injection%20Mode.md) - Embed real-time command execution in questions - [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Configure dangerous commands requiring confirmation - [Command Panel Guide](./09.Command%20Panel%20Guide.md) - Learn more features of interactive mode ## Example Scripts ### Complete Automation Example ```bash #!/bin/bash # Color definitions RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' NC='\033[0m' # No Color # Error handling set -e trap 'echo -e "${RED}Script execution failed${NC}"' ERR echo -e "${YELLOW}Starting automated code review...${NC}" # Get changed files changed_files=$(git diff --name-only HEAD^ | tr '\n' ' ') if [ -z "$changed_files" ]; then echo -e "${RED}No file changes detected${NC}" exit 0 fi echo -e "${GREEN}Detected changed files: $changed_files${NC}" # Initial review echo -e "${YELLOW}Performing initial code review...${NC}" output=$(snow --ask "Review changes in these files: $changed_files") # Extract Session ID session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) if [ -z "$session_id" ]; then echo -e "${RED}Unable to retrieve Session ID${NC}" exit 1 fi echo -e "${GREEN}Session ID: $session_id${NC}" # Detailed analysis echo -e "${YELLOW}Requesting security analysis...${NC}" snow --ask "Analyze these changes from security perspective" "$session_id" echo -e "${YELLOW}Requesting performance analysis...${NC}" snow --ask "Analyze these changes from performance perspective" "$session_id" echo -e "${GREEN}Code review completed!${NC}" ``` This script demonstrates how to: - Error handling and colored output - Session ID extraction and validation - Multiple rounds of continuous conversation - Automated workflow integration ================================================ FILE: docs/usage/en/13.Keyboard Shortcuts Guide.md ================================================ # Keyboard Shortcuts Guide This document lists all available keyboard shortcuts and features in SNOW AI CLI. ## Table of Contents - [Basic Editing](#basic-editing) - [Cursor Movement](#cursor-movement) - [Text Deletion](#text-deletion) - [Mode Switching](#mode-switching) - [Navigation and Selection](#navigation-and-selection) - [Clipboard Operations](#clipboard-operations) - [Command Execution Control](#command-execution-control) - [History and Rollback](#history-and-rollback) - [Panels and Pickers](#panels-and-pickers) ## Basic Editing | Shortcut | Function | Description | | ---------------------- | ---------------- | ----------------------------------------------------- | | `Enter` | Submit Message | Send the current input message to AI | | `Ctrl+Enter` | Insert Newline | Insert a new line in the input box without submitting | | `Ctrl+G` | External Editor | Open Notepad to edit current input (Windows only) | | `Backspace` / `Delete` | Delete Character | Delete the character before the cursor | ## Cursor Movement ### Readline Compatible Shortcuts | Shortcut | Function | Description | | -------------------- | ----------------- | ----------------------------------------------------------------- | | `Ctrl+A` | Beginning of Line | Move cursor to the start of current line | | `Ctrl+E` | End of Line | Move cursor to the end of current line | | `Alt+F` / `Option+F` | Forward One Word | Jump to the beginning of next word (supports CJK punctuation) | | `Alt+B` / `Option+B` | Backward One Word | Jump to the beginning of previous word (supports CJK punctuation) | | `↑` | History Up | Browse previous message in terminal-style history navigation | | `↓` | History Down | Browse next message in terminal-style history navigation | Note: Three detection methods for Option key on macOS: 1. `key.meta` property 2. Escape sequences `\x1bf` / `\x1bb` 3. Terminal.app default special characters `ƒ` / `∫` ## Text Deletion ### Readline Compatible Shortcuts | Shortcut | Function | Description | | -------- | --------------------------- | ----------------------------------------- | | `Ctrl+K` | Delete to End of Line | Delete from cursor to end of current line | | `Ctrl+U` | Delete to Beginning of Line | Delete from beginning of line to cursor | | `Ctrl+W` | Delete Previous Word | Delete the word before cursor | | `Ctrl+D` | Delete Character at Cursor | Delete the character at cursor position | ### Legacy Compatible Shortcuts (Preserved) | Shortcut | Function | Description | | -------- | ------------------ | ---------------------------------------- | | `Ctrl+L` | Clear to Beginning | Delete from beginning to cursor (legacy) | | `Ctrl+R` | Clear to End | Delete from cursor to end (legacy) | ## Mode Switching ### YOLO and Plan Modes | Shortcut | Function | Description | | ----------- | ----------- | ------------------------------------------------ | | `Shift+Tab` | Cycle Modes | Cycle through: YOLO → YOLO+Plan → Plan → All Off | | `Ctrl+Y` | Cycle Modes | Same as `Shift+Tab`, cycle through modes | Mode switching sequence: 1. YOLO Mode 2. YOLO + Plan Mode (automatically disables Vulnerability Hunting when enabling Plan) 3. Plan Mode 4. All Off ### Profile Configuration Switching | Shortcut | Function | Platform | | -------- | ---------------------- | --------------- | | `Ctrl+P` | Switch to Next Profile | macOS | | `Alt+P` | Switch to Next Profile | Windows / Linux | ## Navigation and Selection ### Universal Navigation (All Pickers) | Shortcut | Function | Scope | | -------- | ----------------- | ------------------------------------ | | `↑` | Previous Item | All pickers (circular: first → last) | | `↓` | Next Item | All pickers (circular: last → first) | | `Enter` | Confirm Selection | All pickers | | `ESC` | Close | All pickers and panels | ### File Picker Specific Shortcuts | Shortcut | Function | Description | | --------- | ------------------- | ------------------------------------------------ | | `@` | Trigger File Picker | File list appears automatically after typing `@` | | `Tab` | Select File | Select the currently highlighted file in picker | | Type text | Filter Files | Supports filename and content search | ### Command Panel Shortcuts | Shortcut | Function | Description | | --------- | --------------------- | ----------------------------------------------- | | `/` | Trigger Command Panel | Available command list appears after typing `/` | | `Tab` | Auto-complete | Replace input with selected command name | | Type text | Filter Commands | Fuzzy search by command name and description | ### Agent Picker | Shortcut | Function | Description | | ---------------------- | ----------------- | ---------------------------------------------- | | `/agent-` then `Enter` | Open Agent Picker | Select `agent-` command from command panel | | Type text | Auto-filter | Input automatically updates agent filter state | ### TODO Picker | Shortcut | Function | Description | | --------------------- | ----------------------- | ---------------------------------------------------------------- | | `/todo-` then `Enter` | Open TODO Picker | Select `todo-` command from command panel | | `Space` | Toggle Selection | Select/deselect current TODO item | | `Backspace` | Delete Search Character | Remove last character from search query | | Type text | Search Filter | Supports fuzzy search with multi-byte characters (Chinese, etc.) | ### Profile Picker | Shortcut | Function | Description | | ----------- | ----------------------- | ----------------------------------------------------- | | `Backspace` | Delete Search Character | Remove last character from search query | | Type text | Fuzzy Search | Filter profile list with multi-byte character support | ## Clipboard Operations | Shortcut | Function | Platform | | -------- | -------- | ------------------------------------------ | | `Ctrl+V` | Paste | macOS (supports text and images) | | `Alt+V` | Paste | Windows / Linux (supports text and images) | Note: Paste functionality supports: - Plain text - Images (auto-detection and image placeholder insertion) ## Command Execution Control ### Background Execution | Shortcut | Function | Description | | ---------- | ----------------------------- | -------------------------------------------------- | | `Ctrl+B` | Move command to background | Only available during command execution | | `/backend` | Open background process panel | View and manage all commands running in background | Background execution functionality notes: - When a long-running command occupies the foreground, use `Ctrl+B` to move it to background - Command continues executing in background without affecting your operations - Use `/backend` command to view all background processes - In background process panel: - `↑/↓` - Select process - `Enter` - Terminate selected running process - `ESC` - Close panel ## History and Rollback ### Double-ESC Rollback Menu | Shortcut | Function | Description | | ----------- | --------------------- | ------------------------------------------------------------------------ | | `ESC` `ESC` | Open Rollback Menu | Press ESC twice within 500ms | | `↑` / `↓` | Select Rollback Point | Navigate in history messages to select rollback position | | `Enter` | Confirm Rollback | Rollback to selected message point (shows confirmation if files changed) | | `ESC` | Close Rollback Menu | Exit rollback mode | Rollback functionality notes: - If the selected rollback point has file changes, system will show file rollback confirmation dialog - Supports selective rollback of partial files or full rollback - Supports cross-session rollback (from compressed session to original session) - After rollback, selected history message content will be restored to input box ### File Rollback Confirmation Dialog When rollback point contains file changes, a confirmation dialog appears with fine-grained control: | Shortcut | Function | Description | | --------- | --------------------- | --------------------------------------------------------------------------------------------- | | `Tab` | Toggle View Mode | Switch between compact mode and full file list mode | | `↑` / `↓` | Navigate | Compact mode: select rollback option; Full mode: navigate file list | | `Space` | Toggle File Selection | Full mode only: select/deselect currently highlighted file | | `Enter` | Confirm Action | Compact mode: confirm selected option; Full mode: confirm file selection and execute rollback | | `ESC` | Back/Cancel | Full mode: return to compact mode; Compact mode: cancel entire rollback operation | File selection mode: - All files are selected by default - Use `Space` to deselect files you don't want to rollback - Deselecting all files is equivalent to "conversation only" rollback - Partial selection will only rollback selected files - Full mode displays file selection status: `[x]` selected, `[ ]` unselected ### Terminal-style History Navigation | Shortcut | Function | Description | | -------- | ---------------- | --------------------------------------------- | | `↑` | Previous History | When input box is empty or no panels are open | | `↓` | Next History | Browse history records | ## Panels and Pickers ### Close Priority (ESC Key) When pressing `ESC` key, the system closes panels in the following priority order: 1. Profile Picker 2. TODO Picker 3. Agent Picker 4. File Picker 5. Command Panel 6. History Menu ### Special Commands | Command | Function | Description | | --------- | ----------------- | --------------------------------------- | | `/todo-` | Open TODO Picker | Select and manage TODO items in project | | `/agent-` | Open Agent Picker | Select sub-agent to execute tasks | ## Multi-byte Character Input Support The system fully supports multi-byte input methods: - All search and filter functions support multi-byte characters (Chinese, Japanese, Korean, etc.) - Word boundary detection supports CJK punctuation (`\p{P}` Unicode property) - Input method composition state is handled correctly to avoid triggering search for each letter ## Focus Event Filtering The system automatically filters terminal focus events to prevent interference characters: - Filters all possible focus events within 500ms after component mount - Automatically recognizes and filters `ESC[I` (focus in) and `ESC[O` (focus out) sequences - Supports focus events generated during drag-and-drop operations ## Tips - Most navigation supports circular mode (returns to beginning after reaching end) - Shortcut design follows Readline standards, familiar to bash/zsh users - macOS and Windows/Linux differ in some shortcuts (mainly Ctrl vs Alt/Meta) - All text input supports paste detection, can safely handle large text pastes ================================================ FILE: docs/usage/en/14.MCP Configuration.md ================================================ # Snow CLI User Documentation - MCP Configuration Welcome to Snow CLI! Agentic coding in your terminal. ## MCP Configuration MCP (Model Context Protocol) is an open protocol that allows AI assistants to integrate with external tools and services. Snow CLI supports configuring and managing MCP services. ### What is MCP MCP (Model Context Protocol) is a standardized protocol for connecting AI assistants with various external tools, data sources, and services. Through MCP, Snow CLI can access local file systems, connect to databases, call external APIs, and more. ### View MCP Service Status Enter the `/mcp` command in the chat interface to view the status of all MCP services: **Display Content**: - Service name - Connection status (green ● for connected, red ● for failed, gray ● for disabled) - Service type (System/External/Disabled) - Available tools list **Operations**: - **Up/Down arrows**: Navigate through service list - **Enter key**: Reconnect selected service - **Tab key**: Toggle enable/disable for external services (not supported for built-in services) - Select "Refresh all services" option to refresh all services ### Configure MCP Services #### 1. Enter Configuration Interface Select `MCP Configuration` from the main menu to enter the MCP configuration editor. #### 2. Automatic Editor Detection The system will automatically detect and use an appropriate text editor to open the configuration file: **Editor Priority**: 1. Editor specified by `VISUAL` environment variable 2. Editor specified by `EDITOR` environment variable 3. System default editor **Windows**: Detection order: notepad++ > notepad > code > vim > nano **macOS/Linux**: Detection order: nano > vim > vi **Set Default Editor**: macOS/Linux: ```bash export EDITOR=nano ``` Windows: ```cmd set EDITOR=notepad ``` #### 3. Configuration File Format Configuration file location: `~/.snow/mcp-config.json` **Configuration Structure**: ```json { "mcpServers": { "service-name": { "command": "command", "args": ["arg1", "arg2"], "enabled": true } } } ``` **Configuration Options**: - `mcpServers`: MCP service configuration object - `service-name`: Custom service name (unique identifier) - `type`: Transport type, optional values are `'stdio'`, `'local'`, or `'http'` (optional, auto-detected based on `url` or `command` by default) - `'stdio'`: Local subprocess communication (STDIO mode) - `'local'`: Alias for `'stdio'`, functionally identical - `'http'`: HTTP mode for connecting to remote MCP services - `command`: Command to start the MCP service (required for `stdio`/`local` type) - `args`: Command argument array (optional) - `url`: MCP service endpoint URL (required for `http` type) - `headers`: HTTP request headers configuration (optional for `http` type) - `enabled`: Whether to enable the service (optional, defaults to true) - `timeout`: Tool invocation timeout in milliseconds (optional, defaults to 300000, i.e., 5 minutes) - `env` / `environment`: Environment variables configuration (optional), `environment` is an alias for `env` **Configuration Example**: **STDIO/Local Mode Example**: ```json { "mcpServers": { "filesystem": { "type": "stdio", "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/path/to/files" ], "timeout": 600000 }, "github": { "type": "local", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "enabled": true, "environment": { "GITHUB_TOKEN": "your_token_here" } } } } ``` **HTTP Mode Example**: ```json { "mcpServers": { "remote-service": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_KEY}", "X-Custom-Header": "custom-value" }, "env": { "API_KEY": "your_api_key_here" }, "timeout": 300000 } } } ``` > **Note**: HTTP mode supports reading configuration values from environment variables using the `${VAR_NAME}` syntax. ### Configuration Validation After saving the configuration file, the system will automatically validate it: **Success Message**: ```text MCP configuration saved successfully ! Please use `snow` restart! ``` **Error Message**: ```text Invalid JSON format ``` ### Using MCP Services After configuration, restart Snow CLI for changes to take effect: ```bash snow ``` After startup, use the `/mcp` command to view service connection status. ### Manage MCP Services #### Enable/Disable Services **Method 1: Edit Configuration File** Set the `enabled` field to `false` to disable a service **Method 2: Use /mcp Command** 1. Enter `/mcp` to open the service panel 2. Use up/down arrows to select service 3. Press Tab key to toggle enable/disable status **Note**: Built-in services cannot be disabled #### Reconnect Services In the `/mcp` panel, select a service and press Enter to reconnect ### Troubleshooting #### 1. Editor Cannot Open **Error Message**: ```text No text editor found! Please set the EDITOR or VISUAL environment variable. ``` **Solution**: Set environment variable or install a text editor: macOS/Linux: ```bash export EDITOR=nano ``` Windows: ```cmd set EDITOR=notepad ``` #### 2. Service Connection Failed **Check Items**: 1. Is the command path correct 2. Are dependencies installed (e.g., Node.js for npx) 3. Is the parameter format correct 4. Use `/mcp` to view specific error messages #### 3. Configuration Not Taking Effect **Solution**: 1. Confirm configuration file is saved 2. Restart Snow CLI 3. Use `/mcp` to check service status ### Related Resources - MCP Official Documentation: - MCP Services Repository: - Command Guide: [Command Panel Guide](./09.Command%20Panel%20Guide.md) ================================================ FILE: docs/usage/en/15.Async Task Management.md ================================================ # Snow CLI User Guide - Async Task Management The async task feature allows you to run time-consuming AI tasks in the background while continuing to use your terminal for other work. Tasks run in independent processes and won't block your operations. ## What Are Async Tasks Async tasks are suitable for the following scenarios: - Long-running code analysis and refactoring - Batch file processing and conversion - Generating detailed project documentation - Executing complex multi-step operations You can create tasks to run in the background, check results later, or approve sensitive operations when needed. ## Creating Background Tasks Use the `--task` parameter in the terminal to create a background task: ```bash snow --task "Analyze project code and generate architecture documentation" ``` After execution, task information will be displayed and control returns immediately: ```text Task created: abc-123-def-456 Title: Analyze project code and generate architecture documentation Use "snow --task-list" to view task status ``` The task will run in an independent background process, allowing you to continue using the terminal for other work. ## Opening Task Manager There are two ways to open the task manager to view and manage background tasks: ### 1. Command Line Launch ```bash snow --task-list ``` ### 2. Welcome Menu After launching Snow CLI, select the "Task Manager" option from the main menu. ## Viewing Task List After entering the task manager, you'll see a list of all tasks. Each task displays: - Status icon and color - Task title (first 50 characters of the prompt) - Last update time - Message count ### Task Status - `○` Yellow - Pending: Task created but not yet started - `◐` Cyan - Running: Task is executing in the background - `⏸` Magenta - Paused: Sensitive command detected, waiting for your approval - `●` Green - Completed: Task executed successfully - `✗` Red - Failed: Task execution error ## Operation Shortcuts ### In Task List - `↑` `↓` - Navigate up/down - `Space` - Mark/unmark task (for batch deletion) - `Enter` - View task details - `D` - Delete task - Single delete: Select and press `D`, press `D` again to confirm - Batch delete: Mark multiple tasks with `Space`, press `D`, press `D` again to confirm - `R` - Refresh task list - `Esc` - Exit task manager ### In Task Details - `C` - Convert task to session for continued conversation - Press `C` once to show prompt - Press `C` again to confirm conversion - `A` - Approve sensitive command execution (only available when paused) - `R` - Reject sensitive command (only available when paused) - `Esc` - Return to task list ## Approving Sensitive Commands When a background task needs to execute dangerous operations (like deleting files, resetting code, etc.), it will automatically pause and wait for your approval. ### Approval Steps 1. See the pause icon `⏸` and magenta status in the task list 2. Press `Enter` to view task details 3. Check the specific command shown in the yellow warning box 4. Choose based on the situation: - Press `A` - Approve execution, task continues running - Press `R` - Reject execution ### Rejecting Commands with Reason 1. Press `R` on the paused task details page 2. Enter input mode, cursor displays as █ 3. Enter rejection reason, e.g., "Insufficient permissions, please execute manually" 4. Press `Enter` to submit 5. Press `Esc` to cancel input After rejection, the AI will receive your reason and adjust subsequent operations accordingly. ### Configuring Sensitive Commands You can customize which commands require approval. See [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md). ## Converting Tasks to Sessions Completed tasks can be converted to regular sessions, allowing you to continue conversing with the AI, ask for more details, or request modifications. ### Conversion Method 1. Select a task in the task list 2. Press `Enter` to view details 3. Press `C` key (confirmation prompt appears) 4. Press `C` again to confirm 5. Automatically jump to chat interface ### Notes - Original task will be deleted after conversion - All message history will be preserved in the new session - Incomplete tasks can also be converted, but with a warning prompt - Conversion operation cannot be undone ## Viewing Task Logs Each task has an independent log file that records detailed execution process. ### Log Location Task creation displays the log path: ```text Task abc-123-def-456 started in background (PID: 12345) Logs: /Users/username/.snow/task-logs/abc-123-def-456.log ``` ### Viewing Logs Use any text editor or command-line tool: ```bash # View logs in real-time tail -f ~/.snow/task-logs/abc-123-def-456.log # View complete log cat ~/.snow/task-logs/abc-123-def-456.log ``` Logs contain: - Task start and end times - All output information - Error information and stack traces - Execution process tracking ## Usage Scenarios ### Scenario 1: Long-Running Code Analysis ```bash # Create background task snow --task "Comprehensively analyze project code, generate architecture documentation and optimization suggestions" # Continue other work cd other-project git pull # Check results later snow --task-list ``` ### Scenario 2: Batch File Refactoring ```bash # Execute refactoring in background snow --task "Refactor all components in src/components, use TS strict mode uniformly" # Task will pause when detecting file deletion operations # Open task manager to approve ``` ### Scenario 3: Generate Reports and Continue Discussion ```bash # Create analysis task snow --task "Analyze Git commits from the last week, generate code quality report" # After task completes snow --task-list # Select task → Enter → C → C to convert to session # Then continue asking: "Which parts should be prioritized for optimization?" ``` ## FAQ ### Q: Task status stuck at "Running"? A: The task might be executing time-consuming operations. You can: - Check logs to understand current progress - Wait longer - If confirmed stuck, delete the task and recreate it ### Q: What to do if task failed? A: 1. Check logs to find the error cause 2. Verify if the prompt is reasonable 3. Confirm if system resources are sufficient 4. Modify and recreate the task ### Q: How to delete multiple tasks? A: 1. Use `Space` key to mark tasks to delete (shows marked count) 2. Press `D` key 3. Press `D` again to confirm batch deletion ### Q: Sensitive command not pausing? A: Check if the command pattern has been added in [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md). ### Q: How many tasks can run simultaneously? A: There's no theoretical limit, but each task consumes system resources. It's recommended to control the number based on machine performance. ## Practical Tips 1. **Clear Task Goals** - Provide clear and specific prompts when creating tasks, let the AI know what to do 2. **Regular Cleanup** - Delete unneeded completed tasks to keep the list clean 3. **Use Marking** - Batch mark unwanted tasks for one-time deletion 4. **Check Logs** - For long-running tasks, check logs to understand progress 5. **Convert to Session** - After important tasks complete, convert to session for easy follow-up queries and modifications ## Related Documentation - [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Configure commands requiring approval - [Headless Mode](./12.Headless%20Mode.md) - Another non-interactive execution mode - [Command Panel Guide](./09.Command%20Panel%20Guide.md) - Learn more management commands ================================================ FILE: docs/usage/en/16.Third-Party Relay Configuration.md ================================================ # Snow CLI User Guide - Third-Party Relay Configuration This document explains how to configure Snow CLI to access domestic Claude Code and Codex relay services. ## Configuration Overview Relay service providers implement interception measures for third-party clients. Therefore, you need to configure custom system prompts and request headers in Snow to disguise access. ## Claude Code Relay Configuration ### 1. Configure Custom System Prompt Open the system prompt configuration interface and enter the following content (**Note: Must be exact, no extra or missing characters**): ```text You are Claude Code, Anthropic's official CLI for Claude. ``` **Configuration Location:** 1. Launch Snow CLI 2. Select "System Prompt Configuration" on the welcome page ### 2. Configure Custom Request Headers Open the custom headers configuration interface and add the following JSON configuration: ```json { "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14", "Anthropic-Version": "2023-06-01", "Anthropic-Dangerous-Direct-Browser-Access": "true", "X-App": "cli", "X-Stainless-Helper-Method": "stream", "X-Stainless-Retry-Count": "0", "X-Stainless-Runtime-Version": "v24.3.0", "X-Stainless-Package-Version": "0.55.1", "X-Stainless-Runtime": "node", "X-Stainless-Lang": "js", "X-Stainless-Arch": "arm64", "X-Stainless-Os": "MacOS", "X-Stainless-Timeout": "60", "User-Agent": "claude-cli/1.0.83 (external, cli)", "Connection": "keep-alive", "Accept-Encoding": "gzip, deflate, br, zstd", "Accept": "text/event-stream" } ``` **Enable 1M context request header:** ```json { "Anthropic-Beta": "claude-code-20250219,context-1m-2025-08-07,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14", "Anthropic-Version": "2023-06-01", "Anthropic-Dangerous-Direct-Browser-Access": "true", "X-App": "cli", "X-Stainless-Helper-Method": "stream", "X-Stainless-Retry-Count": "0", "X-Stainless-Runtime-Version": "v24.3.0", "X-Stainless-Package-Version": "0.55.1", "X-Stainless-Runtime": "node", "X-Stainless-Lang": "js", "X-Stainless-Arch": "arm64", "X-Stainless-Os": "MacOS", "X-Stainless-Timeout": "60", "User-Agent": "claude-cli/1.0.83 (external, cli)", "Connection": "keep-alive", "Accept-Encoding": "gzip, deflate, br, zstd", "Accept": "text/event-stream" } ``` **Configuration Location:** 1. Launch Snow CLI 2. Select "Custom Headers Configuration" on the welcome page 3. Or directly edit the `~/.snow/custom-headers.json` file ### 3. Verify Configuration Restart Snow CLI after configuration. If you can chat normally, the configuration is successful. ## Codex Relay Configuration ### 1. Configure Custom System Prompt Codex relay generally does not require header configuration. Only replace the system prompt (**Note: Must be exact, no extra or missing characters**): ```markdown You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer. ## General - The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with ["bash", "-lc"]. - Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary. - When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.) ## Editing constraints - Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them. - Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare. - Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase). - You may be in a dirty git worktree. - NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user. - If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes. - If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them. - If the changes are in unrelated files, just ignore them and don't revert them. - While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed. - **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user. ## Plan tool When using the planning tool: - Skip using the planning tool for straightforward tasks (roughly the easiest 25%). - Do not make single-step plans. - When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan. ## Codex CLI harness, sandboxing, and approvals The Codex CLI harness supports several different configurations for sandboxing and escalation approvals that the user can choose from. Filesystem sandboxing defines which files can be read or written. The options for `sandbox_mode` are: - **read-only**: The sandbox only permits reading files. - **workspace-write**: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval. - **danger-full-access**: No filesystem sandboxing - all commands are permitted. Network sandboxing defines whether network can be accessed without approval. Options for `network_access` are: - **restricted**: Requires approval - **enabled**: No approval needed Approvals are your mechanism to get user consent to run shell commands without the sandbox. Possible configuration options for `approval_policy` are - **untrusted**: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands. - **on-failure**: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox. - **on-request**: Commands will be run in the sandbox by default, and you can specify in your tool call if you want to escalate a command to run without sandboxing. (Note that this mode is not always available. If it is, you'll see parameters for it in the `shell` command description.) - **never**: This is a non-interactive mode where you may NEVER ask the user for approval to run commands. Instead, you must always persist and work around constraints to solve the task for the user. You MUST do your utmost best to finish the task and validate your work before yielding. If this mode is paired with `danger-full-access`, take advantage of it to deliver the best outcome for the user. Further, in this mode, your default testing philosophy is overridden: Even if you don't see local patterns for testing, you may add tests and scripts to validate your work. Just remove them before yielding. When you are running with `approval_policy == on-request`, and sandboxing enabled, here are scenarios where you'll need to request approval: - You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var) - You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files. - You are running sandboxed and need to run a command that requires network access (e.g. installing packages) - If you run a command that is important to solving the user's query, but it fails because of sandboxing, rerun the command with approval. ALWAYS proceed to use the `with_escalated_permissions` and `justification` parameters - do not message the user before requesting approval for the command. - You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for - (for all of these, you should weigh alternative paths that do not require approval) When `sandbox_mode` is set to read-only, you'll need to request approval for any command that isn't a read. You will be told what filesystem sandboxing, network sandboxing, and approval mode are active in a developer or user message. If you are not told about this, assume that you are running with workspace-write, network sandboxing enabled, and approval on-failure. Although they introduce friction to the user because your work is paused until the user responds, you should leverage them when necessary to accomplish important work. If the completing the task requires escalated permissions, Do not let these settings or the sandbox deter you from attempting to accomplish the user's task unless it is set to "never", in which case never ask for approvals. When requesting approval to execute a command that will require escalated privileges: - Provide the `with_escalated_permissions` parameter with the boolean value true - Include a short, 1 sentence explanation for why you need to enable `with_escalated_permissions` in the justification parameter ## Special user requests - If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so. - If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps. ## Presenting your work and final message You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value. - Default: be very concise; friendly coding teammate tone. - Ask only when needed; suggest ideas; mirror the user's style. - For substantial work, summarize clearly; follow final-answer formatting. - Skip heavy formatting for simple confirmations. - Don't dump large files you've written; reference paths only. - No "save/copy this file" - User is on the same machine. - Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something. - For code changes: - Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in. - If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps. - When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number. - The user does not command execution outputs. When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines so the user understands the result. ### Final answer structure and style guidelines - Plain text; CLI handles styling. Use structure only when it helps scanability. - Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help. - Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent. - Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with \*\*. - Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible. - Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task. - Tone: collaborative, concise, factual; present tense, active voice; self-contained; no "above/below"; parallel wording. - Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers. - Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets. - File References: When referencing files in your response, make sure to include the relevant start line and always follow the below rules: - Use inline code to make file paths clickable. - Each reference should have a stand alone path. Even if it's the same file. - Accepted: absolute, workspace-relative, a/ or b/ diff prefixes, or bare filename/suffix. - Line/column (1-based, optional): :line[:column] or #Lline[Ccolumn] (column defaults to 1). - Do not use URIs like file://, vscode://, or https://. - Do not provide range of lines - Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5 ``` **Configuration Location:** Same as Claude Code - paste the complete content above in the system prompt configuration interface. ### 2. Verify Configuration Restart Snow CLI after configuration. If you can chat normally, the configuration is successful. ## Important Notes 1. **Exact Match**: System prompt must be completely identical, no extra or missing characters allowed 2. **Correct Format**: Custom headers must be valid JSON format 3. **Restart Required**: Snow CLI must be restarted after configuration changes to take effect 4. **Configuration File Locations**: - System Prompt: `~/.snow/system-prompt.txt` - Custom Headers: `~/.snow/custom-headers.json` ## FAQ ### Q: Still cannot access after configuration? A: Please check: 1. Is the system prompt completely identical (including punctuation)? 2. Is the custom headers JSON format correct? 3. Have you restarted Snow CLI? 4. Is the relay service API key configured correctly? ### Q: How to verify if configuration is effective? A: Enter the relay service's API endpoint and key in API configuration, then try to start a conversation. If it responds normally, the configuration is successful. ### Q: Can I configure multiple relay services simultaneously? A: Yes, you can switch between different configurations using the Profile feature. See [First Time Configuration](./02.First%20Time%20Configuration.md) for details. ### Q: Where are the configuration files? A: All configuration files are in the `.snow` folder in the user directory: - System Prompt: `~/.snow/system-prompt.txt` - Custom Headers: `~/.snow/custom-headers.json` You can directly edit these files. Restart Snow CLI after modification to take effect. ## Related Documentation - [First Time Configuration](./02.First%20Time%20Configuration.md) - API configuration and model selection - [Proxy and Browser Settings](./03.Proxy%20and%20Browser%20Settings.md) - Network proxy configuration ================================================ FILE: docs/usage/en/17.LSP Configuration.md ================================================ # Snow CLI User Guide - LSP Configuration and Usage Welcome to Snow CLI! Agentic coding in your terminal. ## What is LSP LSP (Language Server Protocol) is a standard protocol that enables a "language server" to provide capabilities to editors/tools, such as: - Go to Definition - Document Symbols / Outline - Hover - References - Completion ## How Snow CLI uses LSP Snow CLI will try to use LSP first for certain code-search capabilities. If LSP is unavailable or times out, it automatically falls back to regex/text-based search (so it won’t block usage). Currently, LSP mainly enhances these built-in tools: - `ace-search` (action=`find_definition`): prefers LSP "go to definition"; falls back to regex search on failure - `ace-search` (action=`file_outline`): prefers LSP `documentSymbol`; falls back to regex search on failure Notes: - LSP calls have an internal timeout (default: 3 seconds). Large projects or cold-starting language servers may exceed this timeout and trigger fallback. - Some servers (e.g., OmniSharp) strongly depend on accurate cursor position; it’s recommended to provide `contextFile + line + column` when calling tools (see below). ## Config file location and loading behavior LSP config file path: `~/.snow/lsp-config.json` Loading behavior: 1. When Snow CLI first needs LSP, it attempts to read `~/.snow/lsp-config.json`. 2. If the file does not exist, Snow CLI creates a default config file and uses the built-in default server list. 3. The config is cached in-process; restart Snow CLI after editing the file. ## Config file formats Two formats are supported: ### Format 1 (recommended): with schemaVersion ```json { "schemaVersion": 1, "servers": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"], "fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"], "installCommand": "npm install -g typescript-language-server typescript", "initializationOptions": {} } } } ``` ### Format 2 (compatible): servers mapping at the root ```json { "typescript": { "command": "typescript-language-server", "args": ["--stdio"], "fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"] } } ``` ## Configuration fields Each language server entry supports: - `command` (required): command used to start the language server (must be resolvable from PATH) - `args` (required): argument array - `fileExtensions` (required): file extensions used to match files to this language - `installCommand` (optional): an installation hint (Snow CLI will not run it automatically) - `initializationOptions` (optional): forwarded to the LSP `initialize` request as `initializationOptions` Important: - The config uses an "all-or-nothing" validation strategy: if any server entry is missing required fields or has incorrect types, the entire config is treated as invalid and Snow CLI falls back to defaults. - Language selection is based on file extensions (e.g., `.ts`, `.py`). Ensure your `fileExtensions` match your actual project files. ## Default built-in servers (written on first creation) Default language keys (you can add/remove/modify): - `typescript`: `typescript-language-server --stdio` - `python`: `pylsp` - `go`: `gopls` - `rust`: `rust-analyzer` - `java`: `jdtls` - `csharp`: `csharp-ls` Note: installation methods differ by platform. The main requirement is that `command` can be found from your terminal. ## Install and verify (Windows examples) On Windows, Snow CLI uses `where ` to check whether a language server is installed and available on PATH. You can verify manually: ```cmd where typescript-language-server where pylsp where gopls where rust-analyzer where jdtls where csharp-ls ``` Common installation examples: 1. TypeScript / JavaScript ```cmd npm install -g typescript-language-server typescript ``` 2. Python ```cmd python -m pip install python-lsp-server ``` 3. Go ```cmd go install golang.org/x/tools/gopls@latest ``` If you don’t want to install LSP for a language, remove its entry (or remove its extensions). Snow CLI will fall back to regex search. ## Using LSP via ACE tools ### 1) Go to definition: `ace-search` (action=`find_definition`) If you provide `contextFile`, Snow CLI will try LSP first; otherwise it uses regex search directly. It’s recommended to pass cursor position: - `line`: 0-indexed (first line is 0) - `column`: 0-indexed (first column is 0) Example: if your editor shows "Line 34, Column 7", you usually pass `line=33`, `column=6`. ### 2) File outline: `ace-search` (action=`file_outline`) For extracting symbols from a single file, Snow CLI tries LSP `documentSymbol` first and falls back to regex search. Tip: - For large files/projects, start with `ace-search` (action=`file_outline`) to get a high-level map, then drill down. ## FAQ ### 1. I edited the config but nothing changed - Make sure `~/.snow/lsp-config.json` is saved - Restart Snow CLI (config is cached) ### 2. It always falls back to regex search Common causes: - Language server not installed or not on PATH (verify with `where ` on Windows) - `fileExtensions` does not match your actual file suffixes - Language server startup is slow and hits the 3s timeout ### 3. Inaccurate jumps / wrong results - Provide `contextFile + line + column` when calling `ace-search` (action=`find_definition`) - If `symbolName` appears multiple times in the file and you don’t pass position, Snow CLI will try the first occurrence, which may be inaccurate ================================================ FILE: docs/usage/en/18.Skills Command Detailed Guide.md ================================================ # Snow CLI Usage Documentation - Skills Command Detailed Guide Skills is a powerful extension feature of Snow CLI that allows you to create and use specialized knowledge bases and toolkits. Each skill contains professional knowledge and practical tools in specific domains, which can be invoked in conversations through the `skill-execute` tool. ## Skills Overview The Skills feature of Snow CLI is fully compatible with **Claude Code Skills**. You can: - Create custom skills to encapsulate domain-specific knowledge and tools - Reuse common task patterns and best practices - Share skills across different projects - Restrict tool access permissions for skills - Create standardized development processes for teams ### Skill Types Skills are mainly divided into the following categories: - **Tool Skills**: Provide encapsulation and usage methods for specific tools (e.g., slack-gif-creator) - **Knowledge Skills**: Contain professional knowledge and best practices in specific domains - **Template Skills**: Provide reusable code, document, or configuration templates - **Workflow Skills**: Define standardized task execution processes ## Skill Structure Each skill is a directory containing the following standard structure: ``` skill-name/ ├── SKILL.md # Main document (required) ├── core/ # Core code modules │ ├── __init__.py │ ├── main.py # Main logic │ └── utils.py # Utility functions ├── templates/ # Template files │ ├── template1.md │ └── template2.txt ├── scripts/ # Auxiliary scripts │ ├── setup.sh │ └── process.py ├── requirements.txt # Dependency list └── LICENSE.txt # License file ``` ### SKILL.md Main Document The main document is the core of a skill, containing: - **YAML Front Matter**: Defines skill name, description, allowed tools, etc. - **Detailed Instructions**: Skill functionality, usage methods, API reference - **Code Examples**: Code snippets showing how to use the skill - **Best Practices**: Usage tips and precautions ````markdown --- name: skill-name description: Detailed description of the skill allowed-tools: tool1, tool2, tool3 license: Complete terms in LICENSE.txt --- # Skill Title ## Function Description Detailed explanation of the skill's functionality and purpose... ## Usage Methods ```python # Code examples ``` ## API Reference ### Function Name Description of the function's purpose and parameters... ## Best Practices Precautions and best practices when using the skill... ```` ## Skill Locations Skills can be stored in two locations: - **Global Location**: `~/.snow/skills/` - Available in all projects - Suitable for general, cross-project skills - **Project Location**: `.snow/skills/` - Only available in the current project - Suitable for project-specific skills **Priority**: Project-level skills override global skills with the same name ## Creating Skills Use the `/skills` command to create new skills: 1. Type `/skills` to open the skill creation dialog 2. Enter a skill name (lowercase letters, numbers, hyphens, max 64 characters) 3. Enter a skill description 4. Select storage location (global or project) 5. Confirm creation After creation, the system automatically generates: - SKILL.md (main document) - Necessary directory structure - Basic template files ## Using Skills ### Use `/skills-` to open the Skills picker (inject into the input) `/skills-` is a shortcut command (similar to `/agent-` and `/todo-`) that opens a picker panel. It lets you select an existing skill and inject its content into the current input box as an injection block, so you can include that skill prompt in your next message. How it differs from `/skills`: - `/skills`: creates a new skill template (generates the directory and `SKILL.md`, etc.). - `/skills-`: selects from existing skills and injects the skill content into the input (does not create files). How to open: - Type `/skills-` in the input and press Enter; or pick `skills-` from the command panel (Enter). Panel interactions (default behavior): - Up/Down: change selected skill (wrap-around). - Tab: toggle focus between the "search" field and the "append" field. - Enter: confirm selection and inject. - Esc: close the panel and return to input. What gets injected (full internal text): - An injection block starting with `# Skill: ` and ending with `# Skill End`. - In the input UI it is rendered as a placeholder: `[Skill:] ` (note the trailing space so you can continue typing). - When you send the message, the full injection block is sent (not just the placeholder). How "append" works: - If the skill markdown contains the `$ARGUMENTS` placeholder, it will be replaced with the append text. - If `$ARGUMENTS` is not present, a `[User Append]` block will be appended (only when append is non-empty). Notes: - The injected end marker `# Skill End` must end with a newline. Otherwise, if you keep typing after the placeholder, it may get glued to the end marker and cause display masking to collapse unintended text. - Skill sources are `.snow/skills/` (project) and `~/.snow/skills/` (global). When IDs collide, project skills take priority. ### Invoking in Conversations (direct tool invocation) Use the `skill-execute` tool to invoke skills: ``` skill: "skill-name" ``` After invocation, you will see: ``` The "skill-name" skill is loading ``` Subsequently, the skill content will expand, providing detailed guidance and usage instructions. ### Usage Examples #### slack-gif-creator Skill Example This is a complete skill example for creating animated GIFs suitable for Slack: ```python # Load the skill skill: "slack-gif-creator" # The skill will provide detailed usage guidance, including: # - Slack's GIF requirements (dimensions, framerate, colors, etc.) # - How to use the GIFBuilder tool class # - Animation effect implementation (shake, pulse, bounce, etc.) # - Optimization techniques # For example, creating an animated GIF from core.gif_builder import GIFBuilder from PIL import Image, ImageDraw # Create builder builder = GIFBuilder(width=128, height=128, fps=10) # Generate frames for i in range(12): frame = Image.new('RGB', (128, 128), (240, 248, 255)) draw = ImageDraw.Draw(frame) # Draw animation # ... drawing code ... builder.add_frame(frame) # Save optimized GIF builder.save('output.gif', num_colors=48, optimize_for_emoji=True) ``` ## Skill Management ### Listing Available Skills All available skills are listed in the `skill-execute` tool description, including: - Skill name - Skill description - Skill location (global/project) ### Deleting Skills Delete custom skills using the `-d` parameter: - **Delete global skill**: `/skill-name -d` (execute in non-project directory) - **Delete project skill**: `/skill-name -d` (execute in project directory) The system automatically identifies the skill location and deletes the corresponding files. ### Skill Restrictions You can restrict tool access for skills through the `allowed-tools` field: ```yaml --- name: restricted-skill description: Skill with restricted tool access allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` This ensures that skills can only use specified safe tools, improving system security. ## Skill Development Best Practices ### 1. Documentation Writing - Use clear structure and headings - Provide rich code examples - Include common problems and solutions - Explain dependencies and environment requirements ### 2. Code Organization - Put core logic in `core/` directory - Use modular design - Provide clear APIs - Add appropriate error handling ### 3. Templates and Scripts - Provide common templates in `templates/` directory - Provide auxiliary scripts in `scripts/` directory - Ensure scripts have executable permissions - Provide usage instructions ### 4. Tool Restrictions - Only allow necessary tools - Avoid high-risk operations - Use tool restrictions to improve security - Document restriction reasons ### 5. Version Control - Add version information to skills - Record change logs - Use semantic versioning - Maintain backward compatibility ## Common Skill Examples ### 1. Code Generation Skill ```markdown --- name: code-generator description: Code generation templates and best practices allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` Provides common code generation templates and patterns. ### 2. Document Template Skill ```markdown --- name: doc-templates description: Collection of document and comment templates allowed-tools: filesystem-read, filesystem-edit --- ``` Provides templates for README, API documentation, comments, etc. ### 3. Test Case Skill ```markdown --- name: test-templates description: Test case templates and testing tools allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` Provides templates for unit tests, integration tests, etc. ### 4. Deployment Script Skill ```markdown --- name: deploy-scripts description: Automated deployment scripts and processes allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` Provides CI/CD deployment scripts and best practices. ## Compatibility with Claude Code Skills The Skills feature of Snow CLI is fully compatible with Claude Code Skills: - **Same Invocation Method**: Use `skill: "skill-name"` to invoke - **Same Structure Requirements**: SKILL.md as main document - **Same Metadata Format**: YAML front matter - **Same Tool Restrictions**: Supports allowed-tools field - **Fully Compatible Ecosystem**: Can directly use existing Claude Code Skills This means you can directly use in Snow CLI: - Official Claude Code Skills provided by Anthropic - Community-created compatible skills - Your own created Snow CLI skills ## Skill Security ### Tool Permission Control Strongly recommend specifying allowed tool list for each skill: ```yaml --- name: safe-skill description: Example of safe skill allowed-tools: filesystem-read, filesystem-edit --- ``` ### Sensitive Operations Avoid including in skills: - Direct system calls - Sensitive information (keys, passwords, etc.) - Destructive operations (deletion, formatting, etc.) ### Code Review Regularly review skill code: - Check for security vulnerabilities - Verify tool usage - Update dependency versions - Remove deprecated functionality ## Troubleshooting ### Skill Not Found **Symptom**: "Skill not found" error when invoking skill **Solutions**: 1. Check skill name spelling 2. Confirm skill is correctly installed 3. Verify skill location (global/project) 4. Check if SKILL.md file exists ### Tool Permission Error **Symptom**: Insufficient tool permissions when running skill **Solutions**: 1. Check allowed-tools configuration 2. Verify tool name spelling 3. Add necessary tools in permission management 4. Contact administrator to grant permissions ### Missing Dependencies **Symptom**: Module not found error when running skill **Solutions**: 1. Check requirements.txt 2. Install missing dependencies: `pip install -r requirements.txt` 3. Verify Python environment 4. Check virtual environment activation status ### Syntax Errors **Symptom**: Syntax errors in skill document or code **Solutions**: 1. Check YAML front matter format 2. Verify Markdown syntax 3. Check code syntax 4. Use code formatting tools ## Related Configuration - [Command Panel Guide](./09.Command%20Panel%20Guide.md) - Basic command introduction - [MCP Configuration](./14.MCP%20Configuration.md) - MCP service configuration - [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Security tool configuration - [Sub-Agent Configuration](./05.Sub-Agent%20Configuration.md) - Sub-agent tool configuration ## Advanced Usage ### Skill Combination You can combine multiple skills: ```python # First invoke code generation skill skill: "code-generator" # Then invoke test template skill skill: "test-templates" # Finally invoke deployment script skill skill: "deploy-scripts" ``` ### Dynamic Skills Skills support dynamic loading, taking effect immediately after modification: 1. Edit skill files 2. Save changes 3. Reinvoke skill No need to restart the application. ### Skill Debugging Use the following methods to debug skills: 1. Check skill directory structure 2. Verify SKILL.md format 3. Test core code modules 4. View error logs ## Community and Sharing ### Skill Sharing You can share your skills with the community: 1. Ensure code quality and complete documentation 2. Add appropriate license 3. Create usage examples 4. Publish to skill repository ### Skill Discovery Ways to find useful skills: 1. Check official skill list 2. Search community skill library 3. Ask other users for recommendations 4. Customize based on project needs ## Summary The Skills feature of Snow CLI is a powerful extension system that allows you to: - **Encapsulate Professional Knowledge**: Package domain knowledge into reusable skills - **Standardize Processes**: Establish unified development processes for teams - **Improve Efficiency**: Reduce repetitive work and focus on innovation - **Ensure Quality**: Use validated best practices - **Promote Collaboration**: Share experiences and skills among team members By using Skills reasonably, you can significantly improve development efficiency and code quality, while establishing more standardized and efficient development processes. ================================================ FILE: docs/usage/en/19.Startup Parameters Guide.md ================================================ # Snow CLI User Documentation - Startup Parameters Guide Welcome to Snow CLI! Agentic coding in your terminal. ## Startup Parameters Guide ### Basic Commands #### 1. Default Launch ```bash snow ``` Launch Snow CLI interactive interface and display the welcome screen. #### 2. Show Version ```bash snow --version # or snow -v ``` Display the currently installed Snow CLI version number. #### 3. Show Help ```bash snow --help # or snow -h ``` Display all available command-line parameters and usage instructions. #### 4. Update to Latest Version ```bash snow --update ``` Automatically update Snow CLI to the latest version. ### Quick Start Modes #### 1. Skip Welcome and Resume Session ```bash snow -c ``` Skip the welcome screen and automatically resume the most recent conversation session. Ideal for quickly continuing previous work. #### 2. YOLO Mode (Auto-approve All Tool Calls) ```bash snow --yolo ``` Skip the welcome screen, start a blank conversation, and enable YOLO mode. In this mode, all tool calls are automatically approved and executed without manual confirmation. **Warning:** YOLO mode will automatically execute all commands. Use with caution! #### 3. YOLO + Plan Mode (YOLO+Plan) ```bash snow --yolo-p ``` Skip the welcome screen, start a blank conversation, enable YOLO mode, and force-enable “Plan Mode”. This is useful when you want auto-execution while still requiring the model to produce a plan before acting. **Warning:** This mode also auto-executes all commands. Use with caution! #### 4. Combined Mode: Resume Session + YOLO ```bash snow --c-yolo ``` Skip the welcome screen, resume the most recent conversation session, and enable YOLO mode. Combines the convenience of session resumption and auto-approval. ### Headless Mode #### 1. Quick Question Mode ```bash snow --ask "your question" ``` Send a single prompt in headless mode, AI responds and exits automatically. Ideal for quick answers or script integration. **Example:** ```bash snow --ask "How to use Promise in JavaScript?" ``` #### 2. Continue Conversation ```bash snow --ask "follow-up question" ``` Continue conversation in a specified session. sessionId is the identifier from a previous session. **Example:** ```bash snow --ask "Can you explain that in more detail?" abc123def ``` ### Async Task Management #### 1. Create Background Task ```bash snow --task "task description" ``` Create a background AI task that executes in the background without blocking the current terminal. **Example:** ```bash snow --task "Refactor error handling logic in auth.ts file" ``` After execution, it displays: - Task ID - Task title - Instructions to view task status #### 2. View Task List ```bash snow --task-list ``` Open task manager interface to view and manage all background tasks, including: - View task status (running, completed, failed) - Approve sensitive commands - Convert tasks to sessions - Delete tasks ### Developer Mode #### Enable Developer Mode ```bash snow --dev ``` Enable developer mode with persistent userId for testing. Use during development and debugging to maintain consistent user identification. On startup, it displays: ``` Developer mode enabled Using persistent userId: Stored in: ~/.snow/dev-user-id ``` ## Parameter Combination Examples ### Common Combinations 1. **Quick resume previous work:** ```bash snow -c ``` 2. **Automated task execution:** ```bash snow --yolo ``` 3. **Automated execution (force plan mode):** ```bash snow --yolo-p ``` 4. **Quick Q&A and exit:** ```bash snow --ask "How to use TypeScript generics?" ``` 5. **Execute complex tasks in background:** ```bash snow --task "Analyze and optimize performance bottlenecks across the entire project" ``` 6. **Continue previous conversation with auto-execution:** ```bash snow --c-yolo ``` 7. **Quick version and help check:** Use `--version` or `--help` for quick information retrieval. These commands execute rapidly without loading animations. 8. **Script integration:** Use the `--ask` parameter to integrate Snow CLI into automation scripts. 9. **Background tasks:** For time-consuming tasks, use `--task` to create background tasks and continue using the terminal for other work. 10. **Session management:** Use the sessionId parameter with `--ask` for multi-turn conversations, suitable for context-dependent questions. 11. **Safe YOLO usage:** While YOLO mode is convenient, it auto-executes all commands. Recommended only in trusted environments and for well-defined tasks. ## Important Notes 1. **YOLO mode risks:** `--yolo` and `--c-yolo` automatically approve all tool calls, including file modifications and command executions. Make sure you understand the operations to be performed. 2. **Background tasks:** Tasks created with `--task` run in a new process. Even if you close the terminal, the task continues executing. 3. **Developer mode:** `--dev` mode uses persistent userId, intended for development and testing environments only. 4. **Headless mode limitations:** In `--ask` mode, the program exits immediately after AI response, and does not support interactive operations. ## Related Documentation - [Headless Mode Detailed Guide](./12.Headless%20Mode.md) - [Async Task Management](./15.Async%20Task%20Management.md) - [Keyboard Shortcuts Guide](./13.Keyboard%20Shortcuts%20Guide.md) ================================================ FILE: docs/usage/en/20.SSE Service Mode.md ================================================ # Snow CLI Usage Documentation - SSE Service Mode Welcome to Snow CLI! Agentic coding in your terminal. ## Quick Start Want to quickly experience the SSE client? We provide a complete browser test client: **Location**: `source/test/sse-client/index.html` Simply open this file in your browser and connect to the SSE server to start testing. ## What is SSE Service Mode SSE (Server-Sent Events) service mode allows you to run Snow CLI as a backend service, providing AI capabilities to external applications. It is perfect for: - Web application integration - Mobile app backend - Third-party tool integration - Microservice architecture - Custom chat interfaces ## Basic Usage ### Starting SSE Server #### Basic Startup ```bash # Use default port 3000 (foreground) snow --sse # Specify port snow --sse --sse-port 8080 # Specify working directory snow --sse --work-dir /path/to/project # Custom interaction timeout (default 300000ms, i.e., 5 minutes) snow --sse --sse-timeout 600000 # Set to 10 minutes # Combined usage snow --sse --sse-port 8080 --work-dir /path/to/project --sse-timeout 600000 ``` #### Background Daemon Mode If you don't want to occupy the terminal, you can run the server as a background daemon: ```bash # Start background daemon (default port 3000) snow --sse-daemon # Specify different ports (supports multiple instances) snow --sse-daemon --sse-port 3000 snow --sse-daemon --sse-port 8080 snow --sse-daemon --sse-port 9000 # Specify full parameters snow --sse-daemon --sse-port 8080 --work-dir /path/to/project --sse-timeout 600000 # Check all daemon status snow --sse-status # Stop daemon (three methods) snow --sse-stop # Stop default port 3000 daemon snow --sse-stop --sse-port 8080 # Stop by port number snow --sse-stop 12345 # Stop by PID ``` Daemon features: - Supports multiple instances (different ports) - Runs in background, doesn't occupy terminal - Individual log file per port: `~/.snow/sse-logs/port-.log` - Individual PID file per port: `~/.snow/sse-daemons/port-.pid` - Supports stop by port or PID - Status check shows all running daemons #### Enabling YOLO Mode on Startup While the SSE server itself doesn't use the `--yolo` parameter, you can achieve similar functionality through the following methods: **Method 1: Client message with yoloMode** This is the recommended approach, allowing flexible control over whether each request uses YOLO mode: ```javascript // Specify YOLO mode when sending message await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'chat', content: 'Your question', yoloMode: true, // Enable YOLO mode }), }); ``` **Method 2: Configure auto-approval list** Add commonly used tools to the project's permission configuration file for default auto-approval: ```bash # Edit project permission configuration vi .snow/permissions.json ``` ```json { "alwaysApprovedTools": [ "filesystem-read", "filesystem-edit", "filesystem-create", "codebase-search", "ace-search", "notebook-add" ] } ``` This way, tools in the list will be automatically approved without requiring confirmation each time. **Notes**: - SSE server startup doesn't support `--yolo` parameter - YOLO mode needs to be enabled via client message's `yoloMode` field - Or implement tool auto-approval via `.snow/permissions.json` configuration - Sensitive commands require confirmation even in YOLO mode ### Server Information After startup, the terminal will display a beautiful server status interface: ``` ✓ SSE server started Port: 3000 | Working Directory: /Users/xxx/project | ● Running Available Endpoints: http://localhost:3000/events POST http://localhost:3000/message POST http://localhost:3000/session/create POST http://localhost:3000/session/load GET http://localhost:3000/session/list GET http://localhost:3000/session/rollback-points?sessionId={sessionId} DELETE http://localhost:3000/session/{sessionId} GET http://localhost:3000/health Running Logs: [14:30:45] SSE service started on port 3000 [14:30:50] Created new session: abc-123 Press Ctrl+C to stop server ``` ## API Endpoints ### 1. SSE Event Stream Connection **Endpoint**: `GET /events` Establish SSE connection to receive real-time event stream. #### JavaScript Example ```javascript const eventSource = new EventSource('http://localhost:3000/events'); eventSource.onmessage = event => { const data = JSON.parse(event.data); console.log('Received event:', data); switch (data.type) { case 'connected': console.log( 'Connection successful, connection ID:', data.data.connectionId, ); break; case 'message': if (data.data.streaming) { console.log('AI is responding:', data.data.content); } else if (data.data.role === 'user') { console.log('User message:', data.data.content); } break; case 'tool_confirmation_request': // User confirmation needed for tool execution handleToolConfirmation(data); break; case 'complete': console.log('Conversation complete'); break; } }; ``` ### 2. Send Message **Endpoint**: `POST /message` **Content-Type**: `application/json` #### Send Plain Text Message ```javascript async function sendMessage(content) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content, }), }); return await response.json(); } // Usage example await sendMessage('Help me create a React component'); ``` #### Continuous Conversation with Session ```javascript async function continueConversation(content, sessionId) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content, sessionId: sessionId, // Use session ID to continue conversation }), }); return await response.json(); } // Session ID will be returned in complete event eventSource.onmessage = event => { const data = JSON.parse(event.data); if (data.type === 'complete') { const sessionId = data.data.sessionId; console.log('Session ID:', sessionId); } }; ``` #### Send Image Message ```javascript async function sendImageMessage(content, imageFile) { // Convert image to Base64 Data URI const reader = new FileReader(); const imageData = await new Promise((resolve, reject) => { reader.onload = e => resolve(e.target.result); reader.onerror = reject; reader.readAsDataURL(imageFile); }); const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content || 'Please analyze this image', images: [ { data: imageData, // Complete data URI, e.g., data:image/png;base64,iVBORw0KG... mimeType: imageFile.type, // e.g., image/png, image/jpeg }, ], }), }); return await response.json(); } // Usage example const fileInput = document.querySelector('input[type="file"]'); fileInput.addEventListener('change', async e => { const file = e.target.files[0]; if (file && file.type.startsWith('image/')) { await sendImageMessage('What is this?', file); } }); ``` #### Abort Running Task ```javascript async function abortTask(sessionId) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'abort', sessionId: sessionId, }), }); return await response.json(); } // Listen for abort confirmation eventSource.onmessage = event => { const data = JSON.parse(event.data); if (data.type === 'complete' && data.data.cancelled) { console.log('Task has been aborted by user'); } }; ``` #### Enable YOLO Mode ```javascript async function sendWithYolo(content) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content, yoloMode: true, // Auto-approve all non-sensitive tools }), }); return await response.json(); } ``` ### 3. Session Management #### Create New Session **Endpoint**: `POST /session/create` **Content-Type**: `application/json` Create a new conversation session, returns session information and automatically binds to current connection. ```javascript async function createSession() { const response = await fetch('http://localhost:3000/session/create', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ connectionId: 'conn_xxx', // Optional, specify connection ID }), }); const data = await response.json(); console.log('Session ID:', data.session.id); console.log('Created at:', data.session.createdAt); return data.session; } ``` #### Load Existing Session **Endpoint**: `POST /session/load` **Content-Type**: `application/json` Load a saved session to restore conversation context. ```javascript async function loadSession(sessionId) { const response = await fetch('http://localhost:3000/session/load', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ sessionId: sessionId, connectionId: 'conn_xxx', // Optional, specify connection ID }), }); const data = await response.json(); if (data.success) { console.log('Session loaded:', data.session.id); console.log('Message count:', data.session.messages.length); return data.session; } else { console.error('Load failed:', data.error); } } ``` #### Get Session List **Endpoint**: `GET /session/list` **Query Parameters**: - `page`: Page number, starting from 0 (optional, default 0) - `pageSize`: Items per page (optional, default 20, max 200) - `q`: Search keyword (optional, searches message content in sessions) Get all saved sessions with pagination and search support. ```javascript async function listSessions(page = 0, pageSize = 20, searchQuery = '') { const params = new URLSearchParams({ page: page.toString(), pageSize: pageSize.toString(), }); if (searchQuery) { params.append('q', searchQuery); } const response = await fetch(`http://localhost:3000/session/list?${params}`); const data = await response.json(); console.log('Total sessions:', data.total); console.log('Current page:', data.page); console.log('Page size:', data.pageSize); console.log('Session list:', data.sessions); // Session list example // data.sessions = [ // { // id: 'abc-123', // createdAt: '2025-12-30T10:00:00.000Z', // updatedAt: '2025-12-30T10:30:00.000Z', // messageCount: 10, // firstMessage: 'Help me create a function' // }, // ... // ] return data; } ``` #### Get Rollback Points **Endpoint**: `GET /session/rollback-points` **Query Parameters**: - `sessionId`: Session ID (required) Returns a list of user messages in the specified session that can be used as rollback points (demo use). ```javascript async function getRollbackPoints(sessionId) { const params = new URLSearchParams({sessionId}); const response = await fetch( `http://localhost:3000/session/rollback-points?${params.toString()}`, ); const data = await response.json(); // Example (key fields): // { // success: true, // sessionId: 'abc-123', // points: [ // { // messageIndex: 0, // role: 'user', // timestamp: 1730000000000, // summary: '...', // hasSnapshot: true, // snapshot: {timestamp: 1730000000000, fileCount: 12}, // filesToRollbackCount: 5 // } // ] // } return data; } ``` #### Delete Session **Endpoint**: `DELETE /session/{sessionId}` Delete the specified session and all its data. ```javascript async function deleteSession(sessionId) { const response = await fetch(`http://localhost:3000/session/${sessionId}`, { method: 'DELETE', }); const data = await response.json(); if (data.success) { console.log('Session deleted:', data.deleted); } return data; } ``` ### 4. Health Check **Endpoint**: `GET /health` Check server status and current connection count. ```javascript async function checkHealth() { const response = await fetch('http://localhost:3000/health'); const data = await response.json(); console.log('Status:', data.status); console.log('Connections:', data.connections); } ``` ## Event Type Descriptions ### connected Connection successful event. ```javascript { type: 'connected', data: { connectionId: 'conn_1234567890' }, timestamp: '2025-12-30T15:30:00.000Z' } ``` ### message Message event (user or AI). ```javascript // User message { type: 'message', data: { role: 'user', content: 'Help me create a function' } } // AI streaming response { type: 'message', data: { role: 'assistant', content: 'Sure, let me help you...', streaming: true } } // AI final response { type: 'message', data: { role: 'assistant', content: 'Complete response content', streaming: false } } ``` ### tool_call Tool invocation event. ```javascript { type: 'tool_call', data: { name: 'filesystem-create', arguments: { filePath: 'example.js', content: '...' } } } ``` ### tool_confirmation_request Request confirmation for tool execution. ```javascript { type: 'tool_confirmation_request', data: { toolCall: { function: { name: 'terminal-execute', arguments: '{"command":"rm -rf node_modules"}' } }, isSensitive: true, // Whether it's a sensitive command sensitiveInfo: { pattern: 'rm -rf', description: 'Delete files or directories' }, availableOptions: [ {value: 'approve', label: 'Approve once'}, {value: 'approve_always', label: 'Always approve'}, // Only for non-sensitive commands {value: 'reject_with_reply', label: 'Reject with reply'}, {value: 'reject', label: 'Reject and end session'} ] }, requestId: 'req_1234567890' } ``` ### tool_result Tool execution result. ```javascript { type: 'tool_result', data: { content: 'Execution successful', status: 'success' } } ``` ### user_question_request AI asking user a question. ```javascript { type: 'user_question_request', data: { question: 'Please select an option', options: ['Option 1', 'Option 2', 'Option 3'], multiSelect: false }, requestId: 'req_1234567890' } ``` ### usage Token usage information. ```javascript { type: 'usage', data: { input_tokens: 150, output_tokens: 200 } } ``` ### error Error message. ```javascript { type: 'error', data: { message: 'Error description', stack: 'Error stack (optional)' } } ``` ### complete Conversation completed. ```javascript { type: 'complete', data: { usage: { input_tokens: 150, output_tokens: 200 }, tokenCount: 350, sessionId: 'abc-123-def-456', // Session ID cancelled: false // Whether cancelled by user (optional) } } ``` ### abort Task abort request (sent by client). ```javascript // Client sends abort request await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'abort', sessionId: 'abc-123-def-456' }) }); // Server responds with abort confirmation { type: 'message', data: { role: 'assistant', content: 'Task has been aborted' }, timestamp: '2025-12-30T15:30:00.000Z' } // Followed by complete event { type: 'complete', data: { usage: {input_tokens: 0, output_tokens: 0}, tokenCount: 0, sessionId: 'abc-123-def-456', cancelled: true } } ``` ## Tool Confirmation Flow ### Confirmation Request Response When receiving a `tool_confirmation_request` event, send a confirmation response: ```javascript async function handleToolConfirmation(event) { const toolCall = event.data.toolCall; const options = event.data.availableOptions; // Display tool information to user console.log('Tool:', toolCall.function.name); console.log('Arguments:', toolCall.function.arguments); console.log('Available options:', options); // Send response after user selection const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'tool_confirmation_response', requestId: event.requestId, response: 'approve', // or 'approve_always', 'reject', {type: 'reject_with_reply', reason: '...'} }), }); return await response.json(); } ``` ### Confirmation Options Explained | Option | Value | Description | Applicable Scenario | | ----------------- | -------------------------------------------- | ------------------------------------- | ------------------- | | Approve once | `'approve'` | Approve this execution only | All tools | | Always approve | `'approve_always'` | Approve and add to auto-approval list | Non-sensitive only | | Reject with reply | `{type: 'reject_with_reply', reason: '...'}` | Reject and tell AI the reason | All tools | | Reject and end | `'reject'` | Reject and end session | All tools | ### Sensitive Command Detection The system automatically detects sensitive commands (like `rm -rf`, `sudo`, etc.). Sensitive commands: - Will not show "Always approve" option - Require confirmation even in YOLO mode - Display warning information and matched command pattern For sensitive command configuration, refer to: [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) ## User Question Response When receiving a `user_question_request` event: ```javascript async function handleUserQuestion(event) { const question = event.data.question; const options = event.data.options; const multiSelect = event.data.multiSelect; // Display question and options to user console.log('Question:', question); console.log('Options:', options); // Send response after user selection const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'user_question_response', requestId: event.requestId, response: { selected: multiSelect ? ['Option 1', 'Option 2'] : 'Option 1', customInput: '', // Optional custom input }, }), }); return await response.json(); } ``` ## Permission Configuration ### Auto-Approval List SSE server automatically reads permission configuration file from project root directory: **Location**: `.snow/permissions.json` ```json { "alwaysApprovedTools": [ "filesystem-read", "codebase-search", "filesystem-edit", "notebook-add", "filesystem-create" ] } ``` ### Permission Inheritance Rules 1. **Project-level Configuration**: Server reads `.snow/permissions.json` from working directory on startup 2. **Auto-approval**: Tools in the list are executed automatically without user confirmation 3. **Sensitive Commands Priority**: Sensitive commands require confirmation even if in auto-approval list 4. **Dynamic Updates**: When user selects "Always approve", the tool is automatically added to configuration file ### Configuration Example ```json { "alwaysApprovedTools": [ "filesystem-read", // Read files "filesystem-edit", // Hashline edit "filesystem-create", // Create files "codebase-search", // Code search "ace-search", // Unified ACE code search (semantic_search / find_definition / find_references / file_outline / text_search via action) "notebook-add" // Add note ] } ``` ## YOLO Mode ### Enable YOLO Mode Carry `yoloMode` parameter when sending message: ```javascript const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'chat', content: 'Your question', yoloMode: true, // Enable YOLO mode }), }); ``` ### YOLO Mode Features - **Auto-approval**: Non-sensitive commands execute automatically - **Sensitive Command Exception**: Sensitive commands still require confirmation - **Fast Response**: Reduce interaction waiting time - **Suitable for Automation**: Script and automation scenarios ### Security Considerations Even with YOLO mode enabled: 1. Sensitive commands still require confirmation 2. Tools not in permission list require first-time confirmation 3. Can abort execution at any time through rejection ## Complete Examples ### JavaScript Client ```javascript class SnowAIClient { constructor(baseUrl = 'http://localhost:3000') { this.baseUrl = baseUrl; this.eventSource = null; this.sessionId = null; } // Connect to SSE server connect() { return new Promise((resolve, reject) => { this.eventSource = new EventSource(`${this.baseUrl}/events`); this.eventSource.onopen = () => { console.log('Connected to Snow AI'); resolve(); }; this.eventSource.onerror = error => { console.error('Connection error:', error); reject(error); }; this.eventSource.onmessage = event => { this.handleEvent(JSON.parse(event.data)); }; }); } // Handle events handleEvent(event) { console.log('[Event]', event.type); switch (event.type) { case 'tool_confirmation_request': this.handleToolConfirmation(event); break; case 'user_question_request': this.handleUserQuestion(event); break; case 'message': if (event.data.streaming) { process.stdout.write(event.data.content); } break; case 'complete': this.sessionId = event.data.sessionId; console.log('\nConversation complete, Session ID:', this.sessionId); break; } } // Handle tool confirmation async handleToolConfirmation(event) { const options = event.data.availableOptions; // Custom confirmation logic can be implemented here // Example: Auto-approve non-sensitive commands const decision = event.data.isSensitive ? 'reject' : 'approve'; await this.sendToolConfirmation(event.requestId, decision); } // Handle user question async handleUserQuestion(event) { // Custom selection logic can be implemented here const selected = event.data.options[0]; await this.sendUserQuestionResponse(event.requestId, { selected: selected, }); } // Send message async sendMessage(content, yoloMode = false) { const payload = { type: 'chat', content: content, }; if (this.sessionId) { payload.sessionId = this.sessionId; } if (yoloMode) { payload.yoloMode = true; } const response = await fetch(`${this.baseUrl}/message`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(payload), }); return await response.json(); } // Send tool confirmation response async sendToolConfirmation(requestId, decision) { const response = await fetch(`${this.baseUrl}/message`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'tool_confirmation_response', requestId: requestId, response: decision, }), }); return await response.json(); } // Send user question response async sendUserQuestionResponse(requestId, answer) { const response = await fetch(`${this.baseUrl}/message`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'user_question_response', requestId: requestId, response: answer, }), }); return await response.json(); } // Disconnect disconnect() { if (this.eventSource) { this.eventSource.close(); this.eventSource = null; } } } // Usage example async function main() { const client = new SnowAIClient(); // Connect await client.connect(); // Send message (enable YOLO mode) await client.sendMessage('Help me create a TypeScript function', true); // Wait for response handling (via event listeners) } main(); ``` ### Python Client ```python import requests import json import sseclient class SnowAIClient: def __init__(self, base_url='http://localhost:3000'): self.base_url = base_url self.session = requests.Session() self.session_id = None def connect(self): """Connect to SSE server""" response = self.session.get( f'{self.base_url}/events', stream=True, headers={'Accept': 'text/event-stream'} ) client = sseclient.SSEClient(response) for event in client.events(): data = json.loads(event.data) self.handle_event(data) def handle_event(self, event): """Handle events""" print(f"[Event] {event['type']}") if event['type'] == 'tool_confirmation_request': self.handle_tool_confirmation(event) elif event['type'] == 'user_question_request': self.handle_user_question(event) elif event['type'] == 'complete': self.session_id = event['data']['sessionId'] print(f"Session ID: {self.session_id}") def handle_tool_confirmation(self, event): """Handle tool confirmation""" # Auto-approve non-sensitive commands decision = 'reject' if event['data']['isSensitive'] else 'approve' self.send_tool_confirmation_response(event['requestId'], decision) def handle_user_question(self, event): """Handle user question""" selected = event['data']['options'][0] self.send_user_question_response(event['requestId'], {'selected': selected}) def send_message(self, content, yolo_mode=False): """Send message""" payload = { 'type': 'chat', 'content': content, } if self.session_id: payload['sessionId'] = self.session_id if yolo_mode: payload['yoloMode'] = True response = self.session.post( f'{self.base_url}/message', json=payload ) return response.json() def send_tool_confirmation_response(self, request_id, decision): """Send tool confirmation response""" response = self.session.post( f'{self.base_url}/message', json={ 'type': 'tool_confirmation_response', 'requestId': request_id, 'response': decision } ) return response.json() def send_user_question_response(self, request_id, answer): """Send user question response""" response = self.session.post( f'{self.base_url}/message', json={ 'type': 'user_question_response', 'requestId': request_id, 'response': answer } ) return response.json() # Usage example if __name__ == '__main__': client = SnowAIClient() # Send message (enable YOLO mode) client.send_message('Help me create a Python function', yolo_mode=True) # Listen for events client.connect() ``` ## Use Cases ### Web Application Integration Integrate Snow AI into your web application to provide intelligent programming assistant functionality: ```javascript // React component example import {useState, useEffect, useRef} from 'react'; function AIAssistantChat() { const [connected, setConnected] = useState(false); const [messages, setMessages] = useState([]); const [sessionId, setSessionId] = useState(null); const eventSourceRef = useRef(null); // Connect to SSE server useEffect(() => { const eventSource = new EventSource('http://localhost:3000/events'); eventSourceRef.current = eventSource; eventSource.onopen = () => { setConnected(true); console.log('Connected to Snow AI'); }; eventSource.onmessage = event => { const data = JSON.parse(event.data); handleSSEEvent(data); }; eventSource.onerror = () => { setConnected(false); console.error('Connection lost'); }; return () => { eventSource.close(); }; }, []); // Handle SSE events const handleSSEEvent = data => { switch (data.type) { case 'message': if (data.data.role === 'assistant') { if (data.data.streaming) { // Stream update last message setMessages(prev => { const newMessages = [...prev]; if ( newMessages.length > 0 && newMessages[newMessages.length - 1].role === 'assistant' ) { newMessages[newMessages.length - 1].content = data.data.content; } else { newMessages.push({ role: 'assistant', content: data.data.content, }); } return newMessages; }); } } break; case 'complete': setSessionId(data.data.sessionId); console.log('Conversation complete'); break; case 'tool_confirmation_request': // Show tool confirmation dialog handleToolConfirmation(data); break; case 'error': console.error('Error:', data.data.message); break; } }; // Send message const sendMessage = async text => { const newMessage = {role: 'user', content: text}; setMessages(prev => [...prev, newMessage]); const payload = { type: 'chat', content: text, yoloMode: true, // Auto-approve safe tools }; if (sessionId) { payload.sessionId = sessionId; } await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(payload), }); }; // Handle tool confirmation const handleToolConfirmation = async event => { const confirmed = window.confirm( `AI wants to execute tool: ${event.data.toolCall.function.name}\nAllow?`, ); await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'tool_confirmation_response', requestId: event.requestId, response: confirmed ? 'approve' : 'reject', }), }); }; return (
Status: {connected ? 'Connected' : 'Disconnected'}
{messages.map((msg, i) => (
{msg.role}: {msg.content}
))}
{ if (e.key === 'Enter') { sendMessage(e.target.value); e.target.value = ''; } }} />
); } ``` ### Mobile App Backend Provide AI capabilities for mobile applications: ```javascript // Express middleware app.post('/api/ai/chat', async (req, res) => { const {message, sessionId} = req.body; // Forward to Snow AI const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'chat', content: message, sessionId: sessionId, yoloMode: true, }), }); res.json(await response.json()); }); ``` ### Microservice Architecture Use as AI microservice: ```yaml # Kubernetes deployment apiVersion: apps/v1 kind: Deployment metadata: name: snow-ai-service spec: replicas: 3 selector: matchLabels: app: snow-ai template: metadata: labels: app: snow-ai spec: containers: - name: snow-ai image: snow-ai:latest command: ['snow', '--sse', '--sse-port', '3000'] ports: - containerPort: 3000 ``` ## Test Client Snow CLI provides a complete HTML test client: **Location**: `sse-test-client.html` ### Features - Real-time SSE event monitoring - Beautiful chat interface - Event log viewer - YOLO mode toggle - Tool confirmation UI (with complete option display) - Session management - Connection status display ### Usage 1. Start SSE server: ```bash snow --sse ``` 2. Open `sse-test-client.html` in browser 3. Click "Connect" button 4. Start chatting and testing ## Best Practices ### 1. Error Handling ```javascript // Comprehensive error handling eventSource.onerror = error => { console.error('SSE connection error:', error); // Auto-reconnect setTimeout(() => { console.log('Attempting to reconnect...'); connect(); }, 5000); }; ``` ### 2. Timeout Handling ```javascript // Set timeout for interaction requests const TIMEOUT = 300000; // 5 minutes (default value, configurable via --sse-timeout parameter) function waitForResponse(requestId) { return new Promise((resolve, reject) => { const timeout = setTimeout(() => { reject(new Error('Interaction timeout')); }, TIMEOUT); // Listen for response // clearTimeout(timeout) after receiving response }); } ``` ### 3. Session Management ```javascript // Persist Session ID localStorage.setItem('snow-session-id', sessionId); // Restore Session const savedSessionId = localStorage.getItem('snow-session-id'); if (savedSessionId) { await client.sendMessage( 'Continue previous conversation', false, savedSessionId, ); } ``` ### 4. Security Considerations ```javascript // Validate and sanitize user input function sanitizeInput(input) { // Remove dangerous characters return input.replace(/[<>]/g, ''); } // Add authentication in production const response = await fetch('http://localhost:3000/message', { headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiToken}`, }, // ... }); ``` ## Limitations and Notes ### Unsupported Features 1. **Interactive UI**: - Cannot use Ink terminal interface - Keyboard shortcuts not supported 2. **Plan Mode**: - Interactive plan approval not supported - All operations execute immediately 3. **Local File Access Restrictions**: - Can only access files under server working directory - Cannot access client-side local files ### Performance Notes 1. **Connection Limit**: - Recommended maximum 100 concurrent connections per server - Consider load balancing 2. **Session Size**: - Long sessions increase memory usage - Regularly clean up old sessions 3. **Network Bandwidth**: - Streaming output continuously occupies connection - Consider message size limits ### Security Notes 1. **Authentication and Authorization**: - Must add authentication in production environment - Implement access control 2. **API Key Protection**: - Don't expose API keys on client side - Use server-side configuration 3. **Command Execution Risks**: - Review all tool invocations - Restrict sensitive operations ## FAQ **Q: What's the difference between SSE server and headless mode?** A: SSE server is a continuously running backend service supporting multiple client connections. Headless mode is single-execution mode that automatically exits after completion. SSE is suitable for web application integration, headless mode for script automation. **Q: How to use different API configurations in SSE mode?** A: SSE server reads configuration files from working directory. Use `--work-dir` parameter to specify different project directories, each with independent configuration. **Q: Can I run multiple SSE servers simultaneously?** A: Yes, but need to use different ports. For example: ```bash snow --sse --sse-port 3000 snow --sse --sse-port 3001 --work-dir /another-project ``` **Q: Do sessions expire?** A: Sessions don't expire and are permanently saved in `~/.snow/sessions/` directory. However, very long sessions increase token consumption. **Q: How to handle tool confirmation timeout?** A: Tool confirmation has a default 5-minute (300000ms) timeout. If timeout occurs, execution is automatically rejected and error returned. Recommend implementing auto-handling or user prompts in client. You can customize the timeout duration via `--sse-timeout` parameter: ```bash # Set to 10 minutes (600000ms) snow --sse --sse-timeout 600000 # Set to 30 seconds (30000ms) snow --sse --sse-timeout 30000 ``` **Q: Does YOLO mode execute all commands?** A: No. Sensitive commands require confirmation even in YOLO mode. YOLO mode only auto-approves safe tools in the permission list. **Q: How to debug SSE connection issues?** A: 1. Check server logs (terminal display) 2. Use browser developer tools to view network requests 3. Use `sse-test-client.html` for testing 4. Check firewall and port usage **Q: Can SSE server run in Docker?** A: Yes. Example Dockerfile: ```dockerfile FROM node:18 RUN npm install -g snow-ai EXPOSE 3000 CMD ["snow", "--sse", "--sse-port", "3000"] ``` ## Configuration File Locations Configuration files used by SSE server: - **API Configuration**: `~/.snow/profiles.json` - **Permission Configuration**: `/.snow/permissions.json` - **Sensitive Commands**: `~/.snow/sensitive-commands.json` - **Session Storage**: `~/.snow/sessions///` For configuration methods, refer to: [First Time Configuration](./02.First%20Time%20Configuration.md) ## Related Features - [Headless Mode](./12.Headless%20Mode.md) - Command line quick conversations - [Sensitive Commands Configuration](./06.Sensitive%20Commands%20Configuration.md) - Configure dangerous commands requiring confirmation - [Async Task Management](./15.Async%20Task%20Management.md) - Background task management - [Startup Parameters Guide](./19.Startup%20Parameters%20Guide.md) - All startup parameters explained ================================================ FILE: docs/usage/en/21.Custom StatusLine Guide.md ================================================ # Snow CLI User Guide - Custom StatusLine ## Overview Snow CLI supports loading custom StatusLine plugins from your user directory. You can place one or more JavaScript files in `~/.snow/plugin/statusline/`, and Snow CLI will load them on startup. Use this feature when you want to: - Show your own environment status - Display project-specific hints - Add time, directory, branch, service, or local machine indicators - Switch status text by Simplified Chinese, Traditional Chinese, and English - Override a built-in StatusLine plugin with your own implementation ## Plugin Directory Snow CLI currently loads StatusLine plugins from: ```bash ~/.snow/plugin/statusline/ ``` Supported file extensions: - `.js` - `.mjs` - `.cjs` Notes: - Plugins are loaded from the user directory only - Snow CLI sorts plugin files by filename before loading - Restart Snow CLI after adding or modifying a plugin file ## Export Formats A plugin module can export in any of these forms: ```js export default { ... } ``` ```js export const statusLineHook = { ... } ``` ```js export const statusLineHooks = [{ ... }, { ... }] ``` If multiple plugins use the same hook `id`, the later loaded plugin overrides the earlier one. ## Hook Structure Each StatusLine hook uses this structure: ```js export default { id: 'custom.example', refreshIntervalMs: 60000, getItems(context) { return { id: 'custom-example-item', text: 'Hello', detailedText: 'Hello from custom status line', color: 'cyan', priority: 200, }; }, }; ``` Field description: - `id`: unique hook id, used for merging and override behavior - `refreshIntervalMs`: optional refresh interval in milliseconds; minimum effective interval is 1000 ms - `enable`: optional, whether to enable this hook, defaults to `true`, set to `false` to temporarily disable - `getItems(context)`: returns one item, multiple items, or `undefined` The `getItems` result supports: - single item object - array of item objects - `undefined` or `null` to render nothing - async return values via `async getItems()` ## Render Item Fields Each render item supports the following fields: - `id`: optional item id; Snow CLI auto-generates one if omitted - `text`: short text used in simple mode - `detailedText`: optional text used in normal mode; falls back to `text` - `color`: optional Ink color string or hex color - `priority`: optional sort priority; lower values render first ## Context Object `getItems(context)` receives this context object: ```js { cwd: '/absolute/current/working/directory', platform: 'darwin', language: 'en', simpleMode: false, labels: { gitBranch: 'Git Branch', }, system: { memory: { usageMb: 186, formattedUsage: '186 MB', }, modes: { yolo: false, plan: true, vulnerabilityHunting: false, toolSearchEnabled: true, hybridCompress: false, simple: false, }, ide: { connectionStatus: 'connected', editorContext: { activeFile: '/path/to/file.ts', selectedText: 'const answer = 42;', cursorPosition: {line: 10, character: 5}, workspaceFolder: '/path/to/workspace', }, selectedTextLength: 18, }, backend: { connectionStatus: 'connected', instanceName: 'default', }, contextWindow: { inputTokens: 18234, maxContextTokens: 128000, cacheCreationTokens: 2048, cacheReadTokens: 8192, percentage: 22.3, totalInputTokens: 28474, hasAnthropicCache: true, hasOpenAICache: false, hasAnyCache: true, }, codebase: { indexing: true, progress: { totalFiles: 100, processedFiles: 42, totalChunks: 320, currentFile: 'source/app.ts', status: 'indexing', }, }, watcher: { enabled: true, fileUpdateNotification: { file: 'source/app.ts', timestamp: 1710000000000, }, }, clipboard: { text: 'Input copied', isError: false, timestamp: 1710000000000, }, profile: { currentName: 'default', baseUrl: 'https://api.openai.com/v1', requestMethod: 'chat', advancedModel: 'gpt-4o', basicModel: 'gpt-4o-mini', maxContextTokens: 128000, maxTokens: 4096, anthropicBeta: false, anthropicCacheTTL: '5m', thinkingEnabled: false, thinkingType: 'adaptive', thinkingBudgetTokens: 4096, thinkingEffort: 'medium', geminiThinkingEnabled: false, geminiThinkingLevel: 'high', responsesReasoningEnabled: false, responsesReasoningEffort: 'medium', responsesFastMode: false, responsesVerbosity: 'medium', anthropicSpeed: 'standard', enablePromptOptimization: true, enableAutoCompress: true, autoCompressThreshold: 80, showThinking: true, streamIdleTimeoutSec: 180, systemPromptId: ['default'], customHeadersSchemeId: 'default', toolResultTokenLimit: 100000, streamingDisplay: false, }, compression: { blockToast: null, }, }, } ``` Field description: - `cwd`: current Snow CLI working directory - `platform`: current Node.js platform value, such as `darwin`, `linux`, `win32` - `language`: current Snow CLI language, one of `en`, `zh`, `zh-TW` - `simpleMode`: whether Snow CLI is in simple theme mode - `labels`: localized labels that built-in plugins may reuse - `system`: a ready-to-use snapshot of current StatusLine system state Available fields under `system`: - `system.memory`: current Snow CLI process memory, including `usageMb` and `formattedUsage` - `system.modes`: current mode flags, including `yolo`, `plan`, `vulnerabilityHunting`, `toolSearchEnabled`, `hybridCompress`, `team`, `simple` - `system.ide`: IDE connection state, including `connectionStatus`, `editorContext`, `selectedTextLength` - `system.backend`: backend connection state, including `connectionStatus`, `instanceName` - `system.contextWindow`: context window state; when present it includes token metrics, cache metrics, `percentage`, and `totalInputTokens` - `system.codebase`: codebase indexing state, including `indexing` and `progress` - `system.watcher`: file watcher state, including `enabled` and `fileUpdateNotification` - `system.clipboard`: most recent copy feedback, including `text`, `isError`, `timestamp` - `system.profile`: current profile full configuration, including `currentName`, `baseUrl`, `requestMethod`, `advancedModel`, `basicModel`, `maxContextTokens`, `maxTokens`, `anthropicBeta`, `anthropicCacheTTL`, `thinkingEnabled`, `thinkingType`, `thinkingBudgetTokens`, `thinkingEffort`, `geminiThinkingEnabled`, `geminiThinkingLevel`, `responsesReasoningEnabled`, `responsesReasoningEffort`, `responsesFastMode`, `responsesVerbosity`, `anthropicSpeed`, `enablePromptOptimization`, `enableAutoCompress`, `autoCompressThreshold`, `showThinking`, `streamIdleTimeoutSec`, `systemPromptId`, `customHeadersSchemeId`, `toolResultTokenLimit`, `streamingDisplay` (excluding `apiKey`) - `system.compression`: auto-compression state, including `blockToast` ## Example 1: Real Clock Plugin A real working example file already exists in your user directory: ````bash ~/.snow/plugin/statusline/example-clock.js Its content is: ```js const messages = { en: { label: 'Current Time', directory: 'Directory', }, zh: { label: '当前时间', directory: '目录', }, 'zh-TW': { label: '當前時間', directory: '目錄', }, }; export default { id: 'custom.example-clock', refreshIntervalMs: 60_000, getItems(context) { const now = new Date(); const hours = String(now.getHours()).padStart(2, '0'); const minutes = String(now.getMinutes()).padStart(2, '0'); const clock = `${hours}:${minutes}`; const message = messages[context.language] || messages.en; return { id: 'custom-example-clock', text: `◷ ${clock}`, detailedText: `◷ ${message.label}: ${clock} · ${message.directory}: ${context.cwd}`, color: '#A78BFA', priority: 200, }; }, }; ```` ## Example 2: Show Current Directory Name ```js import path from 'node:path'; export default { id: 'custom.cwd-name', refreshIntervalMs: 5000, getItems(context) { const folderName = path.basename(context.cwd); return { text: `DIR ${folderName}`, detailedText: `Current Folder: ${folderName}`, color: 'green', priority: 150, }; }, }; ``` ## Example 3: Use System State ```js export default { id: 'custom.system-status', refreshIntervalMs: 3000, getItems(context) { const items = []; if (context.system.ide.connectionStatus === 'connected') { const activeFile = context.system.ide.editorContext?.activeFile; items.push({ id: 'custom-system-ide', text: activeFile ? 'IDE ON' : 'IDE READY', detailedText: activeFile ? `IDE connected · Active file: ${activeFile}` : 'IDE connected', color: '#22C55E', priority: 120, }); } if (context.system.contextWindow) { items.push({ id: 'custom-system-context', text: `CTX ${context.system.contextWindow.percentage.toFixed(1)}%`, detailedText: `Context used: ${context.system.contextWindow.totalInputTokens} tokens`, color: 'cyan', priority: 130, }); } items.push({ id: 'custom-system-memory', text: `MEM ${context.system.memory.formattedUsage}`, detailedText: `Current memory usage: ${context.system.memory.formattedUsage}`, color: 'yellow', priority: 140, }); return items; }, }; ``` ## Example 4: Return Multiple Status Items ```js export default { id: 'custom.multi-status', refreshIntervalMs: 30000, getItems() { const now = new Date(); return [ { text: `T ${String(now.getHours()).padStart(2, '0')}:${String( now.getMinutes(), ).padStart(2, '0')}`, color: 'cyan', priority: 100, }, { text: 'ENV DEV', detailedText: 'Environment: Development', color: 'yellow', priority: 110, }, ]; }, }; ``` ## Built-in Git Branch Example Snow CLI already includes a built-in Git branch StatusLine plugin. Reference implementation: - `source/ui/components/common/statusline/gitBranch.ts` This built-in hook: - uses hook id `builtin.git-branch` - refreshes every 10 seconds - reads the current Git branch from `context.cwd` - renders short and detailed text separately If you create another plugin with the same hook id, you can override the built-in behavior. ## Built-in Hook IDs (Overridable) In addition to `builtin.git-branch`, Snow CLI reserves stable hook ids for all other built-in status items. If your plugin registers a hook with one of these ids, Snow CLI will skip the hard-coded rendering for that item and use your hook's output instead: | Hook ID | Default Rendering | Trigger Condition | | ---------------------------- | ----------------------------------------- | -------------------------------------- | | `builtin.profile` | `§ {profileName}` | A current profile is active | | `builtin.mode-yolo` | `⧴ YOLO` | YOLO mode is enabled | | `builtin.mode-plan` | `⚐ Plan` | Plan mode is enabled | | `builtin.mode-hunt` | `⍨ Vuln Hunt` | Vulnerability hunting mode is enabled | | `builtin.mode-team` | `⚑ Team` | Team mode is enabled | | `builtin.tool-search` | `♾︎ ToolSearch ON` | On-demand tool search is enabled | | `builtin.hybrid-compress` | `⇌ Hybrid Compress` | Hybrid compression is enabled | | `builtin.ide-connection` | `◐/●/○ IDE` | VSCode connection is not disconnected | | `builtin.backend-connection` | `◐/↻/● Backend` | Backend connection is not disconnected | | `builtin.codebase-indexing` | `◐ Indexing {processed}/{total}` or error | Indexing is running or has errored | | `builtin.watcher` | `☉ Watcher` | Watcher is enabled and not indexing | | `builtin.file-update` | `⛁ Updated` | A file update notification arrived | | `builtin.copy-status` | Clipboard success / failure toast | A clipboard message exists | | `builtin.compress-block` | Auto-compression block toast | Auto compression was blocked | | `builtin.memory` | `⛁ {memoryUsage}` | Always rendered | | `builtin.git-branch` | `⑂ {branch}` | The current directory is a Git repo | Notes: - Once a plugin registers a hook with the same id, Snow CLI completely skips the corresponding built-in render. Icons, colors, thresholds, etc. are then fully controlled by your hook. - Whether the built-in item is visible at all (e.g. whether YOLO mode is on) is still determined by Snow CLI. Your plugin can read the same flags via `context.system.modes`, `context.system.ide`, `context.system.contextWindow`, etc. to decide what to return. - Overriding `builtin.memory` removes the default `⛁ 232 MB` block, so make sure your hook renders memory information (you can read `context.system.memory.usageMb`). ## Override Example ```js export default { id: 'builtin.git-branch', refreshIntervalMs: 15000, async getItems(context) { return { text: '⑂ custom-branch', detailedText: `⑂ Custom Git Branch (${context.cwd})`, color: 'magenta', priority: 100, }; }, }; ``` ## Error Handling If a plugin fails: - Snow CLI skips the broken result for that refresh cycle - the error is written to the Snow CLI log - other plugins continue to run Common problems: - file is not in `~/.snow/plugin/statusline/` - file extension is not supported - exported value is not a valid hook object - `text` is missing or empty - plugin code throws at runtime ## Best Practices - Keep `getItems()` fast and lightweight - Use a reasonable refresh interval - Return `undefined` when the status should be hidden - Use stable `id` values for predictable ordering and override behavior - Prefer `detailedText` for verbose mode and `text` for compact mode - Restart Snow CLI after editing plugin files ## Troubleshooting ### Plugin does not appear Check: 1. File path is `~/.snow/plugin/statusline/*.js` 2. Snow CLI was restarted 3. Export format is valid 4. `text` is not empty 5. The plugin does not throw errors during execution ### Status order is unexpected Check `priority` values. - smaller number = earlier render - larger number = later render ### My plugin does not override built-in Git branch Make sure the hook `id` exactly matches: ```js id: 'builtin.git-branch'; ``` ## Related Files - `source/ui/components/common/statusline/useStatusLineHooks.ts` - `source/ui/components/common/statusline/types.ts` - `source/ui/components/common/statusline/gitBranch.ts` - `~/.snow/plugin/statusline/example-clock.js` ================================================ FILE: docs/usage/en/22.Team Mode Guide.md ================================================ # Snow CLI User Guide - Team Mode Team Mode (Multi-Agent Collaboration) is an advanced feature of Snow CLI that allows you to launch multiple AI teammates working independently simultaneously, coordinating through a shared task list to achieve true parallel development. ## What is Team Mode Team Mode allows you to create a team of AI developers where each teammate: - Works in an independent Git worktree without interference - Coordinates分工 through a shared task list - Can communicate with each other to synchronize progress - Merges work back to the main branch upon completion ### Applicable Scenarios - **Large-scale refactoring projects**: Split tasks among multiple teammates for parallel processing - **Full-stack development**: Frontend, backend, and testing proceed simultaneously - **Code review**: Dedicated teammates responsible for review and quality assurance - **Documentation writing**: Multi-language documentation written in parallel - **Complex feature development**: Modular decomposition with each teammate responsible for different modules ## Core Concepts of Team Mode ### Teammate Each teammate is an independent AI instance with: - **Independent Git worktree**: Located in `.snow/worktrees/` directory - **Isolated context**: Separated from the main workflow and other teammates - **Dedicated role**: Can assign different roles (e.g., Frontend Developer, QA Engineer) - **Full tool access**: Can use all Snow CLI tools ### Shared Task List The team coordinates work using a shared task list: - **Task creation**: Can pre-create tasks or add dynamically - **Task assignment**: Can assign to specific teammates or let teammates claim actively - **Dependency management**: Tasks can have dependencies to ensure execution order - **Status tracking**: Real-time view of task progress ### Message Communication Teammates can communicate through the messaging system: - **Unicast**: Send messages to specific teammates - **Broadcast**: Send messages to all teammates - **Auto-sync**: Teammates notify the team when work is completed ## Team Mode Workflow ```mermaid graph TB Start([Start Team Mode]) --> Spawn[Create Teammates] Spawn --> CreateTasks[Create Task List] CreateTasks --> Assign[Assign/Claim Tasks] Assign --> ParallelWork{Parallel Work} ParallelWork --> Teammate1[Teammate A
Processing Task 1] ParallelWork --> Teammate2[Teammate B
Processing Task 2] ParallelWork --> Teammate3[Teammate C
Processing Task 3] Teammate1 --> Message1[Message Communication
Sync Progress] Teammate2 --> Message1 Teammate3 --> Message1 Message1 --> Wait{Wait for Completion} Wait --> Complete[All Tasks Completed] Complete --> Merge[Merge Work] Merge --> Cleanup[Cleanup Team] Cleanup --> End([End]) style Start fill:#e1f5ff style Spawn fill:#fff4e1 style ParallelWork fill:#ffe1f5 style Teammate1 fill:#e1ffe1 style Teammate2 fill:#e1ffe1 style Teammate3 fill:#e1ffe1 style Merge fill:#ffe1e1 style End fill:#e1f5ff ``` ### Workflow Description 1. **Create Teammates**: Use `spawn_teammate` to create required teammates 2. **Create Tasks**: Use `create_task` to add tasks to the shared list 3. **Assign Tasks**: Teammates claim actively or are assigned 4. **Parallel Execution**: Teammates work independently in their respective worktrees 5. **Message Communication**: Coordinate through the messaging system when needed 6. **Wait for Completion**: Wait for all teammates to complete tasks 7. **Merge Work**: Merge each teammate's work into the main branch 8. **Cleanup Team**: Shutdown teammates and clean up worktrees ## Command Reference ### Create Teammate: spawn_teammate Create a new AI teammate, each with their own Git worktree. ```typescript spawn_teammate({ name: "frontend", // Teammate name (short descriptive) prompt: "Task description...", // Complete task prompt require_plan_approval: true // Whether to require plan approval before execution (optional) }) ``` **Examples**: ```typescript // Create a frontend development teammate spawn_teammate({ name: "frontend", prompt: "Responsible for implementing the frontend code for the user login page. Use React + TypeScript, need to include form validation and error handling. Project path: src/pages/login/", require_plan_approval: true }) // Create a testing teammate spawn_teammate({ name: "tester", prompt: "Write unit tests and integration tests for the login feature. Use Jest + React Testing Library, coverage requirement above 80%." }) ``` ### Create Task: create_task Add tasks to the shared task list. ```typescript create_task({ title: "Task Title", // Short task title description: "Detailed description...", // Task specifics assignee_name: "frontend", // Assign to which teammate (optional) dependencies: ["task-id-1"] // List of dependent task IDs (optional) }) ``` **Examples**: ```typescript // Create standalone task create_task({ title: "Implement Login Page", description: "Create login form component, include email and password input, add form validation", assignee_name: "frontend" }) // Create task with dependencies create_task({ title: "Write Login Tests", description: "Write unit tests for login feature", assignee_name: "tester", dependencies: ["task-abc-123"] // Wait for login page completion }) ``` ### Update Task: update_task Update task status or reassign. ```typescript update_task({ task_id: "task-abc-123", status: "in_progress", // pending | in_progress | completed assignee_name: "backend" // Reassign to another teammate }) ``` ### List Tasks: list_tasks View all tasks and their status. ```typescript list_tasks({}) ``` **Return Example**: ``` Task List: ┌─────────┬──────────────────────┬─────────────┬────────────────┐ │ ID │ Title │ Status │ Assignee │ ├─────────┼──────────────────────┼─────────────┼────────────────┤ │ task-1 │ Implement Login Page │ completed │ frontend │ │ task-2 │ Write Login Tests │ in_progress │ tester │ │ task-3 │ API Integration │ pending │ - │ └─────────┴──────────────────────┴─────────────┴────────────────┘ ``` ### List Teammates: list_teammates View all currently running teammates. ```typescript list_teammates({}) ``` **Return Example**: ``` Teammate List: ┌──────────┬────────────────┬─────────┬────────────────────────────────┐ │ MemberID │ Name │ Status │ Current Task │ ├──────────┼────────────────┼─────────┼────────────────────────────────┤ │ mem-abc │ frontend │ working │ Implement Login Page │ │ mem-def │ tester │ working │ Write Login Tests │ │ mem-ghi │ backend │ standby │ Waiting for new task │ └──────────┴────────────────┴─────────┴────────────────────────────────┘ ``` ### Send Message: message_teammate Send a message to a specific teammate. ```typescript message_teammate({ target_id: "mem-abc", // Teammate ID or name content: "Frontend page is complete, testing can begin" }) ``` ### Broadcast Message: broadcast_to_team Broadcast a message to all teammates. ```typescript broadcast_to_team({ content: "Attention all teammates: Project requirements have been updated, please check the documentation" }) ``` ### Wait for Completion: wait_for_teammates Block and wait for all teammates to complete work. ```typescript wait_for_teammates({ timeout_seconds: 600 // Timeout in seconds, default 600 }) ``` **Note**: This command blocks the current flow until all teammates enter `standby` status or timeout. ### Merge Teammate Work: merge_teammate_work Merge a specific teammate's work into the main branch. ```typescript merge_teammate_work({ name: "frontend", strategy: "manual" // manual | theirs | ours | auto }) ``` **Merge Strategies**: - `manual` (default): Manually resolve conflicts - `theirs`: Automatically accept all teammate's changes - `ours`: Automatically keep main branch changes - `auto`: Try normal merge, auto-accept teammate's version on conflicts ### Merge All Work: merge_all_teammate_work Merge all teammates' work into the main branch. ```typescript merge_all_teammate_work({ strategy: "manual" }) ``` ### Shutdown Teammate: shutdown_teammate Shutdown a specific teammate. ```typescript shutdown_teammate({ target_id: "mem-abc", reason: "Task completed" // Shutdown reason (optional) }) ``` **Note**: Teammates cannot shutdown themselves, must be controlled by the team lead. ### Cleanup Team: cleanup_team Cleanup the team, remove all Git worktrees. ```typescript cleanup_team({}) ``` **Important**: Before executing this command, you must: 1. Shutdown all teammates 2. Merge all work you want to keep ## Workflow Examples ### Example 1: Full-Stack Feature Development ```typescript // 1. Create development team spawn_teammate({ name: "backend", prompt: "Responsible for designing and implementing user authentication API. Requirements: 1) Login endpoint 2) Registration endpoint 3) JWT token generation 4) Password encryption. Use Express + Prisma.", require_plan_approval: true }) spawn_teammate({ name: "frontend", prompt: "Responsible for implementing frontend for login and registration pages. Use React + TypeScript + Tailwind CSS, need to integrate with backend API." }) spawn_teammate({ name: "tester", prompt: "Responsible for writing complete test suite. Includes: 1) Backend API tests 2) Frontend component tests 3) Integration tests. Coverage requirement 90%." }) // 2. Create task list create_task({ title: "Design Database Models", description: "Design user table structure, including email, password hash, creation time, etc.", assignee_name: "backend" }) create_task({ title: "Implement Auth API", description: "Implement login, registration, token refresh endpoints", assignee_name: "backend" }) create_task({ title: "Implement Login Page", description: "Create login page UI and form logic", assignee_name: "frontend" }) create_task({ title: "Write Backend Tests", description: "Write unit and integration tests for auth API", assignee_name: "tester", dependencies: ["task-backend-api"] // Depends on backend API completion }) // 3. Wait for all teammates to complete wait_for_teammates({ timeout_seconds: 1800 }) // 4. Merge all work merge_all_teammate_work({ strategy: "manual" }) // 5. Cleanup team cleanup_team({}) ``` ### Example 2: Code Refactoring Project ```typescript // Create multiple refactoring teammates for different modules spawn_teammate({ name: "refactor-utils", prompt: "Refactor all utility functions in the utils directory. Goals: 1) Add type definitions 2) Unify error handling 3) Add JSDoc comments" }) spawn_teammate({ name: "refactor-components", prompt: "Refactor React components in the components directory. Goals: 1) Convert to function components 2) Use TypeScript 3) Optimize performance" }) spawn_teammate({ name: "refactor-api", prompt: "Refactor API layer code. Goals: 1) Unify request encapsulation 2) Add request/response interceptors 3) Improve error handling" }) // Create tasks create_task({ title: "Refactor Utility Functions", assignee_name: "refactor-utils" }) create_task({ title: "Refactor Components", assignee_name: "refactor-components" }) create_task({ title: "Refactor API Layer", assignee_name: "refactor-api" }) // Wait and merge wait_for_teammates({ timeout_seconds: 1200 }) merge_all_teammate_work({ strategy: "auto" }) cleanup_team({}) ``` ### Example 3: Multi-language Documentation ```typescript // Create multiple documentation teammates spawn_teammate({ name: "doc-zh", prompt: "Write Chinese user documentation. Content includes: Installation Guide, Quick Start, API Reference, FAQ." }) spawn_teammate({ name: "doc-en", prompt: "Write English user documentation. Content corresponds to Chinese documentation, keep synchronized updates." }) spawn_teammate({ name: "doc-ja", prompt: "Write Japanese user documentation. Content corresponds to Chinese documentation, keep synchronized updates." }) // Wait for completion wait_for_teammates({ timeout_seconds: 900 }) // Merge each teammate's work separately merge_teammate_work({ name: "doc-zh", strategy: "manual" }) merge_teammate_work({ name: "doc-en", strategy: "manual" }) merge_teammate_work({ name: "doc-ja", strategy: "manual" }) cleanup_team({}) ``` ## Best Practices ### 1. Reasonable Task Splitting - Break large tasks into independent smaller tasks - Each task should have clear completion criteria - Avoid circular dependencies between tasks ### 2. Clear Role Definition When creating teammates, provide detailed and clear prompts: ```typescript spawn_teammate({ name: "backend", prompt: `You are a backend development expert. Task: Implement user authentication system Specific requirements: 1. Use Express.js + Prisma + PostgreSQL 2. Implement registration, login, logout endpoints 3. Use bcrypt for password encryption 4. Use JWT for authentication 5. Add input validation and error handling 6. Write API documentation Project path: /src/server Database config: Check .env file Notify testing teammate upon completion.` }) ``` ### 3. Proper Use of Dependency Management For tasks with dependencies, explicitly set dependency relationships: ```typescript // Create prerequisite task first const task1 = create_task({ title: "Design Database Models", assignee_name: "backend" }) // Create dependent task const task2 = create_task({ title: "Implement API Endpoints", assignee_name: "backend", dependencies: [task1.task_id] // Depends on task1 }) ``` ### 4. Timely Communication and Coordination Keep teammates synchronized through the messaging system: ```typescript // Backend notifies frontend after API completion message_teammate({ target_id: "frontend", content: "API deployed at http://localhost:3000/api, API docs at /docs/api.md" }) // Broadcast important information broadcast_to_team({ content: "Project dependencies updated, please re-run npm install" }) ``` ### 5. Careful Merge Handling Check each teammate's work before merging: ```typescript // Check all task status first list_tasks({}) // Merge one by one, manually resolving conflicts merge_teammate_work({ name: "frontend", strategy: "manual" }) merge_teammate_work({ name: "backend", strategy: "manual" }) // Or use auto strategy for automatic merging merge_all_teammate_work({ strategy: "auto" }) ``` ### 6. Proper Use of Plan Approval For complex tasks, enable plan approval to ensure correct direction: ```typescript spawn_teammate({ name: "architect", prompt: "Design overall system architecture...", require_plan_approval: true // Requires approval for execution plan }) ``` The teammate will submit an execution plan first, which you need to approve before proceeding. ## FAQ ### Q: What's the difference between Team Mode and Sub-Agents? A: Main differences: | Feature | Sub-Agent | Team Mode | |---------|-----------|-----------| | Workspace | Independent context | Independent Git worktree | | Parallelism | Serial invocation | True parallel | | Persistence | Temporary | Persistent worktree | | Collaboration | Unidirectional | Bidirectional communication | | Merge | Return results | Git merge | ### Q: How many teammates can be created simultaneously? A: There is no theoretical limit, but it's recommended to control within 3-5 based on task complexity and machine performance to ensure efficiency. ### Q: Can teammates share code with each other? A: Teammates work independently in their respective worktrees and cannot directly access each other's code. Sharing only occurs after merging to the main branch. ### Q: How to check teammate work progress? A: You can use the following methods: 1. `list_teammates` to view teammate status 2. `list_tasks` to view task progress 3. Use `message_teammate` to ask teammates about progress ### Q: What if there's a conflict in teammate work? A: Use `merge_teammate_work` with `manual` strategy, the system will enter merge state where you can manually resolve conflicts before committing. ### Q: Can new teammates be added midway? A: Yes, you can use `spawn_teammate` at any time to create new teammates and assign tasks. ### Q: Can teammates modify the main branch? A: No, teammates can only work in their own worktrees. Changes need to be applied to the main branch through merge operations. ### Q: How to terminate a running teammate? A: Use `shutdown_teammate` command to close a specific teammate. Note: Teammates cannot close themselves. ## Related Documentation - [Sub-Agent Configuration](./05.Sub-Agent%20Configuration.md) - Learn about sub-agent usage - [Async Task Management](./15.Async%20Task%20Management.md) - Background task management - [Hooks Configuration](./07.Hooks%20Configuration.md) - Git operation hooks configuration ================================================ FILE: docs/usage/en/23.Custom Search Engine Guide.md ================================================ # Snow CLI User Guide - Custom Search Engine ## Overview Snow CLI's web search (the `web-search` MCP tool) is driven by a pluggable search engine layer. Built-in engines are `duckduckgo` and `bing`, both of which scrape results from a headless browser (no official API used). If you want to use a different search provider, you can drop a JavaScript file into your user directory and Snow CLI will register it automatically — no build step, no source code modification. Use this feature when you want to: - Use a regional search provider that isn't shipped by default - Search your company's internal knowledge base or intranet - Customize how an existing provider is scraped (e.g. fix a selector after a layout change) - Temporarily mask a built-in engine without deleting any file > The example below uses a fictional provider `example-search.com` purely > to illustrate the engine contract. You are responsible for complying with > each target site's Terms of Service and `robots.txt` when writing a real > plugin. ## Plugin Directory Snow CLI loads search engine plugins from: ```bash ~/.snow/plugin/search_engines/ ``` Supported file extensions: - `.js` - `.mjs` (recommended for plain ES Modules) - `.cjs` Notes: - Plugins are loaded from the user directory only. - Snow CLI sorts plugin files by filename and loads them on first web search. - Restart Snow CLI after adding or modifying a plugin file (the engine registry caches loaded modules for the lifetime of the process). - Built-in engines (`duckduckgo`, `bing`) are always registered first; a plugin engine with the same `id` overrides the built-in one. ## Export Formats A plugin module can export in any of these forms (the first non-empty match wins, all of them are scanned): ```js export default { ... } ``` ```js export const searchEngine = { ... } ``` ```js export const searchEngines = [{ ... }, { ... }] ``` If multiple plugin files register the same engine `id`, the file loaded later (alphabetically) overrides the earlier one. ## Engine Structure Every engine must satisfy this shape (TypeScript-style for clarity, but plugin files are plain JavaScript): ```ts interface SearchEngine { id: string; // stable identifier, e.g. 'my-engine' name: string; // human readable, shown in the picker enable?: boolean; // optional, defaults to true search( page: Page, // a Puppeteer Page already opened for you query: string, // the user's query string maxResults: number, // how many results to return at most ): Promise; } interface SearchResult { title: string; url: string; snippet: string; displayUrl: string; } ``` Field description: - `id`: the value users put into `~/.snow/proxy-config.json`'s `searchEngine` field and what the picker stores. Keep it stable. - `name`: shown in the proxy config picker. Free-form. - `enable` (optional): defaults to `true`. Set to `false` to temporarily disable an engine without deleting its file. A disabled engine is invisible to `getSearchEngine`, `listSearchEngines`, and the UI picker. - Bonus trick: declaring `{id: 'bing', enable: false, search() {}}` in a plugin will mask the built-in `bing` engine, because the loader removes the same-id entry from the registry when it sees `enable: false`. - `search(page, query, maxResults)`: the actual work. Snow CLI: - launches/connects the browser for you (respects `~/.snow/proxy-config.json`) - opens a fresh `Page` and passes it in - closes the page after `search()` returns Your engine should: - navigate to its own search URL via `page.goto(...)` - wait for the DOM to settle - extract up to `maxResults` results via `page.evaluate(...)` - return them as an array of `SearchResult` Never call `browser.close()` / `page.close()` yourself — the page is owned by the caller. ## Lifecycle and Configuration 1. Drop the plugin file under `~/.snow/plugin/search_engines/`. 2. Start (or restart) Snow CLI. 3. Open the proxy configuration screen (`/settings` → Proxy and Browser Settings, or the dedicated entry point in your build) — your engine will appear in the "Search Engine" picker by its `name`. 4. Select your engine, save. The choice is persisted in `~/.snow/proxy-config.json` as: ```json { "enabled": false, "port": 7890, "searchEngine": "my-engine" } ``` 5. Any subsequent `web-search` MCP call will use your engine. ## Example: A Minimal Plugin Template Below is a complete, runnable template that targets a fictional provider `example-search.com`. Replace the URL, selectors, and id with the values that match your real target. Treat the selectors here as **placeholders** — every search page has a different DOM, you must inspect yours. ```js // ~/.snow/plugin/search_engines/my-engine.mjs const cleanText = text => (text || '') .replace(/\s+/g, ' ') .replace(/[\u200B-\u200D\uFEFF]/g, '') .trim(); export default { id: 'my-engine', name: 'My Search Engine', // Set to `false` to temporarily disable this engine without deleting the // file. Disabled engines are invisible to the picker and `getSearchEngine`. enable: true, async search(page, query, maxResults) { // 1. Build the search URL for your target provider. The example below // uses a fictional host purely to illustrate the shape. const encodedQuery = encodeURIComponent(query); const searchUrl = `https://example-search.com/search?q=${encodedQuery}` + `&n=${Math.max(maxResults, 10)}`; // 2. Navigate. Prefer `domcontentloaded` over `networkidle2` because // real search pages keep loading telemetry forever. try { await page.goto(searchUrl, { waitUntil: 'domcontentloaded', timeout: 30000, }); } catch { // Navigation timeout — try whatever already painted. } // 3. Wait for a representative result selector. Never throw — return // an empty list and let the caller fall back. try { await page.waitForSelector('.results .result-item', {timeout: 10000}); } catch { // Best effort — extraction may still find something. } // 4. Extract inside the browser context. const raw = await page.evaluate(maxLimit => { const out = []; const items = document.querySelectorAll('.results .result-item'); const isHttpUrl = u => /^https?:\/\//i.test(u); for (const item of items) { if (out.length >= maxLimit) break; // Filter ads if the provider marks them. if (item.classList.contains('is-ad')) continue; const linkEl = item.querySelector('a.result-title'); if (!linkEl) continue; const href = linkEl.getAttribute('href') || ''; if (!isHttpUrl(href)) continue; const title = (linkEl.textContent || '').trim(); if (!title) continue; const snippetEl = item.querySelector('.result-snippet'); const snippet = snippetEl ? (snippetEl.textContent || '').trim() : ''; const citeEl = item.querySelector('cite, .result-host'); const displayUrl = citeEl ? (citeEl.textContent || '').trim() : ''; out.push({title, url: href, snippet, displayUrl}); } return out; }, maxResults); // 5. Normalize and return. return raw.map(r => ({ title: cleanText(r.title), url: r.url || '', snippet: cleanText(r.snippet), displayUrl: cleanText(r.displayUrl), })); }, }; ``` To adapt this template to a real provider you need to figure out, for each provider you target: - the search URL pattern (often `?q=` or `?wd=` or `?query=`, plus a result-count parameter); - a stable container selector for organic results; - the title / link selector inside each container; - the snippet selector; - the display-URL / host selector; - how the provider marks ads or sponsored results, so you can skip them. Open the provider's result page in a regular browser, use DevTools to inspect the DOM, then plug the selectors into the template above. ## Writing Your Own Engine: Checklist 1. **Pick a stable `id`**. Once users save it into `proxy-config.json`, renaming will break their config. 2. **Open the target search URL with `domcontentloaded`**, not `networkidle2`. Most search pages keep loading telemetry scripts forever and `networkidle2` will time out before results are usable. 3. **Wrap `page.goto` in `try/catch`**. A navigation timeout is recoverable — the DOM may already contain enough to extract. 4. **Always use `page.waitForSelector` with a timeout**. Never `throw` if it fails; return an empty list and let the caller fall back. 5. **Extract inside `page.evaluate`**. The callback runs in the browser, so you have full DOM access but must `return` only structured-cloneable plain objects. 6. **Filter ads / sponsored results**. Each provider marks them differently — check the DOM yourself. 7. **Normalize text** (`cleanText` helper above) — collapse whitespace and strip zero-width characters. 8. **Never call `browser.close()` or `page.close()`**. The page is owned by `WebSearchService`. 9. **Don't import Node-only modules into `page.evaluate`'s callback** — it runs inside the browser. ## Multi-Engine Plugins You can register multiple engines from a single file: ```js export const searchEngines = [ {id: 'engine-a', name: 'Engine A', async search(...) { /* ... */ }}, {id: 'engine-b', name: 'Engine B', async search(...) { /* ... */ }}, ]; ``` This is convenient for plugins that share a `cleanText` helper or a common result-extraction routine. ## Troubleshooting - **The plugin does not appear in the picker.** - Make sure the file extension is `.js` / `.mjs` / `.cjs`. - Check the Snow CLI startup logs for `[websearch] failed to load search engine plugin "..."`. Syntax errors fail loudly. - Make sure your export is a plain object with `{id, name, search}` — the loader logs `did not export a valid SearchEngine` when validation fails. - **Search always returns 0 results.** - The provider probably updated its DOM. Open the page manually in a browser and inspect the new selectors. - Increase the `page.waitForSelector` timeout. - Some providers redirect bot traffic to a captcha page — try setting a realistic `User-Agent` via `page.setUserAgent(...)` at the start of `search()` (`WebSearchService` already sets one before delegating, but you can override). - **I want to disable a built-in engine.** - Create a plugin file with `{id: 'bing', name: 'Bing', enable: false, async search() { return []; }}`. The loader will see `enable: false` and remove the same-id entry from the registry. ## Related - [Proxy and Browser Settings](./03.Proxy%20and%20Browser%20Settings.md) - [Custom StatusLine Guide](./21.Custom%20StatusLine%20Guide.md) — same plugin-loading philosophy applied to the status line ================================================ FILE: docs/usage/zh/0.目录.md ================================================ # Snow CLI 使用文档——目录 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 快速开始 - [安装指南](./01.安装指南.md) - 系统要求、安装(更新、卸载)步骤、IDE 扩展安装 - [首次配置](./02.首次配置.md) - API 配置、模型选择、基础设置 - [启动参数说明](./19.启动参数说明.md) - 命令行参数详解、快速启动模式、无头模式、异步任务、开发者模式 ## 高级配置 - [代理和浏览器设置](./03.代理和浏览器设置.md) - 网络代理配置、浏览器使用设置 - [代码库设置](./04.代码库设置.md) - 代码库集成、搜索配置 - [子代理设置](./05.子代理设置.md) - 子代理管理、自定义子代理配置 - [敏感命令配置](./06.敏感命令配置.md) - 敏感命令保护、自定义命令规则 - [Hooks 配置](./07.Hooks配置.md) - 工作流程自动化、Hook 类型说明、实用配置示例 - [主题设置](./08.主题设置.md) - 界面主题配置、自定义配色、简洁模式 - [第三方中转配置](./16.第三方中转配置.md) - Claude Code 中转、Codex 中转、自定义请求头配置 ## 功能指南 - [指令面板说明](./09.指令面板说明.md) - 所有可用指令的详细说明、使用技巧、快捷键参考 - [命令注入模式](./10.命令注入模式.md) - 消息中直接执行命令、语法说明、安全机制、使用场景 - [漏洞猎人模式](./11.漏洞猎人模式.md) - 专业安全分析、漏洞检测、验证脚本、详细报告 - [无头模式](./12.无头模式.md) - 命令行快速对话、会话管理、脚本集成、第三方工具集成 - [快捷键指南](./13.快捷键指南.md) - 所有快捷键说明、编辑操作、导航控制、回滚功能 - [MCP 配置](./14.MCP配置.md) - MCP 服务管理、配置外部服务、启用/禁用服务、故障排除 - [异步任务管理](./15.异步任务管理.md) - 后台任务创建、任务管理界面、敏感命令审批、任务转会话 - [Skills 指令详细说明](./18.Skills指令详细说明.md) - 技能创建、使用方法、Claude Code Skills 兼容性、工具限制 - [LSP 配置与用法](./19.LSP配置.md) - LSP 配置文件、语言服务器安装、ACE 工具用法（跳转/大纲） - [SSE 服务模式](./20.SSE服务模式.md) - SSE 服务器启动、API 端点说明、工具确认流程、权限配置、YOLO 模式、客户端集成示例 - [自定义 StatusLine 指南](./21.自定义StatusLine指南.md) - 用户级状态栏插件、hook 结构、覆盖机制、中英文示例 - [Team 模式指南](./22.Team模式指南.md) - 多智能体协作、并行任务执行、团队管理 - [自定义搜索引擎指南](./23.自定义搜索引擎指南.md) - 用户级搜索引擎插件、引擎合约、enable 开关、最小模板示例 ================================================ FILE: docs/usage/zh/01.安装指南.md ================================================ # Snow CLI 使用文档——安装指南 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 安装指南 ### 1、系统环境要求 1. 操作系统：Windows 10+ / macOS 10.15+ / Ubuntu 18.04+ / CentOS 7+ 2. node.js：v18.0.0+ 3. npm: >= 8.3.0 ### 2、安装 node.js + npm 1. Windows: [https://nodejs.org/en/download/](https://nodejs.org/zh-cn/download/) 下载安装包安装 node.js+npm 2. macOS: 通过 Homebrew 安装 node.js+npm ```bash brew install node ``` 3. Linux: 通过 apt-get 安装 node.js+npm ```bash sudo apt-get install nodejs sudo apt-get install npm ``` 4. 验证安装成功 ```bash node -v npm -v ``` ### 3、安装 Snow CLI 与 IDE 插件 1. 使用 npm 安装 Snow CLI ```bash npm install -g snow-ai ``` 2. 编译 Snow CLI 源码安装 ```bash git clone https://github.com/MayDay-wpf/snow-cli cd snow-cli npm install npm run build npm run link ``` 3. 验证安装成功 ```bash snow --version snow --help ``` 4. 安装 VSCode 插件 在扩展市场中搜索 `Snow CLI` 并安装 ![alt text](../images/image.png) 安装完成后在 VSCode 右上角会出现启动图标 ![alt text](../images/image1.png) 5. VSCode 扩展设置 安装 VSCode 插件后，可以在 `设置` 中搜索 `Snow CLI` 进行以下配置： - **终端模式** (`snow-cli.terminalMode`)：选择终端显示模式。 - `split`（默认）：在编辑器右侧分屏打开终端。 - `sidebar`：在侧边栏面板中嵌入终端。 - **启动命令** (`snow-cli.startupCommand`)：终端启动时运行的命令。默认为 `snow`。支持逗号分隔的多个命令，按轮询顺序分配给多个终端。 - **Shell 类型** (`snow-cli.terminal.shellType`)：侧边栏终端使用的 Shell。默认为 `auto`，跟随 VS Code 默认终端配置。也可以指定自定义 Shell 路径（如 `C:\Program Files\Git\bin\bash.exe`、`/usr/bin/zsh`）。 - **代理 URL** (`snow-cli.terminal.proxyUrl`)：可选代理 URL，作为 `HTTP_PROXY`/`HTTPS_PROXY` 注入 Snow CLI 终端。留空则回退到 VS Code 的 `http.proxy` 设置。 - **字体** (`snow-cli.terminal.fontFamily`)：侧边栏终端字体。留空使用默认等宽字体。 - **字号** (`snow-cli.terminal.fontSize`)：侧边栏终端字号（px）。默认为 `14`（范围：8–32）。 - **字重** (`snow-cli.terminal.fontWeight`)：侧边栏终端字重。默认为 `normal`。 - **行高** (`snow-cli.terminal.lineHeight`)：侧边栏终端行高。默认为 `1`（范围：0.8–2）。 - **Git Blame** (`snow-cli.gitBlame.enabled`)：启用 Git Blame 标注，在当前行显示提交信息（作者、时间、消息），类似 GitLens。默认为 `false`。 6. 安装 Jetbrains IDE 插件 在插件市场中搜索 `Snow CLI` 并安装 插件安装成功后，重启 IDE ![alt text](../images/image2.png) 在终端 `Tab` 右侧会有启动图标 ![alt text](../images/image3.png) ================================================ FILE: docs/usage/zh/02.首次配置.md ================================================ # Snow CLI 使用文档——首次配置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 首次配置 ### 1、在任意目录下进入命令行 1. 键入 `snow` 启动 Snow CLI 或点击 IDE 插件中的启动图标 2. Snow CLI 的首选语言为 `English`，可先前往 `Language Settings` 中修改自己语言偏好 ![alt text](../images/image4.png) ### 2、进入配置界面 设置完语言偏好后进入 `API 和模型设置` ![alt text](../images/image5.png) 配置界面提供了完整的 AI 服务配置功能，支持多配置文件（Profile）管理和丰富的模型参数设置。 ## 配置项详细说明 ### 配置文件管理（Profile） **作用**：管理多套配置方案，方便在不同场景下快速切换 **操作方式**： - 按回车键进入配置文件选择界面 - 使用上下箭头选择配置文件 - 当前激活的配置文件会显示绿色 ✓ 标记 **快捷操作**： - 按 `n` 键：创建新配置文件（需输入配置文件名称） - 按 `d` 键：删除当前配置文件（default 配置文件不可删除） **注意事项**： - 每个配置文件独立保存所有设置项 - 切换配置文件会立即加载该配置文件的所有设置 ### 基础配置 #### Base URL（必填） **作用**：API 服务的基础地址 **配置方式**： - 按回车键进入编辑模式 - 输入完整的 API 地址 - 再次按回车键确认 **标准地址**： ![alt text](../images/image6.png) 1. **OpenAI Chat Completion** ``` https://api.openai.com/v1 ``` 适用于 OpenAI 的标准聊天补全 API 2. **OpenAI Responses** ``` https://api.openai.com/v1 ``` 适用于 OpenAI 的响应式 API，支持推理功能 3. **Gemini** ``` https://generativelanguage.googleapis.com/v1beta ``` Google Gemini API 服务地址 4. **Anthropic** ``` https://api.anthropic.com/v1 ``` Claude 模型的 API 服务地址 **注意事项**： - 支持使用代理或第三方中转服务的地址 - 确保地址格式正确，以 `https://` 开头 - 地址末尾通常包含版本号（如 `/v1`） #### API Key（必填） **作用**：API 服务的访问密钥 **配置方式**： - 按回车键进入编辑模式 - 输入完整的 API Key - 输入时会自动隐藏显示为 `*` 号 - 再次按回车键确认 **注意事项**： - API Key 通常以特定前缀开头（如 OpenAI 的 `sk-`） - 保管好 API Key，避免泄露 - 显示时只会显示星号，不会明文显示 #### Request Method（请求方案） **作用**：选择 API 的调用方式，不同方案支持不同的功能特性 **可选值**： - **OpenAI Chat Completion**：标准的 OpenAI 聊天 API - **OpenAI Responses**：支持推理模式的 OpenAI API - **Gemini**：Google 的 Gemini 模型 - **Anthropic**：Claude 模型 **配置方式**： - 按回车键打开选择列表 - 使用上下箭头选择 - 按回车键确认 **注意事项**： - 不同请求方案会显示不同的高级配置项 - 切换请求方案时，特定功能配置项会自动调整 #### 系统提示词（选填） **作用**：为当前配置文件选择要使用的系统提示词 **可选值**： - **跟随全局（无）**：使用全局设置，当前未激活任何系统提示词 - **跟随全局（名称）**：使用全局设置中激活的系统提示词 - **不使用**：明确禁用系统提示词，即使全局有激活的提示词 - **选择具体提示词**：从已配置的系统提示词列表中选择 **配置方式**： - 按回车键打开选择列表 - 使用上下箭头选择 - 按回车键确认 **说明**： - 系统提示词可以在"系统提示词管理"界面中创建和管理 - Profile 级别的设置会覆盖全局设置 - 选择"不使用"可以在特定场景下临时禁用系统提示词 #### 自定义请求头（选填） **作用**：为当前配置文件选择要使用的自定义请求头方案 **可选值**： - **跟随全局（无）**：使用全局设置，当前未激活任何请求头方案 - **跟随全局（名称）**：使用全局设置中激活的请求头方案 - **不使用**：明确禁用自定义请求头，即使全局有激活的方案 - **选择具体方案**：从已配置的请求头方案列表中选择 **配置方式**： - 按回车键打开选择列表 - 使用上下箭头选择 - 按回车键确认 **说明**： - 自定义请求头方案可以在"自定义请求头管理"界面中创建和管理 - Profile 级别的设置会覆盖全局设置 - 选择"不使用"可以在特定场景下临时禁用自定义请求头 ### 高级配置 #### Enable Auto Compress（自动压缩） **作用**：自动压缩长文本内容，减少 token 消耗 **默认值**：启用 **配置方式**： - 按回车键或空格键切换启用/禁用状态 - 显示 "Enabled" 或 "Disabled" **建议**：启用可降低 API 调用成本，但可能会丢失部分上下文细节 #### Show Thinking（显示思考过程） **作用**：在界面中显示 AI 的思考推理过程 **默认值**：启用 **配置方式**： - 按回车键或空格键切换启用/禁用状态 - 显示 "Enabled" 或 "Disabled" **建议**：启用可了解 AI 的推理过程，有助于调试和理解结果 ### Anthropic 专属配置 当选择 `Anthropic` 请求方案时，会显示以下配置项： #### Anthropic Beta（测试功能） **作用**：启用 Anthropic 的 Beta 版本功能 **默认值**：禁用 **配置方式**： - 按回车键或空格键切换启用/禁用状态 **注意事项**：Beta 功能可能不稳定，请谨慎使用 #### Anthropic Cache TTL（缓存时间） **作用**：设置提示词缓存的有效期 **可选值**： - `5m`：5 分钟 - `1h`：1 小时 **默认值**：5 分钟 **配置方式**： - 按回车键打开选择列表 - 选择缓存时间 - 按回车键确认 **说明**：较长的缓存时间可减少重复内容的 token 消耗 #### Thinking Enabled（扩展思考模式） **作用**：启用 Claude 的扩展思考功能 **默认值**：禁用 **配置方式**： - 按回车键或空格键切换启用/禁用状态 **说明**：启用后 AI 会进行更深入的推理 #### Thinking Budget Tokens（思考预算 Token） **作用**：设置扩展思考模式的最大 token 数量 **默认值**：10000 **取值范围**：最小值 1000 **配置方式**： - 按回车键进入编辑模式 - 输入数字（支持退格删除） - 按回车键确认 **注意事项**： - 思考预算越大，AI 推理越深入，但消耗 token 也越多 - 如果输入值小于最小值，保存时会自动调整为最小值 ### Gemini 专属配置 当选择 `Gemini` 请求方案时，会显示以下配置项： #### Gemini Thinking Enabled（Gemini 思考模式） **作用**：启用 Gemini 的思考推理功能 **默认值**：禁用 **配置方式**： - 按回车键或空格键切换启用/禁用状态 #### Gemini Thinking Budget（思考预算） **作用**：设置 Gemini 思考模式的预算值 **默认值**：1024 **取值范围**：最小值 1 **配置方式**： - 按回车键进入编辑模式 - 输入数字（支持退格删除） - 按回车键确认 ### OpenAI Responses 专属配置 当选择 `OpenAI Responses` 请求方案时，会显示以下配置项： #### Responses Reasoning Enabled（推理模式） **作用**：启用 OpenAI 的推理功能 **默认值**：禁用 **配置方式**： - 按回车键或空格键切换启用/禁用状态 #### Responses Reasoning Effort（推理强度） **作用**：设置推理模式的强度级别 **可选值**： - `LOW`：低强度推理 - `MEDIUM`：中等强度推理 - `HIGH`：高强度推理 - `XHIGH`：超高强度推理（仅 responses 方案支持） **默认值**：HIGH **配置方式**： - 按回车键打开选择列表 - 使用上下箭头选择强度 - 按回车键确认 **注意事项**：推理强度越高，推理过程越深入，但耗时和 token 消耗也越大 ### 模型配置 #### Advanced Model（高级模型） **作用**：用于复杂任务的主力模型 **配置方式**： 1. 按回车键自动获取可用模型列表（需要正确配置 Base URL 和 API Key） 2. 如果获取失败，会自动进入手动输入模式 3. 可以使用字母数字输入进行模糊搜索过滤 4. 选择 "Manual Input" 选项可手动输入模型名称 5. 按 `m` 键快速进入手动输入模式 **常见模型示例**： - OpenAI: `gpt-4`, `gpt-4-turbo`, `gpt-4o` - Claude: `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229` - Gemini: `gemini-2.0-flash-exp`, `gemini-pro` **建议**：选择性能较强的模型用于复杂编程任务 #### Basic Model（基础模型） **作用**：用于简单任务的辅助模型 **配置方式**：与 Advanced Model 相同 **常见模型示例**： - OpenAI: `gpt-3.5-turbo`, `gpt-4o-mini` - Claude: `claude-3-haiku-20240307` - Gemini: `gemini-flash` **建议**：选择响应速度快、成本较低的模型 #### Max Context Tokens（最大上下文令牌） **作用**：模型支持的最大上下文窗口大小 **默认值**：4000 **取值范围**：最小值 4000 **配置方式**： - 按回车键进入编辑模式 - 输入数字（支持退格删除） - 按回车键确认 **常见模型上下文容量**： - Claude 3.5 Sonnet: 200000 - GPT-4 Turbo: 128000 - GPT-4: 8192 - Gemini 2.0 Flash: 1000000 - Gemini Pro: 32768 **注意事项**： - 必须设置为模型实际支持的上下文大小 - 设置过大会导致 API 调用失败 - 设置过小会限制对话长度 #### Max Tokens（最大回复令牌数） **作用**：单次响应允许生成的最大 token 数量 **默认值**：4096 **取值范围**：最小值 100 **配置方式**： - 按回车键进入编辑模式 - 输入数字（支持退格删除） - 按回车键确认 **常见模型输出容量**： - Claude 3.5 Sonnet: 64000 - GPT-4 Turbo: 4096 - GPT-4: 8192 - Gemini 2.0 Flash: 8192 **注意事项**： - 不同模型支持的最大输出 token 数不同 - 设置过大会增加响应时间和成本 - 建议根据实际需求合理设置 ## 配置界面操作说明 ### 基本操作 - **上下箭头**：在配置项之间移动 - **回车键**：进入编辑模式或确认输入 - **Esc 键**：保存配置并退出 - **Ctrl+S / Cmd+S**：快速保存配置 - **空格键**：切换开关类配置项（如 Enable/Disable） ### 导航提示 - 配置界面顶部显示当前位置：`(当前项/总项数)` - 配置项超过 8 项时，会自动滚动显示 - 当前选中的配置项会显示 `❯` 标记 ### 模型选择增强功能 在模型选择界面中： - **字母数字输入**：实时过滤模型列表 - **Backspace**：删除过滤字符 - **Esc 键**：退出选择界面 - **m 键**：快速进入手动输入模式 ### 数字输入增强 在编辑 token 相关配置时： - **数字键**：追加数字 - **Backspace/Delete**：删除最后一位数字 - **回车键**：确认并自动校验最小值 ## 配置验证 保存配置时系统会自动验证： 1. **必填项检查**：Base URL 和 API Key 必须填写 2. **格式验证**：检查 Base URL 格式是否正确 3. **数值范围**：自动调整 token 配置到最小值以上 4. **请求方案匹配**：验证所选模型与请求方案的兼容性 **错误提示**： - 验证失败时会在界面底部显示红色错误信息 - 修复错误后可再次尝试保存 ## 配置文件存储 - **主配置文件**：`~/.snowcli/config.json` - **配置文件目录**：`~/.snowcli/profiles/` - **自动保存**：退出配置界面时自动保存到当前激活的配置文件 ## 常见问题 ### 1. 无法获取模型列表？ **解决方案**： - 检查 Base URL 和 API Key 是否正确 - 检查网络连接和代理设置 - 如果持续失败，使用手动输入模式（按 `m` 键） ### 2. 配置保存后不生效？ **解决方案**： - 确认已按 Esc 或 Ctrl+S 保存配置 - 重启 Snow CLI 确保配置加载 - 检查是否选择了正确的配置文件（Profile） ### 3. Token 超限错误？ **解决方案**： - 检查 Max Context Tokens 是否设置正确 - 确认是否超过模型实际支持的上下文大小 - 适当减少 Max Tokens 设置 ### 4. 切换请求方案后配置丢失？ **说明**：不同请求方案的专属配置项（如 Anthropic 的 Thinking 功能）会根据当前方案自动显示/隐藏，配置值仍然保存，切换回来会恢复。 ## 配置最佳实践 1. **首次配置**：先设置 Basic 配置（Base URL、API Key、Request Method），再配置高级功能 2. **多场景使用**：为不同项目创建不同的配置文件（Profile） 3. **成本优化**：合理设置 Max Tokens，启用 Auto Compress 功能 4. **性能优化**：根据任务复杂度选择合适的模型，简单任务使用 Basic Model 5. **调试建议**：启用 Show Thinking 查看 AI 推理过程，便于理解和优化提示词 ================================================ FILE: docs/usage/zh/03.代理和浏览器设置.md ================================================ # Snow CLI 使用文档——首次配置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 代理和浏览器设置 * 启用代理时，CLI的流量会通过自定义的端口传输 * 浏览器设置：CLI 的联网搜索功能会使用浏览器，默认会自动检测系统浏览器路径（Windows/macOS/Linux）。 * 如果默认浏览器更换了安装位置，或在 Linux 上未安装 Chromium/Chrome，需手动指定浏览器路径。 * 常见报错 `Failed to launch the browser process` 通常表示浏览器未安装或依赖缺失。建议先安装 `chromium` 或 `google-chrome`，并在设置里填写可执行文件路径。 * 配置文件路径：`~/.snow/proxy-config.json`，可手动设置 `browserPath`。 ================================================ FILE: docs/usage/zh/04.代码库设置.md ================================================ # Snow CLI 使用文档——代码库设置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 代码库设置 Snow CLI 支持启用本地代码库功能。 _代码库是一个基于向量搜索的 Sqlite 数据库，用于存储代码库的源代码和注释。并通过向量化自然语言查询。_ ## 配置存储 代码库配置分为两部分： - **项目级配置** (`.snow/codebase.json`)：存储在项目根目录，控制当前项目的启停状态、索引参数、重排序配置等 - **全局配置** (`~/.snow/codebase.json`)：存储 Embedding 服务配置，跨项目共享 这样每个项目可以独立控制代码库功能的启停，而 Embedding 配置只需配置一次。 ## 快速启停 使用 `/codebase` 命令可以快速控制当前项目的代码库功能： - `/codebase` - 切换启停状态 - `/codebase on` - 启用代码库 - `/codebase off` - 禁用代码库 - `/codebase status` - 查看当前状态 首次启用时，需要先在 `/home` 中配置 Embedding 服务。 ## 配置界面 在 `/home` → 代码库配置中，设置项按折叠分组排列，节约显示空间： ``` 启用代码库: ← 总开关 Agent 审查: ← 搜索结果 AI 审查（与重排序互斥） 结果重排序: ← 搜索结果重排序（与 Agent 审查互斥） ▶ 嵌入模型配置 ← 按 Enter 展开/收起 ▶ 重排序模型配置 ← 按 Enter 展开/收起 ▶ 批处理设置 ← 按 Enter 展开/收起 ``` 使用 ↑↓ 导航，Enter 编辑/切换/展开，Ctrl+S 或 Esc 保存。 ## 搜索结果优化 代码库搜索返回结果后，有两种优化方式可选（**二者互斥，不能同时开启**）： ### Agent 审查 使用 AI 模型（basicModel）对搜索结果进行语义审查，过滤不相关的结果，并可能建议更好的搜索关键词。适合需要深度理解代码语义的场景。 - 支持多轮重试和关键词建议 - 可识别高置信度文件进行深度探索 - 依赖已配置的 AI 模型（basicModel / advancedModel） ### 结果重排序（Reranking） 使用专用的 Rerank 模型对搜索结果按相关性重新排序，取 Top N 返回。相比 Agent 审查更轻量高效，适合追求速度的场景。 - 调用标准 Rerank API（兼容 Jina Reranker、Cohere Rerank 等） - 内置 3 次失败重试（指数退避） - 内置上下文长度防护：使用 tiktoken 精确计算 token，超长文档自动截断或丢弃，防止爆上下文 - 失败时自动降级为原始搜索结果 **互斥规则**：开启「结果重排序」会自动关闭「Agent 审查」，反之亦然。启用重排序前需要先配置重排序模型，否则无法切换。 ## Embedding 服务配置 在「▶ 嵌入模型配置」中展开设置： - 代码库支持三种请求方案：Jina（OpenAI 兼容）、Ollama（本地部署，支持 OpenAI 兼容 `/v1/embeddings` 与原生 `/api/embed`）和 Gemini。 - 代码库的 BaseURL（支持多种写法，程序会自动补全/规范化到最终端点）： - Jina（OpenAI 兼容）支持：`https://api.jina.ai`、`https://api.jina.ai/v1`、`https://api.jina.ai/v1/embeddings`（最终请求 `.../v1/embeddings`）。 - Ollama 支持：`http://localhost:11434`、`http://localhost:11434/v1`、`http://localhost:11434/v1/embeddings`（OpenAI 兼容）；以及 `http://localhost:11434/api`、`http://localhost:11434/api/embed`（Ollama 原生）。 - 嵌入维度：填写嵌入模型支持的维度即可；部分服务可能忽略 `dimensions` 参数，若返回维度不一致会在日志中提示。 ## 重排序模型配置 在「▶ 重排序模型配置」中展开设置： | 配置项 | 说明 | 默认值 | |--------|------|--------| | 模型名 | Rerank 模型名称，如 `jina-reranker-v2-base-multilingual` | — | | Base URL | Rerank API 地址，如 `https://api.jina.ai`（自动补全为 `/v1/rerank`） | — | | API 密钥 | API 认证密钥（可选，本地部署可留空） | — | | 模型上下文长度 | 模型支持的最大上下文 token 数，用于防止请求超限 | 4096 | | Top N | 重排序后返回前 N 个最相关的结果 | 5 | **上下文长度防护机制**：发送请求前会使用 tiktoken 精确计算所有文档的 token 总量。单个文档超过上下文 30% 会被截断；累计超出上下文窗口的文档会被丢弃。确保请求不会超出模型限制。 ## 索引参数配置 在「▶ 批处理设置」中展开设置： - 分块配置：配置代码如何分割成块以进行索引。这些设置控制代码段的大小和重叠： - `maxLinesPerChunk`：每个分块的最大行数（默认：200） - `minLinesPerChunk`：每个分块的最小行数（默认：10） - `minCharsPerChunk`：每个分块的最小字符数（默认：20） - `overlapLines`：连续分块之间的重叠行数（默认：20） 这些设置影响搜索准确性和索引性能。 - 批处理配置：控制文件如何分批处理以提高索引效率： - `maxLines`：每个批处理请求的最大行数（默认：10） - `concurrency`：并发批处理操作数（默认：3） 这控制每次请求发送到嵌入 API 的 `input` 项数量。 **注意：批处理最大行数代表请求体中的 `input` 数，而非代码切片的行数** ## 相关功能 启用代码库索引后，以下功能会得到显著增强： - [漏洞猎人模式](./11.漏洞猎人模式.md) - 代码库索引可以大幅提升安全分析的准确性和效率 - [指令面板说明](./09.指令面板说明.md) - 使用 `/reindex` 重建代码库索引，使用 `/codebase` 控制启停 ================================================ FILE: docs/usage/zh/05.子代理设置.md ================================================ # Snow CLI 使用文档——子代理设置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是子代理 子代理是 Snow CLI 中主流程的分支，专门用于处理特定的单一需求以节约主流程的上下文占用 ## 系统自带三个子代理 - Explore Agent——探索代理，用于为主流程搜索代码功能，专注查找代码位置 - Plan Agent——计划代理，用于为主流程制定全面的编码计划与指导 - General Purpose Agent——通用代理，用于为主流程提供通用的编码功能，可用于完成单一但是文件量较大的需求，例如（国际化） ## 子代理的工作流程 ```mermaid graph TB Start([用户发起任务]) --> MainProcess[主流程 Main Agent] MainProcess --> Check{是否需要
使用子代理?} Check -->|否| DirectHandle[主流程直接处理] DirectHandle --> End([返回结果]) Check -->|是| SelectAgent{选择子代理类型} SelectAgent -->|代码探索| ExploreAgent[Explore Agent
探索代理] SelectAgent -->|制定计划| PlanAgent[Plan Agent
计划代理] SelectAgent -->|通用编码| GeneralAgent[General Purpose Agent
通用代理] ExploreAgent --> SendTask[主流程发送任务提示词] PlanAgent --> SendTask GeneralAgent --> SendTask SendTask --> SubProcess[子代理接收任务] SubProcess --> Isolate[独立上下文环境
与主流程隔离] Isolate --> SpecializedWork{专业方向处理} SpecializedWork -->|探索代理| SearchCode[搜索代码位置
分析代码结构] SpecializedWork -->|计划代理| MakePlan[制定编码计划
提供指导方案] SpecializedWork -->|通用代理| GeneralWork[执行通用编码
处理批量文件] SearchCode --> Complete[处理完成] MakePlan --> Complete GeneralWork --> Complete Complete --> Return[将结果发送回主流程] Return --> MainReceive[主流程接收结果] MainReceive --> End style MainProcess fill:#e1f5ff style ExploreAgent fill:#fff4e1 style PlanAgent fill:#ffe1f5 style GeneralAgent fill:#e1ffe1 style Isolate fill:#ffe1e1 style SubProcess fill:#f0f0f0 style Return fill:#e1ffe1 ``` ### 流程说明 1. **主流程评估**: 主流程接收到用户任务后，首先评估是否需要使用子代理 2. **子代理选择**: 根据任务类型选择合适的子代理： - **Explore Agent**: 深度代码探索（5+文件）、复杂依赖追踪 - **Plan Agent**: 复杂功能拆解、重大重构规划 - **General Purpose Agent**: 批量修改（5+文件）、系统性重构 3. **任务派发**: 主流程向子代理发送包含完整上下文的任务提示词 4. **独立处理**: 子代理在独立的上下文环境中处理任务，与主流程完全隔离 5. **专业处理**: 每个子代理根据自己的专业方向进行针对性处理 6. **结果返回**: 处理完成后，子代理将结果发送回主流程 7. **主流程继续**: 主流程接收结果并继续后续工作 ### 关键特点 - **上下文隔离**: 子代理拥有独立的上下文，不会影响主流程的对话历史 - **单向通信**: 主流程 → 发送任务 → 子代理 → 返回结果 → 主流程 - **专业分工**: 每个子代理专注于特定领域，提高处理效率 - **资源节约**: 避免主流程上下文被大量探索或计划信息占用 ## 子代理配置管理 ### 新增子代理 通过配置界面可以创建自定义子代理，满足特定的业务需求。 #### 操作步骤 1. **进入配置界面** - 在主菜单中选择"子代理配置"选项 - 选择"新增子代理" 2. **基础信息配置** 按照界面提示依次填写以下字段： - **代理名称** (必填) - 输入子代理的名称 - 建议使用描述性名称，如 "代码审查代理"、"测试代理" 等 - 按 Enter 确认进入下一字段 - **描述** (必填) - 输入子代理的功能描述 - 详细说明该子代理的用途和应用场景 - 按 Enter 确认进入下一字段 - **角色定义** (必填) - 定义子代理的角色和行为规范 - 这是子代理的核心系统提示词，决定其工作方式 - 示例： ``` 你是一个专业的代码审查助手。 你的职责是： 1. 检查代码质量和规范性 2. 发现潜在的bug和安全问题 3. 提供改进建议和最佳实践 ``` - 按 Enter 确认进入下一字段 3. **高级配置选项** **重要提醒**: 子代理不再单独选择「系统提示词」和「自定义请求头」。子代理的系统提示词与请求头会跟随所选的**配置文件**（Profile），配置文件本身已经包含这两项配置。 - **配置文件** (可选) - 为子代理指定专属的 API 配置文件 - 用途：让子代理使用不同的 API 端点、不同的 AI 模型，以及该配置文件内定义的系统提示词与请求头 - 操作： - 使用 ↑/↓ 方向键浏览可用的配置文件 - 按 Space 键选中/取消选中 - 按 ←/→ 方向键在配置选项间快速切换 - 标记说明：`❯` 表示光标位置，`[✓]` 表示已选中 - 应用场景： - 让子代理使用更强大的模型 - 让子代理使用不同的 API 提供商 - 为不同子代理分配不同的计费账户 - 为不同子代理绑定不同的系统提示词/请求头 选择子代理可以使用的工具： - 使用 ↑/↓ 方向键在工具类别间导航 - 使用 ←/→ 方向键在工具类别间切换 - 按 Space 键选中/取消选中工具 - 工具类别包括： - 文件系统工具 (filesystem-read, filesystem-create, filesystem-edit 等) - ACE 代码搜索工具（`ace-search`，通过 action 选择 find_definition / find_references / semantic_search / file_outline / text_search） - 代码库工具 (codebase-search) - 终端工具 (terminal-execute) - TODO 管理工具 - Web 搜索工具 - MCP 工具（如已配置） **建议**: 只授予子代理完成其任务所需的最小权限集 4. **保存配置** - 按 Ctrl+S 保存配置 - 系统会自动验证配置的完整性 - 保存成功后返回主菜单 #### 配置继承说明 新建子代理时，如果未指定 **配置文件**（Profile），子代理将自动跟随当前主流程激活的配置文件。这意味着： - 子代理将使用与主流程相同的 API 配置与模型 - 子代理将使用该配置文件内定义的系统提示词与请求头（再叠加自身的角色定义） ### 编辑子代理 可以编辑现有的子代理配置，包括系统内置的三个代理。 #### 操作步骤 1. **进入编辑界面** - 在主菜单中选择"子代理配置"选项 - 选择要编辑的子代理 2. **编辑限制说明** **系统内置代理**（Explore Agent、Plan Agent、General Purpose Agent）： - 名称、描述、角色定义为只读，不可修改 - 界面会显示"(系统内置 - 不可修改)"提示 - 可以修改：工具权限、配置文件 **自定义代理**： - 所有字段均可修改 3. **修改配置** 导航和操作方式与新增代理相同： - 使用 ↑/↓ 方向键在字段间导航 - 使用 ←/→ 方向键在配置选项间切换 - 按 Space 键选中/取消选中 - 在文本字段中直接输入修改内容 4. **保存更改** - 按 Ctrl+S 保存更改 - 系统会验证修改后的配置 - 保存成功后返回主菜单 #### 编辑配置继承说明 编辑已有子代理时： - 如果子代理已有自定义配置，界面会显示并加载这些配置 - 如果子代理没有自定义配置： - 编辑系统内置代理的副本时，会自动继承当前主流程的配置作为默认值 - 编辑已有的自定义代理时，不会自动填充配置（保持未选中状态） ### 配置最佳实践 1. **角色定义要明确** - 清楚描述子代理的职责范围 - 提供具体的工作步骤或检查清单 - 说明输出格式和质量标准 2. **合理分配工具权限** - 遵循最小权限原则 - 只读任务不授予写入工具 - 探索任务不授予执行工具 3. **善用配置隔离** - 为不同类型的任务配置不同的子代理 - 使用不同的配置文件（Profile）控制成本与模型选择 - 使用不同的配置文件（Profile）绑定不同的系统提示词与请求头 4. **测试配置效果** - 创建后先进行小规模测试 - 观察子代理的行为是否符合预期 - 根据实际效果调整角色定义和工具权限 ### 键盘快捷键 - **↑/↓**: 在选项间导航或滚动列表 - **←/→**: 在字段间切换（配置选项、工具类别） - **Space**: 选中/取消选中（工具、配置选项） - **Enter**: 确认输入并移至下一字段 - **Ctrl+S**: 保存配置 - **Ctrl+C** 或 **ESC**: 取消并返回 ## 快速选择子代理 除了使用 `/agent-` 指令打开子代理选择面板外，您还可以直接在输入框中使用 `#` 符号快速触发子代理选择器： ### 使用方法 1. **触发选择器**: 在输入框中输入 `#`，会自动弹出子代理选择面板 2. **搜索过滤**: 输入 `#关键字` 可以根据子代理的 ID、名称或描述进行过滤 3. **选择子代理**: 使用方向键选择子代理，按 Enter 确认，系统会自动插入 `#子代理ID ` 到输入框 ### 示例 ``` #explore → 选择 explore 子代理 #plan → 选择 plan 子代理 #general → 选择 general 子代理 ``` ### 注意事项 - `#` 符号前面不能有 `@` 符号（如 `@#` 或 `@@#` 不会触发子代理选择器，而是触发文件选择器） - 输入 `#` 后如果继续输入空格或换行，选择器会自动关闭 - 按 ESC 键可以关闭子代理选择面板 ## 向运行中的子代理发送消息 当子代理正在运行时，您可以使用 `>>` 指令向特定的运行中子代理发送消息，实现与主流程的实时交互。 ### 使用方法 1. **触发选择器**: 在输入框开头输入 `>>`（可以带前导空格），会弹出当前运行中的子代理列表 2. **选择子代理**: - 使用 `↑/↓` 方向键选择子代理 - 使用 `Space` 键选中/取消选中子代理（支持多选） - 如果没有显式选择任何子代理，当前高亮项会在按 Enter 时自动被选中 3. **发送消息**: 按 `Enter` 确认选择，输入消息内容后发送 ### 视觉标签说明 选择子代理后，输入框中会显示视觉标签： ``` [»Explore Agent#abcd: 调查项目架构和结构...] 你好，请继续分析 ``` - `»` 符号（U+00BB）：用于避免重新触发选择器 - `Explore Agent`：子代理名称 - `#abcd`：实例 ID 后 4 位（保证唯一性） - `调查项目架构和结构...`：任务提示词的简短摘要 ### 消息路由机制 实际发送的消息中会包含特殊标记： ``` # SubAgentTarget:instanceId:agentName 消息内容 ``` 系统会根据这些标记将消息路由到对应的子代理。 ### 使用场景 - **追问细节**：子代理正在探索代码时，您想询问某个具体函数的实现 - **纠正方向**：发现子代理理解有误，及时发送纠正信息 - **补充上下文**：突然想起某些重要信息，需要告知正在工作的子代理 - **批量指令**：同时向多个运行中的子代理发送相同指令 ### 注意事项 - `>>` 必须出现在输入框**开头**（忽略前导空格）才能触发 - 如果子代理已完成或退出，它将不会出现在选择列表中 - 按 `ESC` 键可以关闭选择面板 - 删除 `>>` 后，选择面板会自动关闭 ### 常见问题 **Q: 为什么我输入 `#` 没有弹出选择器？** A: 请检查以下几点： - 确认 `#` 前面没有 `@` 符号（如 `@#` 会触发文件选择器而非子代理选择器） - 确认 `#` 后面没有输入空格或换行 - 检查是否已配置子代理 **Q: 子代理可以使用主流程的上下文吗？** A: 不可以。子代理与主流程的上下文完全隔离。主流程需要在调用子代理时，在提示词中提供所有必要的上下文信息。 **Q: 如何让子代理使用更强大的模型？** A: 在配置文件选项中，为子代理指定一个使用更强大模型的 API 配置文件即可。 **Q: 配置文件里的系统提示词和子代理的角色定义有什么区别？** A: 角色定义是子代理自身的行为规范（配置子代理时填写/编辑），用于描述这个子代理要怎么工作。配置文件（Profile）中的系统提示词是该 Profile 的全局约束，会同时影响主流程与选择了该 Profile 的子代理。子代理执行时会以所选 Profile 的系统提示词为基础，再叠加子代理的角色定义。 **Q: 编辑系统内置代理会影响原始配置吗？** A: 不会。系统内置代理的核心定义（名称、描述、角色）是只读的。您只能修改其工具权限和配置文件（Profile），这些修改只影响您的使用，不会改变系统预设。 **Q: 如何删除自定义子代理？** A: 在子代理列表中选择要删除的子代理，按 Delete 键或选择删除选项即可。系统内置代理无法删除。 ================================================ FILE: docs/usage/zh/06.敏感命令配置.md ================================================ # Snow CLI 使用文档——敏感命令配置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是敏感命令 敏感命令是指在执行时可能对系统、数据或项目产生重大影响的命令。这些命令在执行前需要用户明确确认，以防止意外操作导致的数据丢失或系统损坏。 Snow CLI 默认内置了一系列常见的敏感命令模式，并支持用户自定义添加需要保护的命令。 ## 为什么需要敏感命令配置 在使用 AI 驱动的命令行工具时，AI 可能会建议执行某些具有破坏性的命令。敏感命令配置功能可以： - 防止意外执行危险命令（如 `rm -rf`、`git reset --hard` 等） - 在执行重要操作前给予用户确认机会 - 提供可自定义的命令保护机制 - 保护项目和数据安全 ## 系统内置的敏感命令 Snow CLI 默认保护以下类型的命令： ### 文件系统操作 - `rm -rf` - 递归强制删除 - `rmdir /s` - Windows 递归删除目录 - `del /f` - Windows 强制删除 ### Git 操作 - `git reset --hard` - 硬重置（丢弃所有更改） - `git clean -fd` - 删除未跟踪的文件和目录 - `git push --force` - 强制推送 - `git branch -D` - 强制删除分支 - `git rebase` - 变基操作 - `git checkout` - 分支切换（可能丢失未提交的更改） ### 系统管理 - `sudo rm` - 以管理员权限删除 - `chmod -R` - 递归修改文件权限 - `chown -R` - 递归修改文件所有者 ### 数据库操作 - `DROP DATABASE` - 删除数据库 - `DROP TABLE` - 删除表 - `TRUNCATE` - 清空表数据 ## 敏感命令配置管理 ### 进入配置界面 1. 启动 Snow CLI 2. 在主菜单中选择"敏感命令配置"选项 3. 进入敏感命令配置界面 ### 查看敏感命令列表 配置界面会显示所有已配置的敏感命令，包括： - 命令模式（支持正则表达式） - 命令描述 - 启用/禁用状态 - 是否为系统内置命令 界面特点： - 使用 `[✓]` 标记已启用的命令 - 使用 `[ ]` 标记已禁用的命令 - 自定义命令会显示 `(自定义)` 标记 - 支持滚动浏览，最多同时显示 13 条命令 ### 启用或禁用命令保护 可以根据需要启用或禁用特定命令的保护。 #### 操作步骤 1. **导航到目标命令** - 使用 ↑/↓ 方向键在命令列表中移动 - 当前选中的命令会高亮显示 2. **切换启用状态** - 按 Space 键切换选中命令的启用/禁用状态 - 系统会显示操作成功提示（2 秒后自动消失） 3. **查看命令详情** - 列表下方会显示当前选中命令的描述 - 显示命令的启用状态 - 如果是自定义命令，会显示 `[自定义]` 标记 ### 添加自定义敏感命令 除了系统内置的敏感命令，您可以添加自己的敏感命令模式。 #### 操作步骤 1. **进入添加模式** - 在命令列表界面按 A 键 - 进入"添加自定义敏感命令"界面 2. **填写命令模式** - 在"命令模式"字段输入要保护的命令 - 支持正则表达式匹配 - 示例： - `npm uninstall` - 精确匹配 - `^docker rm` - 以 docker rm 开头的命令 - `.*--force.*` - 包含 --force 参数的命令 - 按 Enter 或 Tab 键进入下一字段 3. **填写命令描述** - 在"描述"字段输入命令的说明 - 建议清楚描述该命令的危险性或影响 - 示例： - "卸载 npm 包" - "强制删除 Docker 容器" - "包含强制执行参数的命令" - 按 Enter 键提交 4. **完成添加** - 系统验证输入后保存自定义命令 - 显示添加成功提示 - 自动返回命令列表界面 - 新添加的命令默认为启用状态 #### 命令模式编写技巧 1. **精确匹配** ``` git reset --hard ``` 只匹配完全相同的命令 2. **前缀匹配** ``` ^npm uninstall ``` 匹配以 "npm uninstall" 开头的所有命令 3. **包含匹配** ``` .*--force.* ``` 匹配包含 "--force" 的所有命令 4. **多选项匹配** ``` git (reset|clean|push --force) ``` 匹配多个相关的 git 操作 ### 删除自定义敏感命令 可以删除不再需要的自定义敏感命令。注意：系统内置命令无法删除。 #### 操作步骤 1. **选择要删除的命令** - 使用 ↑/↓ 方向键选择自定义命令 - 只有标记为 `(自定义)` 的命令可以删除 2. **请求删除** - 按 D 键请求删除 3. **确认删除** - 再次按 D 键确认删除 - 或按 ESC 键取消删除 - 删除成功后显示提示消息 - 光标自动移动到下一个命令 #### 注意事项 - 系统内置命令无法删除（不会响应 D 键） - 需要二次确认才能删除，防止误操作 - 删除操作不可恢复，请谨慎操作 ### 重置为默认配置 如果您对配置进行了大量修改，可以一键重置为系统默认配置。 #### 操作步骤 1. **请求重置** - 在命令列表界面按 R 键 - 系统会显示确认提示： ``` 确认重置为默认配置? 所有自定义命令将被删除，再次按 R 键确认，按 ESC 取消 ``` 2. **确认重置** - 再次按 R 键确认重置 - 或按 ESC 键取消重置 - 重置成功后显示提示消息 3. **重置效果** - 删除所有自定义命令 - 恢复所有系统内置命令为启用状态 - 配置立即生效 #### 注意事项 - 重置操作会删除所有自定义命令 - 重置操作不可恢复 - 需要二次确认才能执行 - 建议在重置前记录重要的自定义配置 ## 键盘快捷键 ### 命令列表界面 - **↑/↓**: 在命令列表中导航 - **Space**: 启用/禁用选中的命令 - **A**: 添加自定义敏感命令 - **D**: 删除自定义命令（需要二次确认） - **R**: 重置为默认配置（需要二次确认） - **ESC**: 返回主菜单或取消确认操作 ### 添加命令界面 - **Tab**: 在输入字段间切换 - **Enter**: 确认输入并移至下一字段（最后一个字段为提交） - **ESC**: 取消添加并返回列表界面 ## 配置最佳实践 ### 1. 保护关键操作 确保以下类型的命令受到保护： - 删除操作（文件、目录、数据库） - Git 破坏性操作（reset、clean、force push） - 权限修改操作 - 批量操作命令 ### 2. 合理使用正则表达式 - 避免过于宽泛的匹配模式（如 `.*`），可能导致所有命令都需要确认 - 使用精确的前缀或关键字匹配 - 测试正则表达式以确保只匹配预期的命令 ### 3. 清晰的命令描述 - 描述应该说明命令的作用和潜在风险 - 帮助您在确认时快速理解命令的影响 - 例如："强制删除所有未跟踪的文件，不可恢复" ### 4. 定期审查配置 - 定期检查已配置的敏感命令 - 删除不再需要的自定义规则 - 根据项目需求调整保护范围 ### 5. 团队协作建议 如果在团队环境中使用： - 分享常用的自定义敏感命令配置 - 统一团队的命令保护标准 - 培训团队成员理解敏感命令的重要性 ## 敏感命令的工作原理 当 AI 建议执行命令时，Snow CLI 会： 1. **检查命令是否匹配敏感模式** - 遍历所有已启用的敏感命令规则 - 使用正则表达式匹配命令内容 2. **触发确认流程** - 如果命令匹配任何敏感模式 - 暂停执行并显示确认对话框 - 显示命令内容和警告信息 3. **等待用户决策** - 用户可以选择执行或取消 - 取消后 AI 会收到反馈，可能建议替代方案 - 执行后命令正常运行 4. **不匹配则直接执行** - 如果命令不匹配任何敏感模式 - 直接执行，无需额外确认 ## 常见问题 **Q: 敏感命令配置会影响所有项目吗？** A: 是的。敏感命令配置是全局的，应用于所有使用 Snow CLI 的项目。这样可以确保一致的安全保护。 **Q: 我可以临时禁用某个敏感命令保护吗？** A: 可以。进入敏感命令配置界面，找到对应的命令并按 Space 键禁用。完成操作后，建议重新启用保护。 **Q: 正则表达式匹配是否区分大小写？** A: 这取决于您的正则表达式编写方式。如果需要不区分大小写，可以使用不区分大小写的模式或同时匹配大小写变体。 **Q: 如果我不小心删除了自定义命令怎么办？** A: 删除操作不可恢复，但您可以重新添加该命令。建议记录重要的自定义配置，或定期备份配置文件。 **Q: 敏感命令保护可以完全阻止命令执行吗？** A: 不可以。敏感命令保护只是提供确认提示，最终是否执行由用户决定。这是为了在保证安全的同时保持灵活性。 **Q: 系统内置的命令可以永久删除吗？** A: 不可以，但您可以禁用它们。如果需要恢复，使用"重置为默认配置"功能即可。 **Q: 添加自定义命令后需要重启 Snow CLI 吗？** A: 不需要。配置修改立即生效，会在下一次 AI 建议执行命令时应用。 ## 配置文件位置 敏感命令配置存储在 Snow CLI 的配置目录中： - Windows: `%USERPROFILE%\.snow\sensitive-commands.json` - macOS/Linux: `~/.snow/sensitive-commands.json` 您可以直接编辑该文件进行批量配置，但建议使用配置界面以确保格式正确。 ## 相关功能 - [命令注入模式](./10.命令注入模式.md) - 在消息中直接执行命令，同样受敏感命令保护 ================================================ FILE: docs/usage/zh/07.Hooks配置.md ================================================ # Snow CLI 使用文档——Hooks 配置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是 Hooks Hooks 是 Snow CLI 提供的强大扩展机制，允许您在 AI 工作流程的关键节点自动执行自定义命令或触发交互式提示。通过 Hooks，您可以： - 在特定时机自动执行脚本或命令 - 实现工作流程的自动化 - 集成外部工具和服务 - 在关键操作前后进行验证或记录 - 在工作流程结束时触发交互式提示 ## Hooks 工作流程 ```mermaid graph TB Start([AI 工作流程开始]) --> UserMsg{用户发送消息} UserMsg -->|触发| Hook1[onUserMessage Hook] Hook1 --> CheckMatch1{匹配规则?} CheckMatch1 -->|是| Execute1[执行 Hook Actions] CheckMatch1 -->|否| Continue1[继续流程] Execute1 --> Continue1 Continue1 --> AIProcess[AI 处理消息] AIProcess --> ToolCall{AI 调用工具?} ToolCall -->|是| Hook2[beforeToolCall Hook] Hook2 --> CheckMatch2{匹配工具名称?} CheckMatch2 -->|是| Execute2[执行 Hook Actions] CheckMatch2 -->|否| Continue2[继续调用] Execute2 --> Continue2 Continue2 --> NeedConfirm{需要用户确认?} NeedConfirm -->|是| Hook3[toolConfirmation Hook] Hook3 --> CheckMatch3{匹配工具名称?} CheckMatch3 -->|是| Execute3[执行 Hook Actions] CheckMatch3 -->|否| UserConfirm[用户确认] Execute3 --> UserConfirm UserConfirm --> ToolExec[执行工具] NeedConfirm -->|否| ToolExec ToolExec --> Hook4[afterToolCall Hook] Hook4 --> CheckMatch4{匹配工具名称?} CheckMatch4 -->|是| Execute4[执行 Hook Actions] CheckMatch4 -->|否| Continue4[继续流程] Execute4 --> Continue4 Continue4 --> MoreTools{还有更多工具?} MoreTools -->|是| ToolCall MoreTools -->|否| AIResponse[AI 生成响应] ToolCall -->|否| AIResponse AIResponse --> SubAgent{调用子代理?} SubAgent -->|是| SubProcess[子代理处理] SubProcess --> Hook5[onSubAgentComplete Hook] Hook5 --> CheckMatch5{匹配规则?} CheckMatch5 -->|是| Execute5[执行 Hook Actions
可能是 Prompt] CheckMatch5 -->|否| Continue5[继续流程] Execute5 --> Continue5 Continue5 --> CheckCompress SubAgent -->|否| CheckCompress{需要压缩上下文?} CheckCompress -->|是| Hook6[beforeCompress Hook] Hook6 --> Execute6[执行 Hook Actions] Execute6 --> Compress[执行压缩] Compress --> End CheckCompress -->|否| End([流程结束]) End --> Hook7[onStop Hook] Hook7 --> Execute7[执行 Hook Actions
可能是 Prompt] Execute7 --> FinalEnd([最终结束]) style Hook1 fill:#ffe1e1 style Hook2 fill:#e1f5ff style Hook3 fill:#fff4e1 style Hook4 fill:#e1ffe1 style Hook5 fill:#ffe1f5 style Hook6 fill:#f5e1ff style Hook7 fill:#ffe1e1 style Execute1 fill:#ffcccc style Execute2 fill:#ccecff style Execute3 fill:#fff0cc style Execute4 fill:#ccffcc style Execute5 fill:#ffccf5 style Execute6 fill:#f0ccff style Execute7 fill:#ffcccc ``` ## Hook 类型说明 Snow CLI 提供 8 种 Hook 类型，每种类型在不同的时机触发： ### 1. onSessionStart **触发时机**: 当启动新会话或恢复现有会话时 **应用场景**: - 初始化工作环境 - 检查依赖和配置 - 加载项目特定的设置 - 记录会话开始时间 **示例**: ```json { "onSessionStart": [ { "description": "检查开发环境", "hooks": [ { "type": "command", "command": "node --version && npm --version", "timeout": 5000, "enabled": true } ] } ] } ``` ### 2. onUserMessage **触发时机**: 用户发送消息时 **上下文参数**: ```json { "message": "用户输入的消息内容", "imageCount": 2, // 用户上传的图片数量 "source": "normal" // 消息来源: "normal" 或 "pending" } ``` **应用场景**: - 记录用户请求 - 预处理用户输入 - 触发特定的监控或统计 - 根据消息内容执行自动化任务 **stdin 示例**: ```json { "onUserMessage": [ { "description": "记录用户消息", "hooks": [ { "type": "command", "command": "node -e \"const d = JSON.parse(require('fs').readFileSync(0, 'utf-8')); console.log('User:', d.message.substring(0, 50))\"", "timeout": 3000, "enabled": true } ] } ] } ``` ### 3. beforeToolCall **触发时机**: 在 AI 调用工具之前（支持工具匹配） **特殊功能**: 支持 `matcher` 字段匹配特定工具名称 **上下文参数**: ```json { "toolName": "filesystem-edit", // 工具名称 "args": { // 工具参数 "filePath": "src/index.ts", "startLine": 10, "endLine": 20, "newContent": "..." } } ``` **应用场景**: - 在文件操作前进行备份 - 在执行命令前进行环境检查 - 记录工具调用历史 - 针对特定工具的预处理 **Matcher 语法**: - 精确匹配: `filesystem-read` - 通配符匹配: `filesystem-*` (匹配所有文件系统工具) - 多个工具: `filesystem-read,filesystem-edit` (逗号分隔) **stdin 示例**: ```json { "beforeToolCall": [ { "matcher": "filesystem-edit,filesystem-create", "description": "文件修改前自动备份", "hooks": [ { "type": "command", "command": "git add . && git commit -m \"Auto backup before file changes\"", "timeout": 10000, "enabled": true } ] } ] } ``` ### 4. toolConfirmation **触发时机**: 工具二次确认时（包括敏感命令检查） **特殊功能**: 支持 `matcher` 字段匹配特定工具名称 **应用场景**: - 在用户确认敏感操作前执行额外检查 - 记录需要确认的操作 - 发送通知给团队成员 - 针对特定工具的确认前处理 **示例**: ```json { "toolConfirmation": [ { "matcher": "terminal-execute", "description": "敏感命令确认时发送通知", "hooks": [ { "type": "command", "command": "curl -X POST https://hooks.slack.com/... -d '{\"text\":\"Sensitive command needs confirmation\"}'", "timeout": 5000, "enabled": true } ] } ] } ``` ### 5. afterToolCall **触发时机**: 工具调用完成后（支持工具匹配） **特殊功能**: 支持 `matcher` 字段匹配特定工具名称 **上下文参数**: ```json { "toolName": "filesystem-edit", // 工具名称 "args": { // 工具参数 "filePath": "src/index.ts", "startLine": 10, "endLine": 20, "newContent": "..." }, "result": { // 工具执行结果 "success": true, "message": "File edited successfully" }, "error": null // 错误信息（如果执行失败） } ``` **应用场景**: - 在文件修改后运行测试 - 在代码变更后运行代码格式化 - 记录工具执行结果 - 针对特定工具的后处理 **占位符使用**: 在 `prompt` 类型中可以使用 `$TOOLSRESULT$` 占位符访问完整的上下文数据（包括 result 和 error）。 **示例**: ```json { "afterToolCall": [ { "matcher": "filesystem-edit", "description": "代码修改后自动格式化", "hooks": [ { "type": "command", "command": "npm run format", "timeout": 30000, "enabled": true } ] } ] } ``` ### 6. onSubAgentComplete **触发时机**: 子代理任务完成时 **特殊功能**: 支持 `prompt` 类型 Action（交互式提示） **Hook 可接收的上下文参数**: 所有 Hooks 都可以接收主流程传递的上下文参数。这些参数会通过 **stdin** 以 JSON 格式传递给 `command` 类型的 Hook，或通过 **占位符** 注入到 `prompt` 类型的 Hook 中。 **onSubAgentComplete 的上下文参数**: ```json { "agentId": "agent_explore", // 子代理ID "agentName": "Explore Agent", // 子代理名称 "content": "子代理输出的内容", // 子代理返回的内容 "success": true, // 子代理执行是否成功 "usage": { // 子代理的 token 使用情况（如果有） "prompt_tokens": 1000, "completion_tokens": 500, "total_tokens": 1500 } } ``` **应用场景**: - 子代理完成后收集用户反馈 - 询问用户是否继续下一步 - 让用户选择处理方式 - 记录子代理执行结果 **Prompt 类型说明**: - `prompt` 类型会暂停 AI 流程，等待用户输入 - 用户输入的内容会作为新消息发送给 AI - 只能在 `onSubAgentComplete` 和 `onStop` 中使用 - 一个规则中如果有 `prompt` 类型，不能再有其他 Action **Prompt 类型的上下文占位符使用**: 在 `prompt` 类型的 Hook 中，可以使用 `$SUBAGENTRESULT$` 占位符来访问上下文数据： ```json { "onSubAgentComplete": [ { "description": "子代理完成后询问用户", "hooks": [ { "type": "prompt", "prompt": "子代理已完成任务。上下文数据: $SUBAGENTRESULT$\n\n是否需要继续？请输入您的指示：", "timeout": 30000, "enabled": true } ] } ] } ``` 占位符会被替换为完整的上下文 JSON，小模型会根据上下文和提示词生成回复。 **Command 类型的 stdin 使用**: 在 `command` 类型的 Hook 中，上下文数据会通过 **stdin** 以 JSON 格式传递： ```json { "onSubAgentComplete": [ { "description": "记录子代理结果", "hooks": [ { "type": "command", "command": "node -e \"const data = JSON.parse(require('fs').readFileSync(0, 'utf-8')); console.log('Agent:', data.agentName, 'Success:', data.success)\"", "timeout": 3000, "enabled": true } ] } ] } ``` 你的命令可以通过读取 stdin 来获取完整的上下文数据。 ### 7. beforeCompress **触发时机**: 在即将运行上下文压缩操作之前 **应用场景**: - 保存压缩前的上下文快照 - 记录压缩操作的时间点 - 触发上下文备份 - 发送压缩通知 **示例**: ```json { "beforeCompress": [ { "description": "压缩前保存上下文", "hooks": [ { "type": "command", "command": "echo \"Context compression at $(date)\" >> .snow/logs/compression.log", "timeout": 3000, "enabled": true } ] } ] } ``` ### 8. onStop **触发时机**: 用户停止 AI 流程时（Ctrl+C 或结束会话） **特殊功能**: 支持 `prompt` 类型 Action（交互式提示） **上下文参数**: ```json { "messages": [ // 完整的会话消息历史记录 { "role": "user", "content": "用户消息内容" }, { "role": "assistant", "content": "AI 响应内容" } // ... 更多消息 ] } ``` **应用场景**: - 在停止前询问用户是否保存工作 - 收集用户反馈 - 执行清理操作 - 记录停止原因 **占位符使用**: 在 `prompt` 类型中可以使用 `$STOPSESSION$` 占位符访问会话上下文数据。 **示例（Prompt 类型）**: ```json { "onStop": [ { "description": "停止前询问", "hooks": [ { "type": "prompt", "prompt": "即将停止 AI，是否需要保存当前工作？请输入指示：", "timeout": 30000, "enabled": true } ] } ] } ``` ## Hook 配置管理 ### 进入配置界面 1. 启动 Snow CLI 2. 在主菜单中选择"Hooks 配置"选项 3. 选择配置作用域（全局或项目） ### 作用域说明 ```mermaid graph LR Config[Hooks 配置] --> Global[全局作用域] Config --> Project[项目作用域] Global --> GlobalPath[~/.snow/hooks/] Project --> ProjectPath[./.snow/hooks/] GlobalPath --> AllProjects[应用于所有项目] ProjectPath --> CurrentProject[仅应用于当前项目] style Global fill:#e1f5ff style Project fill:#e1ffe1 style GlobalPath fill:#ccecff style ProjectPath fill:#ccffcc ``` **全局 Hooks**: - 存储位置: `~/.snow/hooks/` - 应用范围: 所有使用 Snow CLI 的项目 - 适用场景: 通用的工作流程、全局监控、统一的日志记录 **项目 Hooks**: - 存储位置: `./.snow/hooks/` (当前项目目录) - 应用范围: 仅当前项目 - 适用场景: 项目特定的自动化、特殊的构建流程、项目级别的验证 **执行优先级**: 项目 Hooks 和全局 Hooks 都会执行，项目 Hooks 优先执行 ### 查看 Hook 列表 配置界面会显示所有 8 种 Hook 类型： - 已配置的 Hook 显示 `[✓]` 标记 - 未配置的 Hook 显示 `[ ]` 标记 - 显示每个 Hook 包含的规则数量 - 底部显示当前选中 Hook 的说明 ### 配置 Hook 规则 #### 1. 选择 Hook 类型 使用 ↑/↓ 方向键选择要配置的 Hook 类型，按 Enter 进入详情页面 #### 2. Hook 详情页面 显示该 Hook 下的所有规则： - 规则列表（显示描述、Action 数量、Matcher 信息） - 添加新规则选项 - 删除整个 Hook 配置选项 - 返回上一级选项 #### 3. 编辑规则 选择一个规则或选择"添加新规则"进入编辑界面： **基础字段**: - **描述** (必填) - 规则的简短说明 - 按 Enter 或 Tab 进入下一字段 - 帮助您快速识别规则用途 - **Matcher** (仅工具 Hooks 需要) - 仅在 `beforeToolCall`、`toolConfirmation`、`afterToolCall` 中显示 - 用于匹配特定的工具名称 - 支持通配符: `filesystem-*` - 支持多个工具: `filesystem-read,filesystem-edit` - 留空表示匹配所有工具 **Action 管理**: 每个规则可以包含多个 Action，按顺序执行： - 查看已有的 Action 列表 - 添加新 Action - 编辑现有 Action - 删除 Action #### 4. 编辑 Action 选择一个 Action 或选择"添加 Action"进入 Action 编辑界面： **Action 字段**: - **启用状态** (必填) - 使用 Space 键切换启用/禁用 - `[✓]` 表示启用，`[ ]` 表示禁用 - 禁用的 Action 不会执行但会保留配置 - **类型** (必填) - `command`: 执行命令 - `prompt`: 交互式提示（仅 `onSubAgentComplete` 和 `onStop` 支持） - 按 Space 键切换类型 - 切换类型有限制（见下方说明） - **Command** (type=command 时) - 要执行的命令行命令 - 支持管道和复杂命令 - 示例: `npm run build && npm test` - **Prompt** (type=prompt 时) - 显示给用户的提示文本 - 用户输入会作为新消息发送给 AI - 示例: "请输入您的下一步指示：" - **Timeout** (可选) - 超时时间（毫秒） - 默认值: command=5000ms, prompt=30000ms - 超时后 Action 会被终止 #### 5. Action 类型限制 ```mermaid graph TB Start([选择 Hook 类型]) --> CheckHook{Hook 类型} CheckHook -->|onSubAgentComplete
或 onStop| CanPrompt[可使用 Prompt 或 Command] CheckHook -->|其他 Hook 类型| OnlyCommand[只能使用 Command] CanPrompt --> CheckExist{规则中是否
已有 Action?} CheckExist -->|没有 Action| ChooseType1[可选择任意类型] CheckExist -->|已有 Prompt| NoMore1[不能再添加 Action] CheckExist -->|已有 Command| OnlyCommand2[只能添加 Command] ChooseType1 --> SelectPrompt{选择 Prompt?} SelectPrompt -->|是| SinglePrompt[只能有这一个 Prompt
不能再添加其他 Action] SelectPrompt -->|否| MultiCommand[可以添加多个 Command] style CanPrompt fill:#e1ffe1 style OnlyCommand fill:#ffe1e1 style OnlyCommand2 fill:#ffe1e1 style NoMore1 fill:#ffcccc style SinglePrompt fill:#fff0cc style MultiCommand fill:#ccffcc ``` **限制规则**: 1. **Prompt 类型限制**: - 只能在 `onSubAgentComplete` 和 `onStop` 中使用 - 一个规则中如果有 Prompt，不能有任何其他 Action - Prompt 必须单独存在 2. **Command 类型**: - 可以在所有 Hook 类型中使用 - 一个规则可以有多个 Command Action - 如果规则中已有 Prompt，不能添加 Command 3. **类型切换**: - 切换类型时系统会自动验证 - 不符合规则的切换会被阻止 ### 保存和删除 **保存规则**: - 在规则编辑界面选择"保存规则" - 配置会立即保存到对应的作用域 - 保存后自动返回 Hook 详情页面 **删除规则**: - 在规则编辑界面选择"删除规则"或按 `D` 键 - 按 `D` 键可快速删除（需要在规则编辑界面） - 删除后自动返回 Hook 详情页面 **删除 Hook 配置**: - 在 Hook 详情页面选择"删除 Hook" - 会删除该 Hook 的配置文件 - 删除后返回 Hook 列表 ## 键盘快捷键 ### Hook 列表界面 - **↑/↓**: 在 Hook 类型间导航 - **Enter**: 进入选中的 Hook 详情 - **ESC**: 返回主菜单 ### Hook 详情界面 - **↑/↓**: 在规则列表中导航 - **Enter**: 编辑选中的规则或执行操作 - **ESC**: 返回 Hook 列表 ### 规则编辑界面 - **↑/↓**: 在字段和 Action 间导航 - **Enter**: 编辑字段或 Action - **D**: 快速删除当前规则 - **ESC**: 返回 Hook 详情 ### Action 编辑界面 - **↑/↓**: 在字段间导航 - **Space**: 切换启用状态或类型 - **Enter**: 编辑文本字段 - **D**: 快速删除当前 Action - **ESC**: 返回规则编辑 ### 文本输入状态 - **Enter**: 确认输入 - **ESC**: 取消输入 ## 退出码规则 Hook 命令的退出码决定了 AI 工作流程的后续行为。不同的退出码有不同的语义： | 退出码 | 含义 | 行为 | |--------|------|------| | **0** | 成功 | 正常继续工作流程 | | **1** | 警告 | 阻止当前操作，stderr 作为替代结果返回给 AI（AI 流程继续） | | **2+** | 严重错误 | 阻止当前操作，终止 AI 流程，错误信息直接展示给用户 | ### 各 Hook 类型的退出码行为 #### beforeToolCall | 退出码 | 工具是否执行 | AI 流程 | AI 收到的内容 | |--------|------------|---------|--------------| | 0 | 正常执行 | 继续 | 正常工具结果 | | 1 | **阻止执行** | 继续 | stderr 内容（无 stderr 则显示预设警告） | | 2+ | 阻止执行 | **终止** | 不调用 AI，错误展示给用户 | #### afterToolCall | 退出码 | AI 流程 | AI 收到的内容 | |--------|---------|--------------| | 0 | 继续 | 正常工具结果 | | 1 | 继续 | stderr 内容**替代**原始工具结果（无 stderr 则使用 stdout） | | 2+ | **终止** | 不调用 AI，错误展示给用户 | ### stderr 与 stdout 的优先级 当退出码为 1 时： - 如果有 **stderr** 输出，使用 stderr 作为返回给 AI 的内容 - 如果没有 stderr，使用 **stdout** 输出 - 如果两者都没有，使用预设的警告信息 这意味着您可以在 Hook 脚本中通过 stderr 精确控制返回给 AI 的提示信息。 ### 示例：使用退出码控制工具行为 ```bash #!/bin/bash # beforeToolCall Hook: 阻止在非工作时间修改文件 HOUR=$(date +%H) if [ "$HOUR" -ge 22 ] || [ "$HOUR" -lt 6 ]; then echo "当前为非工作时间，禁止修改文件。请在工作时间（6:00-22:00）再试。" >&2 exit 1 fi exit 0 ``` ```bash #!/bin/bash # afterToolCall Hook: 检测代码修改后的 lint 错误 LINT_OUTPUT=$(npm run lint 2>&1) if [ $? -ne 0 ]; then echo "Lint 检查发现问题，请修复以下错误：\n$LINT_OUTPUT" >&2 exit 1 fi exit 0 ``` ## 配置文件结构 Hooks 配置存储在 JSON 文件中，每个 Hook 类型对应一个文件： **文件位置**: - 全局: `~/.snow/hooks/.json` - 项目: `./.snow/hooks/.json` **文件格式**: ```json { "hookType": [ { "description": "规则描述", "matcher": "工具匹配器（仅工具 Hooks）", "hooks": [ { "type": "command", "command": "执行的命令", "timeout": 5000, "enabled": true } ] } ] } ``` ## 实用配置示例 ### 示例 1: 自动化测试流程 ```json { "afterToolCall": [ { "matcher": "filesystem-edit", "description": "代码修改后自动运行测试", "hooks": [ { "type": "command", "command": "npm run lint", "timeout": 15000, "enabled": true }, { "type": "command", "command": "npm test", "timeout": 60000, "enabled": true } ] } ] } ``` ### 示例 2: 文件备份系统 ```json { "beforeToolCall": [ { "matcher": "filesystem-*", "description": "文件操作前自动备份", "hooks": [ { "type": "command", "command": "mkdir -p .snow/backups && cp -r . .snow/backups/$(date +%Y%m%d_%H%M%S)/", "timeout": 30000, "enabled": true } ] } ] } ``` ### 示例 3: 工作流程记录 ```json { "onUserMessage": [ { "description": "记录所有用户请求", "hooks": [ { "type": "command", "command": "echo \"[$(date '+%Y-%m-%d %H:%M:%S')] User message received\" >> .snow/logs/workflow.log", "timeout": 3000, "enabled": true } ] } ] } ``` ### 示例 4: 交互式反馈收集 ```json { "onSubAgentComplete": [ { "description": "子代理完成后收集反馈", "hooks": [ { "type": "prompt", "prompt": "子代理已完成任务。请查看结果并提供您的反馈或下一步指示：", "timeout": 60000, "enabled": true } ] } ] } ``` ### 示例 5: 团队协作通知 ```json { "toolConfirmation": [ { "matcher": "terminal-execute", "description": "敏感操作通知团队", "hooks": [ { "type": "command", "command": "curl -X POST $SLACK_WEBHOOK -H 'Content-Type: application/json' -d '{\"text\":\"Sensitive operation pending confirmation\"}'", "timeout": 5000, "enabled": true } ] } ] } ``` ### 示例 6: 会话初始化检查 ```json { "onSessionStart": [ { "description": "检查项目环境", "hooks": [ { "type": "command", "command": "node --version", "timeout": 3000, "enabled": true }, { "type": "command", "command": "git status", "timeout": 3000, "enabled": true }, { "type": "command", "command": "npm list --depth=0", "timeout": 10000, "enabled": true } ] } ] } ``` ## 配置最佳实践 ### 1. 合理设置超时时间 - 简单命令: 3000-5000ms - 构建/测试: 30000-60000ms - 交互式 Prompt: 30000-60000ms - 避免设置过短导致命令被中断 - 避免设置过长影响工作流程 ### 2. 使用 Matcher 精确匹配 - 避免过于宽泛的匹配（如匹配所有工具） - 针对性地匹配需要特殊处理的工具 - 使用通配符简化配置: `filesystem-*` - 多个相关工具可以共享规则: `filesystem-read,filesystem-edit` ### 3. 命令执行注意事项 - 确保命令在目标环境中可用 - 使用绝对路径避免环境变量问题 - 考虑跨平台兼容性（Windows/Linux/macOS） - 使用环境变量存储敏感信息（如 API 密钥） ### 4. Prompt 类型使用建议 - 只在必要时使用 Prompt（会中断工作流程） - 提示信息要清晰明确 - 提供足够的上下文帮助用户决策 - 设置合理的超时时间 ### 5. 规则组织 - 每个规则专注于单一职责 - 使用清晰的描述说明规则用途 - 相关的 Action 可以放在同一规则中 - 避免规则间的重复逻辑 ### 6. 测试和调试 - 先在项目作用域测试新配置 - 确认无误后再应用到全局作用域 - 使用 `enabled` 字段临时禁用 Action - 检查命令输出和错误日志 ### 7. 性能考虑 - 避免执行耗时过长的命令 - 考虑使用异步后台任务 - 不要在高频 Hook（如 `onUserMessage`）中执行重操作 - 合理使用禁用功能减少不必要的执行 ## 常见问题 **Q: Hooks 会影响 AI 的响应速度吗？** A: 会有一定影响。Hook 命令是同步执行的，命令执行期间 AI 流程会暂停。建议将 Hook 命令的执行时间控制在合理范围内。 **Q: 可以在 Hook 命令中访问 AI 的上下文信息吗？** A: 目前 Hook 命令只能执行标准的 Shell 命令，无法直接访问 AI 的上下文。您可以通过文件系统或环境变量间接传递信息。 **Q: 项目 Hooks 和全局 Hooks 冲突时怎么办？** A: 不会冲突，两者都会执行。项目 Hooks 会优先执行，然后执行全局 Hooks。 **Q: 如何调试 Hook 命令？** A: 建议先在终端中手动执行命令确保其正确性，然后在 Hook 中使用。您也可以在命令中添加日志输出来追踪执行情况。 **Q: Prompt 类型的 Action 可以调用多次吗？** A: 不可以。一个规则中只能有一个 Prompt Action，且不能与其他 Action 共存。如果需要多次交互，应该创建多个规则。 **Q: Hook 命令执行失败会怎样？** A: 取决于退出码。退出码 1 会阻止当前操作并将 stderr 作为替代结果返回给 AI（AI 流程继续）；退出码 2+ 会终止整个 AI 流程并将错误信息展示给用户。详见"退出码规则"章节。 **Q: 可以在 Windows 上使用 Linux 风格的命令吗？** A: 不建议。应该根据运行平台编写相应的命令，或使用跨平台的工具（如 Node.js 脚本）。 **Q: 如何禁用某个 Hook 而不删除配置？** A: 在 Action 编辑界面，使用 Space 键切换"启用状态"即可。禁用的 Action 会保留配置但不会执行。 **Q: Matcher 支持正则表达式吗？** A: 目前只支持精确匹配和通配符 `*`，不支持完整的正则表达式。 **Q: 可以手动编辑配置文件吗？** A: 可以，但建议使用配置界面以确保格式正确。手动编辑后重启 Snow CLI 以加载新配置。 ================================================ FILE: docs/usage/zh/08.主题设置.md ================================================ # Snow CLI 使用文档——主题设置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是主题 主题定义了 Snow CLI 终端界面的外观，包括颜色方案、代码高亮样式、菜单显示效果等。通过主题设置，您可以： - 选择预设的主题方案 - 自定义配色以适应个人喜好 - 调整界面显示模式（简洁/标准） - 创建和保存自己的主题配色 ## 进入主题设置 1. 启动 Snow CLI 2. 在主菜单中选择"主题设置"选项 3. 进入主题设置界面 ## 简洁模式 简洁模式是一个独立的界面显示选项，可以简化终端界面显示，减少视觉干扰。 ### 功能说明 - **标准模式**: 完整显示所有界面元素（边框、装饰、详细信息） - **简洁模式**: 简化界面显示，隐藏非必要元素，专注于内容本身 ### 操作方法 1. 在主题设置界面，第一个选项即为"简洁模式" 2. 选中后按 Enter 键切换状态 3. 界面显示当前状态： - `简洁模式 已启用` - `简洁模式 已禁用` 4. 简洁模式的切换立即生效 ### 使用场景 - 小屏幕终端：减少空间占用 - 专注工作：减少视觉干扰 - 性能优化：减少渲染开销 - 截图演示：界面更简洁清晰 ## 预设主题 Snow CLI 提供 6 种精心设计的预设主题，每种主题都有独特的配色方案。 ### 1. Dark 主题 **特点**: Snow CLI 的默认主题，经典的深色配色方案 **适用场景**: - 长时间编码工作 - 低光环境使用 - 护眼需求 **配色特征**: - 深色背景 - 柔和的文本颜色 - 清晰的语法高亮 - 舒适的对比度 ### 2. Light 主题 **特点**: 明亮的浅色主题，适合白天使用 **适用场景**: - 明亮环境下使用 - 白天工作时段 - 个人偏好浅色界面 **配色特征**: - 浅色背景 - 深色文本 - 高对比度 - 清晰易读 ### 3. GitHub Dark 主题 **特点**: 模仿 GitHub 的深色主题风格 **适用场景**: - GitHub 用户 - 喜欢 GitHub 配色的开发者 - 需要熟悉的视觉体验 **配色特征**: - GitHub 风格配色 - 专业的代码高亮 - 舒适的深色背景 ### 4. Rainbow 主题 **特点**: 丰富多彩的配色方案 **适用场景**: - 喜欢鲜艳色彩 - 需要区分不同类型信息 - 个性化需求 **配色特征**: - 多彩的高亮颜色 - 鲜明的视觉效果 - 活跃的氛围 ### 5. Solarized Dark 主题 **特点**: 著名的 Solarized 配色方案的深色版本 **适用场景**: - Solarized 爱好者 - 需要科学配色 - 长时间阅读代码 **配色特征**: - 经过科学设计的配色 - 舒适的对比度 - 护眼配色方案 ### 6. Nord 主题 **特点**: 受 Nord 配色方案启发的冷色调主题 **适用场景**: - 喜欢冷色调 - 追求现代感 - 统一的配色体验 **配色特征**: - 北欧风格配色 - 冷色调为主 - 优雅而现代 ## 主题选择和应用 ### 浏览主题 1. 在主题设置界面，使用 ↑/↓ 方向键浏览主题列表 2. 当光标移动到某个主题时，界面会立即预览该主题效果 3. 预览区域显示代码对比示例，展示该主题的语法高亮效果 4. 底部显示当前选中主题的说明信息 **预览特点**: - 无需按 Enter，光标移动即可预览 - 实时显示主题效果 - 代码 Diff 示例展示语法高亮 - 帮助快速选择合适的主题 ### 应用主题 1. 浏览到想要使用的主题 2. 按 Enter 键确认应用 3. 主题配置自动保存到 `~/.snow/theme.json` 4. 主题立即生效并应用到整个界面 ### 取消更改 - 按 ESC 键：取消更改，恢复进入设置前的主题 - 选择"返回"选项：同样会恢复原主题 ## 自定义主题 除了预设主题，您还可以创建完全自定义的主题配色。 ### 进入自定义编辑器 1. 在主题设置界面选择"编辑自定义主题..."选项 2. 按 Enter 进入自定义主题编辑器 3. 编辑器显示所有可自定义的颜色选项 ### 可自定义的颜色 自定义主题包含 16 个颜色选项，分为多个类别： #### 基础颜色（3项） 1. **background** - 背景色 - 界面主要背景 - 建议使用深色或浅色基调 2. **text** - 文本色 - 主要文本内容颜色 - 需要与背景形成良好对比 3. **border** - 边框色 - UI 边框和分隔线 - 通常比背景稍亮或稍暗 #### Diff 显示颜色（3项） 4. **diffAdded** - 添加行背景色 - 代码新增行的背景 - 建议使用绿色系 5. **diffRemoved** - 删除行背景色 - 代码删除行的背景 - 建议使用红色系 6. **diffModified** - 修改内容高亮色 - 行内修改部分的高亮 - 建议使用黄色系 #### 行号颜色（2项） 7. **lineNumber** - 行号文本色 - 代码行号的颜色 - 通常使用灰色系 8. **lineNumberBorder** - 行号区域边框色 - 行号区域的边框 - 与行号颜色协调 #### 菜单颜色（4项） 9. **menuSelected** - 选中菜单项颜色 - 当前选中的菜单项 - 需要醒目突出 10. **menuNormal** - 普通菜单项颜色 - 未选中的菜单项 - 与背景形成适当对比 11. **menuInfo** - 信息类菜单项颜色 - 提示信息、说明文本 - 通常使用青色系 12. **menuSecondary** - 次要菜单项颜色 - 次要信息、辅助文本 - 通常使用灰色系 #### 状态颜色（3项） 13. **error** - 错误提示色 - 错误消息、警告 - 通常使用红色 14. **warning** - 警告提示色 - 警告消息、注意事项 - 通常使用黄色 15. **success** - 成功提示色 - 成功消息、确认信息 - 通常使用绿色 #### Logo 渐变色（1项） 16. **logoGradient** - Logo 渐变色 - Snow CLI Logo 的渐变效果 - 需要输入 3 个颜色值，用逗号分隔 - 格式: `#color1, #color2, #color3` - 示例: `#d3d3d3, #808080, #505050` ### 编辑颜色 #### 选择要编辑的颜色 1. 使用 ↑/↓ 方向键浏览颜色列表 2. 每行显示：`颜色名称: 当前值` 3. 选中要修改的颜色项 4. 按 Enter 键进入编辑模式 #### 输入颜色值 进入编辑模式后： 1. 界面显示当前颜色值 2. 提供输入框供输入新值 3. 支持多种颜色格式： - 十六进制: `#RRGGBB` (如 `#1e1e1e`) - 颜色名称: `red`, `blue`, `green`, `cyan`, `yellow` 等 - RGB 格式: `rgb(30, 30, 30)` 4. 输入完成后按 Enter 确认 5. 颜色立即更新并在预览区域显示效果 #### 取消编辑 - 在编辑模式下按 ESC 键：取消当前颜色的修改 - 返回颜色列表继续编辑其他颜色 自定义编辑器底部的预览区域会实时显示您的配色效果： - 显示代码对比示例 - 展示语法高亮效果 - 显示 Diff 对比效果 - 帮助您评估配色方案 ### 保存自定义主题 完成颜色编辑后： 1. 在颜色列表底部选择"保存"选项 2. 按 Enter 确认保存 3. 自定义配色保存到 `~/.snow/theme.json` 4. 主题自动切换为"Custom"主题 5. 返回主题设置界面 **配置文件格式**: ```json { "theme": "custom", "customColors": { "background": "#1e1e1e", "text": "#d4d4d4", "border": "#3e3e3e", "diffAdded": "#0d4d3d", "diffRemoved": "#5a1f1f", "diffModified": "#dcdcaa", "lineNumber": "#858585", "lineNumberBorder": "#3e3e3e", "menuSelected": "#5e0691ff", "menuNormal": "white", "menuInfo": "cyan", "menuSecondary": "gray", "error": "red", "warning": "yellow", "success": "green", "logoGradient": ["#d3d3d3", "#808080", "#505050"] }, "simpleMode": false } ``` ### 重置为默认配色 如果对自定义配色不满意，可以重置为默认值： 1. 在自定义编辑器中选择"重置为默认"选项 2. 按 Enter 确认 3. 所有颜色恢复为系统默认的自定义主题配色 4. 预览区域立即显示默认配色效果 5. 可以重新开始编辑 **注意**: 重置操作不会立即保存，需要选择"保存"才会写入配置文件 ## 键盘快捷键 ### 主题设置界面 - **↑/↓**: 在主题列表中导航 - **Enter**: 应用选中的主题或执行操作 - **ESC**: 取消更改并返回主菜单 ### 自定义编辑器 - **↑/↓**: 在颜色列表中导航 - **Enter**: 编辑选中的颜色或执行操作 - **ESC**: 返回主题设置（未保存的更改会丢失） ### 颜色编辑模式 - **Enter**: 确认输入的颜色值 - **ESC**: 取消当前颜色编辑 ## 主题配置最佳实践 ### 1. 选择合适的基础主题 根据工作环境选择： - 低光环境：深色主题（Dark, GitHub Dark, Nord） - 明亮环境：浅色主题（Light） - 个人偏好：选择最舒适的配色方案 ### 2. 自定义主题配色建议 #### 对比度 - 确保文本与背景有足够对比度 - 避免过于刺眼的颜色组合 - 测试长时间使用的舒适度 #### 一致性 - 保持配色方案的一致性 - 相关功能使用相似色调 - 避免过多颜色造成混乱 #### 可读性 - 代码高亮颜色要清晰可辨 - Diff 颜色要明确区分添加/删除/修改 - 菜单项颜色层次分明 ### 3. 颜色选择技巧 #### 十六进制颜色 ``` 格式: #RRGGBB 示例: #1e1e1e - 深灰色背景 #d4d4d4 - 浅灰色文本 #0d4d3d - 深绿色（添加行） #5a1f1f - 深红色（删除行） ``` #### 命名颜色 ``` 基础色: black, white, gray 鲜艳色: red, green, blue cyan, magenta, yellow 扩展色: 可查阅终端支持的颜色名称列表 ``` ### 4. Logo 渐变色配置 Logo 渐变需要 3 个颜色形成渐变效果： ``` 从浅到深: #ffffff, #808080, #000000 蓝色系: #5e9cff, #2e5c8f, #1e3c5f 绿色系: #90ee90, #50ae50, #306e30 自定义: 确保三个颜色形成平滑过渡 第一个最亮，第三个最暗 ``` ### 5. 测试主题效果 创建自定义主题后，建议： 1. 测试代码高亮效果 2. 检查 Diff 对比清晰度 3. 验证菜单可读性 4. 确认长时间使用的舒适度 5. 在不同终端中测试兼容性 ### 6. 备份自定义主题 定期备份配置文件： ```bash # 备份主题配置 cp ~/.snow/theme.json ~/.snow/theme.json.backup # 恢复备份 cp ~/.snow/theme.json.backup ~/.snow/theme.json ``` ### 7. 多环境配置 如果在不同设备或环境使用： - 根据屏幕特性选择主题 - 考虑环境光照差异 - 统一团队配色方案（可选） ## 常见问题 **Q: 更改主题后需要重启 Snow CLI 吗？** A: 不需要。主题更改立即生效，会应用到当前界面和后续所有操作。 **Q: 自定义主题的配置文件在哪里？** A: 配置文件位于 `~/.snow/theme.json`，可以手动编辑或通过界面配置。 **Q: 可以导入和导出自定义主题吗？** A: 可以。直接复制 `theme.json` 文件即可分享主题配置。将文件放到 `~/.snow/` 目录下即可使用。 **Q: 简洁模式和主题选择有什么区别？** A: 简洁模式控制界面显示的繁简程度，主题控制颜色方案。两者独立工作，可以组合使用。 **Q: 如果自定义配色后界面显示异常怎么办？** A: 在自定义编辑器中选择"重置为默认"，或者直接删除 `~/.snow/theme.json` 文件，Snow CLI 会自动使用默认配置。 **Q: 所有终端都支持自定义颜色吗？** A: 大多数现代终端支持，但部分老旧终端可能只支持 16 色。建议使用 iTerm2、Windows Terminal、Hyper 等现代终端。 **Q: 可以针对不同项目使用不同主题吗？** A: 目前主题是全局配置，所有项目共享。如有需要可以在启动 Snow CLI 前临时修改配置文件。 **Q: 预览区域显示的代码示例可以自定义吗？** A: 预览代码是固定的示例，用于展示主题效果。实际使用时会应用到您的真实代码中。 **Q: logoGradient 必须是 3 个颜色吗？** A: 是的。Logo 渐变设计需要 3 个颜色来形成平滑的渐变效果。格式必须为 `[color1, color2, color3]`。 **Q: 如何分享我的自定义主题给团队？** A: 复制 `~/.snow/theme.json` 文件中的 `customColors` 部分，分享给团队成员。他们将内容粘贴到自己的配置文件中即可。 ## 主题配置文件说明 主题配置存储在 `~/.snow/theme.json` 文件中。 ### 完整配置示例 ```json { "theme": "custom", "customColors": { "background": "#1e1e1e", "text": "#d4d4d4", "border": "#3e3e3e", "diffAdded": "#0d4d3d", "diffRemoved": "#5a1f1f", "diffModified": "#dcdcaa", "lineNumber": "#858585", "lineNumberBorder": "#3e3e3e", "menuSelected": "#5e0691ff", "menuNormal": "white", "menuInfo": "cyan", "menuSecondary": "gray", "error": "red", "warning": "yellow", "success": "green", "logoGradient": ["#d3d3d3", "#808080", "#505050"] }, "simpleMode": false } ``` ### 字段说明 - **theme**: 当前使用的主题类型 - 可选值: `dark`, `light`, `github-dark`, `rainbow`, `solarized-dark`, `nord`, `custom` - **customColors**: 自定义主题的颜色配置 - 仅在 `theme` 为 `custom` 时使用 - 包含 16 个颜色字段 - **simpleMode**: 简洁模式开关 - `true`: 启用简洁模式 - `false`: 使用标准模式 ### 手动编辑注意事项 如果选择手动编辑配置文件： 1. 确保 JSON 格式正确 2. logoGradient 必须是数组格式 3. 颜色值必须是有效的颜色格式 4. 编辑后重启 Snow CLI 以加载新配置 建议使用配置界面进行修改，以避免格式错误。 ================================================ FILE: docs/usage/zh/09.指令面板说明.md ================================================ # Snow CLI 使用文档——指令面板说明 指令面板是 Snow CLI 提供的快捷命令系统，让您可以通过简单的斜杠命令快速执行各种操作。 ## 指令面板概述 所有指令都以 `/` 开头，在聊天输入框中输入即可执行。指令分为以下几类： - 会话管理 - 模式切换 - 代码审查与分析 - 配置与管理 - 自定义扩展 ## 会话管理指令 ### `/clear` 清除当前聊天上下文。 - **作用**: 清空当前对话历史，开始全新的对话 - **使用场景**: 当对话上下文过长或需要切换话题时 - **示例**: 直接输入 `/clear` 并回车 ### `/resume` 恢复历史会话。 - **作用**: 打开会话选择面板，可以选择并恢复之前保存的对话 - **使用场景**: 需要继续之前未完成的对话或查看历史记录 - **示例**: 输入 `/resume` 查看所有保存的会话 ### `/export` 导出对话记录。 - **作用**: 将当前对话导出为文本文件 - **使用场景**: 需要保存对话内容用于文档或分享 - **示例**: 输入 `/export` 自动保存到项目目录 ### `/copy-last` 复制最后一条 AI 回复。 - **作用**: 将当前会话中最后一条 AI 助手消息复制到系统剪贴板 - **使用场景**: 需要快速复用上一条回复内容，例如粘贴到文档、提交记录或聊天窗口 - **注意事项**: - 只会复制最近一条非子代理的 AI 助手消息 - 如果当前还没有 AI 回复，或最后一条回复为空，会显示提示信息 - **示例**: 输入 `/copy-last` 复制最后一条 AI 回复 ### `/compact` 压缩对话历史。 - **作用**: 使用 AI 压缩对话历史，减少 token 使用 - **使用场景**: 对话过长但不想清除，需要保留关键信息 - **示例**: 输入 `/compact` 开始压缩 ### `/branch` 分支当前会话。 - **作用**: 将当前对话分支（Fork）为一个独立的新会话 - **参数**: 可选分支名称 - **使用场景**: 需要在不影响当前对话的情况下，基于相同上下文尝试不同的思路或方案 - **示例**: - `/branch` - 分支当前会话 - `/branch my-experiment` - 分支并命名为 my-experiment ### `/fork` 分支当前会话（与 `/branch` 完全等价）。 - **作用**: 将当前对话分支（Fork）为一个独立的新会话 - **参数**: 可选分支名称 - **使用场景**: 需要在不影响当前对话的情况下，基于相同上下文尝试不同的思路或方案 - **示例**: - `/fork` - 分支当前会话 - `/fork my-experiment` - 分支并命名为 my-experiment ## 模式切换指令 ### `/yolo` 切换 YOLO 模式（自动批准模式）。 - **作用**: 开启/关闭工具调用自动批准，无需手动确认 - **使用场景**: 信任 AI 操作时快速执行，或需要人工审核时关闭 - **状态**: 状态保存在 localStorage，重启后保持 - **示例**: 输入 `/yolo` 切换模式 ### `/plan` 切换 Plan 模式（计划模式）。 - **作用**: 开启/关闭计划模式，AI 会先制定详细计划再执行 - **使用场景**: 复杂任务需要先规划，或简单任务直接执行 - **状态**: 状态保存在 localStorage - **示例**: 输入 `/plan` 切换模式 ### `/vulnerability-hunting` 切换漏洞猎人模式。 - **作用**: 开启/关闭漏洞猎人模式，这是一个专业的安全分析代理 - **功能**: - 系统化的 5 阶段漏洞分析流程 - 生成可执行的验证脚本 - 创建详细的安全分析报告 - 支持多种漏洞类型检测（逻辑错误、安全漏洞等） - **使用场景**: 进行专业的安全审计或代码漏洞检测 - **状态**: 状态保存在 localStorage - **报告位置**: `.snow/vulnerability-hunting/docs/` - **脚本位置**: `.snow/vulnerability-hunting/scripts/` - **详细说明**: 参考 [漏洞猎人模式](./11.漏洞猎人模式.md) - **示例**: 输入 `/vulnerability-hunting` 切换模式 ### `/tool-search` 切换工具搜索模式。 - **作用**: 开启/关闭 Tool Search（按需搜索并加载工具） - **功能**: - 开启后优先按需发现工具，减少一次性注入的工具数量 - 关闭后会直接提供完整工具集合 - 当前状态会持久化到项目内的 `.snow/settings.json` - **使用场景**: 需要在“节省上下文”和“直接暴露全部工具”之间切换时 - **示例**: 输入 `/tool-search` 切换模式 ## 代码审查与分析指令 ### `/review` 代码审查。 - **作用**: 打开交互式代码审查面板，选择要审查的内容 - **功能**: - 自动检测 Git 仓库 - 显示已暂存更改（Staged）及文件数量 - 显示未暂存更改（Unstaged）及文件数量 - 分页加载历史提交记录（每页 30 条） - 支持多选：可同时选择多个审查目标 - 支持添加审查备注 - AI 分析代码质量、潜在 bug、安全问题 - 提供优化建议 - **面板操作**: - `Up/Down` - 上下移动选择 - `Space` - 勾选/取消勾选当前项 - `Enter` - 确认选择并开始审查 - `ESC` - 关闭面板 - **可选择的审查目标**: - **Staged**: 已暂存的更改 - **Unstaged**: 未暂存的更改 - **历史提交**: 显示 commit SHA、提交信息、作者、日期 - **示例**: - `/review` - 打开审查面板 - 在面板中用空格键选择要审查的内容，按回车确认 ### `/diff` 查看对话修改 Diff。 - **作用**: 打开 Diff Review 面板，按对话中的用户消息查看关联的文件变更，并在 IDE 中打开差异视图 - **功能**: - 根据会话快照列出可回看的对话节点 - 支持先预览单个文件差异，再一次性打开全部文件 Diff - 适合回顾 AI 在当前会话中修改过的代码 - **面板操作**: - `↑/↓` - 选择消息或文件 - `Tab` - 在消息列表与文件列表之间切换 - `Enter` - 打开选中消息对应的全部文件 Diff - `ESC` - 关闭面板 - **前提**: 建议先连接 VSCode/IDE 插件，否则无法在 IDE 中展示 Diff - **示例**: 输入 `/diff` 打开对话变更对比面板 ### `/init` 初始化项目文档。 - **作用**: AI 分析当前项目并生成/更新 AGENTS.md 文档 - **功能**: - 自动探索项目结构 - 读取配置文件和代码 - 生成项目概述、技术栈、架构说明 - **生成内容**: 项目名称、概览、技术栈、目录结构、功能特性、使用说明等 - **示例**: 在项目根目录输入 `/init` ### `/new-prompt` 生成精炼提示词。 - **作用**: 打开 Prompt Generator 面板，根据你的需求描述生成一段可直接继续编辑或发送的提示词 - **功能**: - 输入自然语言需求后由 AI 生成更结构化的 prompt - 生成完成后可预览、重新生成或接受结果 - 接受后会把生成结果放回输入框，不会自动发送 - **面板操作**: - **输入阶段**: 输入需求后按 `Enter` 开始生成 - **预览阶段**: `↑/↓` 滚动预览，`Y` 接受，`R` 重新生成，`N/ESC` 取消 - **使用场景**: 想把模糊需求整理成更清晰、更完整的指令时 - **示例**: 输入 `/new-prompt` 打开提示词生成器 ### `/role` 角色定义文件管理。 - **作用**: 管理 ROLE 文件（支持全局与项目两个作用域），用于定义 AI 的角色和行为 - **功能**: - **创建**: `/role` - 打开交互式面板，选择创建位置 - 全局位置: `~/.snow/ROLE.md` - 项目位置: `./ROLE.md` - **删除**: `/role -d` 或 `/role --delete` - 打开删除面板，选择要删除的 ROLE.md - **列表/切换**: `/role -l` 或 `/role --list` - 打开 ROLE 管理面板，查看当前作用域下的 ROLE 列表并切换活跃项 - **使用场景**: 需要为特定项目定制 AI 的行为与输出风格，或统一配置所有项目的 AI 行为 - **面板操作**: - **创建面板**: `G` - 选择全局，`P` - 选择项目，`ESC` - 取消 - **删除面板**: `G` - 删除全局，`P` - 删除项目，`Y` - 确认删除，`N/ESC` - 取消 - **ROLE 管理面板（/role -l）**: - `Tab` - 切换 Global / Project - `Up/Down` - 移动选择 - `Enter` - 将选中的 ROLE 设为活跃（列表中以 `[✓]` 标记） - `N` - 创建一个新的非活跃 ROLE（文件名形如 `ROLE-.md`） - `D` - 删除选中的非活跃 ROLE（需要二次确认：`Y` 确认，`N/ESC` 取消） - `ESC` - 关闭面板 - **活跃状态持久化**: - 全局: `~/.snow/role.json` - 项目: `<项目根目录>/.snow/role.json` - 字段: `activeRoleId`（缺省或为 `active` 表示读取 `ROLE.md`；否则读取 `ROLE-.md`） - **示例**: - `/role` - 打开创建面板，选择位置后创建 ROLE.md - `/role -d` - 打开删除面板，选择要删除的文件 - `/role -l` - 打开 ROLE 管理面板 ### `/reindex` 重建代码库索引。 - **作用**: 重新扫描并索引项目代码库 - **前提**: 需要先在配置中启用代码库功能 - **参数**: - 无参数: 增量重建，跳过未修改的文件 - `-force`: 强制重建，删除现有数据库后完全重建索引 - **使用场景**: - 代码库更新后需要更新索引 - 索引损坏时使用 `-force` 完全重建 - **示例**: - `/reindex` - 增量重建索引 - `/reindex -force` - 强制完全重建索引 ### `/codebase` 管理当前项目的代码库索引开关。 - **作用**: 开启、关闭或查看当前项目的 Codebase 索引状态 - **参数**: - 无参数: `/codebase` - 直接切换开/关状态 - `on`: `/codebase on` - 启用代码库索引 - `off`: `/codebase off` - 禁用代码库索引 - `status`: `/codebase status` - 查看当前状态 - **前提**: 启用前需要先在 `/home` 中完成 embedding 相关配置 - **行为说明**: - 启用时会保存项目配置，并触发索引构建 - 禁用时会停止索引与文件监听 - **示例**: - `/codebase status` - 查看状态 - `/codebase on` - 启用索引 - `/codebase off` - 禁用索引 ## 配置与管理指令 ### `/home` 返回欢迎页。 - **作用**: 返回 Snow CLI 主菜单/欢迎界面 - **功能**: - 暂停代码库索引 - 清除 API 配置缓存 - 重置客户端连接 - **示例**: 输入 `/home` 返回主页 ### `/ide` 连接 IDE 插件。 - **作用**: 连接到 VSCode 或 JetBrains IDE 插件 - **功能**: - 自动检测并连接 IDE - 显示连接端口 - 强制重连（如已连接） - **前提**: 需要先安装对应的 IDE 插件 - **示例**: 输入 `/ide` 建立连接 ### `/connect` 连接 Snow Instance。 - **作用**: 打开实例连接面板，登录并连接到远程 Snow Instance 用于 AI 处理 - **使用方式**: - 无参数: `/connect` - 打开连接向导 - 带 API 地址: `/connect http://localhost:5136/api` - 打开面板并预填 API URL - **功能**: - 支持读取并复用已保存的连接配置 - 分步骤输入 API 地址、账号密码、实例 ID 与显示名称 - 可在已保存配置页面按 `D` 删除保存的连接配置 - **面板操作**: - `Enter` - 进入下一步或提交当前表单 - `↑/↓` - 在多字段步骤中切换焦点 - `ESC` - 返回上一步或关闭面板 - **示例**: - `/connect` - 打开连接面板 - `/connect http://localhost:5136/api` - 预填地址后连接 ### `/disconnect` 断开当前 Snow Instance 连接。 - **作用**: 断开当前已建立的实例连接 - **使用场景**: 需要切换实例、清理远程连接状态或停止通过实例处理请求时 - **示例**: 输入 `/disconnect` 断开连接 ### `/connection-status` 查看实例连接状态。 - **作用**: 输出当前 Snow Instance 的连接状态、实例信息以及错误信息（如有） - **使用场景**: 排查连接失败、确认当前是否已连接到目标实例 - **示例**: 输入 `/connection-status` 查看连接状态 ### `/mcp` 查看 MCP 服务。 - **作用**: 打开 MCP（Model Context Protocol）服务面板 - **功能**: 显示已配置的 MCP 服务列表和状态 - **示例**: 输入 `/mcp` 查看服务 ### `/usage` 查看使用统计。 - **作用**: 打开使用统计面板 - **功能**: 显示 token 使用量、API 调用次数等统计信息 - **示例**: 输入 `/usage` 查看统计 ### `/permissions` 管理工具权限。 - **作用**: 打开权限管理面板 - **功能**: 管理始终批准的工具列表，控制哪些工具可以自动执行 - **使用场景**: 需要配置工具的自动批准权限，或撤销某些工具的自动执行权限 - **示例**: 输入 `/permissions` 打开权限面板 ### `/auto-format` 切换 MCP 文件编辑后的自动格式化。 - **作用**: 开启、关闭或查看当前项目的自动格式化状态 - **参数**: - 无参数: `/auto-format` - 直接切换当前开关状态 - `on`: `/auto-format on` - 启用自动格式化 - `off`: `/auto-format off` - 禁用自动格式化 - `status`: `/auto-format status` - 查看当前状态 - **行为说明**: - 配置持久化到项目内的 `.snow/settings.json` - 仅对当前项目生效 - 默认状态为启用 - **使用场景**: 需要控制 AI 通过 MCP 修改文件后是否自动格式化时 - **示例**: - `/auto-format` - 切换当前状态 - `/auto-format status` - 查看状态 - `/auto-format off` - 关闭自动格式化 ### `/help` 帮助信息。 - **作用**: 打开帮助面板 - **功能**: 显示快捷键、常用指令说明 - **示例**: 输入 `/help` 或按 `?` 键 ### `/quit` 退出程序。 - **作用**: 安全退出 Snow CLI 应用 - **功能**: - 停止代码库索引 - 断开 VSCode 连接 - 清理资源 - **示例**: 输入 `/quit` 或按 `Ctrl+C` ### `/worktree` Git 分支管理。 - **作用**: 打开交互式 Git 分支管理面板 - **功能**: - 自动检测当前目录是否为 Git 仓库 - 显示所有本地分支列表，标记当前分支 - 快速切换分支 - 创建新分支 - 删除分支（支持强制删除未合并分支） - 本地更改冲突时提示暂存后切换 - **面板操作**: - `↑/↓` - 上下移动选择分支 - `Enter` - 切换到选中的分支 - `N` - 创建新分支 - `D` - 删除选中的分支 - `Y/N` - 确认/取消删除或暂存切换 - `ESC` - 关闭面板 - **使用场景**: 需要在不离开终端的情况下快速管理 Git 分支 - **示例**: 输入 `/worktree` 打开分支管理面板 ### `/add-dir` 添加工作目录。 - **作用**: 添加项目目录到工作目录列表（支持本地目录与 SSH 远程目录） - **使用方式**: - 无参数: `/add-dir` - 打开目录管理面板 - 带本地路径: `/add-dir /path/to/project` - 直接添加本地目录 - 远程目录: 需要在面板中按 `S` 进入「添加 SSH 远程目录」模式，填写主机/端口/用户名/认证方式/远程路径后添加 - **配置文件**: `.snow/working-dirs.json` - **示例**: - `/add-dir` - 打开面板管理（`A` 添加本地，`S` 添加 SSH，`D` 删除已标记） - `/add-dir D:\projects\myapp` - 直接添加本地目录 ### `/backend` 查看后台进程。 - **作用**: 打开后台进程管理面板 - **功能**: - 显示所有后台运行的命令 - 查看进程状态（运行中、已完成、失败） - 查看进程输出和运行时长 - 支持终止正在运行的进程 - **面板操作**: - `↑/↓` - 选择进程 - `Enter` - 终止选中的运行中进程 - `ESC` - 关闭面板 - **使用场景**: 管理通过 `Ctrl+B` 移入后台的长时间运行命令 - **示例**: 输入 `/backend` 查看后台进程 ### `/loop` 创建定时循环任务。 - **作用**: 创建一个按固定间隔周期性执行指定 Prompt 的循环任务（会话级，退出 Snow CLI 后停止） - **语法格式**: - `/loop <时长> ` - 前缀时长格式，如 `/loop 5m 检查服务状态` - `/loop every <数字> <单位>` - 后缀格式，如 `/loop 检查服务状态 every 2 hours` - 不指定时长时默认间隔 10 分钟 - **支持的时长单位**: - 秒: `s`、`sec`、`second`、`seconds` - 分: `m`、`min`、`minute`、`minutes` - 时: `h`、`hr`、`hour`、`hours` - 天: `d`、`day`、`days` - 支持复合格式，如 `8h30m`、`1d12h` - **子命令**: - `/loop list` - 列出所有活跃的循环任务 - `/loop cancel ` 或 `/loop stop ` - 取消指定循环任务 - `/loop tasks` - 打开任务管理器并显示相关任务 - **注意事项**: - 会话级别：Snow CLI 退出后所有循环任务停止 - 最多同时创建 50 个循环任务 - 上一次任务仍在运行时，本次触发会被自动跳过（skipped） - **示例**: - `/loop 5m 检查日志中的错误` - 每 5 分钟执行一次 - `/loop 8h30m 生成每日报告` - 每 8 小时 30 分钟执行一次 - `/loop 检查服务状态 every 2 hours` - 每 2 小时执行一次 - `/loop list` - 查看所有循环任务 - `/loop cancel abc12345` - 取消指定循环任务 ### `/profiles` 打开配置文件与模型切换面板。 - **作用**: 打开 Profile 面板，支持切换配置文件及 AI 模型相关设置 - **功能**: - 切换不同的配置文件（Profile） - 切换当前使用的 AI 模型 - 支持搜索过滤 - 实时切换对话使用的模型 - 支持切换思考强度设置（适用于支持思考功能的模型） - **面板操作**: - `↑/↓` - 上下移动选择 - `Tab` - 进入当前焦点 Profile 的详情编辑面板（不切换 active） - `Enter` - 切换为选中的 Profile（设为 active） - `Backspace/Delete` - 删除搜索关键词末尾字符 - 直接输入字符 - 搜索过滤 Profile 列表 - `ESC` - 关闭面板 - **使用场景**: 快捷键冲突或不方便按键时，可直接通过命令打开面板；也可用于快速切换 AI 模型 - **示例**: 输入 `/profiles` 打开配置与模型选择面板 ## 自定义扩展指令 ### `/custom` 创建自定义命令。 - **作用**: 打开自定义命令配置面板 - **功能**: - 创建新的自定义指令 - 支持两种类型： - **execute**: 在终端执行命令 - **prompt**: 发送提示词给 AI - 支持全局和项目级别 - **支持补充输入**: 可以在指令后面添加额外参数，会自动叠加到命令或提示词后面 - **存储位置**: - 全局: `~/.snow/commands/` - 项目: `.snow/commands/` - **示例**: - 输入 `/custom` 打开配置界面 - 使用补充输入: `/mycommand 额外参数` - 参数会叠加到原命令或提示词后面 #### `description` 字段（可选） 自定义命令的 JSON 文件支持可选字段 `description`，用于在指令面板（输入 `/` 的候选列表）里显示更简短的说明，避免长 prompt 占用大量终端空间。 - **兼容策略**: 未设置 `description` 时，会回退显示 `command`（对于 `type: "prompt"` 的命令即为完整提示词），因此旧命令文件无需修改。 - **设置方式**: 使用 `/custom` 创建命令时可填写该字段；留空则视为未设置。 **示例：** ```json { "type": "prompt", "command": "请根据当前对话生成一份简短总结", "description": "总结当前对话" } ``` #### 命名空间自定义指令 自定义指令支持命名空间格式：`/: [args...]`。 当你需要按功能/团队/环境对指令进行分组管理时，这会非常有用。 **目录映射（指令名由文件路径推导）：** - `.snow/commands/build.json` -> `/build` - `.snow/commands/deploy/stage.json` -> `/deploy:stage` - `.snow/commands/deploy/prod.json` -> `/deploy:prod` 同样的规则也适用于全局目录 `~/.snow/commands/`。 **注意事项 / 限制：** - 参数以空格分隔：`/deploy:stage --dry-run` - `:` 仅作为命名空间分隔符使用。 - namespace 使用 `/` 作为目录层级分隔。 - namespace 的每一段不能是 `.` 或 `..`，且不能包含 `:` 或 `\\`。 - command 部分不能包含空白、`\\`、`/` 或 `:`（且不能是 `.` 或 `..`）。 ### `/skills` 创建技能模板。 - **作用**: 打开技能创建对话框 - **功能**: - 生成 SKILL.md（主文档） - 生成 reference.md（详细参考） - 生成 examples.md（使用示例） - 创建 templates/（模板文件） - 创建 scripts/（辅助脚本） - **存储位置**: - 全局: `~/.snow/skills/` - 项目: `.snow/skills/` - **命名规则**: 小写字母、数字、连字符；可用 `/` 作为命名空间分隔（每段最多 64 字符） - **目录映射**: `~/.snow/skills///SKILL.md` -> skill id `/` - **示例**: 输入 `/skills`，在对话框里填入 `team/my-skill` 创建技能 ### 删除自定义命令/技能 创建自定义命令后，可以使用 `/<命令名> -d` 删除： - **删除自定义命令**: `/mycommand -d` - **位置识别**: 自动识别全局或项目级别 - **示例**: 如果创建了 `/deploy` 命令，使用 `/deploy -d` 删除 - **命名空间示例**: 如果创建了 `/deploy:stage` 命令，使用 `/deploy:stage -d` 删除 ### `/role-subagent` 子代理角色定义文件管理。 - **作用**: 管理子代理的 ROLE 文件（`ROLE-.md`），为不同的子代理定义独立的角色行为 - **功能**: - **创建**: `/role-subagent` - 打开交互式创建面板，依次选择作用域和子代理 - **删除**: `/role-subagent -d` 或 `/role-subagent --delete` - 打开删除面板，选择要删除的子代理角色文件 - **列表**: `/role-subagent -l` 或 `/role-subagent --list` - 打开子代理角色管理面板，查看和管理已有的角色文件 - **存储位置**: - 全局: `~/.snow/ROLE-.md` - 项目: `<项目根目录>/ROLE-.md` - **优先级**: 加载自定义角色时，项目级优先于全局级 - **面板操作**: - **创建面板**: 1. 选择位置: `G` - 全局, `P` - 项目, `ESC` - 取消 2. 选择子代理: `↑/↓` - 导航, `Enter` - 选择, `ESC` - 返回上一步 3. 确认: `Y` - 确认创建, `N` - 返回上一步 - **删除面板**: 1. 选择位置: `G` - 全局, `P` - 项目, `ESC` - 取消 2. 选择文件: `↑/↓` - 导航, `Enter` - 选择, `ESC` - 返回上一步 3. 确认: `Y` - 确认删除, `N` - 返回上一步 - **列表面板**: - `Tab` - 切换 Global / Project - `↑/↓` - 移动选择 - `D` - 删除选中的角色文件（需二次确认: `Y` 确认, `N/ESC` 取消） - `ESC` - 关闭面板 - **使用场景**: 需要为特定子代理（如探索代理、计划代理等）定制角色行为时 - **示例**: - `/role-subagent` - 打开创建面板 - `/role-subagent -d` - 打开删除面板 - `/role-subagent -l` - 打开列表管理面板 ### `/btw` 快捷提问（旁路问答）。 - **作用**: 向 AI 发起一个独立的快捷问题，不影响当前对话上下文 - **功能**: - 在侧边面板中流式展示 AI 回复 - 回复内容不会写入主对话历史 - 支持滚动浏览回复内容 - **面板操作**: - **流式阶段**: `ESC` - 中止流式并关闭 - **完成阶段**: `↑/↓` - 滚动浏览回复, `Enter` - 关闭, `ESC` - 关闭 - **错误阶段**: `Enter` - 关闭, `ESC` - 关闭 - **使用场景**: 需要快速问一个与当前任务无关的问题，又不想打断对话上下文 - **示例**: `/btw 解释一下 TypeScript 中的泛型` ## 特殊指令 ### `/agent-` 选择子代理。 - **作用**: 打开子代理选择面板 - **功能**: 选择不同的专用子代理（探索、计划、通用等） - **使用场景**: 需要特定类型的 AI 助手时 - **示例**: 输入 `/agent-` 查看可用代理 ### `/todo-` TODO 注释选择器。 - **作用**: 打开 TODO 注释选择面板 - **功能**: 扫描代码中的 TODO 注释并进行管理 - **使用场景**: 快速查看和处理代码中的待办事项 - **示例**: 输入 `/todo-` 打开选择器 ### `/skills-` 选择并注入 Skill。 - **作用**: 打开 Skill 选择面板，把选中 Skill 的 `SKILL.md` 内容注入当前输入框 - **功能**: - 支持按 Skill id、名称或描述搜索 - 支持额外追加补充文本 - 注入后在输入框里以占位形式显示，发送时仍会还原完整内容 - **面板操作**: - `↑/↓` - 选择 Skill - `Tab` - 在“搜索”和“追加文本”输入框之间切换 - `Enter` - 确认注入当前 Skill - `Backspace/Delete` - 删除当前焦点字段中的字符 - `ESC` - 关闭面板 - **使用场景**: 需要复用已有 Skill 模板，并在发送前追加具体上下文时 - **示例**: 输入 `/skills-` 打开 Skill 选择器 ## 快捷键 除了斜杠指令，还有一些便捷的快捷键： - `Ctrl+P`/`Alt+P`: 切换配置文件（Profile） - `Ctrl+L`: 向前清除输入框 - `ESC`: 中断 AI 响应 - `↑/↓`: 浏览历史输入 - `#`: 打开子代理选择面板（在输入框中输入 `#` 触发） - `>>`: 向运行中的子代理发送消息（在输入框开头输入 `>>` 触发） ## 使用技巧 1. **自动补全**: 输入 `/` 后会显示所有可用指令，可以使用方向键选择 2. **指令组合**: 某些指令可以与模式组合使用，例如： - 开启 `/yolo` 模式后执行 `/review` 可以快速审查代码 - 开启 `/plan` 模式后执行 `/init` 会生成更详细的项目文档 3. **自定义工作流**: 使用 `/custom` 创建常用操作的快捷指令 - 例如创建 `/deploy` 执行部署脚本 - 创建 `/test` 运行测试命令 4. **技能复用**: 使用 `/skills` 创建可复用的任务模板 - 代码生成模板 - 文档模板 - 测试用例模板 - 详细说明请参考 [Skills 指令详细说明](./18.Skills指令详细说明.md) 5. **会话管理**: 定期使用 `/export` 备份重要对话，使用 `/compact` 压缩长对话 ## 常见问题 ### Q: 指令不生效怎么办？ A: 检查以下几点： - 确认指令拼写正确（区分大小写） - 某些指令有前置条件（如 `/reindex` 需要启用代码库） - 查看错误提示信息 ### Q: 如何查看所有可用指令？ A: 输入 `/` 然后等待，会显示自动补全列表，或使用 `/help` 查看帮助 ### Q: 自定义指令保存在哪里？ A: - 全局指令: `~/.snow/commands/` - 项目指令: `<项目根目录>/.snow/commands/` ### Q: 如何在不同项目间共享自定义指令？ A: 创建指令时选择"全局"位置，或手动复制 `.snow/commands/` 目录到其他项目 ## 相关配置 - [敏感命令配置](./06.敏感命令配置.md) - 配置需要确认的危险操作 - [Hooks 配置](./07.Hooks配置.md) - 配置指令执行前后的自动化操作 - [代码库设置](./04.代码库设置.md) - 配置代码库索引功能（`/reindex` 所需） - [命令注入模式](./10.命令注入模式.md) - 在消息中直接执行命令的高级功能 - [漏洞猎人模式](./11.漏洞猎人模式.md) - 专业的安全分析和漏洞检测功能 ================================================ FILE: docs/usage/zh/10.命令注入模式.md ================================================ # Snow CLI 使用文档——命令注入模式与 Bash 模式 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是命令注入模式和 Bash 模式 Snow CLI 提供了两种命令执行模式，让您可以在对话中直接执行终端命令： ### 命令注入模式（单感叹号 `!`） 命令注入模式允许您在对话消息中直接嵌入命令，由系统自动执行并将结果替换到消息中，然后发送给 AI。这使得 AI 可以在不依赖工具调用的情况下，快速获取命令执行结果，提升交互效率。 ### Bash 模式（双感叹号 `!!`） Bash 模式是一个纯终端模式，执行命令但不发送给 AI。就像一个真正的终端一样，仅执行命令并显示结果，不会触发 AI 对话。适合快速执行命令而不需要 AI 参与的场景。 ## 为什么使用这两种模式 ### 命令注入模式的优势 传统的命令执行方式需要 AI 调用工具，等待用户批准，然后执行命令。命令注入模式提供了更直接的方式： - 在消息中直接嵌入命令，无需额外的工具调用流程 - AI 可以获取实时的系统状态信息 - 适合快速查询和简单操作 - 与敏感命令保护机制集成，确保安全 ### Bash 模式的优势 Bash 模式提供了一个纯粹的终端体验： - 快速执行命令，不触发 AI 对话 - 节省 API 调用成本 - 适合日常终端操作 - 与命令注入模式共享敏感命令保护机制 ## 语法对比 ### 命令注入模式（单感叹号） **基础语法：** ``` !`command` ``` 在消息中使用单感叹号加反引号包裹命令，系统会执行命令并将结果替换到消息中，然后发送给 AI。 **示例：** ``` 检查当前目录：!`pwd` 列出文件：!`ls -la` 查看Git状态：!`git status` ``` **自定义超时时间：** ``` !`command` ``` 在命令后使用尖括号指定超时时间（单位：毫秒）。如果不指定，默认超时时间为 30000 毫秒（30 秒）。 **示例：** ``` !`npm install`<60000> !`docker build .`<120000> !`sleep 5`<10000> ``` ### Bash 模式（双感叹号） **基础语法：** ``` !!`command` ``` 在消息中使用双感叹号加反引号包裹命令，系统会执行命令但不发送给 AI。 **示例：** ``` !!`pwd` !!`ls -la` !!`git status` ``` **自定义超时时间：** ``` !!`command` ``` 语法与命令注入模式相同，支持自定义超时时间。 **示例：** ``` !!`npm install`<60000> !!`docker build .`<120000> !!`sleep 5`<10000> ``` ### 语法规则 **命令注入模式：** - 必须使用完整的 `!` + `` ` `` 组合，缺一不可 - 反引号内为要执行的命令 - 超时时间可选，格式为 `<数字>`，单位毫秒 - 一条消息中可以包含多个命令注入 - 命令按顺序执行 - 执行结果会替换命令语法，然后发送给 AI **Bash 模式：** - 必须使用完整的 `!!` + `` ` `` 组合，缺一不可 - 反引号内为要执行的命令 - 超时时间可选，格式为 `<数字>`，单位毫秒 - 一条消息中可以包含多个命令 - 命令按顺序执行 - 执行结果仅显示，不发送给 AI ## 命令执行流程 ### 命令注入模式流程 当您在消息中使用命令注入语法（单感叹号）时，系统会： #### 1. 解析命令 系统使用正则表达式 `/!`([^`]+)`(?:<(\d+)>)?/g` 解析消息中的所有命令： - 提取命令内容 - 提取超时时间（如果有） - 标记命令在消息中的位置 #### 2. 敏感命令检查 在执行前，系统会检查命令是否匹配敏感命令规则： - 遍历已启用的敏感命令模式 - 如果匹配，弹出确认对话框 - 显示命令内容、匹配模式、风险说明 - 等待用户确认或取消 关于敏感命令配置，请参考：[敏感命令配置](./06.敏感命令配置.md) #### 3. 执行命令 用户确认后（或非敏感命令直接执行）： - Windows 系统使用 `cmd.exe` 执行 - Unix-like 系统（macOS、Linux）使用 `sh` 执行 - 使用当前工作目录作为执行路径 - 继承当前环境变量 - 应用指定的超时时间 #### 4. 收集输出 命令执行期间： - 捕获标准输出（stdout） - 捕获标准错误（stderr） - 记录退出代码 - 检测超时情况 #### 5. 替换消息内容 执行完成后，系统会将原命令语法替换为执行结果： 成功时： ``` --- Command: ls -la --- total 48 drwxr-xr-x 10 user staff 320 Dec 5 10:30 . drwxr-xr-x 20 user staff 640 Dec 4 15:22 .. -rw-r--r-- 1 user staff 1234 Dec 5 10:30 README.md --- End of output --- ``` 失败时： ``` --- Command: invalid-command --- Error: command not found: invalid-command --- End of output --- ``` #### 6. 发送给 AI 替换后的完整消息发送给 AI，AI 可以基于真实的命令输出进行分析和回复。 ### Bash 模式流程 当您在消息中使用 Bash 模式语法（双感叹号）时，系统会： #### 1. 解析命令 系统使用正则表达式 `/!!`([^`]+)`(?:<(\d+)>)?/g` 解析消息中的所有命令： - 提取命令内容 - 提取超时时间（如果有） - 标记命令在消息中的位置 #### 2. 敏感命令检查 与命令注入模式相同，执行前会检查敏感命令规则。 #### 3. 执行命令 执行方式与命令注入模式完全相同。 #### 4. 显示输出 命令执行完成后，结果会显示在终端中，但不会发送给 AI。 #### 5. 终止流程 Bash 模式不会触发 AI 对话，执行完成后流程结束。 ## 使用场景 ### 命令注入模式场景 #### 快速状态查询 ``` 当前目录情况如何？!`ls -la` ``` AI 会看到实际的文件列表，并基于此回答问题。 #### 获取系统信息 ``` 帮我分析系统资源使用： 内存：!`free -h` 磁盘：!`df -h` ``` #### Git 操作查询 ``` 当前分支状态：!`git status` 最近提交：!`git log -5 --oneline` ``` #### 环境检查 ``` 检查Node版本：!`node --version` 检查依赖：!`npm list --depth=0` ``` #### 多命令组合 ``` 项目信息： Git分支：!`git branch --show-current` 未提交更改：!`git status --short` 最近提交：!`git log -1 --oneline` ``` ### Bash 模式场景 #### 快速终端操作 ``` !!`pwd` !!`ls -la` !!`git status` ``` 不触发 AI 对话，仅显示命令执行结果。 #### 日常命令执行 ``` !!`npm run build` !!`git pull` !!`docker ps` ``` 适合不需要 AI 参与的日常操作。 #### 测试命令 ``` !!`echo "Hello World"` !!`date` !!`whoami` ``` 快速测试命令是否正常工作。 ## 安全机制 ### 敏感命令保护 命令注入模式与敏感命令配置完全集成： 1. **自动检测** - 所有命令在执行前都会检查是否匹配敏感模式 - 匹配的命令会触发确认流程 2. **用户确认** - 显示完整的命令内容 - 显示匹配的敏感模式和风险描述 - 显示超时时间（如果有自定义） - 用户可以选择执行或取消 3. **拒绝反馈** - 如果用户拒绝执行敏感命令 - AI 会收到反馈，可能建议替代方案 - 被拒绝的命令不会出现在最终消息中 ### 超时保护 - 默认 30 秒超时防止命令卡死 - 可以为长时间运行的命令自定义超时 - 超时后命令会被强制终止 - 超时信息会反馈给 AI ### 环境隔离 - 命令在当前工作目录执行 - 继承当前 shell 环境变量 - 不会影响 Snow CLI 主进程 - 命令失败不会导致 CLI 崩溃 ## 最佳实践 ### 1. 合理使用命令注入 **适合的场景**： - 快速查询系统状态 - 获取文件列表或内容 - 检查环境配置 - 简单的 Git 操作查询 **不适合的场景**： - 复杂的批量操作（使用工具调用更安全） - 需要交互的命令（如需要输入密码） - 长时间运行的任务（除非设置足够的超时） - 危险的系统操作（应通过工具调用并仔细确认） ### 2. 设置合适的超时时间 根据命令的预期执行时间设置超时： ``` 快速查询（使用默认）：!`pwd` 安装依赖（60秒）：!`npm install`<60000> 构建镜像（120秒）：!`docker build .`<120000> 运行测试（180秒）：!`npm test`<180000> ``` ### 3. 结合上下文使用 给 AI 提供上下文，让它更好地理解命令输出： ``` 我想优化这个项目的依赖，先帮我看看当前安装了哪些包：!`npm list --depth=0` ``` ### 4. 处理敏感命令 对于可能触发敏感命令保护的操作： ``` 请帮我检查是否有未使用的文件可以清理（不要直接删除）：!`git clean -n` ``` 使用安全的查询选项（如 git clean -n），而不是直接执行危险操作。 ### 5. 多命令协作 将相关命令组合在一起，让 AI 获得完整视图： ``` 分析这个分支的情况： 当前分支：!`git branch --show-current` 未合并的提交：!`git log origin/main..HEAD --oneline` 未提交的更改：!`git status --short` ``` ## 常见问题 **Q: 命令注入和工具调用有什么区别？** A: 命令注入会在消息发送给 AI 前执行命令并替换结果，AI 看到的是执行结果。工具调用是 AI 主动请求执行命令，在 AI 响应过程中进行。命令注入更适合快速查询，工具调用更适合复杂操作。 **Q: 为什么我的命令没有执行？** A: 检查以下几点： - 确认语法正确：`!`command`` - 感叹号和反引号必须都存在 - 如果是敏感命令，确认是否在确认对话框中选择了执行 - 查看是否超时（默认 30 秒） **Q: 可以在一条消息中使用多个命令吗？** A: 可以。系统会按顺序执行所有命令，每个命令的结果会替换对应的语法位置。 **Q: 命令执行失败会怎样？** A: 失败的命令会在输出中显示错误信息，AI 会看到完整的错误内容并可能提供解决方案。 **Q: 超时时间最大可以设置多少？** A: 理论上没有上限，但建议不超过 300000 毫秒（5 分钟）。超长运行的任务建议使用工具调用方式，可以更好地监控和管理。 **Q: 命令注入会绕过敏感命令保护吗？** A: 不会。所有通过命令注入执行的命令都会经过敏感命令检查，匹配敏感模式的命令必须经过用户确认。 **Q: 可以注入需要交互的命令吗？** A: 不建议。命令注入不支持交互式输入，这类命令会挂起直到超时。如果需要执行交互式命令，请使用 Snow CLI 的工具调用功能。 **Q: Windows 和 Unix 系统的命令有区别吗？** A: 是的。Windows 使用 `cmd.exe` 执行，Unix-like 系统使用 `sh` 执行。编写命令时需要考虑跨平台兼容性，或者明确指定目标平台。 ## 配置文件位置 命令注入模式本身无需配置，但它依赖敏感命令配置： - Windows: `%USERPROFILE%\.snow\sensitive-commands.json` - macOS/Linux: `~/.snow/sensitive-commands.json` 详细配置方法请参考：[敏感命令配置](./06.敏感命令配置.md) ## 相关功能 - [敏感命令配置](./06.敏感命令配置.md) - 配置需要确认的危险命令 - [指令面板说明](./09.指令面板说明.md) - 了解其他快捷指令功能 - [漏洞猎人模式](./11.漏洞猎人模式.md) - 专业的安全分析功能，也会使用敏感命令保护 ================================================ FILE: docs/usage/zh/11.漏洞猎人模式.md ================================================ # Snow CLI 使用文档——漏洞猎人模式 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是漏洞猎人模式 漏洞猎人模式（Vulnerability Hunting Mode）是 Snow CLI 的一个专业安全分析代理模式，专注于发现和验证代码库中的安全漏洞。与普通对话模式不同，该模式会遵循严格的安全分析流程，提供系统化的漏洞检测、证据收集、验证脚本生成和详细报告。 ## 为什么使用漏洞猎人模式 在软件开发过程中，安全漏洞可能导致严重后果。漏洞猎人模式提供了专业的安全分析能力： - 系统化的漏洞检测流程，涵盖多种漏洞类型 - 基于证据的分析，避免误报 - 为每个漏洞生成可执行的验证脚本 - 详细的修复建议和优先级排序 - 交互式沟通，确保分析范围准确 - 专注于特定模块，避免泛泛而谈 ## 启用漏洞猎人模式 ### 使用指令切换 在 Snow CLI 对话界面输入： ``` /vulnerability-hunting ``` 系统会显示模式切换提示，再次输入该指令可以关闭该模式。 ### 模式状态 - 模式状态会保存在 localStorage 中 - 重启应用后保持上次的状态 - 可以随时切换回普通模式 ## 核心原则 漏洞猎人模式遵循以下核心原则： ### 1. 用户查询优先 AI 会优先响应您的实际问题和需求，不会在您没有要求时擅自分析整个代码库。 ### 2. 语言适应 AI 始终使用与您相同的语言进行回复和生成报告。 ### 3. 交互式沟通 AI 会频繁使用交互式问答来： - 澄清模糊的需求 - 确认分析范围 - 询问具体测试场景 - 验证发现的问题 - 获取修改代码的权限 ### 4. 基于证据的分析 所有漏洞报告必须有具体的代码证据，AI 不会进行猜测或假设。 ### 5. 聚焦范围 每次只分析特定的模块或组件，不会一次性分析整个代码库。 ### 6. 验证要求 每个漏洞都必须有验证脚本或概念验证代码。 ### 7. 只读分析 除非您明确要求，否则 AI 不会修改源代码，只会生成报告和建议。 ## 完整工作流程 漏洞猎人模式遵循严格的5阶段工作流程： ### 阶段 1：范围定义（强制性） **目标**：明确定义要分析的具体区域。 **流程**： 1. **如果您没有指定模块**： - AI 会探索代码库结构 - 列出主要模块和组件 - 询问您想分析哪个具体区域 2. **如果您指定了模糊区域**： - AI 会将其细分为更小的子组件 - 询问您是否关注所有部分还是特定部分 3. **开始分析前确认**： - 优先检查哪类漏洞（逻辑错误 vs 安全问题） - 预期的分析深度 - 是否有特定关注点或已知问题 ## 使用场景示例 ### 场景 1：分析特定模块 您：进入漏洞猎人模式，分析认证模块 AI：好的，我已切换到漏洞猎人模式。让我先探索认证模块的结构... 我发现了以下认证相关组件： 1. 登录流程（login.ts, auth.ts） 2. 会话管理（session.ts, middleware.ts） 3. 密码重置（resetPassword.ts） 4. Token 处理（jwt.ts, tokenService.ts） 您想先分析哪个具体区域？还是我应该检查所有组件？ 您：先检查 JWT token 处理 AI：明白了。在开始分析前，我想确认一下： 您希望我优先关注： 1. 逻辑错误（空值检查、边界情况、竞态条件） 2. 安全问题（注入、认证绕过、数据泄露） 3. 两者都检查 您：两者都检查 AI：好的，我将全面分析 JWT token 处理模块... [执行分析...] 我发现了以下问题： 1. [严重] JWT 签名验证缺失 2. [高危] Token 过期检查逻辑错误 3. [中危] 缺少 Token 刷新机制 我已经创建了验证脚本。您想查看详细报告吗？ ### 场景 2：验证已知问题 您：我怀疑用户输入处理有 SQL 注入问题，帮我验证一下 AI：好的，让我定位用户输入处理的相关代码... 我找到了这些处理用户输入的地方： - src/controllers/userController.ts:searchUser() - src/controllers/productController.ts:search() - src/services/queryBuilder.ts:buildQuery() 这些都是您关注的吗？还是有特定的函数？ 您：主要是 searchUser 函数 AI：明白了。我将重点分析该函数的 SQL 注入风险... [分析后...] 确认发现 SQL 注入漏洞！详情： - 位置：src/controllers/userController.ts:42 - 问题：直接拼接用户输入到 SQL 查询 - 严重程度：严重 我已创建验证脚本：.snow/vulnerability-hunting/scripts/verify-sql-injection.sh 运行该脚本可以实际触发漏洞。需要我生成详细报告和修复建议吗？ ### 场景 3：生成安全报告 您：为整个 API 模块生成安全分析报告 AI：好的，API 模块很大。让我先列出主要的子模块： 1. 用户 API（/api/users/*） 2. 产品 API（/api/products/*） 3. 订单 API（/api/orders/*） 4. 认证 API（/api/auth/*） 5. 管理 API（/api/admin/*） 由于模块较多，建议分批分析。您想从哪个开始？ 还是我应该做一个快速的高层次扫描，找出最明显的问题？ 您：先做快速扫描，找出严重问题 AI：明白了，我将进行快速安全扫描，重点关注严重漏洞... [扫描后...] 快速扫描完成，发现以下严重问题： 1. [严重] 用户 API：SQL 注入（3处） 2. [严重] 认证 API：JWT 签名验证缺失 3. [严重] 管理 API：缺少权限检查 4. [高危] 订单 API：竞态条件可能导致重复扣款 建议先修复这些严重问题。需要我对每个问题创建详细报告和验证脚本吗？ ## 文件结构 漏洞猎人模式生成的所有文件都存储在项目的 `.snow/vulnerability-hunting/` 目录下： ```text .snow/ └── vulnerability-hunting/ ├── docs/ # 分析报告目录 │ ├── auth-module.md # 认证模块报告 │ ├── api-security-scan.md # API 安全扫描报告 │ └── payment-module.md # 支付模块报告 └── scripts/ # 验证脚本目录 ├── verify-jwt-bypass.js # JWT 绕过验证 ├── verify-sql-injection.sh # SQL 注入验证 ├── verify-race-condition.js # 竞态条件验证 └── verify-auth-bypass.py # 认证绕过验证 ``` ### 报告命名规范 - 使用小写字母和连字符 - 格式：`[模块名]-[报告类型].md` - 示例：`auth-module.md`、`api-security-scan.md` ### 脚本命名规范 - 使用小写字母和连字符 - 格式：`verify-[漏洞类型].[扩展名]` - 示例：`verify-sql-injection.sh`、`verify-null-pointer.js` ## 最佳实践 ### 1. 明确分析范围 不要要求分析整个代码库，而是： - 指定具体的模块或组件 - 明确关注的漏洞类型 - 提供已知的风险点 ### 2. 及时沟通 AI 会频繁询问以确认细节，请： - 回答 AI 的问题以明确需求 - 提供额外的上下文信息 - 说明特定的安全关注点 ### 3. 验证发现 对于 AI 发现的问题： - 运行提供的验证脚本 - 在测试环境中确认 - 评估实际影响 ### 4. 优先级修复 根据报告中的优先级： - 立即修复严重漏洞 - 按优先级排序其他问题 - 记录修复过程 ### 5. 持续改进 漏洞修复后： - 要求 AI 重新验证 - 添加安全测试 - 更新安全检查清单 ## 限制和注意事项 ### 1. 分析范围 - 每次只分析特定模块，不是整个代码库 - 需要明确指定分析范围 - 大型项目建议分多次分析 ### 2. 验证脚本 - 脚本应在隔离环境中运行 - 某些脚本可能需要特定的测试环境 - 运行前请仔细阅读脚本内容 ### 3. 只读模式 - 默认情况下不修改源代码 - 只生成报告和修复建议 - 需要代码修复时必须明确要求 ### 4. 误报可能性 - AI 分析可能产生误报 - 始终验证发现的问题 - 结合人工审查 ### 5. 覆盖范围 - 不能保证发现所有漏洞 - 专注于常见和严重的安全问题 - 建议结合其他安全工具 ## 常见问题 **Q: 漏洞猎人模式和普通模式有什么区别？** A: 漏洞猎人模式是专门的安全分析代理，遵循严格的5阶段工作流程，生成详细报告和验证脚本。普通模式更通用，适合日常开发任务。 **Q: 分析一个模块需要多长时间？** A: 取决于模块大小和复杂度。小型模块（几百行）可能需要几分钟，中型模块（几千行）可能需要10-30分钟，大型模块建议拆分分析。 **Q: 验证脚本安全吗？** A: 验证脚本设计为安全运行，不会造成永久性损害。但建议在隔离的测试环境中运行，不要在生产环境执行。 **Q: AI 可以自动修复漏洞吗？** A: 默认情况下不会。AI 只提供修复建议。如果需要自动修复，必须明确要求，AI 会先征求您的确认。 **Q: 如何查看之前的分析报告？** A: 所有报告保存在 `.snow/vulnerability-hunting/docs/` 目录下，可以随时查看。 **Q: 可以自定义分析类别吗？** A: 可以。AI 会在开始前询问您关注哪些类别。您可以指定只检查逻辑错误、只检查安全问题，或两者都检查。 **Q: 漏洞猎人模式支持哪些编程语言？** A: 支持常见的编程语言，包括 JavaScript/TypeScript、Python、Java、Go、Rust、C# 等。分析质量取决于代码库的索引状态。 **Q: 发现的漏洞会自动报告给团队吗？** A: 不会。所有报告只存储在本地。您需要手动分享报告或集成到您的安全工作流中。 **Q: 可以导出报告到其他格式吗？** A: 报告以 Markdown 格式生成，可以轻松转换为 PDF、HTML 或其他格式。您也可以要求 AI 生成特定格式的报告。 **Q: 如何结合 CI/CD 使用？** A: 可以在 CI/CD 流程中运行验证脚本，检测已知漏洞是否修复。但完整的分析建议手动触发，因为需要交互式沟通。 ## 相关功能 - [指令面板说明](./09.指令面板说明.md) - 了解 `/vulnerability-hunting` 等指令 - [敏感命令配置](./06.敏感命令配置.md) - 配置需要确认的危险命令 - [代码库设置](./04.代码库设置.md) - 启用代码库索引以提升分析效果 ================================================ FILE: docs/usage/zh/12.无头模式.md ================================================ # Snow CLI 使用文档——无头模式 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是无头模式 无头模式（Headless Mode）是 Snow CLI 的快速对话功能，允许您直接在命令行中提问并获得 AI 回复，无需进入交互式界面。它非常适合： - 脚本自动化 - CI/CD 集成 - 快速咨询 - 第三方工具集成 ## 基础用法 ### 单次提问 ```bash snow --ask "你的问题" ``` 示例： ```bash snow --ask "帮我解释这段代码的作用" snow --ask "如何优化这个SQL查询" snow --ask "解释一下React的useState钩子" ``` ### 连续对话 无头模式支持会话上下文保持，允许您进行连续对话： ```bash # 第一次提问 snow --ask "帮我创建一个React组件" # 输出会包含 SESSION_ID=abc-123-def-456 # 使用返回的 Session ID 继续对话 snow --ask "给这个组件添加样式" abc-123-def-456 # 继续对话 snow --ask "再添加一些交互功能" abc-123-def-456 ``` ## 特性说明 ### 自动会话管理 - 每次对话都会自动创建会话并保存 - 会话 ID 会在输出末尾以 `SESSION_ID=` 格式显示 - 历史消息会被加载并作为上下文传递给 AI - 支持跨平台会话共享（同一项目） ### YOLO 模式 无头模式默认启用 YOLO 模式（自动批准工具调用）： - 非敏感命令自动执行 - 敏感命令仍需手动确认 - 提高自动化效率 关于敏感命令配置，请参考：[敏感命令配置](./6.敏感命令配置.md) ### 文件引用 无头模式支持在问题中引用文件： ```bash snow --ask "分析这个文件的问题 @src/App.tsx" snow --ask "优化这段代码 @utils/helper.js" ``` ### 彩色输出 无头模式提供友好的彩色终端输出： - 用户查询：青色边框 - AI 响应：Markdown 渲染，代码高亮 - 工具执行：黄色/绿色/红色状态标识 - 会话信息：蓝色信息框 ## 会话恢复机制 ### 工作原理 1. **首次对话**：创建新会话，生成 UUID 2. **保存历史**：所有消息自动保存到 `~/.snow/sessions/` 3. **提供会话 ID**：在输出末尾显示 `SESSION_ID=` 4. **恢复对话**：使用会话 ID 加载历史消息 5. **继续对话**：新消息追加到历史记录 ### 会话格式 输出中的会话信息包含两部分： 1. **人类友好格式**（彩色框）： ``` ┌─ Session Information │ Session ID: abc-123-def-456 │ To continue this conversation, use: │ snow --ask "your next question" abc-123-def-456 └─ ``` 2. **机器可解析格式**（纯文本）： ``` SESSION_ID=abc-123-def-456 ``` ### 会话存储位置 - Windows: `%USERPROFILE%\.snow\sessions\<项目名>\<日期>\.json` - macOS/Linux: `~/.snow/sessions/<项目名>/<日期>/.json` 会话按项目和日期自动分类，便于管理。 ## 第三方集成 ### Shell 脚本集成 ```bash #!/bin/bash # 执行对话并提取 Session ID output=$(snow --ask "创建一个API接口") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) # 使用 Session ID 继续对话 snow --ask "添加错误处理" "$session_id" snow --ask "添加单元测试" "$session_id" ``` ### Python 集成 ```python import subprocess import re # 执行对话 result = subprocess.run( ['snow', '--ask', '帮我分析这个错误'], capture_output=True, text=True ) # 提取 Session ID match = re.search(r'SESSION_ID=(.+)', result.stdout) if match: session_id = match.group(1).strip() # 继续对话 subprocess.run([ 'snow', '--ask', '如何修复这个问题', session_id ]) ``` ### Node.js 集成 ```javascript const { execSync } = require('child_process'); // 执行对话 const output = execSync('snow --ask "创建一个Express路由"', { encoding: 'utf-8' }); // 提取 Session ID const match = output.match(/SESSION_ID=(.+)/); if (match) { const sessionId = match[1].trim(); // 继续对话 execSync(`snow --ask "添加中间件" ${sessionId}`); } ``` ### CI/CD 集成 在 GitHub Actions 中使用： ```yaml name: AI Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup Snow CLI run: npm install -g snow-ai - name: AI Review run: | # 分析变更的文件 changed_files=$(git diff --name-only HEAD^) # 请求 AI 分析 output=$(snow --ask "分析这些文件的变更：$changed_files") # 提取建议 echo "$output" >> $GITHUB_STEP_SUMMARY ``` ## 输出格式 ### 标准输出结构 ``` ╭─────────────────────────────────────────────────────────╮ │ ❆ Snow AI CLI - Headless Mode ❆ │ ╰─────────────────────────────────────────────────────────╯ ┌─ Continuing Session (如果是继续对话) │ Session ID: abc-123-def-456 │ Previous messages: 4 ┌─ User Query │ 你的问题内容 └─ Assistant Response AI 的回复内容（Markdown 格式，代码高亮） ┌─ Session Information │ Session ID: abc-123-def-456 │ To continue this conversation, use: │ snow --ask "your next question" abc-123-def-456 └─ SESSION_ID=abc-123-def-456 ``` ### 解析建议 对于脚本和工具集成，推荐的解析方式： 1. **提取 Session ID**： - 使用正则表达式 `/SESSION_ID=(.+)/` - 或直接查找最后一行的 `SESSION_ID=` 前缀 2. **提取 AI 响应**： - 查找 `└─ Assistant Response` 之后的内容 - 去除 ANSI 颜色代码（如需要） 3. **错误处理**： - 检查退出代码 - 查找 `✗ Error:` 标记 ## 使用场景 ### 代码审查助手 ```bash # 快速代码审查 git diff | snow --ask "审查这些代码变更，指出潜在问题" # 针对性审查 snow --ask "这段代码有性能问题吗 @src/utils/parser.ts" ``` ### 文档生成 ```bash # 生成函数文档 snow --ask "为这个函数生成 JSDoc 注释 @src/api.ts" # 生成 README snow --ask "根据代码结构生成项目 README @src/" ``` ### 快速咨询 ```bash # 技术问题 snow --ask "React 18 的并发特性如何使用" # 调试建议 snow --ask "这个错误怎么解决：TypeError: Cannot read property 'map' of undefined" ``` ### 自动化工作流 ```bash #!/bin/bash # 自动化代码优化流程 output=$(snow --ask "分析项目依赖 @package.json") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) snow --ask "建议需要更新的依赖" "$session_id" snow --ask "生成依赖更新脚本" "$session_id" ``` ### 测试生成 ```bash # 生成单元测试 snow --ask "为这个函数生成单元测试 @src/calculator.ts" # 生成测试数据 output=$(snow --ask "生成测试用的用户数据 JSON") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) snow --ask "再生成10个变体数据" "$session_id" ``` ## 最佳实践 ### 1. 清晰的问题描述 ```bash # 好的示例 snow --ask "优化这个 SQL 查询的性能，重点关注索引使用 @query.sql" # 不够清晰 snow --ask "优化 @query.sql" ``` ### 2. 合理使用会话上下文 ```bash # 建立上下文后的连续对话 output=$(snow --ask "创建一个用户认证系统") session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) # 后续问题可以更简洁 snow --ask "添加密码重置功能" "$session_id" snow --ask "添加邮箱验证" "$session_id" ``` ### 3. 处理长时间任务 对于可能需要长时间思考的任务： ```bash # 复杂任务可能需要更多时间 snow --ask "重构整个认证模块，使用最佳实践 @src/auth/" ``` 等待 AI 完成思考和工具调用。 ### 4. 结合命令注入 ```bash # 在问题中嵌入实时信息 snow --ask "分析当前 Git 分支状态 !`git status` 并提供建议" ``` 关于命令注入，请参考：[命令注入模式](./10.命令注入模式.md) ### 5. 错误处理 ```bash #!/bin/bash # 脚本中的错误处理 if ! output=$(snow --ask "你的问题" 2>&1); then echo "错误：AI 对话失败" echo "$output" exit 1 fi # 检查是否成功生成 Session ID if ! echo "$output" | grep -q "SESSION_ID="; then echo "警告：未能获取 Session ID" fi ``` ## 限制和注意事项 ### 不支持的功能 1. **交互式工具**： - `askuser` 工具不可用 - 无法在无头模式下请求用户输入 2. **Plan 模式**： - 无头模式不支持 Plan 模式 - 所有工具调用立即执行（YOLO 模式） 3. **实时更新显示**： - 不支持实时流式输出到终端 - 完成后一次性显示结果 ### 安全考虑 1. **敏感命令确认**： - 即使在 YOLO 模式下，敏感命令仍需确认 - 不适合完全无人值守的自动化 2. **API 密钥保护**： - 在 CI/CD 中使用时，确保 API 密钥安全存储 - 使用环境变量或密钥管理服务 3. **输出内容审查**： - AI 输出可能包含敏感信息 - 在公开日志中使用时注意过滤 ### 性能注意事项 1. **会话大小**： - 长会话历史会增加 Token 消耗 - 建议周期性开始新会话 2. **并发限制**： - 同时运行多个无头模式实例时注意 API 限流 3. **网络延迟**： - 响应时间取决于网络和 AI 服务 - 考虑设置合理的超时 ## 常见问题 **Q: 无头模式和交互式模式有什么区别？** A: 无头模式是单次执行模式，执行完成后自动退出，适合脚本和自动化。交互式模式提供完整的 UI 界面，支持持续对话和更多高级功能。 **Q: Session ID 会过期吗？** A: Session ID 不会过期，会话文件永久保存在本地。但是非常旧的会话可能因为上下文过大而影响性能。 **Q: 可以在不同项目间共享会话吗？** A: 不可以。会话按项目路径分类存储，确保不同项目的对话不会混淆。 **Q: 如何查看所有历史会话？** A: 会话保存在 `~/.snow/sessions/` 目录下，按项目和日期组织。您可以使用文件管理器浏览，或使用 `/resume` 查看会话。 **Q: Session ID 丢失了怎么办？** A: 可以在会话存储目录中查找最近的会话文件，文件名即为 Session ID。或者使用交互式模式的 `/resume` 命令查看历史会话。 **Q: 无头模式支持文件上传吗？** A: 支持通过 `@文件路径` 语法引用文件，但不支持图片上传。图片分析请使用交互式模式。 **Q: 如何在无头模式中使用不同的 API 配置？** A: 无头模式使用全局配置文件（`~/.snow/profiles.json`）。如需切换配置，请先在交互式模式中切换 Profile，或直接编辑配置文件。 **Q: 输出的 ANSI 颜色代码如何去除？** A: ```bash # 使用 sed 去除颜色代码 snow --ask "你的问题" | sed 's/\x1b\[[0-9;]*m//g' # 或使用其他工具 snow --ask "你的问题" | ansi2txt ``` **Q: 可以重定向输出到文件吗？** A: 可以，但会保留 ANSI 颜色代码： ```bash snow --ask "你的问题" > output.txt # 同时保存到文件和显示在终端 snow --ask "你的问题" | tee output.txt ``` ## 配置文件位置 无头模式使用全局配置： - **API 配置**: `~/.snow/profiles.json` - **敏感命令**: `~/.snow/sensitive-commands.json` - **会话存储**: `~/.snow/sessions/<项目名>/<日期>/` 配置方法请参考：[首次配置](./02.首次配置.md) ## 相关功能 - [命令注入模式](./10.命令注入模式.md) - 在问题中嵌入实时命令执行 - [敏感命令配置](./06.敏感命令配置.md) - 配置需要确认的危险命令 - [指令面板说明](./09.指令面板说明.md) - 了解交互式模式的更多功能 ## 示例脚本 ### 完整的自动化示例 ```bash #!/bin/bash # 颜色定义 RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' NC='\033[0m' # No Color # 错误处理 set -e trap 'echo -e "${RED}脚本执行失败${NC}"' ERR echo -e "${YELLOW}开始自动化代码审查...${NC}" # 获取变更的文件 changed_files=$(git diff --name-only HEAD^ | tr '\n' ' ') if [ -z "$changed_files" ]; then echo -e "${RED}没有检测到文件变更${NC}" exit 0 fi echo -e "${GREEN}检测到变更文件: $changed_files${NC}" # 初始审查 echo -e "${YELLOW}执行初始代码审查...${NC}" output=$(snow --ask "审查这些文件的变更：$changed_files") # 提取 Session ID session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2) if [ -z "$session_id" ]; then echo -e "${RED}无法获取 Session ID${NC}" exit 1 fi echo -e "${GREEN}Session ID: $session_id${NC}" # 详细分析 echo -e "${YELLOW}请求安全分析...${NC}" snow --ask "从安全角度分析这些变更" "$session_id" echo -e "${YELLOW}请求性能分析...${NC}" snow --ask "从性能角度分析这些变更" "$session_id" echo -e "${GREEN}代码审查完成！${NC}" ``` 这个脚本展示了如何： - 错误处理和颜色输出 - Session ID 提取和验证 - 多轮连续对话 - 自动化工作流集成 ================================================ FILE: docs/usage/zh/13.快捷键指南.md ================================================ # 快捷键指南 本文档列出了 SNOW AI CLI 中所有可用的快捷键和功能。 ## 目录 - [基本编辑](#基本编辑) - [光标移动](#光标移动) - [文本删除](#文本删除) - [模式切换](#模式切换) - [导航和选择](#导航和选择) - [剪贴板操作](#剪贴板操作) - [命令执行控制](#命令执行控制) - [历史记录和回滚](#历史记录和回滚) - [面板和选择器](#面板和选择器) ## 基本编辑 | 快捷键 | 功能 | 说明 | | ---------------------- | -------- | ------------------------------ | | `Enter` | 提交消息 | 发送当前输入的消息给 AI | | `Ctrl+Enter` | 插入换行 | 在输入框中插入新行，不提交消息 | | `Ctrl+G` | 外部编辑 | 在 Notepad 中编辑当前输入（仅 Windows） | | `Backspace` / `Delete` | 删除字符 | 删除光标前的字符 | ## 光标移动 ### Readline 兼容快捷键 | 快捷键 | 功能 | 说明 | | -------------------- | -------------- | ------------------------------------ | | `Ctrl+A` | 行首 | 移动光标到当前行开头 | | `Ctrl+E` | 行尾 | 移动光标到当前行末尾 | | `Alt+F` / `Option+F` | 向前一个词 | 跳转到下一个词的开头（支持中文标点） | | `Alt+B` / `Option+B` | 向后一个词 | 跳转到上一个词的开头（支持中文标点） | | `↑` | 历史记录上一条 | 在终端风格历史导航中浏览上一条消息 | | `↓` | 历史记录下一条 | 在终端风格历史导航中浏览下一条消息 | 注意：macOS 上 Option 键的三种检测方式： 1. `key.meta` 属性 2. 转义序列 `\x1bf` / `\x1bb` 3. Terminal.app 默认特殊字符 `ƒ` / `∫` ## 文本删除 ### Readline 兼容快捷键 | 快捷键 | 功能 | 说明 | | -------- | ------------ | ------------------------------------ | | `Ctrl+K` | 删除到行尾 | 删除从光标位置到当前行末尾的所有内容 | | `Ctrl+U` | 删除到行首 | 删除从当前行开头到光标位置的所有内容 | | `Ctrl+W` | 删除前一个词 | 删除光标前的一个单词 | | `Ctrl+D` | 删除当前字符 | 删除光标位置的字符 | ### 旧版兼容快捷键（保留） | 快捷键 | 功能 | 说明 | | -------- | ---------- | ---------------------------------- | | `Ctrl+L` | 清除到开头 | 删除从开头到光标的内容（旧版兼容） | | `Ctrl+R` | 清除到末尾 | 删除从光标到末尾的内容（旧版兼容） | ## 模式切换 ### YOLO 和 Plan 模式 | 快捷键 | 功能 | 说明 | | ----------- | ------------ | ---------------------------------------------- | | `Shift+Tab` | 循环切换模式 | 按顺序切换：YOLO → YOLO+Plan → Plan → 全部关闭 | | `Ctrl+Y` | 循环切换模式 | 同 `Shift+Tab`，按顺序切换模式 | 模式切换顺序： 1. YOLO 模式 2. YOLO + Plan 模式（启用 Plan 时自动禁用漏洞搜寻模式） 3. Plan 模式 4. 全部关闭 ### Profile 配置切换 | 快捷键 | 功能 | 平台 | | -------- | -------------------- | --------------- | | `Ctrl+P` | 切换到下一个 Profile | macOS | | `Alt+P` | 切换到下一个 Profile | Windows / Linux | ## 导航和选择 ### 通用导航（所有选择器） | 快捷键 | 功能 | 适用范围 | | ------- | -------- | ----------------------------------------- | | `↑` | 上一项 | 所有选择器（循环导航：第一项 → 最后一项） | | `↓` | 下一项 | 所有选择器（循环导航：最后一项 → 第一项） | | `Enter` | 确认选择 | 所有选择器 | | `ESC` | 关闭 | 所有选择器和面板 | ### 文件选择器特定快捷键 | 快捷键 | 功能 | 说明 | | -------- | -------------- | -------------------------------- | | `@` | 触发文件选择器 | 输入 `@` 符号后自动显示文件列表 | | `Tab` | 选择文件 | 在文件选择器中选择当前高亮的文件 | | 输入文本 | 过滤文件 | 支持文件名和内容搜索 | ### 命令面板快捷键 | 快捷键 | 功能 | 说明 | | -------- | ------------ | ------------------------------- | | `/` | 触发命令面板 | 输入 `/` 符号后显示可用命令列表 | | `Tab` | 自动完成 | 用选中的命令名替换输入框内容 | | 输入文本 | 过滤命令 | 根据命令名和描述进行模糊搜索 | ### Agent 选择器 | 快捷键 | 功能 | 说明 | | ---------------------- | ----------------- | ----------------------------- | | `/agent-` 后按 `Enter` | 打开 Agent 选择器 | 从命令面板选择 `agent-` 命令 | | 输入文本 | 自动过滤 | 输入会自动更新 Agent 过滤状态 | ### TODO 选择器 | 快捷键 | 功能 | 说明 | | --------------------- | ---------------- | ------------------------------ | | `/todo-` 后按 `Enter` | 打开 TODO 选择器 | 从命令面板选择 `todo-` 命令 | | `Space` | 切换选择 | 选择/取消选择当前 TODO 项 | | `Backspace` | 删除搜索字符 | 删除搜索查询的最后一个字符 | | 输入文本 | 搜索过滤 | 支持中文等多字节字符的模糊搜索 | ### Profile 选择器 | 快捷键 | 功能 | 说明 | | ----------- | ------------ | ------------------------------------- | | `Backspace` | 删除搜索字符 | 删除搜索查询的最后一个字符 | | 输入文本 | 模糊搜索 | 支持中文等多字节字符过滤 Profile 列表 | ## 剪贴板操作 | 快捷键 | 功能 | 平台 | | -------- | ---- | --------------------------------- | | `Ctrl+V` | 粘贴 | macOS（支持文本和图片） | | `Alt+V` | 粘贴 | Windows / Linux（支持文本和图片） | 注意：粘贴功能支持： - 纯文本 - 图片（自动检测并插入图片占位符） ## 命令执行控制 ### 后台运行 | 快捷键 | 功能 | 说明 | | ---------- | -------------------- | ---------------------------- | | `Ctrl+B` | 将命令移入后台 | 仅在命令执行过程中可用 | | `/backend` | 打开后台进程管理面板 | 查看和管理所有后台运行的命令 | 后台运行功能说明： - 当长时间运行的命令占用前台时，可以使用 `Ctrl+B` 将其移入后台 - 命令会继续在后台执行，不影响你继续操作 - 使用 `/backend` 指令查看所有后台进程 - 在后台进程面板中： - `↑/↓` - 选择进程 - `Enter` - 终止选中的运行中进程 - `ESC` - 关闭面板 ## 历史记录和回滚 ### 双击 ESC 回滚菜单 | 快捷键 | 功能 | 说明 | | ----------- | ------------ | ---------------------------------------------- | | `ESC` `ESC` | 打开回滚菜单 | 在 500ms 内按两次 ESC 键 | | `↑` / `↓` | 选择回滚点 | 在历史消息中导航,选择要回滚到的位置 | | `Enter` | 确认回滚 | 回滚到选中的消息点(如有文件变更会弹出二次确认) | | `ESC` | 关闭回滚菜单 | 退出回滚模式 | 回滚功能说明: - 如果选中的回滚点有文件变更,系统会显示文件回滚确认对话框 - 支持选择性回滚部分文件或全部回滚 - 支持跨会话回滚(从压缩后的会话回滚到原始会话) - 回滚后会将选中的历史消息内容恢复到输入框 ### 文件回滚确认对话框 当回滚点包含文件变更时,会显示确认对话框支持精细控制: | 快捷键 | 功能 | 说明 | | --------- | ------------ | -------------------------------------------------------- | | `Tab` | 切换视图模式 | 在简洁模式和完整文件列表模式之间切换 | | `↑` / `↓` | 导航 | 简洁模式: 选择回滚选项; 完整模式: 导航文件列表 | | `Space` | 切换文件选择 | 仅在完整模式下: 选择/取消选择当前高亮的文件 | | `Enter` | 确认操作 | 简洁模式: 确认选中选项; 完整模式: 确认文件选择并执行回滚 | | `ESC` | 返回/取消 | 完整模式: 返回简洁模式; 简洁模式: 取消整个回滚操作 | 文件选择模式: - 默认所有文件都被选中 - 使用 `Space` 可以取消选择不想回滚的文件 - 如果取消选择所有文件,相当于"仅回滚对话" - 部分选择时,只会回滚选中的文件 - 完整模式下显示文件的选择状态: `[x]` 已选择, `[ ]` 未选择 ### 终端风格历史导航 | 快捷键 | 功能 | 说明 | | ------ | ---------- | ---------------------------- | | `↑` | 上一条历史 | 输入框为空或未打开任何面板时 | | `↓` | 下一条历史 | 浏览历史记录 | ## 面板和选择器 ### 关闭顺序（按 ESC 键） 当按下 `ESC` 键时，系统按以下优先级关闭面板： 1. Profile 选择器 2. TODO 选择器 3. Agent 选择器 4. 文件选择器 5. 命令面板 6. 历史菜单 ### 特殊命令 | 命令 | 功能 | 说明 | | --------- | ----------------- | -------------------------- | | `/todo-` | 打开 TODO 选择器 | 选择和管理项目中的 TODO 项 | | `/agent-` | 打开 Agent 选择器 | 选择子代理执行任务 | ## 中文输入支持 系统完整支持中文输入法： - 所有搜索和过滤功能都支持多字节字符（中文、日文、韩文等） - 词边界检测支持中文标点符号（`\p{P}` Unicode 属性） - 输入法组合状态得到正确处理，避免每个字母都触发搜索 ## 焦点事件过滤 系统自动过滤终端焦点事件，防止产生干扰字符： - 组件挂载后 500ms 内过滤所有可能的焦点事件 - 自动识别并过滤 `ESC[I` (焦点进入) 和 `ESC[O` (焦点退出) 序列 - 支持拖放操作时产生的焦点事件 ## 提示 - 大多数导航都支持循环模式（到达列表末尾后返回开头） - 快捷键设计遵循 Readline 标准，熟悉 bash/zsh 的用户会感到熟悉 - macOS 和 Windows/Linux 在某些快捷键上有差异（主要是 Ctrl vs Alt/Meta） - 所有文本输入都支持粘贴检测，可以安全处理大量文本粘贴 ================================================ FILE: docs/usage/zh/14.MCP配置.md ================================================ # Snow CLI 使用文档——MCP 配置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## MCP 配置 MCP（Model Context Protocol）是一个开放协议，允许 AI 助手与外部工具和服务集成。Snow CLI 支持配置和管理 MCP 服务。 ### 什么是 MCP MCP（Model Context Protocol）是一种标准化协议，用于连接 AI 助手与各种外部工具、数据源和服务。通过 MCP，Snow CLI 可以访问本地文件系统、连接数据库、调用外部 API 等。 ### 查看 MCP 服务状态 在对话界面输入 `/mcp` 指令可以查看所有 MCP 服务的状态： **显示内容**： - 服务名称 - 连接状态（绿色 ● 表示已连接，红色 ● 表示连接失败，灰色 ● 表示已禁用） - 服务类型（System/External/Disabled） - 可用工具列表 **操作方式**： - **上下箭头**：在服务列表中导航 - **回车键**：重新连接选中的服务 - **Tab 键**：切换外部服务的启用/禁用状态（内置服务不支持） - 选择 "Refresh all services" 选项可刷新所有服务 ### 配置 MCP 服务 #### 1. 进入配置界面 在主菜单中选择 `MCP Configuration` 进入 MCP 配置编辑器。 #### 2. 自动打开编辑器 系统会自动检测并使用合适的文本编辑器打开配置文件： **编辑器优先级**： 1. 环境变量 `VISUAL` 指定的编辑器 2. 环境变量 `EDITOR` 指定的编辑器 3. 系统默认编辑器 **Windows 系统**：检测顺序为 notepad++ > notepad > code > vim > nano **macOS/Linux 系统**：检测顺序为 nano > vim > vi **设置默认编辑器**： macOS/Linux: ```bash export EDITOR=nano ``` Windows: ```cmd set EDITOR=notepad ``` #### 3. 配置文件格式 配置文件位置：`~/.snow/mcp-config.json` **配置文件结构**： ```json { "mcpServers": { "服务名称": { "command": "命令", "args": ["参数1", "参数2"], "enabled": true } } } ``` **配置项说明**： - `mcpServers`：MCP 服务配置对象 - `服务名称`：自定义的服务名称（唯一标识） - `type`：传输类型，可选值为 `'stdio'`、`'local'` 或 `'http'`（可选，默认为根据 `url` 或 `command` 自动推断） - `'stdio'`：本地子进程通信（STDIO 模式） - `'local'`：`'stdio'` 的别名，功能完全相同 - `'http'`：HTTP 模式，用于连接远程 MCP 服务 - `command`：启动 MCP 服务的命令（`stdio`/`local` 类型必需） - `args`：命令参数数组（可选） - `url`：MCP 服务端点 URL（`http` 类型必需） - `headers`：HTTP 请求头配置（`http` 类型可选） - `enabled`：是否启用该服务（可选，默认为 true） - `timeout`：工具调用超时时间，单位毫秒（可选，默认为 300000，即 5 分钟） - `env` / `environment`：环境变量配置（可选），`environment` 是 `env` 的别名 **配置示例**： **STDIO/Local 模式示例**： ```json { "mcpServers": { "filesystem": { "type": "stdio", "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/path/to/files" ], "timeout": 600000 }, "github": { "type": "local", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "enabled": true, "environment": { "GITHUB_TOKEN": "your_token_here" } } } } ``` **HTTP 模式示例**： ```json { "mcpServers": { "remote-service": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_KEY}", "X-Custom-Header": "custom-value" }, "env": { "API_KEY": "your_api_key_here" }, "timeout": 300000 } } } ``` > **注意**：HTTP 模式支持从环境变量读取配置值，使用 `${VAR_NAME}` 语法。 ### 配置验证 保存配置文件后，系统会自动进行验证： **成功提示**： ```text MCP configuration saved successfully ! Please use `snow` restart! ``` **错误提示**： ```text Invalid JSON format ``` ### 使用 MCP 服务 配置后需要重启 Snow CLI 使配置生效： ```bash snow ``` 启动后可以使用 `/mcp` 指令查看服务连接状态。 ### 管理 MCP 服务 #### 启用/禁用服务 **方法 1：编辑配置文件** 设置 `enabled` 字段为 `false` 禁用服务 **方法 2：使用 /mcp 指令** 1. 输入 `/mcp` 打开服务面板 2. 使用上下箭头选择服务 3. 按 Tab 键切换启用/禁用状态 **注意**：内置服务无法禁用 #### 重新连接服务 在 `/mcp` 面板中选择服务并按回车键可重新连接 ### 故障排除 #### 1. 编辑器无法打开 **错误信息**： ```text No text editor found! Please set the EDITOR or VISUAL environment variable. ``` **解决方案**： 设置环境变量或安装文本编辑器： macOS/Linux: ```bash export EDITOR=nano ``` Windows: ```cmd set EDITOR=notepad ``` #### 2. 服务连接失败 **检查项**： 1. 命令路径是否正确 2. 是否已安装依赖包（如使用 npx 需要 Node.js） 3. 参数格式是否正确 4. 使用 `/mcp` 查看具体错误信息 #### 3. 配置不生效 **解决方案**： 1. 确认已保存配置文件 2. 重启 Snow CLI 3. 使用 `/mcp` 查看服务状态 ### 相关资源 - MCP 官方文档： - MCP 服务仓库： - 指令说明：[指令面板说明](./09.指令面板说明.md) ================================================ FILE: docs/usage/zh/15.异步任务管理.md ================================================ # Snow CLI 使用文档——异步任务管理 异步任务功能允许你在后台运行耗时的 AI 任务，同时继续使用终端进行其他工作。任务会在独立进程中运行，不会阻塞你的操作。 ## 什么是异步任务 异步任务适用于以下场景： - 需要长时间运行的代码分析和重构 - 批量文件处理和转换 - 生成详细的项目文档 - 执行复杂的多步骤操作 你可以创建任务后让它在后台执行，稍后查看结果，或在需要时审批敏感操作。 ## 创建后台任务 在终端中使用 `--task` 参数创建后台任务： ```bash snow --task "分析项目代码并生成架构文档" ``` 执行后会显示任务信息并立即返回： ```text Task created: abc-123-def-456 Title: 分析项目代码并生成架构文档 Use "snow --task-list" to view task status ``` 任务会在后台独立进程中运行，你可以继续使用终端做其他事情。 ## 打开任务管理器 有两种方式打开任务管理器查看和管理后台任务： ### 1、命令行启动 ```bash snow --task-list ``` ### 2、欢迎页菜单 启动 Snow CLI 后，在主菜单中选择"任务管理器"选项。 ## 查看任务列表 进入任务管理器后，你会看到所有任务的列表，每个任务显示： - 状态图标和颜色 - 任务标题（提示词的前 50 个字符） - 最后更新时间 - 消息数量 ### 任务状态 - `○` 黄色 - 待执行：任务已创建但还未开始 - `◐` 青色 - 运行中：任务正在后台执行 - `⏸` 洋红色 - 已暂停：检测到敏感命令，等待你审批 - `●` 绿色 - 已完成：任务执行成功 - `✗` 红色 - 失败：任务执行出错 ## 操作快捷键 ### 在任务列表中 - `↑` `↓` - 上下移动选择 - `Space` - 标记/取消标记任务（用于批量删除） - `Enter` - 查看任务详情 - `D` - 删除任务 - 单个删除：选中后按 `D`，再按 `D` 确认 - 批量删除：先用 `Space` 标记多个任务，按 `D`，再按 `D` 确认 - `R` - 刷新任务列表 - `Esc` - 退出任务管理器 ### 在任务详情页 - `C` - 将任务转为会话继续对话 - 按一次 `C` 显示提示 - 再按一次 `C` 确认转换 - `A` - 同意执行敏感命令（仅暂停状态可用） - `R` - 拒绝敏感命令（仅暂停状态可用） - `Esc` - 返回任务列表 ## 审批敏感命令 当后台任务需要执行危险操作时（如删除文件、重置代码等），会自动暂停并等待你的审批。 ### 审批步骤 1. 在任务列表中看到暂停图标 `⏸` 和洋红色状态 2. 按 `Enter` 进入任务详情 3. 查看黄色警告框中显示的具体命令 4. 根据情况选择： - 按 `A` - 同意执行，任务继续运行 - 按 `R` - 拒绝执行 ### 拒绝命令并说明原因 1. 在暂停任务详情页按 `R` 2. 进入输入模式，光标显示为 █ 3. 输入拒绝原因，例如："权限不足，请手动执行" 4. 按 `Enter` 提交 5. 按 `Esc` 取消输入 拒绝后，AI 会收到你的原因并据此调整后续操作。 ### 配置敏感命令 你可以自定义哪些命令需要审批，详见[敏感命令配置](./06.敏感命令配置.md)。 ## 将任务转为会话 完成的任务可以转换为普通会话，这样你就能继续与 AI 对话，询问更多细节或请求修改。 ### 转换方法 1. 在任务列表中选择任务 2. 按 `Enter` 查看详情 3. 按 `C` 键（显示确认提示） 4. 再按 `C` 确认 5. 自动跳转到聊天界面 ### 注意事项 - 转换后原任务会被删除 - 所有消息历史会保留到新会话 - 未完成的任务也可以转换，但会有警告提示 - 转换操作不可撤销 ## 查看任务日志 每个任务都有独立的日志文件，记录详细的执行过程。 ### 日志位置 创建任务时会显示日志路径： ```text Task abc-123-def-456 started in background (PID: 12345) Logs: /Users/username/.snow/task-logs/abc-123-def-456.log ``` ### 查看日志 使用任何文本编辑器或命令行工具： ```bash # 实时查看日志 tail -f ~/.snow/task-logs/abc-123-def-456.log # 查看完整日志 cat ~/.snow/task-logs/abc-123-def-456.log ``` 日志包含： - 任务启动和结束时间 - 所有输出信息 - 错误信息和堆栈 - 执行过程跟踪 ## 使用场景示例 ### 场景 1：长时间代码分析 ```bash # 创建后台任务 snow --task "全面分析项目代码，生成架构文档和优化建议" # 继续其他工作 cd other-project git pull # 稍后查看结果 snow --task-list ``` ### 场景 2：批量文件重构 ```bash # 后台执行重构 snow --task "重构 src/components 下所有组件，统一使用 TS 严格模式" # 任务检测到删除文件操作会暂停 # 打开任务管理器审批即可 ``` ### 场景 3：生成报告并继续讨论 ```bash # 创建分析任务 snow --task "分析最近一周的 Git 提交，生成代码质量报告" # 任务完成后 snow --task-list # 选择任务 → Enter → C → C 转为会话 # 然后可以继续问："重点优化哪些部分？" ``` ## 常见问题 ### Q：任务状态一直是"运行中"？ A：可能是任务正在执行耗时操作，可以： - 查看日志了解当前进度 - 等待更长时间 - 如果确认卡住，可以删除任务重新创建 ### Q：任务失败了怎么办？ A： 1. 查看日志找出错误原因 2. 检查提示词是否合理 3. 确认系统资源是否充足 4. 修改后重新创建任务 ### Q：如何删除多个任务？ A： 1. 用 `Space` 键标记要删除的任务（会显示标记数量） 2. 按 `D` 键 3. 再按 `D` 确认批量删除 ### Q：敏感命令没有暂停？ A：检查是否在[敏感命令配置](./06.敏感命令配置.md)中添加了该命令模式。 ### Q：可以同时运行多少个任务？ A：理论上没有限制，但每个任务会占用系统资源，建议根据机器性能控制在合理数量。 ## 实用技巧 1. **明确任务目标** - 创建任务时提供清晰具体的提示词，让 AI 知道要做什么 2. **定期清理** - 删除不需要的已完成任务，保持列表整洁 3. **善用标记** - 批量标记不需要的任务一次性删除 4. **检查日志** - 长时间运行的任务可以通过日志了解进度 5. **转为会话** - 重要任务完成后转为会话，方便后续查询和修改 ## 相关文档 - [敏感命令配置](./06.敏感命令配置.md) - 配置需要审批的危险命令 - [无头模式](./12.无头模式.md) - 另一种非交互式执行方式 - [指令面板说明](./09.指令面板说明.md) - 了解更多管理指令 ================================================ FILE: docs/usage/zh/16.第三方中转配置.md ================================================ # Snow CLI 使用文档——第三方中转配置 本文档介绍如何配置 Snow CLI 访问国内的 Claude Code 和 Codex 中转服务。 ## 配置说明 中转服务提供商会对第三方客户端设置拦截措施，因此你需要在 Snow 中配置自定义系统提示词和请求头来伪装访问。 ## Claude Code 中转配置 ### 1、配置自定义系统提示词 打开系统提示词配置界面，输入以下内容（**注意：不能多字也不能少字**）： ```text You are Claude Code, Anthropic's official CLI for Claude. ``` **配置位置：** 1. 启动 Snow CLI 2. 在欢迎页选择"系统提示词配置" ### 2、配置自定义请求头 打开自定义请求头配置界面，添加以下 JSON 配置： ```json { "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14", "Anthropic-Version": "2023-06-01", "Anthropic-Dangerous-Direct-Browser-Access": "true", "X-App": "cli", "X-Stainless-Helper-Method": "stream", "X-Stainless-Retry-Count": "0", "X-Stainless-Runtime-Version": "v24.3.0", "X-Stainless-Package-Version": "0.55.1", "X-Stainless-Runtime": "node", "X-Stainless-Lang": "js", "X-Stainless-Arch": "arm64", "X-Stainless-Os": "MacOS", "X-Stainless-Timeout": "60", "User-Agent": "claude-cli/1.0.83 (external, cli)", "Connection": "keep-alive", "Accept-Encoding": "gzip, deflate, br, zstd", "Accept": "text/event-stream" } ``` **启用1M上下文的请求头：** ```json { "Anthropic-Beta": "claude-code-20250219,context-1m-2025-08-07,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14", "Anthropic-Version": "2023-06-01", "Anthropic-Dangerous-Direct-Browser-Access": "true", "X-App": "cli", "X-Stainless-Helper-Method": "stream", "X-Stainless-Retry-Count": "0", "X-Stainless-Runtime-Version": "v24.3.0", "X-Stainless-Package-Version": "0.55.1", "X-Stainless-Runtime": "node", "X-Stainless-Lang": "js", "X-Stainless-Arch": "arm64", "X-Stainless-Os": "MacOS", "X-Stainless-Timeout": "60", "User-Agent": "claude-cli/1.0.83 (external, cli)", "Connection": "keep-alive", "Accept-Encoding": "gzip, deflate, br, zstd", "Accept": "text/event-stream" } ``` **配置位置：** 1. 启动 Snow CLI 2. 在欢迎页选择"自定义请求头配置" 3. 或直接编辑 `~/.snow/custom-headers.json` 文件 ### 3、验证配置 配置完成后重启 Snow CLI，如果能正常对话则说明配置成功。 ## Codex 中转配置 ### 1、配置自定义系统提示词 Codex 中转一般不需要配置请求头，只需替换系统提示词（**注意：不能多字也不能少字**）： ```markdown You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer. ## General - The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with ["bash", "-lc"]. - Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary. - When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.) ## Editing constraints - Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them. - Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare. - Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase). - You may be in a dirty git worktree. - NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user. - If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes. - If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them. - If the changes are in unrelated files, just ignore them and don't revert them. - While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed. - **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user. ## Plan tool When using the planning tool: - Skip using the planning tool for straightforward tasks (roughly the easiest 25%). - Do not make single-step plans. - When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan. ## Codex CLI harness, sandboxing, and approvals The Codex CLI harness supports several different configurations for sandboxing and escalation approvals that the user can choose from. Filesystem sandboxing defines which files can be read or written. The options for `sandbox_mode` are: - **read-only**: The sandbox only permits reading files. - **workspace-write**: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval. - **danger-full-access**: No filesystem sandboxing - all commands are permitted. Network sandboxing defines whether network can be accessed without approval. Options for `network_access` are: - **restricted**: Requires approval - **enabled**: No approval needed Approvals are your mechanism to get user consent to run shell commands without the sandbox. Possible configuration options for `approval_policy` are - **untrusted**: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands. - **on-failure**: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox. - **on-request**: Commands will be run in the sandbox by default, and you can specify in your tool call if you want to escalate a command to run without sandboxing. (Note that this mode is not always available. If it is, you'll see parameters for it in the `shell` command description.) - **never**: This is a non-interactive mode where you may NEVER ask the user for approval to run commands. Instead, you must always persist and work around constraints to solve the task for the user. You MUST do your utmost best to finish the task and validate your work before yielding. If this mode is paired with `danger-full-access`, take advantage of it to deliver the best outcome for the user. Further, in this mode, your default testing philosophy is overridden: Even if you don't see local patterns for testing, you may add tests and scripts to validate your work. Just remove them before yielding. When you are running with `approval_policy == on-request`, and sandboxing enabled, here are scenarios where you'll need to request approval: - You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var) - You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files. - You are running sandboxed and need to run a command that requires network access (e.g. installing packages) - If you run a command that is important to solving the user's query, but it fails because of sandboxing, rerun the command with approval. ALWAYS proceed to use the `with_escalated_permissions` and `justification` parameters - do not message the user before requesting approval for the command. - You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for - (for all of these, you should weigh alternative paths that do not require approval) When `sandbox_mode` is set to read-only, you'll need to request approval for any command that isn't a read. You will be told what filesystem sandboxing, network sandboxing, and approval mode are active in a developer or user message. If you are not told about this, assume that you are running with workspace-write, network sandboxing enabled, and approval on-failure. Although they introduce friction to the user because your work is paused until the user responds, you should leverage them when necessary to accomplish important work. If the completing the task requires escalated permissions, Do not let these settings or the sandbox deter you from attempting to accomplish the user's task unless it is set to "never", in which case never ask for approvals. When requesting approval to execute a command that will require escalated privileges: - Provide the `with_escalated_permissions` parameter with the boolean value true - Include a short, 1 sentence explanation for why you need to enable `with_escalated_permissions` in the justification parameter ## Special user requests - If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so. - If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps. ## Presenting your work and final message You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value. - Default: be very concise; friendly coding teammate tone. - Ask only when needed; suggest ideas; mirror the user's style. - For substantial work, summarize clearly; follow final-answer formatting. - Skip heavy formatting for simple confirmations. - Don't dump large files you've written; reference paths only. - No "save/copy this file" - User is on the same machine. - Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something. - For code changes: - Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in. - If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps. - When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number. - The user does not command execution outputs. When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines so the user understands the result. ### Final answer structure and style guidelines - Plain text; CLI handles styling. Use structure only when it helps scanability. - Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help. - Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent. - Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with \*\*. - Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible. - Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task. - Tone: collaborative, concise, factual; present tense, active voice; self-contained; no "above/below"; parallel wording. - Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers. - Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets. - File References: When referencing files in your response, make sure to include the relevant start line and always follow the below rules: - Use inline code to make file paths clickable. - Each reference should have a stand alone path. Even if it's the same file. - Accepted: absolute, workspace-relative, a/ or b/ diff prefixes, or bare filename/suffix. - Line/column (1-based, optional): :line[:column] or #Lline[Ccolumn] (column defaults to 1). - Do not use URIs like file://, vscode://, or https://. - Do not provide range of lines - Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5 ``` **配置位置：** 与 Claude Code 相同，在系统提示词配置界面中粘贴以上完整内容。 ### 2、验证配置 配置完成后重启 Snow CLI，如果能正常对话则说明配置成功。 ## 注意事项 1. **精确匹配**：系统提示词必须完全一致，不能有任何多余或缺少的字符 2. **格式正确**：自定义请求头必须是合法的 JSON 格式 3. **重启生效**：配置修改后需要重启 Snow CLI 才能生效 4. **配置文件位置**： - 系统提示词：`~/.snow/system-prompt.json` - 自定义请求头：`~/.snow/custom-headers.json` ## 常见问题 ### Q：配置后仍然无法访问？ A：请检查： 1. 系统提示词是否完全一致（包括标点符号） 2. 自定义请求头 JSON 格式是否正确 3. 是否已重启 Snow CLI 4. 中转服务的 API 密钥是否正确配置 ### Q：如何验证配置是否生效？ A：在 API 配置中输入中转服务的 API 端点和密钥，然后尝试发起对话。如果能正常响应则配置成功。 ### Q：是否可以同时配置多个中转服务？ A：可以通过配置文件（Profile）功能切换不同的配置。详见[首次配置](./02.首次配置.md)。 ### Q：配置文件在哪里？ A：所有配置文件都在用户目录下的 `.snow` 文件夹中： - 系统提示词：`~/.snow/system-prompt.json` - 自定义请求头：`~/.snow/custom-headers.json` 可以直接编辑这些文件，修改后重启 Snow CLI 即可生效。 ## 开箱即用（直接Copy） - `~/.snow/system-prompt.json` ```json { "active": "1762780994030", "prompts": [ { "id": "default", "name": "Default", "content": "You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.\r\n\r\n## General\r\n\r\n- The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with [\"bash\", \"-lc\"].\r\n- Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary.\r\n- When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)\r\n\r\n## Editing constraints\r\n\r\n- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.\r\n- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like \"Assigns the value to the variable\", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.\r\n- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).\r\n- You may be in a dirty git worktree.\r\n * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.\r\n * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.\r\n * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.\r\n * If the changes are in unrelated files, just ignore them and don't revert them.\r\n- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.\r\n- **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user.\r\n\r\n## Plan tool\r\n\r\nWhen using the planning tool:\r\n- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).\r\n- Do not make single-step plans.\r\n- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.\r\n\r\n## Codex CLI harness, sandboxing, and approvals\r\n\r\nThe Codex CLI harness supports several different configurations for sandboxing and escalation approvals that the user can choose from.\r\n\r\nFilesystem sandboxing defines which files can be read or written. The options for `sandbox_mode` are:\r\n- **read-only**: The sandbox only permits reading files.\r\n- **workspace-write**: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval.\r\n- **danger-full-access**: No filesystem sandboxing - all commands are permitted.\r\n\r\nNetwork sandboxing defines whether network can be accessed without approval. Options for `network_access` are:\r\n- **restricted**: Requires approval\r\n- **enabled**: No approval needed\r\n\r\nApprovals are your mechanism to get user consent to run shell commands without the sandbox. Possible configuration options for `approval_policy` are\r\n- **untrusted**: The harness will escalate most commands for user approval, apart from a limited allowlist of safe \"read\" commands.\r\n- **on-failure**: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.\r\n- **on-request**: Commands will be run in the sandbox by default, and you can specify in your tool call if you want to escalate a command to run without sandboxing. (Note that this mode is not always available. If it is, you'll see parameters for it in the `shell` command description.)\r\n- **never**: This is a non-interactive mode where you may NEVER ask the user for approval to run commands. Instead, you must always persist and work around constraints to solve the task for the user. You MUST do your utmost best to finish the task and validate your work before yielding. If this mode is paired with `danger-full-access`, take advantage of it to deliver the best outcome for the user. Further, in this mode, your default testing philosophy is overridden: Even if you don't see local patterns for testing, you may add tests and scripts to validate your work. Just remove them before yielding.\r\n\r\nWhen you are running with `approval_policy == on-request`, and sandboxing enabled, here are scenarios where you'll need to request approval:\r\n- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var)\r\n- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.\r\n- You are running sandboxed and need to run a command that requires network access (e.g. installing packages)\r\n- If you run a command that is important to solving the user's query, but it fails because of sandboxing, rerun the command with approval. ALWAYS proceed to use the `with_escalated_permissions` and `justification` parameters - do not message the user before requesting approval for the command.\r\n- You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for\r\n- (for all of these, you should weigh alternative paths that do not require approval)\r\n\r\nWhen `sandbox_mode` is set to read-only, you'll need to request approval for any command that isn't a read.\r\n\r\nYou will be told what filesystem sandboxing, network sandboxing, and approval mode are active in a developer or user message. If you are not told about this, assume that you are running with workspace-write, network sandboxing enabled, and approval on-failure.\r\n\r\nAlthough they introduce friction to the user because your work is paused until the user responds, you should leverage them when necessary to accomplish important work. If the completing the task requires escalated permissions, Do not let these settings or the sandbox deter you from attempting to accomplish the user's task unless it is set to \"never\", in which case never ask for approvals.\r\n\r\nWhen requesting approval to execute a command that will require escalated privileges:\r\n - Provide the `with_escalated_permissions` parameter with the boolean value true\r\n - Include a short, 1 sentence explanation for why you need to enable `with_escalated_permissions` in the justification parameter\r\n\r\n## Special user requests\r\n\r\n- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so.\r\n- If the user asks for a \"review\", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.\r\n\r\n## Presenting your work and final message\r\n\r\nYou are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.\r\n\r\n- Default: be very concise; friendly coding teammate tone.\r\n- Ask only when needed; suggest ideas; mirror the user's style.\r\n- For substantial work, summarize clearly; follow final-answer formatting.\r\n- Skip heavy formatting for simple confirmations.\r\n- Don't dump large files you've written; reference paths only.\r\n- No \"save/copy this file\" - User is on the same machine.\r\n- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.\r\n- For code changes:\r\n * Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with \"summary\", just jump right in.\r\n * If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.\r\n * When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.\r\n- The user does not command execution outputs. When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines so the user understands the result.\r\n\r\n### Final answer structure and style guidelines\r\n\r\n- Plain text; CLI handles styling. Use structure only when it helps scanability.\r\n- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.\r\n- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.\r\n- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.\r\n- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.\r\n- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.\r\n- Tone: collaborative, concise, factual; present tense, active voice; self-contained; no \"above/below\"; parallel wording.\r\n- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.\r\n- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.\r\n- File References: When referencing files in your response, make sure to include the relevant start line and always follow the below rules:\r\n * Use inline code to make file paths clickable.\r\n * Each reference should have a stand alone path. Even if it's the same file.\r\n * Accepted: absolute, workspace-relative, a/ or b/ diff prefixes, or bare filename/suffix.\r\n * Line/column (1-based, optional): :line[:column] or #Lline[Ccolumn] (column defaults to 1).\r\n * Do not use URIs like file://, vscode://, or https://.\r\n * Do not provide range of lines\r\n * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\\repo\\project\\main.rs:12:5", "createdAt": "2025-11-10T11:58:56.455Z" }, { "id": "1762780994030", "name": "ClaudeCode", "content": "You are Claude Code, Anthropic's official CLI for Claude.", "createdAt": "2025-11-10T13:23:14.030Z" } ] } ``` - `~/.snow/custom-headers.json` ```json { "active": "1763885270535", "schemes": [ { "id": "1763885270535", "name": "Claude", "headers": { "Anthropic-Beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14", "Anthropic-Version": "2023-06-01", "Anthropic-Dangerous-Direct-Browser-Access": "true", "X-App": "cli", "X-Stainless-Helper-Method": "stream", "X-Stainless-Retry-Count": "0", "X-Stainless-Runtime-Version": "v24.3.0", "X-Stainless-Package-Version": "0.55.1", "X-Stainless-Runtime": "node", "X-Stainless-Lang": "js", "X-Stainless-Arch": "arm64", "X-Stainless-Os": "MacOS", "X-Stainless-Timeout": "60", "User-Agent": "claude-cli/1.0.83 (external, cli)", "Connection": "keep-alive", "Accept-Encoding": "gzip, deflate, br, zstd", "Accept": "text/event-stream" }, "createdAt": "2025-11-23T08:07:50.535Z" } ] } ``` ## 相关文档 - [首次配置](./02.首次配置.md) - API 配置和模型选择 - [代理和浏览器设置](./03.代理和浏览器设置.md) - 网络代理配置 ================================================ FILE: docs/usage/zh/17.LSP配置.md ================================================ # Snow CLI 使用文档——LSP 配置与用法 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是 LSP LSP（Language Server Protocol）是一套通用协议，用来让“语言服务器”向编辑器/工具提供能力，例如： - 跳转到定义（Go to Definition） - 符号提取（Outline / Document Symbols） - 悬浮信息（Hover） - 查找引用（References） - 补全（Completion） ## Snow CLI 中的 LSP 用途 Snow CLI 会在部分代码搜索能力中优先尝试使用 LSP；当 LSP 不可用或超时失败时，会自动回退到正则/文本搜索（不会阻塞使用）。 目前 Snow CLI 的 LSP 主要用于增强以下内置工具： - `ace-search`（action=`find_definition`）：优先用 LSP 做“跳转到定义”；失败则回退到正则搜索 - `ace-search`（action=`file_outline`）：优先用 LSP 抽取“文件符号大纲”；失败则回退到正则搜索 注意： - LSP 调用有内部超时（默认 3 秒）。项目较大或语言服务器冷启动时可能触发超时，从而回退到正则搜索。 - 某些语言服务器（例如 OmniSharp）强烈依赖准确的光标位置参数；建议在调用时提供 `contextFile + line + column`（见下文）。 ## 配置文件位置与加载机制 LSP 配置文件位置：`~/.snow/lsp-config.json` 加载机制： 1. 当 Snow CLI 首次需要使用 LSP 时，会尝试读取 `~/.snow/lsp-config.json`。 2. 若文件不存在，会自动创建一个默认配置文件，并使用内置默认服务列表。 3. 配置在进程内会缓存；修改配置后建议重启 Snow CLI 以确保重新加载。 ## 配置文件格式 支持两种格式： ### 格式 1（推荐）：带 schemaVersion ```json { "schemaVersion": 1, "servers": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"], "fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"], "installCommand": "npm install -g typescript-language-server typescript", "initializationOptions": {} } } } ``` ### 格式 2（兼容）：直接写 servers 映射 ```json { "typescript": { "command": "typescript-language-server", "args": ["--stdio"], "fileExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"] } } ``` ## 配置项说明 每个语言服务器配置项包含： - `command`（必填）：启动语言服务器的命令（要求可在 PATH 中被找到） - `args`（必填）：启动参数数组 - `fileExtensions`（必填）：该语言服务器处理的文件扩展名列表（用于按文件后缀匹配语言） - `installCommand`（可选）：安装提示命令（仅用于提示/记录，不会被 Snow CLI 自动执行） - `initializationOptions`（可选）：会透传到 LSP `initialize` 请求的 `initializationOptions` 重要说明： - 配置文件采用“整体校验、整体生效”的策略：只要任意一个 server 的必填字段缺失/类型不正确，整份配置会被视为无效并回退到默认配置。 - 语言选择基于文件后缀（`.ts`、`.py` 等）；请确保 `fileExtensions` 覆盖你项目里实际的文件类型。 ## 默认内置服务器（首次创建配置文件时会写入） 默认包含的语言键（可自行修改/增删）： - `typescript`：`typescript-language-server --stdio` - `python`：`pylsp` - `go`：`gopls` - `rust`：`rust-analyzer` - `java`：`jdtls` - `csharp`：`csharp-ls` 提示：不同平台安装方式不同；以你本机的安装方式为准，核心要求是 `command` 能在终端中被找到。 ## 安装与验证（Windows 示例） Snow CLI 在 Windows 下会使用 `where ` 判断语言服务器是否已安装并在 PATH 可用。 你可以先自行验证： ```cmd where typescript-language-server where pylsp where gopls where rust-analyzer where jdtls where csharp-ls ``` 常见安装方式示例： 1. TypeScript / JavaScript ```cmd npm install -g typescript-language-server typescript ``` 2. Python ```cmd python -m pip install python-lsp-server ``` 3. Go ```cmd go install golang.org/x/tools/gopls@latest ``` 如果你不想安装某个语言的 LSP，可在配置里删除对应语言键或移除其扩展名（这样会直接回退到正则搜索）。 ## 通过 ACE 工具使用 LSP（用法说明） ### 1) 跳转到定义：`ace-search`（action=`find_definition`） 当你提供 `contextFile` 时，Snow CLI 会优先尝试用 LSP 获取定义位置；否则会直接使用正则搜索。 推荐提供光标位置信息： - `line`：0 基索引（第一行是 0） - `column`：0 基索引（第一列是 0） 例如：如果你在 IDE 中看到“第 34 行，第 7 列”，通常需要传 `line=33`、`column=6`。 ### 2) 文件大纲：`ace-search`（action=`file_outline`） 对单文件提取符号列表时，Snow CLI 会优先用 LSP 取 `documentSymbol`，失败则回退到正则搜索。 建议： - 对大文件/大项目，优先使用 `ace-search`（action=`file_outline`）获取概要，再按需要继续深入。 ## 常见问题 ### 1. 配置改了但不生效 - 确认已保存 `~/.snow/lsp-config.json` - 重启 Snow CLI（配置会缓存） ### 2. LSP 总是回退到正则搜索 常见原因： - 语言服务器未安装或不在 PATH（Windows 可用 `where ` 验证） - `fileExtensions` 未覆盖实际文件后缀 - 语言服务器启动较慢触发超时（默认 3 秒） ### 3. 定位不准 / 跳转结果不对 - 确保调用 `ace-search`（action=`find_definition`）时提供 `contextFile + line + column` - 如果 `symbolName` 在当前文件出现多次，且未提供行列信息，系统会尝试用“首次出现位置”推断，可能不准确 ================================================ FILE: docs/usage/zh/18.Skills指令详细说明.md ================================================ # Snow CLI 使用文档——Skills 指令详细说明 Skills 是 Snow CLI 的强大扩展功能，允许您创建和使用专门的知识库和工具集。每个技能都包含特定领域的专业知识和实用工具，可以通过 `skill-execute` 工具在对话中调用。 ## Skills 概述 Snow CLI 的 Skills 功能与 **Claude Code Skills** 完全兼容，您可以： - 创建自定义技能来封装特定领域的知识和工具 - 复用常用的任务模式和最佳实践 - 在不同项目间共享技能 - 限制技能可访问的工具权限 - 为团队创建标准化的开发流程 ### 技能类型 技能主要分为以下几类： - **工具技能**: 提供特定工具的封装和使用方法（如 slack-gif-creator） - **知识技能**: 包含特定领域的专业知识和最佳实践 - **模板技能**: 提供可复用的代码、文档或配置模板 - **工作流技能**: 定义标准化的任务执行流程 ## 技能结构 每个技能都是一个目录，包含以下标准结构： ``` skill-name/ ├── SKILL.md # 主文档（必需） ├── core/ # 核心代码模块 │ ├── __init__.py │ ├── main.py # 主要逻辑 │ └── utils.py # 工具函数 ├── templates/ # 模板文件 │ ├── template1.md │ └── template2.txt ├── scripts/ # 辅助脚本 │ ├── setup.sh │ └── process.py ├── requirements.txt # 依赖列表 └── LICENSE.txt # 许可证文件 ``` ### SKILL.md 主文档 主文档是技能的核心，包含： - **YAML 前置元数据**: 定义技能名称、描述、允许的工具等 - **详细说明**: 技能的功能、使用方法、API 参考 - **代码示例**: 展示如何使用技能的代码片段 - **最佳实践**: 使用技巧和注意事项 ```markdown --- name: skill-name description: 技能的详细描述 allowed-tools: tool1, tool2, tool3 license: Complete terms in LICENSE.txt --- # 技能标题 ## 功能描述 详细说明技能的功能和用途... ## 使用方法 # 代码示例 ## API 参考 ### 函数名 描述函数的用途和参数... ## 最佳实践 使用技能时的注意事项和最佳实践... ``` ## 技能位置 技能可以存储在两个位置： - **全局位置**: `~/.snow/skills/` - 可在所有项目中使用 - 适合通用的、跨项目的技能 - **项目位置**: `.snow/skills/` - 仅在当前项目中使用 - 适合项目特定的技能 **优先级**: 项目级技能会覆盖同名的全局技能 ## 创建技能 使用 `/skills` 指令创建新的技能： 1. 输入 `/skills` 打开技能创建对话框 2. 输入技能名称（小写字母、数字、连字符，最多 64 字符） 3. 输入技能描述 4. 选择存储位置（全局或项目） 5. 确认创建 创建完成后，系统会自动生成： - SKILL.md（主文档） - 必要的目录结构 - 基础模板文件 ## 使用技能 ### 使用 `/skills-` 打开技能选择器（注入到输入框） `/skills-` 是一个“选择并注入技能内容”的快捷指令（类似 `/agent-`、`/todo-` 的选择面板），用于把某个技能的内容以“注入块”的形式插入到当前输入框中，方便你在本次对话里直接携带该技能的提示词。 它与 `/skills` 的区别： - `/skills`：创建一个新的技能模板（生成目录、`SKILL.md` 等）。 - `/skills-`：从已有技能列表里选择一个技能，把该技能内容注入到输入框（不创建文件）。 打开方式： - 在输入框输入 `/skills-`，然后回车；或在命令面板中选中 `skills-`（回车）。 面板交互（默认行为）： - 上/下方向键：切换技能条目（循环）。 - Tab：在“搜索框(search)”与“附加内容(append)”之间切换焦点。 - 回车：确认选择并注入。 - Esc：关闭面板并回到输入。 注入后的文本形态（内部完整内容）： - 会生成一段以 `# Skill: ` 开头、以 `# Skill End` 结尾的注入块。 - 输入框视觉上会折叠为占位符：`[Skill:] `（末尾带一个空格，方便你继续输入）。 - 发送消息时会按完整注入块发送（不是只发送占位符）。 附加内容（append）如何生效： - 如果技能的 `SKILL.md` 内容里包含占位符 `$ARGUMENTS`，则会用 append 内容替换 `$ARGUMENTS`。 - 如果不包含 `$ARGUMENTS`，则会在注入块末尾追加一个： - `[User Append]` 区块（仅当 append 非空时）。 注意事项： - 注入块结尾的 `# Skill End` 必须以换行结束，否则你在占位符后继续输入时可能与 end marker 黏连，导致显示层折叠范围异常。 - 技能内容来源于 `.snow/skills/`（项目级）与 `~/.snow/skills/`（全局）。同名技能时项目级优先。 ### 在对话中调用（直接调用技能工具） 使用 `skill-execute` 工具调用技能： ``` skill: "skill-name" ``` 调用后，您会看到： ``` The "skill-name" skill is loading ``` 随后技能的内容会展开，提供详细的指导和使用说明。 ### 使用示例 #### slack-gif-creator 技能示例 这是一个完整的技能示例，用于创建适合 Slack 的动画 GIF： ```python # 加载技能 skill: "slack-gif-creator" # 技能会提供详细的使用指导，包括： # - Slack 的 GIF 要求（尺寸、帧率、颜色等） # - GIFBuilder 工具类的使用方法 # - 动画效果实现（抖动、脉冲、弹跳等） # - 优化技巧 # 例如创建动画GIF from core.gif_builder import GIFBuilder from PIL import Image, ImageDraw # 创建构建器 builder = GIFBuilder(width=128, height=128, fps=10) # 生成帧 for i in range(12): frame = Image.new('RGB', (128, 128), (240, 248, 255)) draw = ImageDraw.Draw(frame) # 绘制动画 # ... 绘制代码 ... builder.add_frame(frame) # 保存优化的 GIF builder.save('output.gif', num_colors=48, optimize_for_emoji=True) ``` ## 技能管理 ### 列出可用技能 所有可用的技能会在 `skill-execute` 工具的描述中列出，包括： - 技能名称 - 技能描述 - 技能位置（全局/项目） ### 删除技能 删除自定义技能使用 `-d` 参数： - **删除全局技能**: `/skill-name -d`（在非项目目录执行） - **删除项目技能**: `/skill-name -d`（在项目目录执行） 系统会自动识别技能位置并删除对应文件。 ### 技能限制 可以通过 `allowed-tools` 字段限制技能可访问的工具： ```yaml --- name: restricted-skill description: 限制工具访问的技能 allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` 这确保技能只能使用指定的安全工具，提高系统安全性。 ## 技能开发最佳实践 ### 1. 文档编写 - 使用清晰的结构和标题 - 提供丰富的代码示例 - 包含常见问题和解决方案 - 说明依赖和环境要求 ### 2. 代码组织 - 将核心逻辑放在 `core/` 目录 - 使用模块化设计 - 提供清晰的 API - 添加适当的错误处理 ### 3. 模板和脚本 - 在 `templates/` 目录提供常用模板 - 在 `scripts/` 目录提供辅助脚本 - 确保脚本可执行权限 - 提供使用说明 ### 4. 工具限制 - 仅允许必要的工具 - 避免高风险操作 - 使用工具限制提高安全性 - 记录限制原因 ### 5. 版本控制 - 为技能添加版本信息 - 记录变更日志 - 使用语义化版本号 - 保持向后兼容 ## 常用技能示例 ### 1. 代码生成技能 ```markdown --- name: code-generator description: 代码生成模板和最佳实践 allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` 提供常用的代码生成模板和模式。 ### 2. 文档模板技能 ```markdown --- name: doc-templates description: 文档和注释模板集合 allowed-tools: filesystem-read, filesystem-edit --- ``` 提供 README、API 文档、注释等模板。 ### 3. 测试用例技能 ```markdown --- name: test-templates description: 测试用例模板和测试工具 allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` 提供单元测试、集成测试等模板。 ### 4. 部署脚本技能 ```markdown --- name: deploy-scripts description: 自动化部署脚本和流程 allowed-tools: filesystem-read, filesystem-edit, terminal-execute --- ``` 提供 CI/CD 部署脚本和最佳实践。 ## 与 Claude Code Skills 的兼容性 Snow CLI 的 Skills 功能与 Claude Code Skills 完全兼容： - **相同的调用方式**: 使用 `skill: "skill-name"` 调用 - **相同的结构要求**: SKILL.md 作为主文档 - **相同的元数据格式**: YAML 前置元数据 - **相同的工具限制**: 支持 allowed-tools 字段 - **完全兼容的生态**: 可以直接使用现有的 Claude Code Skills 这意味着您可以直接在 Snow CLI 中使用： - Anthropic 官方提供的 Claude Code Skills - 社区创建的兼容技能 - 您自己创建的 Snow CLI 技能 ## 技能安全 ### 工具权限控制 强烈建议为每个技能指定允许的工具列表： ```yaml --- name: safe-skill description: 安全的技能示例 allowed-tools: filesystem-read, filesystem-edit --- ``` ### 敏感操作 避免在技能中包含： - 直接的系统调用 - 敏感信息（密钥、密码等） - 破坏性操作（删除、格式化等） ### 代码审查 定期审查技能代码： - 检查安全漏洞 - 验证工具使用 - 更新依赖版本 - 移除废弃功能 ## 故障排除 ### 技能未找到 **症状**: 调用技能时提示 "Skill not found" **解决方案**: 1. 检查技能名称拼写 2. 确认技能已正确安装 3. 验证技能位置（全局/项目） 4. 检查 SKILL.md 文件是否存在 ### 工具权限错误 **症状**: 技能运行时提示工具权限不足 **解决方案**: 1. 检查 allowed-tools 配置 2. 验证工具名称拼写 3. 在权限管理中添加必要工具 4. 联系管理员授予权限 ### 依赖缺失 **症状**: 技能运行时提示模块未找到 **解决方案**: 1. 检查 requirements.txt 2. 安装缺失的依赖: `pip install -r requirements.txt` 3. 验证 Python 环境 4. 检查虚拟环境激活状态 ### 语法错误 **症状**: 技能文档或代码存在语法错误 **解决方案**: 1. 检查 YAML 前置元数据格式 2. 验证 Markdown 语法 3. 检查代码语法 4. 使用代码格式化工具 ## 相关配置 - [指令面板说明](./09.指令面板说明.md) - 基础指令介绍 - [MCP 配置](./14.MCP配置.md) - MCP 服务配置 - [敏感命令配置](./06.敏感命令配置.md) - 安全工具配置 - [子代理设置](./05.子代理设置.md) - 子代理工具配置 ## 高级用法 ### 技能组合 可以将多个技能组合使用： ```python # 先调用代码生成技能 skill: "code-generator" # 再调用测试模板技能 skill: "test-templates" # 最后调用部署脚本技能 skill: "deploy-scripts" ``` ### 动态技能 技能支持动态加载，修改后立即生效： 1. 编辑技能文件 2. 保存更改 3. 重新调用技能 无需重启应用程序。 ### 技能调试 使用以下方法调试技能： 1. 检查技能目录结构 2. 验证 SKILL.md 格式 3. 测试核心代码模块 4. 查看错误日志 ## 社区和共享 ### 技能分享 可以将您的技能分享给社区： 1. 确保代码质量和文档完整 2. 添加适当的许可证 3. 创建使用示例 4. 发布到技能仓库 ### 技能发现 寻找有用技能的方式： 1. 查看官方技能列表 2. 搜索社区技能库 3. 询问其他用户推荐 4. 根据项目需求定制 ## 总结 Snow CLI 的 Skills 功能是一个强大的扩展系统，让您可以： - **封装专业知识**: 将领域知识封装为可复用的技能 - **标准化流程**: 建立团队统一的开发流程 - **提高效率**: 减少重复工作，专注于创新 - **保证质量**: 使用经过验证的最佳实践 - **促进协作**: 在团队间共享经验和技能 通过合理使用 Skills，您可以显著提升开发效率和代码质量，同时建立更加规范和高效的开发流程。 ================================================ FILE: docs/usage/zh/19.启动参数说明.md ================================================ # Snow CLI 使用文档——启动参数说明 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 启动参数说明 ### 基本命令 #### 1. 默认启动 ```bash snow ``` 启动 Snow CLI 交互式界面，显示欢迎屏幕。 #### 2. 查看版本 ```bash snow --version # 或 snow -v ``` 显示当前安装的 Snow CLI 版本号。 #### 3. 查看帮助 ```bash snow --help # 或 snow -h ``` 显示所有可用的命令行参数和使用说明。 #### 4. 更新到最新版本 ```bash snow --update ``` 自动更新 Snow CLI 到最新版本。 ### 快速启动模式 #### 1. 跳过欢迎页直接恢复会话 ```bash snow -c ``` 跳过欢迎屏幕，自动恢复最近的对话会话。适合快速继续之前的工作。 #### 2. YOLO 模式（自动批准所有工具调用） ```bash snow --yolo ``` 跳过欢迎屏幕，启动空白对话，并开启 YOLO 模式。在此模式下，所有工具调用会自动批准执行，无需手动确认。 **注意：** YOLO 模式会自动执行所有命令，请谨慎使用！ #### 3. YOLO + 计划模式（YOLO+Plan） ```bash snow --yolo-p ``` 跳过欢迎屏幕，启动空白对话，并开启 YOLO 模式，同时强制启用“计划模式”。适合希望在自动执行的同时，让模型先输出计划再行动的场景。 **注意：** 该模式同样会自动执行所有命令，请谨慎使用！ #### 4. 组合模式：恢复会话 + YOLO ```bash snow --c-yolo ``` 跳过欢迎屏幕，恢复最近的对话会话，并开启 YOLO 模式。结合了会话恢复和自动批准的便利性。 ### 无头模式（Headless Mode） #### 1. 快速提问模式 ```bash snow --ask "你的问题" ``` 无头模式下发送单个提示，AI 回复后自动退出。适合快速获取答案或脚本集成。 **示例：** ```bash snow --ask "如何在JavaScript中使用Promise？" ``` #### 2. 继续对话 ```bash snow --ask "继续的问题" ``` 在指定会话中继续对话。sessionId 是之前会话的标识符。 **示例：** ```bash snow --ask "能详细解释一下吗？" abc123def ``` ### 异步任务管理 #### 1. 创建后台任务 ```bash snow --task "任务描述" ``` 创建一个后台 AI 任务，任务会在后台执行，不阻塞当前终端。 **示例：** ```bash snow --task "重构 auth.ts 文件的错误处理逻辑" ``` 执行后会显示： - 任务 ID - 任务标题 - 查看任务状态的提示 #### 2. 查看任务列表 ```bash snow --task-list ``` 打开任务管理器界面，可以查看和管理所有后台任务，包括： - 查看任务状态（运行中、已完成、失败） - 审批敏感命令 - 将任务转换为会话 - 删除任务 ### 开发者模式 #### 启用开发者模式 ```bash snow --dev ``` 启用开发者模式，使用持久化的 userId 进行测试。在开发和调试时使用，保持用户标识一致。 启动时会显示： ``` Developer mode enabled Using persistent userId: Stored in: ~/.snow/dev-user-id ``` ### 常用组合 1. **快速恢复上次工作：** ```bash snow -c ``` 2. **自动化执行任务：** ```bash snow --yolo ``` 3. **自动化执行任务（并强制计划模式）：** ```bash snow --yolo-p ``` 4. **快速问答并退出：** ```bash snow --ask "TypeScript 泛型怎么用？" ``` 5. **后台执行复杂任务：** ```bash snow --task "分析并优化整个项目的性能瓶颈" ``` 6. **继续之前的对话并自动执行：** ```bash snow --c-yolo ``` ## 使用技巧 1. **快速查看版本和帮助：** 使用 `--version` 或 `--help` 快速获取信息，这些命令执行速度快，不会显示加载动画。 2. **脚本集成：** 使用 `--ask` 参数可以将 Snow CLI 集成到自动化脚本中。 3. **后台任务：** 对于耗时较长的任务，使用 `--task` 创建后台任务，可以继续使用终端做其他工作。 4. **会话管理：** 使用 `--ask` 的 sessionId 参数可以实现多轮对话，适合需要上下文的问题。 5. **安全使用 YOLO：** YOLO 模式虽然方便，但会自动执行所有命令。建议只在信任的环境和明确的任务中使用。 ## 注意事项 1. **YOLO 模式风险：** `--yolo` 和 `--c-yolo` 会自动批准所有工具调用，包括文件修改、命令执行等，请确保了解将要执行的操作。 2. **后台任务：** 使用 `--task` 创建的后台任务会在新进程中运行，即使关闭终端，任务仍会继续执行。 3. **开发者模式：** `--dev` 模式会使用持久化的 userId，仅用于开发和测试环境。 4. **无头模式限制：** `--ask` 模式下，AI 回复后会立即退出，不支持交互式操作。 ## 相关文档 - [无头模式详细说明](./12.无头模式.md) - [异步任务管理](./15.异步任务管理.md) - [快捷键指南](./13.快捷键指南.md) ================================================ FILE: docs/usage/zh/20.SSE服务模式.md ================================================ # Snow CLI 使用文档——SSE 服务模式 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 快速体验 想要快速体验 SSE 客户端？我们提供了一个完整的浏览器测试客户端： **位置**：`source/test/sse-client/index.html` 直接在浏览器中打开该文件，连接到 SSE 服务器即可开始测试。 ## 什么是 SSE 服务模式 SSE（Server-Sent Events）服务模式允许您将 Snow CLI 作为后端服务运行，为外部应用程序提供 AI 能力。它非常适合： - Web 应用集成 - 移动应用后端 - 第三方工具集成 - 微服务架构 - 自定义聊天界面 ## 基础用法 ### 启动 SSE 服务器 #### 基础启动 ```bash # 使用默认端口 3000（前台运行） snow --sse # 指定端口 snow --sse --sse-port 8080 # 指定工作目录 snow --sse --work-dir /path/to/project # 自定义交互超时时长（默认 300000ms 即 5 分钟） snow --sse --sse-timeout 600000 # 设置为 10 分钟 # 组合使用 snow --sse --sse-port 8080 --work-dir /path/to/project --sse-timeout 600000 ``` #### 后台守护进程模式 如果不想让终端被占用，可以使用守护进程模式在后台运行： ```bash # 启动后台守护进程（默认端口 3000） snow --sse-daemon # 指定不同端口（支持多开） snow --sse-daemon --sse-port 3000 snow --sse-daemon --sse-port 8080 snow --sse-daemon --sse-port 9000 # 指定完整参数 snow --sse-daemon --sse-port 8080 --work-dir /path/to/project --sse-timeout 600000 # 查看所有守护进程状态 snow --sse-status # 停止守护进程（三种方式） snow --sse-stop # 停止默认端口3000的守护进程 snow --sse-stop --sse-port 8080 # 通过端口号停止 snow --sse-stop 12345 # 通过PID停止 ``` 守护进程特性： - 支持多实例运行（不同端口） - 在后台运行，不占用终端 - 每个端口独立的日志文件：`~/.snow/sse-logs/port-<端口>.log` - 每个端口独立的 PID 文件：`~/.snow/sse-daemons/port-<端口>.pid` - 支持通过端口或 PID 停止进程 - 查看状态时显示所有运行的守护进程 #### 启动时启用 YOLO 模式 虽然 SSE 服务器本身不使用 `--yolo` 参数，但您可以通过以下方式实现类似效果： **方式一：客户端消息携带 yoloMode** 这是推荐的方式，灵活控制每个请求是否使用 YOLO 模式： ```javascript // 发送消息时指定 YOLO 模式 await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'chat', content: '你的问题', yoloMode: true, // 启用 YOLO 模式 }), }); ``` **方式二：配置权限自动批准列表** 将常用工具添加到项目的权限配置文件中，实现默认自动批准： ```bash # 编辑项目权限配置 vi .snow/permissions.json ``` ```json { "alwaysApprovedTools": [ "filesystem-read", "filesystem-edit", "filesystem-create", "codebase-search", "ace-search", "notebook-add" ] } ``` 这样，列表中的工具会自动批准，无需每次确认。 **注意事项**： - SSE 服务器启动时不支持 `--yolo` 参数 - YOLO 模式需要通过客户端消息的 `yoloMode` 字段启用 - 或者通过配置 `.snow/permissions.json` 实现工具自动批准 - 敏感命令即使在 YOLO 模式下也需要确认 ### 服务器信息 启动后，终端会显示美观的服务器状态界面： ``` ✓ SSE 服务器已启动 端口: 3000 | 工作目录: /Users/xxx/project | ● 运行中 可用端点: http://localhost:3000/events POST http://localhost:3000/message POST http://localhost:3000/session/create POST http://localhost:3000/session/load GET http://localhost:3000/session/list GET http://localhost:3000/session/rollback-points?sessionId={sessionId} DELETE http://localhost:3000/session/{sessionId} GET http://localhost:3000/health 运行日志: [14:30:45] SSE 服务已启动在端口 3000 [14:30:50] 创建新 session: abc-123 按 Ctrl+C 停止服务器 ``` ## API 端点 ### 1. SSE 事件流连接 **端点**: `GET /events` 建立 SSE 连接，接收实时事件流。 #### JavaScript 示例 ```javascript const eventSource = new EventSource('http://localhost:3000/events'); eventSource.onmessage = event => { const data = JSON.parse(event.data); console.log('收到事件:', data); switch (data.type) { case 'connected': console.log('连接成功，连接ID:', data.data.connectionId); break; case 'message': if (data.data.streaming) { console.log('AI 正在回复:', data.data.content); } else if (data.data.role === 'user') { console.log('用户消息:', data.data.content); } break; case 'tool_confirmation_request': // 需要用户确认工具执行 handleToolConfirmation(data); break; case 'complete': console.log('对话完成'); break; } }; ``` ### 2. 发送消息 **端点**: `POST /message` **Content-Type**: `application/json` #### 发送普通文本消息 ```javascript async function sendMessage(content) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content, }), }); return await response.json(); } // 使用示例 await sendMessage('帮我创建一个 React 组件'); ``` #### 带 Session 的连续对话 ```javascript async function continueConversation(content, sessionId) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content, sessionId: sessionId, // 使用 session ID 继续对话 }), }); return await response.json(); } // Session ID 会在 complete 事件中返回 eventSource.onmessage = event => { const data = JSON.parse(event.data); if (data.type === 'complete') { const sessionId = data.data.sessionId; console.log('Session ID:', sessionId); } }; ``` #### 发送图片消息 ```javascript async function sendImageMessage(content, imageFile) { // 将图片转换为 Base64 Data URI const reader = new FileReader(); const imageData = await new Promise((resolve, reject) => { reader.onload = e => resolve(e.target.result); reader.onerror = reject; reader.readAsDataURL(imageFile); }); const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content || '请分析这张图片', images: [ { data: imageData, // 完整的 data URI，如 data:image/png;base64,iVBORw0KG... mimeType: imageFile.type, // 如 image/png, image/jpeg }, ], }), }); return await response.json(); } // 使用示例 const fileInput = document.querySelector('input[type="file"]'); fileInput.addEventListener('change', async e => { const file = e.target.files[0]; if (file && file.type.startsWith('image/')) { await sendImageMessage('这是什么？', file); } }); ``` #### 中断正在执行的任务 ```javascript async function abortTask(sessionId) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'abort', sessionId: sessionId, }), }); return await response.json(); } // 监听中断确认 eventSource.onmessage = event => { const data = JSON.parse(event.data); if (data.type === 'complete' && data.data.cancelled) { console.log('任务已被用户中断'); } }; ``` #### 启用 YOLO 模式 ```javascript async function sendWithYolo(content) { const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'chat', content: content, yoloMode: true, // 自动批准所有非敏感工具 }), }); return await response.json(); } ``` ### 3. 会话管理 #### 创建新会话 **端点**: `POST /session/create` **Content-Type**: `application/json` 创建一个新的对话会话，返回会话信息并自动绑定到当前连接。 ```javascript async function createSession() { const response = await fetch('http://localhost:3000/session/create', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ connectionId: 'conn_xxx', // 可选，指定连接ID }), }); const data = await response.json(); console.log('会话ID:', data.session.id); console.log('创建时间:', data.session.createdAt); return data.session; } ``` #### 加载已有会话 **端点**: `POST /session/load` **Content-Type**: `application/json` 加载一个已保存的会话，恢复对话上下文。 ```javascript async function loadSession(sessionId) { const response = await fetch('http://localhost:3000/session/load', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ sessionId: sessionId, connectionId: 'conn_xxx', // 可选，指定连接ID }), }); const data = await response.json(); if (data.success) { console.log('会话已加载:', data.session.id); console.log('消息数量:', data.session.messages.length); return data.session; } else { console.error('加载失败:', data.error); } } ``` #### 获取会话列表 **端点**: `GET /session/list` **查询参数**: - `page`: 页码，从 0 开始（可选，默认 0） - `pageSize`: 每页数量（可选，默认 20，最大 200） - `q`: 搜索关键词（可选，搜索会话中的消息内容） 获取所有已保存的会话列表，支持分页和搜索。 ```javascript async function listSessions(page = 0, pageSize = 20, searchQuery = '') { const params = new URLSearchParams({ page: page.toString(), pageSize: pageSize.toString(), }); if (searchQuery) { params.append('q', searchQuery); } const response = await fetch(`http://localhost:3000/session/list?${params}`); const data = await response.json(); console.log('总会话数:', data.total); console.log('当前页:', data.page); console.log('每页数量:', data.pageSize); console.log('会话列表:', data.sessions); // 会话列表示例 // data.sessions = [ // { // id: 'abc-123', // createdAt: '2025-12-30T10:00:00.000Z', // updatedAt: '2025-12-30T10:30:00.000Z', // messageCount: 10, // firstMessage: '帮我创建一个函数' // }, // ... // ] return data; } ``` #### 获取回滚点列表 **端点**: `GET /session/rollback-points` **查询参数**: - `sessionId`: 会话 ID（必填） 返回指定会话中可用于回滚的用户消息列表（demo 使用）。 ```javascript async function getRollbackPoints(sessionId) { const params = new URLSearchParams({sessionId}); const response = await fetch( `http://localhost:3000/session/rollback-points?${params.toString()}`, ); const data = await response.json(); // 返回示例（关键字段）: // { // success: true, // sessionId: 'abc-123', // points: [ // { // messageIndex: 0, // role: 'user', // timestamp: 1730000000000, // summary: '...', // hasSnapshot: true, // snapshot: {timestamp: 1730000000000, fileCount: 12}, // filesToRollbackCount: 5 // } // ] // } return data; } ``` #### 删除会话 **端点**: `DELETE /session/{sessionId}` 删除指定的会话及其所有数据。 ```javascript async function deleteSession(sessionId) { const response = await fetch(`http://localhost:3000/session/${sessionId}`, { method: 'DELETE', }); const data = await response.json(); if (data.success) { console.log('会话已删除:', data.deleted); } return data; } ``` ### 4. 健康检查 **端点**: `GET /health` 检查服务器状态和当前连接数。 ```javascript async function checkHealth() { const response = await fetch('http://localhost:3000/health'); const data = await response.json(); console.log('状态:', data.status); console.log('连接数:', data.connections); } ``` ## 事件类型说明 ### connected 连接成功事件。 ```javascript { type: 'connected', data: { connectionId: 'conn_1234567890' }, timestamp: '2025-12-30T15:30:00.000Z' } ``` ### message 消息事件（用户或 AI）。 ```javascript // 用户消息 { type: 'message', data: { role: 'user', content: '帮我创建一个函数' } } // AI 流式响应 { type: 'message', data: { role: 'assistant', content: '当然，我来帮你...', streaming: true } } // AI 最终响应 { type: 'message', data: { role: 'assistant', content: '完整的回复内容', streaming: false } } ``` ### tool_call 工具调用事件。 ```javascript { type: 'tool_call', data: { name: 'filesystem-create', arguments: { filePath: 'example.js', content: '...' } } } ``` ### tool_confirmation_request 请求确认工具执行。 ```javascript { type: 'tool_confirmation_request', data: { toolCall: { function: { name: 'terminal-execute', arguments: '{"command":"rm -rf node_modules"}' } }, isSensitive: true, // 是否为敏感命令 sensitiveInfo: { pattern: 'rm -rf', description: '删除文件或目录' }, availableOptions: [ {value: 'approve', label: 'Approve once'}, {value: 'approve_always', label: 'Always approve'}, // 非敏感命令才有 {value: 'reject_with_reply', label: 'Reject with reply'}, {value: 'reject', label: 'Reject and end session'} ] }, requestId: 'req_1234567890' } ``` ### tool_result 工具执行结果。 ```javascript { type: 'tool_result', data: { content: '执行成功', status: 'success' } } ``` ### user_question_request AI 询问用户问题。 ```javascript { type: 'user_question_request', data: { question: '请选择一个选项', options: ['选项1', '选项2', '选项3'], multiSelect: false }, requestId: 'req_1234567890' } ``` ### usage Token 使用情况。 ```javascript { type: 'usage', data: { prompt_tokens: 150, completion_tokens: 200, total_tokens: 350 } } ``` ### error 错误信息。 ```javascript { type: 'error', data: { message: '错误描述', stack: '错误堆栈（可选）' } } ``` ### complete 对话完成。 ```javascript { type: 'complete', data: { usage: { input_tokens: 150, output_tokens: 200 }, tokenCount: 350, sessionId: 'abc-123-def-456', // 会话 ID cancelled: false // 是否被用户取消（可选） } } ``` ### abort 任务中断请求（客户端主动发送）。 ```javascript // 客户端发送中断请求 await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'abort', sessionId: 'abc-123-def-456' }) }); // 服务器响应中断确认 { type: 'message', data: { role: 'assistant', content: 'Task has been aborted' }, timestamp: '2025-12-30T15:30:00.000Z' } // 随后发送完成事件 { type: 'complete', data: { usage: {input_tokens: 0, output_tokens: 0}, tokenCount: 0, sessionId: 'abc-123-def-456', cancelled: true } } ``` ## 工具确认流程 ### 确认请求响应 当收到 `tool_confirmation_request` 事件时，需要发送确认响应： ```javascript async function handleToolConfirmation(event) { const toolCall = event.data.toolCall; const options = event.data.availableOptions; // 显示工具信息给用户 console.log('工具:', toolCall.function.name); console.log('参数:', toolCall.function.arguments); console.log('可用选项:', options); // 用户选择后发送响应 const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'tool_confirmation_response', requestId: event.requestId, response: 'approve', // 或 'approve_always', 'reject', {type: 'reject_with_reply', reason: '...'} }), }); return await response.json(); } ``` ### 确认选项说明 | 选项 | 值 | 说明 | 适用场景 | | ---------- | --------------------------------------------- | ------------------------ | ------------ | | 批准一次 | `'approve'` | 仅批准这一次执行 | 所有工具 | | 总是批准 | `'approve_always'` | 批准并添加到自动批准列表 | 仅非敏感命令 | | 拒绝并回复 | `{type: 'reject_with_reply', reason: '原因'}` | 拒绝并告诉 AI 原因 | 所有工具 | | 拒绝并结束 | `'reject'` | 拒绝并结束会话 | 所有工具 | ### 敏感命令检测 系统会自动检测敏感命令（如 `rm -rf`、`sudo` 等），敏感命令： - 不会显示"总是批准"选项 - 即使在 YOLO 模式下也需要确认 - 会显示警告信息和匹配的命令模式 关于敏感命令配置，请参考：[敏感命令配置](./06.敏感命令配置.md) ## 用户问题响应 当收到 `user_question_request` 事件时： ```javascript async function handleUserQuestion(event) { const question = event.data.question; const options = event.data.options; const multiSelect = event.data.multiSelect; // 显示问题和选项给用户 console.log('问题:', question); console.log('选项:', options); // 用户选择后发送响应 const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'user_question_response', requestId: event.requestId, response: { selected: multiSelect ? ['选项1', '选项2'] : '选项1', customInput: '', // 可选的自定义输入 }, }), }); return await response.json(); } ``` ## 权限配置 ### 自动批准列表 SSE 服务器会自动读取项目根目录的权限配置文件： **位置**: `.snow/permissions.json` ```json { "alwaysApprovedTools": [ "filesystem-read", "codebase-search", "filesystem-edit", "notebook-add", "filesystem-create" ] } ``` ### 权限继承规则 1. **项目级配置**：服务器启动时读取工作目录下的 `.snow/permissions.json` 2. **自动批准**：列表中的工具会自动执行，不需要用户确认 3. **敏感命令优先**：即使在自动批准列表中，敏感命令仍需确认 4. **动态更新**：用户选择"总是批准"时，工具会自动添加到配置文件 ### 配置示例 ```json { "alwaysApprovedTools": [ "filesystem-read", // 读取文件 "filesystem-edit", // Hashline 编辑 "filesystem-create", // 创建文件 "codebase-search", // 代码搜索 "ace-search", // 统一 ACE 代码搜索（通过 action 选择 semantic_search / find_definition / find_references / file_outline / text_search） "notebook-add" // 添加笔记 ] } ``` ## YOLO 模式 ### 启用 YOLO 模式 在发送消息时携带 `yoloMode` 参数： ```javascript const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'chat', content: '你的问题', yoloMode: true, // 启用 YOLO 模式 }), }); ``` ### YOLO 模式特性 - **自动批准**：非敏感命令自动执行 - **敏感命令例外**：敏感命令仍需确认 - **快速响应**：减少交互等待时间 - **适合自动化**：脚本和自动化场景 ### 安全考虑 即使启用 YOLO 模式： 1. 敏感命令仍需确认 2. 不在权限列表中的工具首次需要确认 3. 可以随时通过拒绝来中止执行 ## 完整示例 ### JavaScript 客户端 ```javascript class SnowAIClient { constructor(baseUrl = 'http://localhost:3000') { this.baseUrl = baseUrl; this.eventSource = null; this.sessionId = null; } // 连接到 SSE 服务器 connect() { return new Promise((resolve, reject) => { this.eventSource = new EventSource(`${this.baseUrl}/events`); this.eventSource.onopen = () => { console.log('已连接到 Snow AI'); resolve(); }; this.eventSource.onerror = error => { console.error('连接错误:', error); reject(error); }; this.eventSource.onmessage = event => { this.handleEvent(JSON.parse(event.data)); }; }); } // 处理事件 handleEvent(event) { console.log('[事件]', event.type); switch (event.type) { case 'tool_confirmation_request': this.handleToolConfirmation(event); break; case 'user_question_request': this.handleUserQuestion(event); break; case 'message': if (event.data.streaming) { process.stdout.write(event.data.content); } break; case 'complete': this.sessionId = event.data.sessionId; console.log('\n对话完成，Session ID:', this.sessionId); break; } } // 处理工具确认 async handleToolConfirmation(event) { const options = event.data.availableOptions; // 这里可以实现自定义的确认逻辑 // 示例：自动批准非敏感命令 const decision = event.data.isSensitive ? 'reject' : 'approve'; await this.sendToolConfirmation(event.requestId, decision); } // 处理用户问题 async handleUserQuestion(event) { // 这里可以实现自定义的选择逻辑 const selected = event.data.options[0]; await this.sendUserQuestionResponse(event.requestId, { selected: selected, }); } // 发送消息 async sendMessage(content, yoloMode = false) { const payload = { type: 'chat', content: content, }; if (this.sessionId) { payload.sessionId = this.sessionId; } if (yoloMode) { payload.yoloMode = true; } const response = await fetch(`${this.baseUrl}/message`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(payload), }); return await response.json(); } // 发送工具确认响应 async sendToolConfirmation(requestId, decision) { const response = await fetch(`${this.baseUrl}/message`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'tool_confirmation_response', requestId: requestId, response: decision, }), }); return await response.json(); } // 发送用户问题响应 async sendUserQuestionResponse(requestId, answer) { const response = await fetch(`${this.baseUrl}/message`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'user_question_response', requestId: requestId, response: answer, }), }); return await response.json(); } // 断开连接 disconnect() { if (this.eventSource) { this.eventSource.close(); this.eventSource = null; } } } // 使用示例 async function main() { const client = new SnowAIClient(); // 连接 await client.connect(); // 发送消息（启用 YOLO 模式） await client.sendMessage('帮我创建一个 TypeScript 函数', true); // 等待响应处理（通过事件监听器） } main(); ``` ### Python 客户端 ```python import requests import json import sseclient class SnowAIClient: def __init__(self, base_url='http://localhost:3000'): self.base_url = base_url self.session = requests.Session() self.session_id = None def connect(self): """连接到 SSE 服务器""" response = self.session.get( f'{self.base_url}/events', stream=True, headers={'Accept': 'text/event-stream'} ) client = sseclient.SSEClient(response) for event in client.events(): data = json.loads(event.data) self.handle_event(data) def handle_event(self, event): """处理事件""" print(f"[事件] {event['type']}") if event['type'] == 'tool_confirmation_request': self.handle_tool_confirmation(event) elif event['type'] == 'user_question_request': self.handle_user_question(event) elif event['type'] == 'complete': self.session_id = event['data']['sessionId'] print(f"Session ID: {self.session_id}") def handle_tool_confirmation(self, event): """处理工具确认""" # 自动批准非敏感命令 decision = 'reject' if event['data']['isSensitive'] else 'approve' self.send_tool_confirmation_response(event['requestId'], decision) def handle_user_question(self, event): """处理用户问题""" selected = event['data']['options'][0] self.send_user_question_response(event['requestId'], {'selected': selected}) def send_message(self, content, yolo_mode=False): """发送消息""" payload = { 'type': 'chat', 'content': content, } if self.session_id: payload['sessionId'] = self.session_id if yolo_mode: payload['yoloMode'] = True response = self.session.post( f'{self.base_url}/message', json=payload ) return response.json() def send_tool_confirmation_response(self, request_id, decision): """发送工具确认响应""" response = self.session.post( f'{self.base_url}/message', json={ 'type': 'tool_confirmation_response', 'requestId': request_id, 'response': decision } ) return response.json() def send_user_question_response(self, request_id, answer): """发送用户问题响应""" response = self.session.post( f'{self.base_url}/message', json={ 'type': 'user_question_response', 'requestId': request_id, 'response': answer } ) return response.json() # 使用示例 if __name__ == '__main__': client = SnowAIClient() # 发送消息（启用 YOLO 模式） client.send_message('帮我创建一个 Python 函数', yolo_mode=True) # 监听事件 client.connect() ``` ## 使用场景 ### Web 应用集成 将 Snow AI 集成到您的 Web 应用中，提供智能编程助手功能： ```javascript // React 组件示例 import {useState, useEffect, useRef} from 'react'; function AIAssistantChat() { const [connected, setConnected] = useState(false); const [messages, setMessages] = useState([]); const [sessionId, setSessionId] = useState(null); const eventSourceRef = useRef(null); // 连接到 SSE 服务器 useEffect(() => { const eventSource = new EventSource('http://localhost:3000/events'); eventSourceRef.current = eventSource; eventSource.onopen = () => { setConnected(true); console.log('已连接到 Snow AI'); }; eventSource.onmessage = event => { const data = JSON.parse(event.data); handleSSEEvent(data); }; eventSource.onerror = () => { setConnected(false); console.error('连接断开'); }; return () => { eventSource.close(); }; }, []); // 处理 SSE 事件 const handleSSEEvent = data => { switch (data.type) { case 'message': if (data.data.role === 'assistant') { if (data.data.streaming) { // 流式更新最后一条消息 setMessages(prev => { const newMessages = [...prev]; if ( newMessages.length > 0 && newMessages[newMessages.length - 1].role === 'assistant' ) { newMessages[newMessages.length - 1].content = data.data.content; } else { newMessages.push({ role: 'assistant', content: data.data.content, }); } return newMessages; }); } } break; case 'complete': setSessionId(data.data.sessionId); console.log('对话完成'); break; case 'tool_confirmation_request': // 显示工具确认对话框 handleToolConfirmation(data); break; case 'error': console.error('错误:', data.data.message); break; } }; // 发送消息 const sendMessage = async text => { const newMessage = {role: 'user', content: text}; setMessages(prev => [...prev, newMessage]); const payload = { type: 'chat', content: text, yoloMode: true, // 自动批准安全工具 }; if (sessionId) { payload.sessionId = sessionId; } await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(payload), }); }; // 处理工具确认 const handleToolConfirmation = async event => { const confirmed = window.confirm( `AI 想要执行工具: ${event.data.toolCall.function.name}\n是否允许？`, ); await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'tool_confirmation_response', requestId: event.requestId, response: confirmed ? 'approve' : 'reject', }), }); }; return (
状态: {connected ? '已连接' : '未连接'}
{messages.map((msg, i) => (
{msg.role}: {msg.content}
))}
{ if (e.key === 'Enter') { sendMessage(e.target.value); e.target.value = ''; } }} />
); } ``` ### 移动应用后端 为移动应用提供 AI 能力： ```javascript // Express 中间件 app.post('/api/ai/chat', async (req, res) => { const {message, sessionId} = req.body; // 转发到 Snow AI const response = await fetch('http://localhost:3000/message', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'chat', content: message, sessionId: sessionId, yoloMode: true, }), }); res.json(await response.json()); }); ``` ### 微服务架构 作为 AI 微服务： ```javascript // Kubernetes 部署 apiVersion: apps/v1 kind: Deployment metadata: name: snow-ai-service spec: replicas: 3 selector: matchLabels: app: snow-ai template: metadata: labels: app: snow-ai spec: containers: - name: snow-ai image: snow-ai:latest command: ["snow", "--sse", "--sse-port", "3000"] ports: - containerPort: 3000 ``` ## 测试客户端 Snow CLI 提供了一个完整的 HTML 测试客户端： **位置**: `sse-test-client.html` ### 功能特性 - 实时 SSE 事件监听 - 美观的聊天界面 - 事件日志查看 - YOLO 模式开关 - 工具确认 UI（包含完整的选项展示） - Session 管理 - 连接状态显示 ### 使用方法 1. 启动 SSE 服务器： ```bash snow --sse ``` 2. 在浏览器中打开 `sse-test-client.html` 3. 点击"连接"按钮 4. 开始聊天测试 ## 最佳实践 ### 1. 错误处理 ```javascript // 完善的错误处理 eventSource.onerror = error => { console.error('SSE 连接错误:', error); // 自动重连 setTimeout(() => { console.log('尝试重新连接...'); connect(); }, 5000); }; ``` ### 2. 超时处理 ```javascript // 为交互请求设置超时 const TIMEOUT = 300000; // 5 分钟（默认值，可通过 --sse-timeout 参数调整） function waitForResponse(requestId) { return new Promise((resolve, reject) => { const timeout = setTimeout(() => { reject(new Error('交互超时')); }, TIMEOUT); // 监听响应 // 收到响应后 clearTimeout(timeout) }); } ``` ### 3. Session 管理 ```javascript // 持久化 Session ID localStorage.setItem('snow-session-id', sessionId); // 恢复 Session const savedSessionId = localStorage.getItem('snow-session-id'); if (savedSessionId) { await client.sendMessage('继续之前的对话', false, savedSessionId); } ``` ### 4. 安全考虑 ```javascript // 验证和清理用户输入 function sanitizeInput(input) { // 移除危险字符 return input.replace(/[<>]/g, ''); } // 在生产环境中添加认证 const response = await fetch('http://localhost:3000/message', { headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiToken}`, }, // ... }); ``` ## 限制和注意事项 ### 不支持的功能 1. **交互式 UI**： - 无法使用 Ink 终端界面 - 不支持快捷键 2. **Plan 模式**： - 不支持交互式计划审批 - 所有操作立即执行 3. **本地文件访问限制**： - 只能访问服务器工作目录下的文件 - 不能访问客户端本地文件 ### 性能注意事项 1. **连接数限制**： - 建议单个服务器不超过 100 个并发连接 - 考虑负载均衡 2. **Session 大小**： - 长会话会增加内存使用 - 定期清理旧 Session 3. **网络带宽**： - 流式输出会持续占用连接 - 考虑消息大小限制 ### 安全注意事项 1. **认证和授权**： - 生产环境必须添加认证 - 实施访问控制 2. **API 密钥保护**： - 不要在客户端暴露 API 密钥 - 使用服务器端配置 3. **命令执行风险**： - 审查所有工具调用 - 限制敏感操作 ## 常见问题 **Q: SSE 服务器和无头模式有什么区别？** A: SSE 服务器是持续运行的后端服务，支持多个客户端连接。无头模式是单次执行模式，执行完成后自动退出。SSE 适合 Web 应用集成，无头模式适合脚本自动化。 **Q: 如何在 SSE 模式下使用不同的 API 配置？** A: SSE 服务器读取工作目录下的配置文件。可以通过 `--work-dir` 参数指定不同的项目目录，每个目录有独立的配置。 **Q: 可以同时运行多个 SSE 服务器吗？** A: 可以，但需要使用不同的端口。例如： ```bash snow --sse --sse-port 3000 snow --sse --sse-port 3001 --work-dir /另一个项目 ``` **Q: Session 会过期吗？** A: Session 不会过期，会永久保存在 `~/.snow/sessions/` 目录下。但是非常长的 Session 会增加 Token 消耗。 **Q: 如何处理工具确认超时？** A: 工具确认默认有 5 分钟（300000ms）超时。如果超时，会自动拒绝执行并返回错误。建议在客户端实现自动处理或提示用户。 您可以通过 `--sse-timeout` 参数自定义超时时长： ```bash # 设置为 10 分钟（600000ms） snow --sse --sse-timeout 600000 # 设置为 30 秒（30000ms） snow --sse --sse-timeout 30000 ``` **Q: YOLO 模式会执行所有命令吗？** A: 不会。敏感命令即使在 YOLO 模式下也需要确认。YOLO 模式只自动批准安全的、在权限列表中的工具。 **Q: 如何调试 SSE 连接问题？** A: 1. 检查服务器日志（终端显示） 2. 使用浏览器开发工具查看网络请求 3. 使用 `sse-test-client.html` 测试 4. 检查防火墙和端口占用 **Q: 可以在 Docker 中运行 SSE 服务器吗？** A: 可以。示例 Dockerfile： ```dockerfile FROM node:18 RUN npm install -g snow-ai EXPOSE 3000 CMD ["snow", "--sse", "--sse-port", "3000"] ``` ## 配置文件位置 SSE 服务器使用的配置文件： - **API 配置**: `~/.snow/profiles.json` - **权限配置**: `<工作目录>/.snow/permissions.json` - **敏感命令**: `~/.snow/sensitive-commands.json` - **Session 存储**: `~/.snow/sessions/<项目名>/<日期>/` 配置方法请参考：[首次配置](./02.首次配置.md) ## 相关功能 - [无头模式](./12.无头模式.md) - 命令行快速对话 - [敏感命令配置](./06.敏感命令配置.md) - 配置需要确认的危险命令 - [异步任务管理](./15.异步任务管理.md) - 后台任务管理 - [启动参数说明](./19.启动参数说明.md) - 所有启动参数详解 ================================================ FILE: docs/usage/zh/21.自定义StatusLine指南.md ================================================ # Snow CLI 使用文档——自定义 StatusLine 指南 ## 概述 Snow CLI 支持从用户目录加载自定义 StatusLine 插件。你只需要把一个或多个 JavaScript 文件放到 `~/.snow/plugin/statusline/`，Snow CLI 启动时就会自动加载。 适合这些场景： - 显示你自己的环境状态 - 显示项目特定提示 - 添加时间、目录、分支、服务、本机状态等信息 - 按简体中文、繁体中文、英语切换状态文本 - 用自己的实现覆盖内置 StatusLine 插件 ## 插件目录 当前 Snow CLI 只会从这里加载 StatusLine 插件： ```bash ~/.snow/plugin/statusline/ ``` 支持的文件扩展名： - `.js` - `.mjs` - `.cjs` 说明： - 目前只支持用户目录插件 - Snow CLI 会按文件名排序后加载插件文件 - 新增或修改插件文件后，需要重启 Snow CLI ## 支持的导出形式 一个插件模块可以使用以下任意一种导出形式： ```js export default { ... } ``` ```js export const statusLineHook = { ... } ``` ```js export const statusLineHooks = [{ ... }, { ... }] ``` 如果多个插件使用相同的 hook `id`，后加载的插件会覆盖先加载的插件。 ## Hook 结构 每个 StatusLine hook 都使用下面这种结构： ```js export default { id: 'custom.example', refreshIntervalMs: 60000, getItems(context) { return { id: 'custom-example-item', text: 'Hello', detailedText: '来自自定义状态栏的问候', color: 'cyan', priority: 200, }; }, }; ``` 字段说明： - `id`：hook 的唯一标识，用于合并和覆盖 - `refreshIntervalMs`：可选，刷新间隔，单位毫秒；系统最小生效值为 1000 ms - `enable`：可选，是否启用该 hook，默认为 `true`，设为 `false` 可临时禁用 - `getItems(context)`：返回一个状态项、多个状态项，或 `undefined` `getItems` 支持返回： - 单个对象 - 对象数组 - `undefined` 或 `null`，表示本次不显示 - `async getItems()` 的异步返回 ## 状态项字段 每个渲染项支持这些字段： - `id`：可选，状态项 id；如果不传，Snow CLI 会自动补全 - `text`：简洁模式下显示的短文本 - `detailedText`：普通模式下优先显示的详细文本；没有则回退到 `text` - `color`：可选，Ink 颜色字符串或十六进制颜色 - `priority`：可选，排序优先级；值越小越靠前 ## context 对象 `getItems(context)` 会收到下面这个上下文对象： ```js { cwd: '/absolute/current/working/directory', platform: 'darwin', language: 'zh', simpleMode: false, labels: { gitBranch: 'Git分支', }, system: { memory: { usageMb: 186, formattedUsage: '186 MB', }, modes: { yolo: false, plan: true, vulnerabilityHunting: false, toolSearchEnabled: true, hybridCompress: false, simple: false, }, ide: { connectionStatus: 'connected', editorContext: { activeFile: '/path/to/file.ts', selectedText: 'const answer = 42;', cursorPosition: {line: 10, character: 5}, workspaceFolder: '/path/to/workspace', }, selectedTextLength: 18, }, backend: { connectionStatus: 'connected', instanceName: 'default', }, contextWindow: { inputTokens: 18234, maxContextTokens: 128000, cacheCreationTokens: 2048, cacheReadTokens: 8192, percentage: 22.3, totalInputTokens: 28474, hasAnthropicCache: true, hasOpenAICache: false, hasAnyCache: true, }, codebase: { indexing: true, progress: { totalFiles: 100, processedFiles: 42, totalChunks: 320, currentFile: 'source/app.ts', status: 'indexing', }, }, watcher: { enabled: true, fileUpdateNotification: { file: 'source/app.ts', timestamp: 1710000000000, }, }, clipboard: { text: '已复制输入内容', isError: false, timestamp: 1710000000000, }, profile: { currentName: 'default', baseUrl: 'https://api.openai.com/v1', requestMethod: 'chat', advancedModel: 'gpt-4o', basicModel: 'gpt-4o-mini', maxContextTokens: 128000, maxTokens: 4096, anthropicBeta: false, anthropicCacheTTL: '5m', thinkingEnabled: false, thinkingType: 'adaptive', thinkingBudgetTokens: 4096, thinkingEffort: 'medium', geminiThinkingEnabled: false, geminiThinkingLevel: 'high', responsesReasoningEnabled: false, responsesReasoningEffort: 'medium', responsesFastMode: false, responsesVerbosity: 'medium', anthropicSpeed: 'standard', enablePromptOptimization: true, enableAutoCompress: true, autoCompressThreshold: 80, showThinking: true, streamIdleTimeoutSec: 180, systemPromptId: ['default'], customHeadersSchemeId: 'default', toolResultTokenLimit: 100000, streamingDisplay: false, }, compression: { blockToast: null, }, }, } ``` 字段说明： - `cwd`：当前 Snow CLI 工作目录 - `platform`：当前 Node.js 平台值，例如 `darwin`、`linux`、`win32` - `language`：当前 Snow CLI 语言，可能是 `en`、`zh`、`zh-TW` - `simpleMode`：当前是否为简洁主题模式 - `labels`：内置插件可复用的本地化标签 - `system`：当前状态栏可直接复用的系统状态快照 `system` 下可用字段： - `system.memory`：当前 Snow CLI 进程内存，包含 `usageMb` 和 `formattedUsage` - `system.modes`：当前模式状态，包含 `yolo`、`plan`、`vulnerabilityHunting`、`toolSearchEnabled`、`hybridCompress`、`team`、`simple` - `system.ide`：IDE 连接状态，包含 `connectionStatus`、`editorContext`、`selectedTextLength` - `system.backend`：后端连接状态，包含 `connectionStatus`、`instanceName` - `system.contextWindow`：上下文窗口状态；存在时包含 token 统计、缓存命中以及 `percentage`、`totalInputTokens` - `system.codebase`：代码库索引状态，包含 `indexing` 和 `progress` - `system.watcher`：文件监视器状态，包含 `enabled` 和 `fileUpdateNotification` - `system.clipboard`：最近一次复制提示，包含 `text`、`isError`、`timestamp` - `system.profile`：当前 Profile 完整配置信息，包含 `currentName`、`baseUrl`、`requestMethod`、`advancedModel`、`basicModel`、`maxContextTokens`、`maxTokens`、`anthropicBeta`、`anthropicCacheTTL`、`thinkingEnabled`、`thinkingType`、`thinkingBudgetTokens`、`thinkingEffort`、`geminiThinkingEnabled`、`geminiThinkingLevel`、`responsesReasoningEnabled`、`responsesReasoningEffort`、`responsesFastMode`、`responsesVerbosity`、`anthropicSpeed`、`enablePromptOptimization`、`enableAutoCompress`、`autoCompressThreshold`、`showThinking`、`streamIdleTimeoutSec`、`systemPromptId`、`customHeadersSchemeId`、`toolResultTokenLimit`、`streamingDisplay`（不含 `apiKey`） - `system.compression`：自动压缩提示，包含 `blockToast` ## 示例 1：真实可用的时钟插件 现在你的用户目录里已经有一个真实可用的插件文件： ````bash ~/.snow/plugin/statusline/example-clock.js 内容如下： ```js const messages = { en: { label: 'Current Time', directory: 'Directory', }, zh: { label: '当前时间', directory: '目录', }, 'zh-TW': { label: '當前時間', directory: '目錄', }, }; export default { id: 'custom.example-clock', refreshIntervalMs: 60_000, getItems(context) { const now = new Date(); const hours = String(now.getHours()).padStart(2, '0'); const minutes = String(now.getMinutes()).padStart(2, '0'); const clock = `${hours}:${minutes}`; const message = messages[context.language] || messages.en; return { id: 'custom-example-clock', text: `◷ ${clock}`, detailedText: `◷ ${message.label}: ${clock} · ${message.directory}: ${context.cwd}`, color: '#A78BFA', priority: 200, }; }, }; ```` ## 示例 2：显示当前目录名 ```js import path from 'node:path'; export default { id: 'custom.cwd-name', refreshIntervalMs: 5000, getItems(context) { const folderName = path.basename(context.cwd); return { text: `DIR ${folderName}`, detailedText: `当前目录名: ${folderName}`, color: 'green', priority: 150, }; }, }; ``` ## 示例 3：使用系统状态 ```js export default { id: 'custom.system-status', refreshIntervalMs: 3000, getItems(context) { const items = []; if (context.system.ide.connectionStatus === 'connected') { const activeFile = context.system.ide.editorContext?.activeFile; items.push({ id: 'custom-system-ide', text: activeFile ? 'IDE ON' : 'IDE READY', detailedText: activeFile ? `IDE 已连接 · 当前文件: ${activeFile}` : 'IDE 已连接', color: '#22C55E', priority: 120, }); } if (context.system.contextWindow) { items.push({ id: 'custom-system-context', text: `CTX ${context.system.contextWindow.percentage.toFixed(1)}%`, detailedText: `上下文已使用 ${context.system.contextWindow.totalInputTokens} tokens`, color: 'cyan', priority: 130, }); } items.push({ id: 'custom-system-memory', text: `MEM ${context.system.memory.formattedUsage}`, detailedText: `当前内存占用: ${context.system.memory.formattedUsage}`, color: 'yellow', priority: 140, }); return items; }, }; ``` ## 示例 4：一次返回多个状态 ```js export default { id: 'custom.multi-status', refreshIntervalMs: 30000, getItems() { const now = new Date(); return [ { text: `T ${String(now.getHours()).padStart(2, '0')}:${String( now.getMinutes(), ).padStart(2, '0')}`, color: 'cyan', priority: 100, }, { text: 'ENV DEV', detailedText: '运行环境: Development', color: 'yellow', priority: 110, }, ]; }, }; ``` ## 内置 Git 分支插件示例 Snow CLI 已经内置了一个 Git 分支 StatusLine 插件。 参考实现： - `source/ui/components/common/statusline/gitBranch.ts` 这个内置 hook： - hook id 是 `builtin.git-branch` - 每 10 秒刷新一次 - 从 `context.cwd` 读取当前 Git 分支 - 分别输出短文本和详细文本 如果你写一个相同 hook id 的插件，就可以覆盖内置 Git 分支行为。 ## 内置 Hook 列表（可被覆盖的 id） 除 `builtin.git-branch` 外，Snow CLI 还为其他内置状态项预留了稳定 hook id。 只要你的插件返回一个相同 id 的 hook，对应的内置状态项就会被你的实现替换： | Hook ID | 默认渲染内容 | 触发条件 | | ---------------------------- | --------------------------------------- | ------------------------------ | | `builtin.profile` | `§ {profileName}` | 存在当前 Profile | | `builtin.mode-yolo` | `⧴ YOLO` | YOLO 模式开启 | | `builtin.mode-plan` | `⚐ Plan` | Plan 模式开启 | | `builtin.mode-hunt` | `⍨ Vuln Hunt` | 漏洞挖掘模式开启 | | `builtin.mode-team` | `⚑ Team` | Team 模式开启 | | `builtin.tool-search` | `♾︎ ToolSearch ON` | 工具按需搜索启用 | | `builtin.hybrid-compress` | `⇌ Hybrid Compress` | 混合压缩开启 | | `builtin.ide-connection` | `◐/●/○ IDE` | VSCode 连接状态非 disconnected | | `builtin.backend-connection` | `◐/↻/● Backend` | 后端连接状态非 disconnected | | `builtin.codebase-indexing` | `◐ 索引 {processed}/{total}` 或错误提示 | 正在索引或索引出错 | | `builtin.watcher` | `☉ 文件监视` | 监视器启用且未在索引 | | `builtin.file-update` | `⛁ 已更新` | 收到文件更新通知 | | `builtin.copy-status` | 复制成功 / 失败提示文案 | 收到剪贴板提示 | | `builtin.compress-block` | 自动压缩被中断提示文案 | 自动压缩被阻断 | | `builtin.memory` | `⛁ {memoryUsage}` | 始终显示当前进程内存 | | `builtin.git-branch` | `⑂ {branch}` | 当前目录在 Git 仓库中 | 注意事项： - 一旦插件以相同 id 注册了 hook，Snow CLI 就会**完全**跳过对应内置项的硬编码渲染。 这意味着原本的徽章、图标、颜色、阈值等全部交由你的 hook 控制。 - 内置项的"是否显示"条件（例如 YOLO 模式是否开启）由 Snow CLI 主程序决定。 插件可以通过 `context.system.modes`、`context.system.ide`、`context.system.contextWindow` 等字段读取相同的状态信息，自行决定是否返回内容。 - 覆盖 `builtin.memory` 后默认的"⛁ 232 MB"将不再渲染，请确保你的 hook 能合理展示内存信息（可以读取 `context.system.memory.usageMb`）。 ## 覆盖内置插件示例 ```js export default { id: 'builtin.git-branch', refreshIntervalMs: 15000, async getItems(context) { return { text: '⑂ custom-branch', detailedText: `⑂ 自定义 Git 分支 (${context.cwd})`, color: 'magenta', priority: 100, }; }, }; ``` ## 错误处理 如果某个插件出错： - Snow CLI 会跳过这次刷新结果 - 错误会写入 Snow CLI 日志 - 其他插件仍会继续执行 常见问题： - 文件不在 `~/.snow/plugin/statusline/` - 扩展名不受支持 - 导出的值不是合法 hook 对象 - `text` 缺失或为空 - 插件代码运行时报错 ## 最佳实践 - 保持 `getItems()` 足够轻量 - 设置合理刷新间隔 - 不需要显示时返回 `undefined` - 使用稳定的 `id` 方便排序和覆盖 - 普通模式优先写 `detailedText`，简洁模式写 `text` - 修改插件文件后记得重启 Snow CLI ## 故障排查 ### 插件没有显示 请检查： 1. 文件路径是否为 `~/.snow/plugin/statusline/*.js` 2. 是否已经重启 Snow CLI 3. 导出格式是否正确 4. `text` 是否为空 5. 插件执行时是否抛错 ### 状态顺序不对 检查 `priority`： - 数值越小越靠前 - 数值越大越靠后 ### 为什么没有覆盖内置 Git 分支 请确认 hook `id` 完全一致： ```js id: 'builtin.git-branch'; ``` ## 相关文件 - `source/ui/components/common/statusline/useStatusLineHooks.ts` - `source/ui/components/common/statusline/types.ts` - `source/ui/components/common/statusline/gitBranch.ts` - `~/.snow/plugin/statusline/example-clock.js` ================================================ FILE: docs/usage/zh/22.Team模式指南.md ================================================ # Snow CLI 使用文档——Team模式指南 Team模式（多智能体协作）是 Snow CLI 的高级功能，允许你同时启动多个独立工作的 AI 队友，通过共享任务列表协调工作，实现真正的并行开发。 ## 什么是Team模式 Team模式允许你创建一支 AI 开发团队，每个队友： - 在独立的 Git 工作树中工作，互不干扰 - 通过共享任务列表协调分工 - 可以相互通信，同步进度 - 完成后将工作合并回主分支 ### 适用场景 - **大型重构项目**：将任务拆分给多个队友并行处理 - **全栈开发**：前端、后端、测试同时进行 - **代码审查**：专门队友负责审查和质量保证 - **文档编写**：多语言文档并行撰写 - **复杂功能开发**：模块化分解，各 teammate 负责不同模块 ## Team模式核心概念 ### 队友（Teammate） 每个队友是一个独立的 AI 实例，拥有： - **独立的 Git 工作树**：在 `.snow/worktrees/` 目录下 - **独立的上下文**：与主流程和其他队友隔离 - **专属角色**：可以指定不同角色（如前端开发、测试工程师） - **完整工具访问**：可以使用所有 Snow CLI 工具 ### 共享任务列表 团队使用共享的任务列表协调工作： - **任务创建**：可以预先创建任务或动态添加 - **任务分配**：可以指定给特定队友，也可以让队友主动认领 - **依赖管理**：任务可以设置依赖关系，确保执行顺序 - **状态追踪**：实时查看任务进度 ### 消息通信 队友之间可以通过消息系统通信： - **单播**：向特定队友发送消息 - **广播**：向所有队友发送消息 - **自动同步**：队友完成工作后会通知团队 ## Team模式工作流程 ```mermaid graph TB Start([启动Team模式]) --> Spawn[创建队友] Spawn --> CreateTasks[创建任务列表] CreateTasks --> Assign[分配/认领任务] Assign --> ParallelWork{并行工作} ParallelWork --> Teammate1[队友A
处理任务1] ParallelWork --> Teammate2[队友B
处理任务2] ParallelWork --> Teammate3[队友C
处理任务3] Teammate1 --> Message1[消息通信
同步进度] Teammate2 --> Message1 Teammate3 --> Message1 Message1 --> Wait{等待完成} Wait --> Complete[所有任务完成] Complete --> Merge[合并工作] Merge --> Cleanup[清理团队] Cleanup --> End([结束]) style Start fill:#e1f5ff style Spawn fill:#fff4e1 style ParallelWork fill:#ffe1f5 style Teammate1 fill:#e1ffe1 style Teammate2 fill:#e1ffe1 style Teammate3 fill:#e1ffe1 style Merge fill:#ffe1e1 style End fill:#e1f5ff ``` ### 工作流程说明 1. **创建队友**：使用 `spawn_teammate` 创建需要的队友 2. **创建任务**：使用 `create_task` 添加任务到共享列表 3. **分配任务**：队友主动认领或指定分配 4. **并行执行**：队友在各自的工作树中独立工作 5. **消息通信**：需要时通过消息系统协调 6. **等待完成**：等待所有队友完成任务 7. **合并工作**：将各队友的工作合并到主分支 8. **清理团队**：关闭队友并清理工作树 ## 命令详解 ### 创建队友：spawn_teammate 创建一个新的 AI 队友，每个队友有自己的 Git 工作树。 ```typescript spawn_teammate({ name: "frontend", // 队友名称（简短描述性） prompt: "任务描述...", // 完整的任务提示词 require_plan_approval: true // 是否需要在执行前审批计划（可选） }) ``` **示例**： ```typescript // 创建一个前端开发队友 spawn_teammate({ name: "frontend", prompt: "负责实现用户登录页面的前端代码。使用 React + TypeScript，需要包含表单验证和错误处理。项目路径：src/pages/login/", require_plan_approval: true }) // 创建一个测试队友 spawn_teammate({ name: "tester", prompt: "为登录功能编写单元测试和集成测试。使用 Jest + React Testing Library，覆盖率要求 80%以上。" }) ``` ### 创建任务：create_task 在共享任务列表中添加任务。 ```typescript create_task({ title: "任务标题", // 简短的任务标题 description: "详细描述...", // 任务的具体内容 assignee_name: "frontend", // 指定给哪个队友（可选） dependencies: ["task-id-1"] // 依赖的任务ID列表（可选） }) ``` **示例**： ```typescript // 创建独立任务 create_task({ title: "实现登录页面", description: "创建登录表单组件，包含邮箱和密码输入，添加表单验证", assignee_name: "frontend" }) // 创建有依赖的任务 create_task({ title: "编写登录测试", description: "为登录功能编写单元测试", assignee_name: "tester", dependencies: ["task-abc-123"] // 等待登录页面完成 }) ``` ### 更新任务：update_task 更新任务状态或重新分配。 ```typescript update_task({ task_id: "task-abc-123", status: "in_progress", // pending | in_progress | completed assignee_name: "backend" // 重新分配给其他队友 }) ``` ### 查看任务列表：list_tasks 查看所有任务及其状态。 ```typescript list_tasks({}) ``` **返回示例**： ``` 任务列表： ┌─────────┬──────────────────┬─────────────┬────────────────┐ │ ID │ 标题 │ 状态 │ 负责人 │ ├─────────┼──────────────────┼─────────────┼────────────────┤ │ task-1 │ 实现登录页面 │ completed │ frontend │ │ task-2 │ 编写登录测试 │ in_progress │ tester │ │ task-3 │ API接口对接 │ pending │ - │ └─────────┴──────────────────┴─────────────┴────────────────┘ ``` ### 查看队友：list_teammates 查看当前运行的所有队友。 ```typescript list_teammates({}) ``` **返回示例**： ``` 队友列表： ┌──────────┬────────────────┬─────────────┬────────────────────────────┐ │ 成员ID │ 名称 │ 状态 │ 当前任务 │ ├──────────┼────────────────┼─────────────┼────────────────────────────┤ │ mem-abc │ frontend │ working │ 实现登录页面 │ │ mem-def │ tester │ working │ 编写登录测试 │ │ mem-ghi │ backend │ standby │ 等待新任务 │ └──────────┴────────────────┴─────────────┴────────────────────────────┘ ``` ### 发送消息：message_teammate 向特定队友发送消息。 ```typescript message_teammate({ target_id: "mem-abc", // 队友ID或名称 content: "前端页面已经完成，可以开始测试了" }) ``` ### 广播消息：broadcast_to_team 向所有队友广播消息。 ```typescript broadcast_to_team({ content: "所有队友注意：项目需求有更新，请查看文档" }) ``` ### 等待完成：wait_for_teammates 阻塞并等待所有队友完成工作。 ```typescript wait_for_teammates({ timeout_seconds: 600 // 超时时间（秒），默认600秒 }) ``` **注意**：此命令会阻塞当前流程，直到所有队友进入 `standby` 状态或超时。 ### 合并队友工作：merge_teammate_work 合并特定队友的工作到主分支。 ```typescript merge_teammate_work({ name: "frontend", strategy: "manual" // manual | theirs | ours | auto }) ``` **合并策略**： - `manual`（默认）：手动解决冲突 - `theirs`：自动接受队友的所有更改 - `ours`：自动保留主分支的更改 - `auto`：尝试正常合并，冲突时自动接受队友版本 ### 合并所有工作：merge_all_teammate_work 合并所有队友的工作到主分支。 ```typescript merge_all_teammate_work({ strategy: "manual" }) ``` ### 关闭队友：shutdown_teammate 关闭特定队友。 ```typescript shutdown_teammate({ target_id: "mem-abc", reason: "任务已完成" // 关闭原因（可选） }) ``` **注意**：队友不能自行关闭，必须由团队负责人控制。 ### 清理团队：cleanup_team 清理团队，移除所有 Git 工作树。 ```typescript cleanup_team({}) ``` **重要**：执行此命令前必须： 1. 关闭所有队友 2. 合并所有需要保留的工作 ## 工作流示例 ### 示例1：全栈功能开发 ```typescript // 1. 创建开发团队 spawn_teammate({ name: "backend", prompt: "负责设计和实现用户认证API。需要：1）登录接口 2）注册接口 3）JWT token生成 4）密码加密存储。使用 Express + Prisma。", require_plan_approval: true }) spawn_teammate({ name: "frontend", prompt: "负责实现登录和注册页面的前端。使用 React + TypeScript + Tailwind CSS，需要与后端API对接。" }) spawn_teammate({ name: "tester", prompt: "负责编写完整的测试套件。包括：1）后端API测试 2）前端组件测试 3）集成测试。覆盖率要求90%。" }) // 2. 创建任务列表 create_task({ title: "设计数据库模型", description: "设计用户表结构，包含邮箱、密码哈希、创建时间等字段", assignee_name: "backend" }) create_task({ title: "实现认证API", description: "实现登录、注册、token刷新等接口", assignee_name: "backend" }) create_task({ title: "实现登录页面", description: "创建登录页面UI和表单逻辑", assignee_name: "frontend" }) create_task({ title: "编写后端测试", description: "为认证API编写单元测试和集成测试", assignee_name: "tester", dependencies: ["task-backend-api"] // 依赖后端API完成 }) // 3. 等待所有队友完成 wait_for_teammates({ timeout_seconds: 1800 }) // 4. 合并所有工作 merge_all_teammate_work({ strategy: "manual" }) // 5. 清理团队 cleanup_team({}) ``` ### 示例2：代码重构项目 ```typescript // 创建多个重构队友，分别负责不同模块 spawn_teammate({ name: "refactor-utils", prompt: "重构 utils 目录下的所有工具函数。目标：1）添加类型定义 2）统一错误处理 3）添加 JSDoc 注释" }) spawn_teammate({ name: "refactor-components", prompt: "重构 components 目录下的 React 组件。目标：1）转换为函数组件 2）使用 TypeScript 3）优化性能" }) spawn_teammate({ name: "refactor-api", prompt: "重构 API 层代码。目标：1）统一请求封装 2）添加请求/响应拦截器 3）完善错误处理" }) // 创建任务 create_task({ title: "重构工具函数", assignee_name: "refactor-utils" }) create_task({ title: "重构组件", assignee_name: "refactor-components" }) create_task({ title: "重构API层", assignee_name: "refactor-api" }) // 等待并合并 wait_for_teammates({ timeout_seconds: 1200 }) merge_all_teammate_work({ strategy: "auto" }) cleanup_team({}) ``` ### 示例3：多语言文档编写 ```typescript // 创建多个文档编写队友 spawn_teammate({ name: "doc-zh", prompt: "编写中文用户文档。内容包括：安装指南、快速入门、API参考、常见问题。" }) spawn_teammate({ name: "doc-en", prompt: "编写英文用户文档。内容与中文文档对应，保持同步更新。" }) spawn_teammate({ name: "doc-ja", prompt: "编写日文用户文档。内容与中文文档对应，保持同步更新。" }) // 等待完成 wait_for_teammates({ timeout_seconds: 900 }) // 分别合并每个队友的工作 merge_teammate_work({ name: "doc-zh", strategy: "manual" }) merge_teammate_work({ name: "doc-en", strategy: "manual" }) merge_teammate_work({ name: "doc-ja", strategy: "manual" }) cleanup_team({}) ``` ## 最佳实践 ### 1. 合理拆分任务 - 将大型任务拆分为独立的小任务 - 每个任务应该有明确的完成标准 - 避免任务之间产生循环依赖 ### 2. 清晰的角色定义 创建队友时，提供详细明确的提示词： ```typescript spawn_teammate({ name: "backend", prompt: `你是一个后端开发专家。 任务：实现用户认证系统 具体要求： 1. 使用 Express.js + Prisma + PostgreSQL 2. 实现注册、登录、登出接口 3. 使用 bcrypt 进行密码加密 4. 使用 JWT 进行身份验证 5. 添加输入验证和错误处理 6. 编写 API 文档 项目路径：/src/server 数据库配置：查看 .env 文件 完成后通知测试队友。` }) ``` ### 3. 善用依赖管理 对于有前后依赖的任务，明确设置依赖关系： ```typescript // 先创建前置任务 const task1 = create_task({ title: "设计数据库模型", assignee_name: "backend" }) // 后创建依赖任务 const task2 = create_task({ title: "实现API接口", assignee_name: "backend", dependencies: [task1.task_id] // 依赖 task1 }) ``` ### 4. 及时沟通协调 通过消息系统保持队友间同步： ```typescript // 后端完成API后通知前端 message_teammate({ target_id: "frontend", content: "API已部署到 http://localhost:3000/api，接口文档在 /docs/api.md" }) // 广播重要信息 broadcast_to_team({ content: "项目依赖有更新，请重新执行 npm install" }) ``` ### 5. 谨慎处理合并 合并前检查每个队友的工作： ```typescript // 先查看所有任务状态 list_tasks({}) // 逐个合并，手动解决冲突 merge_teammate_work({ name: "frontend", strategy: "manual" }) merge_teammate_work({ name: "backend", strategy: "manual" }) // 或者使用 auto 策略自动合并 merge_all_teammate_work({ strategy: "auto" }) ``` ### 6. 合理使用计划审批 对于复杂任务，启用计划审批确保方向正确： ```typescript spawn_teammate({ name: "architect", prompt: "设计系统整体架构...", require_plan_approval: true // 需要审批执行计划 }) ``` 队友会先提交执行计划，你需要审批后才能继续执行。 ## 常见问题 ### Q：Team模式和子代理有什么区别？ A：主要区别： | 特性 | 子代理 | Team模式 | |------|--------|----------| | 工作空间 | 独立上下文 | 独立 Git 工作树 | | 并行性 | 串行调用 | 真正并行 | | 持久性 | 临时 | 持久工作树 | | 协作 | 单向 | 双向通信 | | 合并 | 返回结果 | Git 合并 | ### Q：可以同时创建多少个队友？ A：理论上没有限制，但建议根据任务复杂度和机器性能控制在 3-5 个以内，以保证效率。 ### Q：队友之间可以共享代码吗？ A：队友在各自的工作树中独立工作，不能直接访问彼此的代码。需要通过合并到主分支后才能共享。 ### Q：如何查看队友的工作进度？ A：可以使用以下方式： 1. `list_teammates` 查看队友状态 2. `list_tasks` 查看任务进度 3. 通过 `message_teammate` 询问队友进度 ### Q：队友的工作出现冲突怎么办？ A：使用 `merge_teammate_work` 时选择 `manual` 策略，系统会进入合并状态，你可以手动解决冲突后提交。 ### Q：可以中途添加新队友吗？ A：可以，随时可以使用 `spawn_teammate` 创建新队友并分配任务。 ### Q：队友可以修改主分支吗？ A：不可以，队友只能在自己的工作树中工作，需要通过合并操作才能将更改应用到主分支。 ### Q：如何终止正在运行的队友？ A：使用 `shutdown_teammate` 命令关闭特定队友。注意：队友不能自行关闭。 ## 相关文档 - [子代理设置](./05.子代理设置.md) - 了解子代理的使用 - [异步任务管理](./15.异步任务管理.md) - 后台任务管理 - [Hooks配置](./07.Hooks配置.md) - Git 操作钩子配置 ================================================ FILE: docs/usage/zh/23.自定义搜索引擎指南.md ================================================ # Snow CLI 使用文档——自定义搜索引擎指南 ## 概述 Snow CLI 的联网搜索（`web-search` MCP 工具）使用可插拔的搜索引擎层。内置引擎包括 `duckduckgo` 和 `bing`，二者均通过无头浏览器抓取页面结果（不调用任何官方 API）。 如果你想使用其他搜索源，只需要把一个 JavaScript 文件放进用户目录，Snow CLI 启动后会自动注册它——无需构建、无需修改源代码。 适合这些场景： - 使用 Snow CLI 默认未提供的本地化搜索引擎 - 搜索公司内部知识库或内网 - 自定义现有引擎的抓取逻辑（例如页面改版后修复选择器） - 临时屏蔽某个内置引擎，又不想删文件 > 下文示例使用虚构的 `example-search.com` 仅用于演示引擎契约。你在为真实站点编写插件时，需自行确认目标站点的服务条款（ToS）与 `robots.txt` 政策，并自行承担合规责任。 ## 插件目录 Snow CLI 从以下目录加载搜索引擎插件： ```bash ~/.snow/plugin/search_engines/ ``` 支持的文件扩展名： - `.js` - `.mjs`（推荐，纯 ES Module 写法） - `.cjs` 说明： - 只支持从用户目录加载插件。 - Snow CLI 按文件名排序后，在首次执行联网搜索时加载所有插件。 - 新增或修改插件文件后，需要重启 Snow CLI（引擎注册表在进程生命周期内有缓存）。 - 内置引擎（`duckduckgo`、`bing`）总是先注册；插件引擎使用相同的 `id` 时会覆盖内置实现。 ## 支持的导出形式 一个插件模块可以使用以下任意一种导出形式（加载器会扫描所有形式）： ```js export default { ... } ``` ```js export const searchEngine = { ... } ``` ```js export const searchEngines = [{ ... }, { ... }] ``` 如果多个插件文件注册了相同的引擎 `id`，按文件名排序后加载的文件会覆盖先加载的。 ## 引擎结构 每个引擎都必须满足以下结构（使用 TypeScript 表达更直观，但插件文件本身是普通 JavaScript）： ```ts interface SearchEngine { id: string; // 稳定标识，例如 'my-engine' name: string; // 显示名，在选择器中展示 enable?: boolean; // 可选，默认 true search( page: Page, // Snow CLI 已为你打开的 Puppeteer Page query: string, // 用户的查询字符串 maxResults: number, // 最多返回多少条结果 ): Promise; } interface SearchResult { title: string; url: string; snippet: string; displayUrl: string; } ``` 字段说明： - `id`：用户在 `~/.snow/proxy-config.json` 中 `searchEngine` 字段填写的值，也是选择器记录的值。一旦发布给用户就请保持稳定。 - `name`：在代理配置界面的选择器中显示，自由格式。 - `enable`（可选）：默认 `true`。设为 `false` 可临时停用某个引擎而无需删除文件，停用后对 `getSearchEngine`、`listSearchEngines` 和 UI 选择器都不可见。 - 小技巧：在插件里写 `{id: 'bing', enable: false, search() {}}`，可以屏蔽内置 `bing` 引擎——加载器看到 `enable: false` 时会把注册表里同 `id` 的内置项删掉。 - `search(page, query, maxResults)`：实际工作函数。Snow CLI 会： - 帮你启动/连接浏览器（遵循 `~/.snow/proxy-config.json` 的代理设置） - 打开一个新的 `Page` 并传入 - 在 `search()` 返回后关闭这个 page 你的引擎应该： - 通过 `page.goto(...)` 跳转到自己的搜索 URL - 等待 DOM 渲染稳定 - 通过 `page.evaluate(...)` 提取最多 `maxResults` 条结果 - 返回 `SearchResult` 数组 千万**不要**自己调用 `browser.close()` / `page.close()`——page 由调用方拥有。 ## 生命周期与配置 1. 把插件文件放到 `~/.snow/plugin/search_engines/` 下。 2. 启动（或重启）Snow CLI。 3. 打开代理配置界面（`/settings` → 代理和浏览器设置，或你的版本中对应的入口）——你的引擎会按 `name` 出现在「搜索引擎」选择器中。 4. 选中你的引擎并保存。选择会持久化到 `~/.snow/proxy-config.json`： ```json { "enabled": false, "port": 7890, "searchEngine": "my-engine" } ``` 5. 后续所有 `web-search` MCP 调用都会使用你的引擎。 ## 示例：一个最小可用的插件模板 下面是一份完整可运行的模板，目标站点是虚构的 `example-search.com`。请把其中的 URL、选择器和 `id` 替换为你的真实目标站点对应的值。模板中的 CSS 选择器只是**占位符**——每家搜索页面的 DOM 结构都不同，必须自行打开页面用 DevTools 审查后填写。 ```js // ~/.snow/plugin/search_engines/my-engine.mjs const cleanText = text => (text || '') .replace(/\s+/g, ' ') .replace(/[\u200B-\u200D\uFEFF]/g, '') .trim(); export default { id: 'my-engine', name: 'My Search Engine', // 设为 false 可临时停用此引擎，无需删除文件； // 停用后对选择器和 getSearchEngine 都不可见。 enable: true, async search(page, query, maxResults) { // 1. 构造目标站点的搜索 URL。下面的 host 是虚构的，仅用于演示形态。 const encodedQuery = encodeURIComponent(query); const searchUrl = `https://example-search.com/search?q=${encodedQuery}` + `&n=${Math.max(maxResults, 10)}`; // 2. 跳转。优先使用 `domcontentloaded`，不要用 `networkidle2`—— // 真实的搜索页面会持续加载埋点脚本，networkidle2 通常超时。 try { await page.goto(searchUrl, { waitUntil: 'domcontentloaded', timeout: 30000, }); } catch { // 导航超时 —— 用已经渲染好的内容继续尝试提取 } // 3. 等待一个有代表性的结果容器选择器。绝对不要抛错， // 失败时直接返回空数组，让调用方走 fallback。 try { await page.waitForSelector('.results .result-item', {timeout: 10000}); } catch { // 尽力而为，提取阶段可能仍能找到结果 } // 4. 在浏览器上下文中提取。 const raw = await page.evaluate(maxLimit => { const out = []; const items = document.querySelectorAll('.results .result-item'); const isHttpUrl = u => /^https?:\/\//i.test(u); for (const item of items) { if (out.length >= maxLimit) break; // 如果站点对广告做了标记，这里过滤掉。 if (item.classList.contains('is-ad')) continue; const linkEl = item.querySelector('a.result-title'); if (!linkEl) continue; const href = linkEl.getAttribute('href') || ''; if (!isHttpUrl(href)) continue; const title = (linkEl.textContent || '').trim(); if (!title) continue; const snippetEl = item.querySelector('.result-snippet'); const snippet = snippetEl ? (snippetEl.textContent || '').trim() : ''; const citeEl = item.querySelector('cite, .result-host'); const displayUrl = citeEl ? (citeEl.textContent || '').trim() : ''; out.push({title, url: href, snippet, displayUrl}); } return out; }, maxResults); // 5. 文本规范化后返回。 return raw.map(r => ({ title: cleanText(r.title), url: r.url || '', snippet: cleanText(r.snippet), displayUrl: cleanText(r.displayUrl), })); }, }; ``` 要把这份模板适配到真实站点，你需要为目标站点确认以下信息： - 搜索 URL 的参数命名（常见有 `?q=` / `?wd=` / `?query=`，以及表示结果数量的参数）； - 一个稳定的有机结果容器选择器； - 容器内的标题/链接选择器； - 摘要选择器； - 显示 URL / 主机名选择器； - 站点对广告 / 推广位的标记方式，以便跳过。 打开目标站点的结果页面，用浏览器 DevTools 审查 DOM，然后把上面的选择器替换进模板即可。 ## 编写自己的引擎：检查清单 1. **`id` 要稳定**。一旦用户把它保存到 `proxy-config.json`，改名就会破坏配置。 2. **`page.goto` 用 `domcontentloaded`，不要用 `networkidle2`**。大多数搜索页会一直加载埋点脚本，`networkidle2` 通常会超时，结果还没出来就失败。 3. **`page.goto` 用 `try/catch` 包起来**。导航超时是可恢复的——DOM 可能已经渲染了足够的内容。 4. **`page.waitForSelector` 必须带超时，绝不抛错**。失败时返回空列表，让调用方走 fallback。 5. **提取逻辑放在 `page.evaluate` 内**。回调运行在浏览器里，可以使用完整 DOM API，但只能 `return` 可结构化克隆的纯对象。 6. **过滤广告 / 推广位**。每家搜索引擎标记方式不同——自己查 DOM。 7. **规范化文本**（参考上面的 `cleanText`）——合并空白、去除零宽字符。 8. **绝对不要调用 `browser.close()` 或 `page.close()`**。Page 由 `WebSearchService` 拥有。 9. **不要在 `page.evaluate` 回调里 import Node 专属模块**——它运行在浏览器里。 ## 一个文件注册多个引擎 可以从同一个文件中注册多个引擎： ```js export const searchEngines = [ {id: 'engine-a', name: 'Engine A', async search(...) { /* ... */ }}, {id: 'engine-b', name: 'Engine B', async search(...) { /* ... */ }}, ]; ``` 适合多个引擎共享 `cleanText` 工具函数或公共提取逻辑的场景。 ## 故障排查 - **插件没有出现在选择器里。** - 确认扩展名是 `.js` / `.mjs` / `.cjs`。 - 检查 Snow CLI 启动日志中是否有 `[websearch] failed to load search engine plugin "..."`，语法错误会被记录。 - 确认导出的是包含 `{id, name, search}` 的纯对象——校验失败时加载器会输出 `did not export a valid SearchEngine`。 - **搜索总是返回 0 条结果。** - 大概率是页面 DOM 改版。手动用浏览器打开页面，重新审查选择器。 - 适当增大 `page.waitForSelector` 的超时时间。 - 部分引擎会把机器人流量重定向到验证码页面——可以在 `search()` 开始时通过 `page.setUserAgent(...)` 设置一个真实的 User-Agent（`WebSearchService` 在调用前已经设置过一个，你可以覆盖）。 - **我想停用某个内置引擎。** - 写一个插件文件 `{id: 'bing', name: 'Bing', enable: false, async search() { return []; }}`。加载器看到 `enable: false` 时会把同 `id` 的项从注册表中删除。 ## 相关文档 - [代理和浏览器设置](./03.代理和浏览器设置.md) - [自定义 StatusLine 指南](./21.自定义StatusLine指南.md)——状态栏部分使用了相同的插件加载理念 ================================================ FILE: package.json ================================================ { "name": "snow-ai", "version": "0.7.26", "description": "Agentic coding in your terminal", "license": "MIT", "bin": { "snow": "bundle/cli.mjs" }, "type": "module", "keywords": [ "cli", "ai", "assistant", "bot", "terminal", "ai coding", "agentic", "snow", "snow cli" ], "author": "Mufasa", "repository": { "type": "git", "url": "https://github.com/MayDay-wpf/snow-cli.git" }, "bugs": { "url": "https://github.com/MayDay-wpf/snow-cli/issues" }, "homepage": "https://github.com/MayDay-wpf/snow-cli#readme", "engines": { "node": ">=22", "npm": ">=8.3.0" }, "scripts": { "build": "node scripts/clean-build.cjs && tsc && node build.mjs", "build:ts": "tsc", "build:bundle": "node build.mjs", "dev": "tsc --watch", "start": "node bundle/cli.mjs", "start:dev": "node build.mjs && node bundle/cli.mjs", "link": "npm run build && npm link", "unlink": "npm unlink -g snow-ai", "prepublishOnly": "npm run build", "postinstall": "node scripts/postinstall.cjs", "test": "prettier --check . && xo && ava", "lint": "xo", "format": "prettier --write ." }, "files": [ "bundle", "scripts" ], "dependencies": { "@microsoft/signalr": "^10.0.0", "abort-controller": "^3.0.0", "eventsource": "^2.0.2", "fetch-cookie": "^3.0.1", "node-fetch": "^2.7.0", "ssh2": "^1.17.0", "tough-cookie": "^6.0.0", "ws": "^8.14.2" }, "devDependencies": { "@agentclientprotocol/sdk": "^0.14.1", "@alcalzone/ansi-tokenize": "^0.3.0", "@inkjs/ui": "^2.0.0", "@modelcontextprotocol/sdk": "^1.17.3", "@sindresorhus/tsconfig": "^3.0.1", "@types/diff": "^7.0.2", "@types/fs-extra": "^11.0.4", "@types/marked-terminal": "^6.1.1", "@types/pdf-parse": "^1.1.5", "@types/prettier": "^2.7.3", "@types/react": "^18.3.0", "@types/sharp": "^0.32.0", "@types/sql.js": "^1.4.9", "@types/ssh2": "^1.15.5", "@types/ws": "^8.5.8", "@vdemedes/prettier-config": "^2.0.1", "@vercel/ncc": "^0.38.4", "ansi-escapes": "^7.3.0", "ansi-styles": "^6.2.3", "auto-bind": "^5.0.1", "ava": "^5.2.0", "chalk": "^5.2.0", "chardet": "^2.1.1", "chokidar": "^4.0.3", "cli-boxes": "^4.0.1", "cli-cursor": "^5.0.0", "cli-highlight": "^2.1.11", "diff": "^8.0.2", "es-toolkit": "^1.46.0", "esbuild": "^0.27.0", "esbuild-plugin-copy": "^2.1.1", "eslint-config-xo-react": "^0.27.0", "eslint-plugin-react": "^7.32.2", "eslint-plugin-react-hooks": "^4.6.0", "fzf": "^0.5.2", "gray-matter": "^4.0.3", "http-proxy-agent": "^7.0.2", "https-proxy-agent": "^7.0.6", "iconv-lite": "^0.7.2", "ignore": "^7.0.5", "ink-gradient": "^4.0.0", "ink-select-input": "^6.2.0", "ink-spinner": "^5.0.0", "ink-testing-library": "^4.0.0", "ink-text-input": "^6.0.0", "is-in-ci": "^2.0.0", "katex": "^0.16.27", "mammoth": "^1.11.0", "marked": "^15.0.6", "marked-terminal": "^7.3.0", "meow": "^11.0.0", "patch-console": "^2.0.0", "pdf-parse": "^2.4.5", "pptx-parser": "^1.1.7-beta.9", "prettier": "^2.8.7", "puppeteer-core": "^24.25.0", "react": "^18.3.1", "react-reconciler": "^0.29.2", "signal-exit": "^4.1.0", "slice-ansi": "^9.0.0", "sql.js": "^1.13.0", "stack-utils": "^2.0.6", "string-width": "^7.2.0", "tiktoken": "^1.0.22", "ts-node": "^10.9.1", "type-fest": "^5.6.0", "typescript": "^5.0.3", "undici": "^7.16.0", "vscode-jsonrpc": "8.2.1", "vscode-languageserver-protocol": "^3.17.5", "widest-line": "^6.0.0", "wrap-ansi": "^10.0.0", "xlsx": "^0.18.5", "xo": "^0.53.1" }, "overrides": { "glob": "^10.0.0", "rimraf": "^5.0.0", "tough-cookie": "^6.0.0" }, "ava": { "extensions": { "ts": "module", "tsx": "module" }, "nodeArguments": [ "--loader=ts-node/esm" ] }, "xo": { "extends": "xo-react", "prettier": true, "rules": { "react/prop-types": "off", "react-hooks/rules-of-hooks": "error", "react-hooks/exhaustive-deps": "warn" } }, "prettier": "@vdemedes/prettier-config", "optionalDependencies": { "sharp": "^0.34.5" } } ================================================ FILE: scripts/clean-build.cjs ================================================ /* eslint-disable unicorn/prefer-module */ /** * 清理构建产物目录，避免 tsc 残留旧输出导致 bundle 与 source 不一致。 * * 说明： * - tsc 默认不会删除已不存在源文件对应的 dist 输出文件 * - build.mjs 依赖 dist/ 作为入口进行打包 * - 因此在 build 前清理 dist/ 与 bundle/ 可显著降低“幽灵文件”带来的回归风险 */ const fs = require('fs'); for (const dir of ['dist', 'bundle']) { try { fs.rmSync(dir, {recursive: true, force: true}); } catch { // 清理失败不应阻断构建流程 } } ================================================ FILE: scripts/postinstall.cjs ================================================ #!/usr/bin/env node /** * Post-install script to provide installation optimization tips for users */ const https = require('https'); const { execSync } = require('child_process'); // ANSI color codes const colors = { reset: '\x1b[0m', bright: '\x1b[1m', cyan: '\x1b[36m', yellow: '\x1b[33m', green: '\x1b[32m', }; /** * Detect if user is in China based on IP geolocation */ function detectRegion() { return new Promise((resolve) => { const timeout = setTimeout(() => resolve('unknown'), 3000); https.get('https://ipapi.co/json/', (res) => { let data = ''; res.on('data', (chunk) => data += chunk); res.on('end', () => { clearTimeout(timeout); try { const info = JSON.parse(data); resolve(info.country_code === 'CN' ? 'china' : 'other'); } catch { resolve('unknown'); } }); }).on('error', () => { clearTimeout(timeout); resolve('unknown'); }); }); } /** * Check current npm registry */ function getCurrentRegistry() { try { const registry = execSync('npm config get registry', { encoding: 'utf8' }).trim(); return registry; } catch { return 'https://registry.npmjs.org'; } } /** * Check Node.js version compatibility */ function checkNodeVersion() { const currentVersion = process.version; const major = parseInt(currentVersion.slice(1).split('.')[0], 10); const minVersion = 16; if (major < minVersion) { console.error(`\n${colors.bright}${colors.yellow}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}`); console.error(`${colors.bright}${colors.yellow} ⚠️ Node.js Version Compatibility Error${colors.reset}`); console.error(`${colors.bright}${colors.yellow}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}\n`); console.error(`${colors.yellow}Current Node.js version: ${currentVersion}${colors.reset}`); console.error(`${colors.yellow}Required: Node.js >= ${minVersion}.x${colors.reset}\n`); console.error(`${colors.green}Please upgrade Node.js to continue:${colors.reset}\n`); console.error(`${colors.cyan}# Using nvm (recommended):${colors.reset}`); console.error(` nvm install ${minVersion}`); console.error(` nvm use ${minVersion}\n`); console.error(`${colors.cyan}# Or download from official website:${colors.reset}`); console.error(` https://nodejs.org/\n`); console.error(`${colors.yellow}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}\n`); process.exit(1); } } /** * Try to install sharp as optional dependency */ function tryInstallSharp() { try { // Check if sharp is already installed require.resolve('sharp'); console.log(`${colors.green}✓ sharp is already installed${colors.reset}`); return true; } catch { console.log(`${colors.yellow}Installing optional dependency: sharp (for SVG to PNG conversion)${colors.reset}`); try { execSync('npm install --no-save --prefer-offline sharp', { stdio: 'inherit', cwd: process.cwd() }); console.log(`${colors.green}✓ sharp installed successfully${colors.reset}`); return true; } catch (error) { console.log(`${colors.yellow}⚠ sharp installation failed (this is OK - SVG will be returned as-is)${colors.reset}`); console.log(`${colors.cyan} Reason: sharp requires native binaries that may not be compatible with your system${colors.reset}`); return false; } } } /** * Main function */ async function main() { // Check Node.js version first checkNodeVersion(); // Skip if running in CI environment if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) { return; } // Try to install sharp (optional dependency) tryInstallSharp(); const currentRegistry = getCurrentRegistry(); const isUsingMirror = currentRegistry.includes('npmmirror.com') || currentRegistry.includes('taobao.org'); // If already using a mirror, skip the tips if (isUsingMirror) { return; } console.log(`\n${colors.cyan}${colors.bright}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}`); console.log(`${colors.cyan}${colors.bright} Snow AI - Installation Optimization Tips${colors.reset}`); console.log(`${colors.cyan}${colors.bright}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}\n`); const region = await detectRegion(); if (region === 'china') { console.log(`${colors.yellow}检测到您在中国大陆地区,建议配置 npm 镜像源以加速安装:${colors.reset}\n`); console.log(`${colors.green}# 方案 1: 使用淘宝镜像 (推荐)${colors.reset}`); console.log(` npm config set registry https://registry.npmmirror.com\n`); console.log(`${colors.green}# 方案 2: 临时使用镜像安装${colors.reset}`); console.log(` npm install -g snow-ai --registry=https://registry.npmmirror.com\n`); console.log(`${colors.green}# 恢复官方源${colors.reset}`); console.log(` npm config set registry https://registry.npmjs.org\n`); } else { console.log(`${colors.yellow}To speed up npm installation, you can:${colors.reset}\n`); console.log(`${colors.green}# Enable parallel downloads${colors.reset}`); console.log(` npm config set maxsockets 10\n`); console.log(`${colors.green}# Use offline cache when possible${colors.reset}`); console.log(` npm config set prefer-offline true\n`); console.log(`${colors.green}# Skip unnecessary checks${colors.reset}`); console.log(` npm config set audit false\n`); console.log(` npm config set fund false\n`); } console.log(`${colors.cyan}Current registry: ${currentRegistry}${colors.reset}`); console.log(`${colors.cyan}${colors.bright}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}\n`); } main().catch(() => { // Silently fail - don't break installation }); ================================================ FILE: source/agents/bashOutputSummaryAgent.ts ================================================ import {getSnowConfig} from '../utils/config/apiConfig.js'; import {logger} from '../utils/core/logger.js'; import {createStreamingChatCompletion, type ChatMessage} from '../api/chat.js'; import {createStreamingResponse} from '../api/responses.js'; import {createStreamingGeminiCompletion} from '../api/gemini.js'; import {createStreamingAnthropicCompletion} from '../api/anthropic.js'; import type {RequestMethod} from '../utils/config/apiConfig.js'; import type {CommandExecutionResult} from '../mcp/types/bash.types.js'; /** * Bash output summarization agent. * Uses basicModel and follows the same request routing as the main flow. */ export class BashOutputSummaryAgent { private modelName: string = ''; private requestMethod: RequestMethod = 'chat'; private initialized: boolean = false; private async initialize(): Promise { try { const config = getSnowConfig(); if (!config.basicModel) { return false; } this.modelName = config.basicModel; this.requestMethod = config.requestMethod; this.initialized = true; return true; } catch (error) { logger.warn('Bash output summary agent: initialize failed', error); return false; } } clearCache(): void { this.initialized = false; this.modelName = ''; this.requestMethod = 'chat'; } async isAvailable(): Promise { if (!this.initialized) { return this.initialize(); } return true; } private async callModel( messages: ChatMessage[], abortSignal?: AbortSignal, ): Promise { let streamGenerator: AsyncGenerator; switch (this.requestMethod) { case 'anthropic': streamGenerator = createStreamingAnthropicCompletion( { model: this.modelName, messages, max_tokens: 1200, includeBuiltinSystemPrompt: false, disableThinking: true, }, abortSignal, ); break; case 'gemini': streamGenerator = createStreamingGeminiCompletion( { model: this.modelName, messages, includeBuiltinSystemPrompt: false, disableThinking: true, }, abortSignal, ); break; case 'responses': streamGenerator = createStreamingResponse( { model: this.modelName, messages, stream: true, includeBuiltinSystemPrompt: false, disableThinking: true, }, abortSignal, ); break; case 'chat': default: streamGenerator = createStreamingChatCompletion( { model: this.modelName, messages, stream: true, includeBuiltinSystemPrompt: false, disableThinking: true, }, abortSignal, ); break; } let content = ''; for await (const chunk of streamGenerator) { if (abortSignal?.aborted) { throw new Error('Request aborted'); } if (this.requestMethod === 'chat') { if (chunk.choices && chunk.choices[0]?.delta?.content) { content += chunk.choices[0].delta.content; } } else if (chunk.type === 'content' && chunk.content) { content += chunk.content; } } return content.trim(); } async summarizeCommandResult( commandResult: CommandExecutionResult, abortSignal?: AbortSignal, ): Promise { const available = await this.isAvailable(); if (!available) { return commandResult; } try { const prompt = `You are a terminal output compression assistant. Your goal is to compress noisy command output into useful, actionable information for another AI agent. Requirements: 1) Keep factual correctness. Do not invent outputs. 2) Error-first policy: always report errors before warnings, even if warning volume is much higher. 3) If any errors exist, list all unique errors with exact lines/snippets and likely impact first. 4) Prioritize actionable next steps, key artifacts/paths, and final status after errors/warnings. 5) Remove repetitive logs, progress bars, and low-value noise. 6) Keep language concise and structured. 7) Preserve important command snippets and exact error lines when needed. 8) Output plain text only. Command: ${commandResult.command} Exit code: ${commandResult.exitCode} Executed at: ${commandResult.executedAt} STDOUT: ${commandResult.stdout || '(empty)'} STDERR: ${commandResult.stderr || '(empty)'} Now produce the compressed terminal result:`; const messages: ChatMessage[] = [{role: 'user', content: prompt}]; const summary = await this.callModel(messages, abortSignal); if (!summary) { return commandResult; } return { ...commandResult, stdout: summary, stderr: '', }; } catch (error) { logger.warn( 'Bash output summary agent: summarize failed, fallback to original output', error, ); return commandResult; } } } export const bashOutputSummaryAgent = new BashOutputSummaryAgent(); ================================================ FILE: source/agents/codebaseIndexAgent.ts ================================================ import path from 'node:path'; import fs from 'node:fs'; import crypto from 'node:crypto'; import ignore, {type Ignore} from 'ignore'; import chokidar from 'chokidar'; import {logger} from '../utils/core/logger.js'; import { CodebaseDatabase, type CodeChunk, } from '../utils/codebase/codebaseDatabase.js'; import {createEmbeddings} from '../api/embedding.js'; import { loadCodebaseConfig, type CodebaseConfig, } from '../utils/config/codebaseConfig.js'; import {withRetry} from '../utils/core/retryUtils.js'; import {readOfficeDocument} from '../mcp/utils/filesystem/office-parser.utils.js'; /** * Progress callback for UI updates */ export type ProgressCallback = (progress: { totalFiles: number; processedFiles: number; totalChunks: number; currentFile: string; status: 'scanning' | 'indexing' | 'completed' | 'error'; error?: string; }) => void; /** * Codebase Index Agent * Handles automatic code scanning, chunking, and embedding */ export class CodebaseIndexAgent { private db: CodebaseDatabase; private config: CodebaseConfig; private projectRoot: string; private ignoreFilter: Ignore; private isRunning: boolean = false; private shouldStop: boolean = false; private progressCallback?: ProgressCallback; private consecutiveFailures: number = 0; private readonly MAX_CONSECUTIVE_FAILURES = 3; private fileWatcher: any | null = null; private watcherClosePromise: Promise | null = null; private watchDebounceTimers: Map = new Map(); // Supported code file extensions private static readonly CODE_EXTENSIONS = new Set([ '.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.cpp', '.c', '.h', '.hpp', '.cs', '.go', '.rs', '.rb', '.php', '.swift', '.kt', '.scala', '.m', '.md', '.mm', '.sh', '.bash', '.sql', '.txt', '.graphql', '.proto', '.json', '.yaml', '.yml', '.toml', '.xml', '.html', '.css', '.scss', '.less', '.vue', '.svelte', ]); // Supported office/document file extensions private static readonly OFFICE_EXTENSIONS = new Set([ '.pdf', '.docx', '.doc', '.xlsx', '.xls', '.pptx', '.ppt', ]); constructor(projectRoot: string) { this.projectRoot = projectRoot; this.config = loadCodebaseConfig(); this.db = new CodebaseDatabase(projectRoot); this.ignoreFilter = ignore(); // Load .gitignore if exists this.loadGitignore(); // Add default ignore patterns this.addDefaultIgnorePatterns(); } /** * Start indexing process */ async start(progressCallback?: ProgressCallback): Promise { if (this.isRunning) { logger.warn('Indexing already in progress'); return; } // Reload config to check if it was changed this.config = loadCodebaseConfig(); if (!this.config.enabled) { logger.info('Codebase indexing is disabled'); return; } // Check if .gitignore exists const gitignorePath = path.join(this.projectRoot, '.gitignore'); if (!fs.existsSync(gitignorePath)) { // Import translations dynamically to get localized error message const {getCurrentLanguage} = await import( '../utils/config/languageConfig.js' ); const {translations} = await import('../i18n/index.js'); const currentLanguage = getCurrentLanguage(); const t = translations[currentLanguage]; const errorMessage = t.codebaseConfig.gitignoreNotFound; logger.error(errorMessage); if (progressCallback) { progressCallback({ totalFiles: 0, processedFiles: 0, totalChunks: 0, currentFile: '', status: 'error', error: errorMessage, }); } return; } this.isRunning = true; this.shouldStop = false; this.progressCallback = progressCallback; try { // Initialize database await this.db.initialize(); // Check if stopped before starting if (this.shouldStop) { logger.info('Indexing cancelled before start'); return; } // Check if we should resume or start fresh const progress = this.db.getProgress(); const isResuming = progress.status === 'indexing'; if (isResuming) { logger.info('Resuming previous indexing session'); } // Scan files first this.notifyProgress({ totalFiles: 0, processedFiles: 0, totalChunks: 0, currentFile: '', status: 'scanning', }); const files = await this.scanFiles(); logger.info(`Found ${files.length} code files to index`); // Reset progress if file count changed (project structure changed) // or if previous session was interrupted abnormally const shouldReset = isResuming && (progress.totalFiles !== files.length || progress.processedFiles > files.length); if (shouldReset) { logger.info( 'File count changed or progress corrupted, resetting progress', ); this.db.updateProgress({ totalFiles: files.length, processedFiles: 0, totalChunks: this.db.getTotalChunks(), status: 'indexing', startedAt: Date.now(), lastProcessedFile: undefined, }); } else { // Update status to indexing this.db.updateProgress({ status: 'indexing', totalFiles: files.length, startedAt: isResuming ? progress.startedAt : Date.now(), }); } // Check if stopped after initialization if (this.shouldStop) { logger.info('Indexing cancelled after initialization'); return; } // Process files with concurrency control await this.processFiles(files); // Only mark as completed if not stopped by user if (!this.shouldStop) { // Mark as completed this.db.updateProgress({ status: 'completed', completedAt: Date.now(), }); this.notifyProgress({ totalFiles: files.length, processedFiles: files.length, totalChunks: this.db.getTotalChunks(), currentFile: '', status: 'completed', }); logger.info('Indexing completed successfully'); } else { logger.info('Indexing paused by user, progress saved'); } } catch (error) { const errorMessage = this.extractDetailedError(error); this.db.updateProgress({ status: 'error', lastError: errorMessage, }); this.notifyProgress({ totalFiles: 0, processedFiles: 0, totalChunks: 0, currentFile: '', status: 'error', error: errorMessage, }); logger.error('Indexing failed', error); throw error; } finally { this.isRunning = false; this.shouldStop = false; // Don't change status to 'idle' if indexing was stopped // This allows resuming when returning to chat screen // Status will remain as 'indexing' so it can be resumed } } /** * Stop indexing gracefully */ async stop(): Promise { if (!this.isRunning) { return; } logger.info('Stopping indexing...'); this.shouldStop = true; // Also stop file watcher to ensure everything is stopped this.stopWatching(); // Wait for current operation to finish while (this.isRunning) { await new Promise(resolve => setTimeout(resolve, 100)); } } /** * Check if indexing is in progress */ isIndexing(): boolean { return this.isRunning; } /** * Get current progress */ async getProgress() { // Initialize database if not already done if (!this.db) { this.db = new CodebaseDatabase(this.projectRoot); } await this.db.initialize(); return this.db.getProgress(); } /** * Clear all indexed data */ clear(): void { this.db.clear(); } /** * Close database connection */ close(): void { this.stopWatching(); this.db.close(); } /** * Check if watcher is enabled in database */ async isWatcherEnabled(): Promise { try { await this.db.initialize(); return this.db.isWatcherEnabled(); } catch (error) { return false; } } /** * Start watching for file changes */ startWatching(progressCallback?: ProgressCallback): void { if (this.fileWatcher) { logger.debug('File watcher already running'); return; } // Reload config to check if it was changed this.config = loadCodebaseConfig(); if (!this.config.enabled) { logger.info('Codebase indexing is disabled, not starting watcher'); return; } // Save progress callback for file change notifications if (progressCallback) { this.progressCallback = progressCallback; } try { // Use chokidar for better cross-platform performance and reliability // Reuse existing ignoreFilter to keep consistency with scanFiles this.fileWatcher = chokidar.watch(this.projectRoot, { ignored: (filePath: string) => { const relativePath = path.relative(this.projectRoot, filePath); // Skip empty paths (the root directory itself) and check ignore filter if (!relativePath || relativePath === '.') { return false; } return this.ignoreFilter.ignores(relativePath); }, ignoreInitial: true, // Don't trigger events for initial scan persistent: true, }); // Handle file added or changed this.fileWatcher.on('add', (filePath: string) => { const ext = path.extname(filePath).toLowerCase(); if ( !CodebaseIndexAgent.CODE_EXTENSIONS.has(ext) && !CodebaseIndexAgent.OFFICE_EXTENSIONS.has(ext) ) { return; } const relativePath = path.relative(this.projectRoot, filePath); logger.debug(`File created, indexing: ${relativePath}`); this.debounceFileChange(filePath, relativePath); }); this.fileWatcher.on('change', (filePath: string) => { const ext = path.extname(filePath).toLowerCase(); if ( !CodebaseIndexAgent.CODE_EXTENSIONS.has(ext) && !CodebaseIndexAgent.OFFICE_EXTENSIONS.has(ext) ) { return; } const relativePath = path.relative(this.projectRoot, filePath); logger.debug(`File modified, reindexing: ${relativePath}`); this.debounceFileChange(filePath, relativePath); }); // Handle file deleted this.fileWatcher.on('unlink', (filePath: string) => { const ext = path.extname(filePath).toLowerCase(); if ( !CodebaseIndexAgent.CODE_EXTENSIONS.has(ext) && !CodebaseIndexAgent.OFFICE_EXTENSIONS.has(ext) ) { return; } const relativePath = path.relative(this.projectRoot, filePath); logger.debug(`File deleted, removing from index: ${relativePath}`); this.db.deleteChunksByFile(relativePath); }); // Handle watcher errors this.fileWatcher.on('error', (error: Error) => { // Ignore ELOOP errors (circular symlinks) - common in some project structures if ((error as NodeJS.ErrnoException).code === 'ELOOP') { logger.debug('Skipping circular symlink during file watching'); return; } // Log other errors but don't crash the watcher logger.warn('File watcher error', error); }); // Persist watcher state to database this.db.setWatcherEnabled(true); logger.info('File watcher started successfully'); } catch (error) { logger.error('Failed to start file watcher', error); } } /** * Stop watching for file changes */ stopWatching(): void { if (this.fileWatcher) { this.watcherClosePromise = this.fileWatcher.close(); this.fileWatcher = null; // Persist watcher state to database this.db.setWatcherEnabled(false); logger.info('File watcher stopped'); } // Clear all pending debounce timers for (const timer of this.watchDebounceTimers.values()) { clearTimeout(timer); } this.watchDebounceTimers.clear(); } /** * Wait for the chokidar file watcher to fully close its libuv handles. * Must be awaited before process.exit() on Windows to avoid * UV_HANDLE_CLOSING assertion failure. */ async waitForWatcherClose(): Promise { if (this.watcherClosePromise) { await this.watcherClosePromise; this.watcherClosePromise = null; } } /** * Debounce file changes to avoid multiple rapid updates */ private debounceFileChange(filePath: string, relativePath: string): void { // Clear existing timer for this file const existingTimer = this.watchDebounceTimers.get(relativePath); if (existingTimer) { clearTimeout(existingTimer); } // Set new timer const timer = setTimeout(() => { this.watchDebounceTimers.delete(relativePath); this.handleFileChange(filePath, relativePath); }, 5000); // 5 second debounce - optimized for AI code editing this.watchDebounceTimers.set(relativePath, timer); } /** * Handle file change event */ private async handleFileChange( filePath: string, relativePath: string, ): Promise { try { // Notify UI that file is being reindexed this.notifyProgress({ totalFiles: 0, processedFiles: 0, totalChunks: this.db.getTotalChunks(), currentFile: relativePath, status: 'indexing', }); await this.processFile(filePath); // Notify UI that reindexing is complete this.notifyProgress({ totalFiles: 0, processedFiles: 0, totalChunks: this.db.getTotalChunks(), currentFile: '', status: 'completed', }); } catch (error) { logger.error(`Failed to reindex file: ${relativePath}`, error); } } /** * Load .gitignore file */ private loadGitignore(): void { const gitignorePath = path.join(this.projectRoot, '.gitignore'); if (fs.existsSync(gitignorePath)) { const content = fs.readFileSync(gitignorePath, 'utf-8'); this.ignoreFilter.add(content); } } /** * Add default ignore patterns */ private addDefaultIgnorePatterns(): void { this.ignoreFilter.add([ 'node_modules', '.git', '.snow', 'dist', 'build', 'out', 'coverage', '.next', '.nuxt', '.cache', '*.min.js', '*.min.css', '*.map', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', ]); } /** * Scan project directory for code files */ public async scanFiles(): Promise { const files: string[] = []; const scanDir = (dir: string) => { let entries: fs.Dirent[]; try { entries = fs.readdirSync(dir, {withFileTypes: true}); } catch (error: any) { // 处理权限不足等错误，跳过该目录而不是崩溃 if (error.code === 'EPERM' || error.code === 'EACCES') { logger.warn(`跳过无权限访问的目录: ${dir}`); return; } // 其他错误也记录但不中断扫描 logger.warn(`扫描目录失败 (${error.code || 'unknown'}): ${dir}`); return; } for (const entry of entries) { if (this.shouldStop) break; const fullPath = path.join(dir, entry.name); const relativePath = path.relative(this.projectRoot, fullPath); // Check if should be ignored // Skip empty paths (should not happen, but defensive check) if ( relativePath && relativePath !== '.' && this.ignoreFilter.ignores(relativePath) ) { continue; } if (entry.isDirectory()) { scanDir(fullPath); } else if (entry.isFile()) { const ext = path.extname(entry.name); if ( CodebaseIndexAgent.CODE_EXTENSIONS.has(ext) || CodebaseIndexAgent.OFFICE_EXTENSIONS.has(ext) ) { files.push(fullPath); } } } }; scanDir(this.projectRoot); return files; } /** * Count scannable files */ public async countFiles(): Promise { const files = await this.scanFiles(); return files.length; } /** * Process files with concurrency control */ private async processFiles(files: string[]): Promise { const concurrency = this.config.batch.concurrency; // Process files in batches for (let i = 0; i < files.length; i += concurrency) { if (this.shouldStop) { logger.info('Indexing stopped by user'); break; } const batch = files.slice(i, i + concurrency); const promises = batch.map(file => this.processFile(file)); await Promise.allSettled(promises); // Update processed count accurately (current batch end index) const processedCount = Math.min(i + batch.length, files.length); this.db.updateProgress({ processedFiles: processedCount, }); } } /** * Process single file */ private async processFile(filePath: string): Promise { try { const relativePath = path.relative(this.projectRoot, filePath); this.notifyProgress({ totalFiles: this.db.getProgress().totalFiles, processedFiles: this.db.getProgress().processedFiles, totalChunks: this.db.getTotalChunks(), currentFile: relativePath, status: 'indexing', }); const ext = path.extname(filePath).toLowerCase(); const isOfficeFile = CodebaseIndexAgent.OFFICE_EXTENSIONS.has(ext); let content: string; let fileHash: string; if (isOfficeFile) { // Parse Office document to extract text const docContent = await readOfficeDocument(filePath); if (!docContent) { logger.warn(`Failed to parse Office document: ${relativePath}`); return; } content = docContent.text; // Calculate hash based on extracted content (not binary file) fileHash = crypto.createHash('sha256').update(content).digest('hex'); } else { // Read regular text file content = fs.readFileSync(filePath, 'utf-8'); fileHash = crypto.createHash('sha256').update(content).digest('hex'); } // Check if file has been indexed and unchanged if (this.db.hasFileHash(fileHash)) { logger.debug(`File unchanged, skipping: ${relativePath}`); return; } // Delete old chunks for this file this.db.deleteChunksByFile(relativePath); // Split content into chunks using appropriate method const chunks = isOfficeFile ? this.splitDocumentIntoChunks(content, relativePath) : this.splitIntoChunks(content, relativePath); if (chunks.length === 0) { logger.debug(`No chunks generated for: ${relativePath}`); return; } // Generate embeddings in batches const maxLines = this.config.batch.maxLines; const embeddingBatches: CodeChunk[][] = []; for (let i = 0; i < chunks.length; i += maxLines) { const batch = chunks.slice(i, i + maxLines); embeddingBatches.push(batch); } for (const batch of embeddingBatches) { if (this.shouldStop) break; try { // Check if codebase feature was disabled this.config = loadCodebaseConfig(); if (!this.config.enabled) { logger.info('Codebase feature disabled, stopping indexing'); this.shouldStop = true; break; } // Extract text content for embedding const texts = batch.map(chunk => chunk.content); // Check again before making API call if (this.shouldStop) break; // Call embedding API with retry const response = await withRetry( async () => { // Check if stopped during retry if (this.shouldStop) { throw new Error('Indexing stopped by user'); } return await createEmbeddings({ input: texts, }); }, { maxRetries: 3, baseDelay: 2000, onRetry: (error, attempt, nextDelay) => { logger.warn( `Embedding API failed for ${relativePath} (attempt ${attempt}/3), retrying in ${nextDelay}ms...`, error.message, ); }, }, ); // Attach embeddings to chunks for (let i = 0; i < batch.length; i++) { batch[i]!.embedding = response.data[i]!.embedding; batch[i]!.fileHash = fileHash; batch[i]!.createdAt = Date.now(); batch[i]!.updatedAt = Date.now(); } // Store chunks to database with retry await withRetry( async () => { this.db.insertChunks(batch); }, { maxRetries: 2, baseDelay: 500, }, ); // Update total chunks count this.db.updateProgress({ totalChunks: this.db.getTotalChunks(), lastProcessedFile: relativePath, }); // Reset failure counter on success this.consecutiveFailures = 0; } catch (error) { this.consecutiveFailures++; const detailedError = this.extractDetailedError(error); logger.error( `Failed to process batch for ${relativePath} (consecutive failures: ${this.consecutiveFailures}):`, detailedError, ); // Stop indexing if too many consecutive failures if (this.consecutiveFailures >= this.MAX_CONSECUTIVE_FAILURES) { logger.error( `Stopping indexing after ${this.MAX_CONSECUTIVE_FAILURES} consecutive failures`, ); this.db.updateProgress({ status: 'error', lastError: `Too many failures: ${detailedError}`, }); throw new Error( `Indexing stopped after ${this.MAX_CONSECUTIVE_FAILURES} consecutive failures`, ); } // Skip this batch and continue continue; } } logger.debug(`Indexed ${chunks.length} chunks from: ${relativePath}`); } catch (error) { logger.error(`Failed to process file: ${filePath}`, error); // Continue with next file } } /** * Split file content into chunks */ private splitIntoChunks(content: string, filePath: string): CodeChunk[] { const lines = content.split('\n'); const chunks: CodeChunk[] = []; const {maxLinesPerChunk, minLinesPerChunk, minCharsPerChunk, overlapLines} = this.config.chunking; for (let i = 0; i < lines.length; i += maxLinesPerChunk - overlapLines) { const startLine = i; const endLine = Math.min(i + maxLinesPerChunk, lines.length); const chunkLines = lines.slice(startLine, endLine); const chunkContent = chunkLines.join('\n'); const trimmedContent = chunkContent.trim(); // Skip chunks that are too small (less than minimum lines or characters) // This prevents creating chunks with just a few characters or empty lines const actualLineCount = chunkLines.filter( line => line.trim().length > 0, ).length; if ( trimmedContent.length < minCharsPerChunk || actualLineCount < minLinesPerChunk ) { // If this is the last chunk and it's too small, try to merge with previous if (i > 0 && endLine >= lines.length && chunks.length > 0) { const lastChunk = chunks[chunks.length - 1]!; // Merge with previous chunk if the combined size is reasonable const mergedLines = lines.slice(lastChunk.startLine - 1, endLine); if (mergedLines.length <= maxLinesPerChunk * 1.5) { lastChunk.content = mergedLines.join('\n'); lastChunk.endLine = endLine; } } continue; } chunks.push({ filePath, content: chunkContent, startLine: startLine + 1, // 1-indexed endLine: endLine, embedding: [], // Will be filled later fileHash: '', // Will be filled later createdAt: 0, updatedAt: 0, }); } return chunks; } /** * Split document content into chunks based on semantic boundaries * Documents (PDF, Word, etc.) need different chunking than code files * - Uses paragraph boundaries instead of fixed line counts * - Respects heading structures * - Maintains semantic coherence */ private splitDocumentIntoChunks( content: string, filePath: string, ): CodeChunk[] { const chunks: CodeChunk[] = []; // Document chunking configuration const MAX_CHUNK_CHARS = 3000; // Maximum characters per chunk const MIN_CHUNK_CHARS = 200; // Minimum characters per chunk // Split by paragraphs (double newlines) while preserving single newlines within paragraphs const paragraphs = content .split(/\n{2,}/) .map(p => p.trim()) .filter(p => p.length > 0); if (paragraphs.length === 0) { return chunks; } let currentChunk: string[] = []; let currentCharCount = 0; let startParagraph = 0; for (let i = 0; i < paragraphs.length; i++) { const paragraph = paragraphs[i]!; const paraLength = paragraph.length; // Check if adding this paragraph would exceed max size if ( currentCharCount + paraLength > MAX_CHUNK_CHARS && currentChunk.length > 0 ) { // Save current chunk const chunkContent = currentChunk.join('\n\n'); if (chunkContent.length >= MIN_CHUNK_CHARS) { chunks.push({ filePath, content: chunkContent, startLine: startParagraph + 1, // Use paragraph index (1-based) endLine: i, // End paragraph index embedding: [], fileHash: '', createdAt: 0, updatedAt: 0, }); } // Start new chunk with overlap const overlapStart = Math.max(0, currentChunk.length - 1); currentChunk = currentChunk.slice(overlapStart); currentCharCount = currentChunk.reduce((sum, p) => sum + p.length, 0); startParagraph = i - currentChunk.length; } currentChunk.push(paragraph); currentCharCount += paraLength; } // Don't forget the last chunk if (currentChunk.length > 0) { const chunkContent = currentChunk.join('\n\n'); if (chunkContent.length >= MIN_CHUNK_CHARS) { chunks.push({ filePath, content: chunkContent, startLine: startParagraph + 1, endLine: paragraphs.length, embedding: [], fileHash: '', createdAt: 0, updatedAt: 0, }); } else if (chunks.length > 0) { // Merge small last chunk with previous chunk const lastChunk = chunks[chunks.length - 1]!; lastChunk.content += '\n\n' + chunkContent; lastChunk.endLine = paragraphs.length; } } logger.debug( `Document split into ${chunks.length} semantic chunks for: ${filePath}`, ); return chunks; } /** * Extract detailed error message including cause chain */ private extractDetailedError(error: unknown): string { if (!(error instanceof Error)) { return String(error); } const parts: string[] = [error.message]; let current: unknown = (error as any).cause; while (current) { if (current instanceof Error) { parts.push(current.message); current = (current as any).cause; } else { parts.push(String(current)); break; } } return parts.join(' -> '); } /** * Notify progress to callback */ private notifyProgress(progress: { totalFiles: number; processedFiles: number; totalChunks: number; currentFile: string; status: 'scanning' | 'indexing' | 'completed' | 'error'; error?: string; }): void { if (this.progressCallback) { this.progressCallback(progress); } } } ================================================ FILE: source/agents/codebaseReviewAgent.ts ================================================ import {getSnowConfig} from '../utils/config/apiConfig.js'; import {logger} from '../utils/core/logger.js'; import {createStreamingChatCompletion, type ChatMessage} from '../api/chat.js'; import {createStreamingResponse} from '../api/responses.js'; import {createStreamingGeminiCompletion} from '../api/gemini.js'; import {createStreamingAnthropicCompletion} from '../api/anthropic.js'; import type {RequestMethod} from '../utils/config/apiConfig.js'; /** * Codebase Review Agent Service * * Reviews codebase search results to filter out irrelevant items. * Uses basicModel for efficient, low-cost relevance checking. * Can also suggest better search keywords if results are not relevant. */ export class CodebaseReviewAgent { private modelName: string = ''; private requestMethod: RequestMethod = 'chat'; private initialized: boolean = false; private readonly MAX_RETRIES = 3; /** * Function calling tool definition for result review */ private readonly REVIEW_TOOL = { type: 'function' as const, function: { name: 'review_search_results', description: 'Review code search results and identify relevant ones, suggest improvements', parameters: { type: 'object', properties: { relevantIndices: { type: 'array', items: {type: 'integer'}, description: 'Array of relevant result indices (1-based). Example: [1, 3, 5]', }, removedIndices: { type: 'array', items: {type: 'integer'}, description: 'Array of irrelevant result indices that should be removed (1-based). Example: [2, 4]', }, suggestion: { type: 'string', description: 'If there are relevant results but not enough, extract actual code snippet from the RELEVANT results to use as new search term. Copy real code text like function names, class names, key variable names, or important code lines. Example: if relevant result contains "async function validateUserInput(data)", extract "validateUserInput" or "async function validateUserInput". This helps find similar code patterns.', }, highConfidenceFiles: { type: 'array', items: {type: 'string'}, description: 'File paths with high confidence that may contain more relevant code. Include files with >2 relevant results or core implementation files', }, }, required: ['relevantIndices', 'removedIndices'], }, }, }; /** * Initialize the review agent with current configuration */ private async initialize(): Promise { try { const config = getSnowConfig(); if (!config.basicModel) { logger.warn( 'Codebase review agent: Basic model not configured, using advanced model as fallback', ); if (!config.advancedModel) { logger.warn('Codebase review agent: No model configured'); return false; } this.modelName = config.advancedModel; } else { this.modelName = config.basicModel; } this.requestMethod = config.requestMethod; this.initialized = true; return true; } catch (error) { logger.warn('Codebase review agent: Failed to initialize:', error); return false; } } /** * Clear cached configuration (called when profile switches) */ clearCache(): void { this.initialized = false; this.modelName = ''; this.requestMethod = 'chat'; } /** * Check if review agent is available */ async isAvailable(): Promise { if (!this.initialized) { return await this.initialize(); } return true; } /** * Call the model with streaming API and assemble complete response * Uses Function Calling to ensure structured output */ private async callModel( messages: ChatMessage[], abortSignal?: AbortSignal, ): Promise<{content: string; tool_calls?: any[]}> { let streamGenerator: AsyncGenerator; switch (this.requestMethod) { case 'anthropic': streamGenerator = createStreamingAnthropicCompletion( { model: this.modelName, messages, tools: [this.REVIEW_TOOL], includeBuiltinSystemPrompt: false, disableThinking: true, }, abortSignal, ); break; case 'gemini': streamGenerator = createStreamingGeminiCompletion( { model: this.modelName, messages, tools: [this.REVIEW_TOOL], includeBuiltinSystemPrompt: false, disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; case 'responses': streamGenerator = createStreamingResponse( { model: this.modelName, messages, tools: [this.REVIEW_TOOL], stream: true, includeBuiltinSystemPrompt: false, disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; case 'chat': default: streamGenerator = createStreamingChatCompletion( { model: this.modelName, messages, tools: [this.REVIEW_TOOL], stream: true, includeBuiltinSystemPrompt: false, disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; } let completeContent = ''; let tool_calls: any[] = []; try { for await (const chunk of streamGenerator) { if (abortSignal?.aborted) { throw new Error('Request aborted'); } if (this.requestMethod === 'chat') { // OpenAI chat format if (chunk.choices && chunk.choices[0]?.delta?.content) { completeContent += chunk.choices[0].delta.content; } if (chunk.choices && chunk.choices[0]?.delta?.tool_calls) { // Accumulate tool calls const deltaToolCalls = chunk.choices[0].delta.tool_calls; for (const tc of deltaToolCalls) { if (tc.index !== undefined) { if (!tool_calls[tc.index]) { tool_calls[tc.index] = { id: tc.id || '', type: 'function', function: {name: '', arguments: ''}, }; } if (tc.function?.name) { tool_calls[tc.index].function.name += tc.function.name; } if (tc.function?.arguments) { tool_calls[tc.index].function.arguments += tc.function.arguments; } } } } } else { // Anthropic/Gemini/Responses format if (chunk.type === 'content' && chunk.content) { completeContent += chunk.content; } if (chunk.type === 'tool_calls' && chunk.tool_calls) { tool_calls = chunk.tool_calls; } } } } catch (streamError) { logger.error('Codebase review agent: Streaming error:', streamError); throw streamError; } return {content: completeContent, tool_calls}; } /** * Try to parse JSON response with retry logic */ private tryParseJSON(response: string): any | null { try { // Extract JSON from markdown code blocks if present let jsonStr = response.trim(); const jsonMatch = jsonStr.match( /```(?:json)?\\s*\\n?([\\s\\S]*?)\\n?```/, ); if (jsonMatch) { jsonStr = jsonMatch[1]!.trim(); } const parsed = JSON.parse(jsonStr); // Validate structure if (!Array.isArray(parsed.relevantIndices)) { logger.warn( 'Codebase review agent: Invalid JSON structure - missing relevantIndices array', ); return null; } return parsed; } catch (error) { logger.warn('Codebase review agent: JSON parse error:', error); return null; } } /** * Review search results with retry mechanism */ private async reviewWithRetry( query: string, results: Array<{ rank: number; filePath: string; startLine: number; endLine: number; content: string; similarityScore: string; location: string; }>, conversationContext?: Array<{role: string; content: string}>, abortSignal?: AbortSignal, ): Promise<{parsed: any; attempt: number} | null> { // Build conversation context section let conversationSection = ''; if (conversationContext && conversationContext.length > 0) { conversationSection = `\n\nConversation Context (Recent Messages):\n` + conversationContext .map((msg, idx) => `[${idx + 1}] ${msg.role}: ${msg.content}`) .join('\n') + '\n'; } const reviewPrompt = `You are a code search result reviewer. Your task is to analyze search results and determine which ones are truly relevant to the user's query. ${conversationSection} Search Query: "${query}" Search Results (${results.length} items): ${results .map( (r, idx) => `\n[Result ${idx + 1}] File: ${r.filePath} Lines: ${r.startLine}-${r.endLine} Similarity Score: ${r.similarityScore}% Code: \`\`\` ${r.content} \`\`\``, ) .join('\n---')} Please call the review_search_results function to provide your analysis. Guidelines: - Be strict but fair: code doesn't need to match exactly, but should be semantically related - Consider file paths, code content, and context - If a result is marginally relevant, keep it - IMPORTANT for suggestion: If there are relevant results but not enough (results < threshold), extract actual code snippet from the RELEVANT results. Copy real code text like function names, class names, key variable names, or important code lines that appear in relevant results. Example: if relevant result contains "async function validateUserInput(data)", extract "validateUserInput" or "async function validateUserInput". Use this extracted code as the new search term to find similar code patterns. - Identify files with >2 relevant results OR that seem to be core implementation files (look for patterns: multiple hits, core modules, entry points)`; const messages: ChatMessage[] = [ { role: 'user', content: reviewPrompt, }, ]; // Retry loop for (let attempt = 1; attempt <= this.MAX_RETRIES; attempt++) { try { logger.info( `Codebase review agent: Attempt ${attempt}/${this.MAX_RETRIES}`, ); const response = await this.callModel(messages, abortSignal); // Check for empty response if ( !response || (!response.content && (!response.tool_calls || response.tool_calls.length === 0)) ) { logger.warn( `Codebase review agent: Empty response on attempt ${attempt}`, ); if (attempt < this.MAX_RETRIES) { await this.sleep(500 * attempt); // Exponential backoff continue; } return null; } // Try to parse from tool calls first (more reliable) if (response.tool_calls && response.tool_calls.length > 0) { try { const toolCall = response.tool_calls[0]; if ( toolCall.type === 'function' && toolCall.function?.name === 'review_search_results' ) { const parsed = JSON.parse(toolCall.function.arguments); // Validate structure if (!Array.isArray(parsed.relevantIndices)) { logger.warn( `Codebase review agent: Tool call returned invalid structure on attempt ${attempt}`, ); if (attempt < this.MAX_RETRIES) { await this.sleep(500 * attempt); continue; } return null; } logger.info( `Codebase review agent: Successfully parsed from tool call on attempt ${attempt}`, ); return {parsed, attempt}; } } catch (toolError) { logger.warn( 'Codebase review agent: Tool call parse error:', toolError, ); // Fall through to try JSON parsing from content } } // Fallback: Try to parse JSON from content if (response.content) { const parsed = this.tryParseJSON(response.content); if (parsed) { logger.info( `Codebase review agent: Successfully parsed from content on attempt ${attempt}`, ); return {parsed, attempt}; } } // If parse failed and we have retries left if (attempt < this.MAX_RETRIES) { logger.warn( `Codebase review agent: Parse failed on attempt ${attempt}, retrying...`, ); await this.sleep(500 * attempt); // Exponential backoff continue; } return null; } catch (error) { logger.error( `Codebase review agent: Error on attempt ${attempt}:`, error, ); if (attempt < this.MAX_RETRIES) { await this.sleep(500 * attempt); // Exponential backoff continue; } return null; } } return null; } /** * Sleep utility for retry backoff */ private sleep(ms: number): Promise { return new Promise(resolve => setTimeout(resolve, ms)); } /** * Review search results and filter out irrelevant ones * With retry mechanism and graceful degradation * * @param query - Original search query * @param results - Search results to review * @param conversationContext - Optional conversation context (messages without tool calls) * @param returns Object with filtered results and optional suggestion */ async reviewResults( query: string, results: Array<{ rank: number; filePath: string; startLine: number; endLine: number; content: string; similarityScore: string; location: string; }>, conversationContext?: Array<{role: string; content: string}>, abortSignal?: AbortSignal, ): Promise<{ filteredResults: typeof results; removedCount: number; suggestion?: string; highConfidenceFiles?: string[]; reviewFailed?: boolean; }> { const available = await this.isAvailable(); if (!available) { logger.warn( 'Codebase review agent: Not available, returning original results', ); return { filteredResults: results, removedCount: 0, reviewFailed: true, }; } // Attempt review with retry const reviewResult = await this.reviewWithRetry( query, results, conversationContext, abortSignal, ); // If all retries failed, gracefully degrade if (!reviewResult) { logger.warn( 'Codebase review agent: All retry attempts failed, returning original results', ); return { filteredResults: results, removedCount: 0, reviewFailed: true, }; } // Success - filter results const {parsed, attempt} = reviewResult; const filteredResults = results.filter((_, idx) => parsed.relevantIndices.includes(idx + 1), ); const removedCount = results.length - filteredResults.length; logger.info('Codebase review agent: Review completed', { originalCount: results.length, filteredCount: filteredResults.length, removedCount, attempts: attempt, hasSuggestion: !!parsed.suggestion, hasHighConfidenceFiles: !!parsed.highConfidenceFiles?.length, }); return { filteredResults, removedCount, suggestion: parsed.suggestion || undefined, highConfidenceFiles: parsed.highConfidenceFiles || undefined, reviewFailed: false, }; } } // Export singleton instance export const codebaseReviewAgent = new CodebaseReviewAgent(); ================================================ FILE: source/agents/compactAgent.ts ================================================ import {getSnowConfig} from '../utils/config/apiConfig.js'; import {logger} from '../utils/core/logger.js'; import {createStreamingChatCompletion, type ChatMessage} from '../api/chat.js'; import {createStreamingResponse} from '../api/responses.js'; import {createStreamingGeminiCompletion} from '../api/gemini.js'; import {createStreamingAnthropicCompletion} from '../api/anthropic.js'; import type {RequestMethod} from '../utils/config/apiConfig.js'; /** * Compact Agent Service * * Provides lightweight AI agent capabilities using the basic model. * This service operates independently from the main conversation flow * but follows the EXACT same configuration and routing as the main flow: * - API endpoint (baseUrl) * - Authentication (apiKey) * - Custom headers * - Request method (chat, responses, gemini, anthropic) * - Uses basicModel instead of advancedModel * * All requests go through streaming APIs and are intercepted to assemble * the complete response, ensuring complete consistency with main flow. * * Use cases: * - Content preprocessing for web pages * - Information extraction from large documents * - Quick analysis tasks that don't require the main model */ export class CompactAgent { private modelName: string = ''; private requestMethod: RequestMethod = 'chat'; private initialized: boolean = false; /** * Initialize the compact agent with current configuration * @returns true if initialized successfully, false otherwise */ private async initialize(): Promise { try { const config = getSnowConfig(); // Check if basic model is configured if (!config.basicModel) { return false; } this.modelName = config.basicModel; this.requestMethod = config.requestMethod; // Follow main flow's request method this.initialized = true; return true; } catch (error) { logger.warn('Failed to initialize compact agent:', error); return false; } } /** * Clear cached configuration (called when profile switches) */ clearCache(): void { this.initialized = false; this.modelName = ''; this.requestMethod = 'chat'; } /** * Check if compact agent is available */ async isAvailable(): Promise { if (!this.initialized) { return await this.initialize(); } return true; } /** * Call the compact model with the same routing as main flow * Uses streaming APIs and intercepts to assemble complete response * This ensures 100% consistency with main flow routing * @param messages - Chat messages * @param abortSignal - Optional abort signal to cancel the request * @param onTokenUpdate - Optional callback to update token count during streaming */ private async callCompactModel( messages: ChatMessage[], abortSignal?: AbortSignal, onTokenUpdate?: (tokenCount: number) => void, ): Promise { const config = getSnowConfig(); if (!config.basicModel) { throw new Error('Basic model not configured'); } // Temporarily override advancedModel with basicModel const originalAdvancedModel = config.advancedModel; try { // Override config to use basicModel config.advancedModel = config.basicModel; let streamGenerator: AsyncGenerator; // Route to appropriate streaming API based on request method (follows main flow exactly) switch (this.requestMethod) { case 'anthropic': streamGenerator = createStreamingAnthropicCompletion( { model: this.modelName, messages, max_tokens: 4096, includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用 Extended Thinking }, abortSignal, ); break; case 'gemini': streamGenerator = createStreamingGeminiCompletion( { model: this.modelName, messages, includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; case 'responses': streamGenerator = createStreamingResponse( { model: this.modelName, messages, stream: true, includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; case 'chat': default: streamGenerator = createStreamingChatCompletion( { model: this.modelName, messages, stream: true, includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; } // Intercept streaming response and assemble complete content let completeContent = ''; let chunkCount = 0; // Initialize token encoder for token counting let encoder; try { const {encoding_for_model} = await import('tiktoken'); try { encoder = encoding_for_model('gpt-5'); } catch { encoder = encoding_for_model('gpt-3.5-turbo'); } } catch (e) { // tiktoken unavailable, token counting will be skipped } try { for await (const chunk of streamGenerator) { chunkCount++; // Check abort signal if (abortSignal?.aborted) { throw new Error('Request aborted'); } // Handle different chunk formats based on request method if (this.requestMethod === 'chat') { // Chat API uses standard OpenAI format: {choices: [{delta: {content}}]} if (chunk.choices && chunk.choices[0]?.delta?.content) { completeContent += chunk.choices[0].delta.content; // Update token count if callback provided if (onTokenUpdate && encoder) { try { const tokens = encoder.encode(completeContent); onTokenUpdate(tokens.length); } catch (e) { // Ignore encoding errors } } } } else { // Responses, Gemini, and Anthropic APIs all use: {type: 'content', content: string} if (chunk.type === 'content' && chunk.content) { completeContent += chunk.content; // Update token count if callback provided if (onTokenUpdate && encoder) { try { const tokens = encoder.encode(completeContent); onTokenUpdate(tokens.length); } catch (e) { // Ignore encoding errors } } } } } } catch (streamError) { // Log streaming error with details if (streamError instanceof Error) { logger.error('Compact agent: Streaming error:', { error: streamError.message, stack: streamError.stack, name: streamError.name, chunkCount, contentLength: completeContent.length, }); } else { logger.error('Compact agent: Unknown streaming error:', { error: streamError, chunkCount, contentLength: completeContent.length, }); } throw streamError; } finally { // Free encoder if (encoder) { encoder.free(); } } return completeContent; } catch (error) { // Log detailed error from API call setup or streaming if (error instanceof Error) { logger.error('Compact agent: API call failed:', { error: error.message, stack: error.stack, name: error.name, requestMethod: this.requestMethod, modelName: this.modelName, }); } else { logger.error('Compact agent: Unknown API error:', { error, requestMethod: this.requestMethod, modelName: this.modelName, }); } throw error; } finally { // Restore original config config.advancedModel = originalAdvancedModel; } } /** * Extract key information from web page content based on user query * * @param content - Full web page content * @param userQuery - User's original question/query * @param url - URL of the web page (for context) * @param abortSignal - Optional abort signal to cancel extraction * @param onTokenUpdate - Optional callback to update token count during streaming * @returns Extracted key information relevant to the query */ async extractWebPageContent( content: string, userQuery: string, url: string, abortSignal?: AbortSignal, onTokenUpdate?: (tokenCount: number) => void, ): Promise { const available = await this.isAvailable(); if (!available) { // If compact agent is not available, return original content return content; } try { const extractionPrompt = `You are a content extraction assistant. Your task is to extract and summarize the most relevant information from a web page based on the user's query. User's Query: ${userQuery} Web Page URL: ${url} Web Page Content: ${content} Instructions: 1. Extract ONLY the information that is directly relevant to the user's query 2. Preserve important details, facts, code examples, and key points 3. Remove navigation, ads, irrelevant sections, and boilerplate text 4. Organize the information in a clear, structured format 5. If there are multiple relevant sections, separate them clearly 6. Keep technical terms and specific details intact Provide the extracted content below:`; const messages: ChatMessage[] = [ { role: 'user', content: extractionPrompt, }, ]; const extractedContent = await this.callCompactModel( messages, abortSignal, onTokenUpdate, ); if (!extractedContent || extractedContent.trim().length === 0) { logger.warn( 'Compact agent returned empty response, using original content', ); return content; } return extractedContent; } catch (error) { // Log detailed error information if (error instanceof Error) { logger.warn( 'Compact agent extraction failed, using original content:', { error: error.message, stack: error.stack, name: error.name, }, ); } else { logger.warn( 'Compact agent extraction failed with unknown error:', error, ); } return content; } } } // Export singleton instance export const compactAgent = new CompactAgent(); ================================================ FILE: source/agents/reviewAgent.ts ================================================ import { getSnowConfig, getCustomSystemPrompt, } from '../utils/config/apiConfig.js'; import {logger} from '../utils/core/logger.js'; import {createStreamingChatCompletion, type ChatMessage} from '../api/chat.js'; import {createStreamingResponse} from '../api/responses.js'; import {createStreamingGeminiCompletion} from '../api/gemini.js'; import {createStreamingAnthropicCompletion} from '../api/anthropic.js'; import type {RequestMethod} from '../utils/config/apiConfig.js'; import {execSync, spawnSync} from 'child_process'; import * as path from 'path'; import * as fs from 'fs'; export class ReviewAgent { private modelName: string = ''; private requestMethod: RequestMethod = 'chat'; private initialized: boolean = false; /** * Initialize the review agent with current configuration * Uses advanced model (same as main flow) */ private async initialize(): Promise { try { const config = getSnowConfig(); if (!config.advancedModel) { return false; } this.modelName = config.advancedModel; this.requestMethod = config.requestMethod; this.initialized = true; return true; } catch (error) { logger.warn('Failed to initialize review agent:', error); return false; } } /** * Clear cached configuration (called when profile switches) */ clearCache(): void { this.initialized = false; this.modelName = ''; this.requestMethod = 'chat'; } /** * Check if review agent is available */ async isAvailable(): Promise { if (!this.initialized) { return await this.initialize(); } return true; } /** * Check if current directory or any parent directory is a git repository * @param startDir - Starting directory to check * @returns Path to git root directory, or null if not found */ private findGitRoot(startDir: string): string | null { let currentDir = path.resolve(startDir); const root = path.parse(currentDir).root; while (currentDir !== root) { const gitDir = path.join(currentDir, '.git'); if (fs.existsSync(gitDir)) { return currentDir; } currentDir = path.dirname(currentDir); } return null; } /** * Check if git is available and current directory is in a git repository * @returns Object with isGitRepo flag and optional error message */ checkGitRepository(): {isGitRepo: boolean; gitRoot?: string; error?: string} { try { // Check if git command is available try { execSync('git --version', {stdio: 'ignore'}); } catch { return { isGitRepo: false, error: 'Git is not installed or not available in PATH', }; } // Find git root directory (check current and parent directories) const gitRoot = this.findGitRoot(process.cwd()); if (!gitRoot) { return { isGitRepo: false, error: 'Current directory is not in a git repository. Please run this command from within a git repository.', }; } return {isGitRepo: true, gitRoot}; } catch (error) { return { isGitRepo: false, error: error instanceof Error ? error.message : 'Failed to check git repository', }; } } /** * Check if there are staged or unstaged changes * @param gitRoot - Git repository root directory * @returns Object with hasStaged and hasUnstaged flags */ getWorkingTreeStatus(gitRoot: string): { hasStaged: boolean; hasUnstaged: boolean; stagedFileCount: number; unstagedFileCount: number; } { let hasStaged = false; let hasUnstaged = false; let stagedFileCount = 0; let unstagedFileCount = 0; try { execSync('git diff --cached --quiet', { cwd: gitRoot, encoding: 'utf-8', stdio: 'pipe', }); } catch { hasStaged = true; try { const stagedFiles = execSync('git diff --cached --name-only', { cwd: gitRoot, encoding: 'utf-8', stdio: 'pipe', }); stagedFileCount = stagedFiles.trim().split('\n').filter(Boolean).length; } catch { // Ignore errors } } try { execSync('git diff --quiet', { cwd: gitRoot, encoding: 'utf-8', stdio: 'pipe', }); } catch { hasUnstaged = true; try { const unstagedFiles = execSync('git diff --name-only', { cwd: gitRoot, encoding: 'utf-8', stdio: 'pipe', }); unstagedFileCount = unstagedFiles .trim() .split('\n') .filter(Boolean).length; } catch { // Ignore errors } } return {hasStaged, hasUnstaged, stagedFileCount, unstagedFileCount}; } /** * Get staged changes diff only * @param gitRoot - Git repository root directory * @returns Staged diff output */ getStagedDiff(gitRoot: string): string { try { const stagedDiff = execSync('git diff --cached', { cwd: gitRoot, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: 'pipe', }); if (!stagedDiff) { return 'No staged changes detected.'; } return '# Staged Changes\n\n' + stagedDiff; } catch (error) { logger.error('Failed to get staged diff:', error); throw new Error( 'Failed to get staged changes: ' + (error instanceof Error ? error.message : 'Unknown error'), ); } } /** * Get unstaged changes diff only * @param gitRoot - Git repository root directory * @returns Unstaged diff output */ getUnstagedDiff(gitRoot: string): string { try { const unstagedDiff = execSync('git diff', { cwd: gitRoot, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: 'pipe', }); if (!unstagedDiff) { return 'No unstaged changes detected.'; } return '# Unstaged Changes\n\n' + unstagedDiff; } catch (error) { logger.error('Failed to get unstaged diff:', error); throw new Error( 'Failed to get unstaged changes: ' + (error instanceof Error ? error.message : 'Unknown error'), ); } } /** * Get git diff for uncommitted changes * @param gitRoot - Git repository root directory * @returns Git diff output */ getGitDiff(gitRoot: string): string { try { const stagedDiff = execSync('git diff --cached', { cwd: gitRoot, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: 'pipe', }); const unstagedDiff = execSync('git diff', { cwd: gitRoot, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, stdio: 'pipe', }); // Combine both diffs let combinedDiff = ''; if (stagedDiff) { combinedDiff += '# Staged Changes\n\n' + stagedDiff + '\n\n'; } if (unstagedDiff) { combinedDiff += '# Unstaged Changes\n\n' + unstagedDiff; } if (!combinedDiff) { return 'No changes detected in the repository.'; } return combinedDiff; } catch (error) { logger.error('Failed to get git diff:', error); throw new Error( 'Failed to get git changes: ' + (error instanceof Error ? error.message : 'Unknown error'), ); } } private runGit( gitRoot: string, args: string[], ): {stdout: string; stderr: string; status: number | null} { const result = spawnSync('git', args, { cwd: gitRoot, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, }); return { stdout: result.stdout ?? '', stderr: result.stderr ?? '', status: result.status, }; } private assertSafeCommitSha(sha: string): void { if (!/^[0-9a-f]{7,40}$/i.test(sha)) { throw new Error('Invalid commit SHA'); } } private normalizeNonNegativeInt(value: number, name: string): number { if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) { throw new Error(`Invalid ${name}`); } return value; } listCommitsPaginated( gitRoot: string, skip: number, limit: number, ): { commits: Array<{ sha: string; authorName: string; dateIso: string; subject: string; }>; hasMore: boolean; nextSkip: number; } { const safeSkip = this.normalizeNonNegativeInt(skip, 'skip'); const safeLimit = this.normalizeNonNegativeInt(limit, 'limit'); // Use a unit separator as field delimiter for robust parsing const format = '%H%x1f%an%x1f%ad%x1f%s'; const {stdout, stderr, status} = this.runGit(gitRoot, [ 'log', '--date=iso-strict', `--pretty=format:${format}`, `--skip=${safeSkip}`, '-n', String(safeLimit), ]); if (status !== 0) { throw new Error( `Failed to list commits: ${stderr.trim() || 'Unknown error'}`, ); } const lines = stdout .split('\n') .map(l => l.trim()) .filter(Boolean); const commits = lines .map(line => { const parts = line.split('\x1f'); if (parts.length < 4) return null; const [sha, authorName, dateIso, subject] = parts; return {sha, authorName, dateIso, subject}; }) .filter(Boolean) as Array<{ sha: string; authorName: string; dateIso: string; subject: string; }>; return { commits, hasMore: commits.length === safeLimit, nextSkip: safeSkip + commits.length, }; } getCommitPatch(gitRoot: string, sha: string): string { this.assertSafeCommitSha(sha); try { const {stdout, stderr, status} = this.runGit(gitRoot, [ 'show', '--no-color', sha, ]); if (status !== 0) { throw new Error(stderr.trim() || 'Unknown error'); } return stdout; } catch (error) { logger.error('Failed to get commit patch:', error); throw new Error( 'Failed to get commit patch: ' + (error instanceof Error ? error.message : 'Unknown error'), ); } } /** * Generate code review prompt */ private generateReviewPrompt(gitDiff: string): string { return `You are a senior code reviewer. Please review the following git changes and provide feedback. **Your task:** 1. Identify potential bugs, security issues, or logic errors 2. Suggest performance optimizations 3. Point out code quality issues (readability, maintainability) 4. Check for best practices violations 5. Highlight any breaking changes or compatibility issues **Important:** - DO NOT modify the code yourself - Focus on finding issues and suggesting improvements - Ask the user if they want to fix any issues you find - Be constructive and specific in your feedback - Prioritize critical issues over minor style preferences **Git Changes:** \`\`\`diff ${gitDiff} \`\`\` Please provide your review in a clear, structured format.`; } /** * Call the advanced model with streaming (same routing as main flow) */ private async *callAdvancedModel( messages: ChatMessage[], abortSignal?: AbortSignal, ): AsyncGenerator { const config = getSnowConfig(); if (!config.advancedModel) { throw new Error('Advanced model not configured'); } // Get custom system prompt if configured const customSystemPrompts = getCustomSystemPrompt(); // If custom system prompt exists, prepend it to messages let processedMessages = messages; if (customSystemPrompts && customSystemPrompts.length > 0) { processedMessages = [ { role: 'system', content: customSystemPrompts.join('\n\n'), }, ...messages, ]; } // Route to appropriate streaming API based on request method switch (this.requestMethod) { case 'anthropic': yield* createStreamingAnthropicCompletion( { model: this.modelName, messages: processedMessages, max_tokens: 4096, disableThinking: true, // Agents 不使用 Extended Thinking }, abortSignal, ); break; case 'gemini': yield* createStreamingGeminiCompletion( { model: this.modelName, messages: processedMessages, }, abortSignal, ); break; case 'responses': yield* createStreamingResponse( { model: this.modelName, messages: processedMessages, stream: true, }, abortSignal, ); break; case 'chat': default: yield* createStreamingChatCompletion( { model: this.modelName, messages: processedMessages, stream: true, }, abortSignal, ); break; } } /** * Review git changes and return streaming generator * @param abortSignal - Optional abort signal * @returns Async generator for streaming response */ async *reviewChanges( abortSignal?: AbortSignal, ): AsyncGenerator { const available = await this.isAvailable(); if (!available) { throw new Error('Review agent is not available'); } // Check git repository const gitCheck = this.checkGitRepository(); if (!gitCheck.isGitRepo) { throw new Error(gitCheck.error || 'Not a git repository'); } // Get git diff const gitDiff = this.getGitDiff(gitCheck.gitRoot!); if (gitDiff === 'No changes detected in the repository.') { throw new Error( 'No changes detected. Please make some changes before running code review.', ); } // Generate review prompt const reviewPrompt = this.generateReviewPrompt(gitDiff); const messages: ChatMessage[] = [ { role: 'user', content: reviewPrompt, }, ]; // Stream the response yield* this.callAdvancedModel(messages, abortSignal); } } // Export singleton instance export const reviewAgent = new ReviewAgent(); ================================================ FILE: source/agents/summaryAgent.ts ================================================ import {getSnowConfig} from '../utils/config/apiConfig.js'; import {logger} from '../utils/core/logger.js'; import {createStreamingChatCompletion, type ChatMessage} from '../api/chat.js'; import {createStreamingResponse} from '../api/responses.js'; import {createStreamingGeminiCompletion} from '../api/gemini.js'; import {createStreamingAnthropicCompletion} from '../api/anthropic.js'; import type {RequestMethod} from '../utils/config/apiConfig.js'; /** * Summary Agent Service * * Generates concise summaries for conversations after the first user-assistant exchange. * This service operates in the background without blocking the main conversation flow. * * Features: * - Uses basicModel for efficient, low-cost summarization * - Follows the same API routing as main flow (chat, responses, gemini, anthropic) * - Generates title (max 50 chars) and summary (max 150 chars) * - Only runs once after the first complete conversation exchange * - Silent execution with error handling to prevent main flow disruption */ export class SummaryAgent { private modelName: string = ''; private requestMethod: RequestMethod = 'chat'; private initialized: boolean = false; /** * Initialize the summary agent with current configuration * @returns true if initialized successfully, false otherwise */ private async initialize(): Promise { try { const config = getSnowConfig(); // Use basicModel first, fallback to advancedModel if not configured const basicModel = config.basicModel?.trim(); const advancedModel = config.advancedModel?.trim(); if (basicModel) { this.modelName = basicModel; } else if (advancedModel) { this.modelName = advancedModel; } else { logger.warn('Summary agent: No model configured'); return false; } this.requestMethod = config.requestMethod; this.initialized = true; return true; } catch (error) { logger.warn('Summary agent: Failed to initialize:', error); return false; } } /** * Clear cached configuration (called when profile switches) */ clearCache(): void { this.initialized = false; this.modelName = ''; this.requestMethod = 'chat'; } /** * Check if summary agent is available */ async isAvailable(): Promise { if (!this.initialized) { return await this.initialize(); } return true; } /** * Call the model with streaming API and assemble complete response * Uses the same routing logic as main flow for consistency * * @param messages - Chat messages * @param abortSignal - Optional abort signal to cancel the request */ private async callModel( messages: ChatMessage[], abortSignal?: AbortSignal, ): Promise { let streamGenerator: AsyncGenerator; // Route to appropriate streaming API based on request method switch (this.requestMethod) { case 'anthropic': streamGenerator = createStreamingAnthropicCompletion( { model: this.modelName, messages, max_tokens: 500, // Limited tokens for summary generation includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用 Extended Thinking }, abortSignal, ); break; case 'gemini': streamGenerator = createStreamingGeminiCompletion( { model: this.modelName, messages, includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; case 'responses': streamGenerator = createStreamingResponse( { model: this.modelName, messages, stream: true, includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; case 'chat': default: streamGenerator = createStreamingChatCompletion( { model: this.modelName, messages, stream: true, includeBuiltinSystemPrompt: false, // 不需要内置系统提示词 disableThinking: true, // Agents 不使用思考功能 }, abortSignal, ); break; } // Assemble complete content from streaming response let completeContent = ''; try { for await (const chunk of streamGenerator) { // Check abort signal if (abortSignal?.aborted) { throw new Error('Request aborted'); } // Handle different chunk formats based on request method if (this.requestMethod === 'chat') { // Chat API uses standard OpenAI format if (chunk.choices && chunk.choices[0]?.delta?.content) { completeContent += chunk.choices[0].delta.content; } } else { // Responses, Gemini, and Anthropic APIs use unified format if (chunk.type === 'content' && chunk.content) { completeContent += chunk.content; } } } } catch (streamError) { logger.error('Summary agent: Streaming error:', streamError); throw streamError; } return completeContent; } /** * Generate title and summary for a conversation * * @param userMessage - User's first message content * @param assistantMessage - Assistant's first response content * @param abortSignal - Optional abort signal to cancel generation * @returns Object containing title and summary, or null if generation fails */ async generateSummary( userMessage: string, assistantMessage: string, abortSignal?: AbortSignal, ): Promise<{title: string; summary: string} | null> { const result = await this.generateSummaryInternal( userMessage, assistantMessage, abortSignal, ); // 无论生成成功或回退，都用 title 更新终端标题 this.applyTerminalTitle(result?.title); return result; } /** * 把 summary 标题设置为终端窗口/标签标题，失败时静默忽略 */ private applyTerminalTitle(title: string | undefined): void { if (!title) return; try { if (!process.stdout?.isTTY) return; const finalTitle = `Snow CLI - ${title}`; try { process.title = finalTitle; } catch { // 某些受限环境写入 process.title 会失败，忽略 } process.stdout.write(`\x1b]0;${finalTitle}\x07`); } catch (error) { logger.warn('Summary agent: Failed to set terminal title', error); } } private async generateSummaryInternal( userMessage: string, assistantMessage: string, abortSignal?: AbortSignal, ): Promise<{title: string; summary: string} | null> { const available = await this.isAvailable(); if (!available) { logger.warn('Summary agent: Not available, using fallback summary'); return this.generateFallbackSummary(userMessage, assistantMessage); } try { const summaryPrompt = `You are a conversation summarization assistant. Based on the first exchange between the user and AI assistant below, generate a concise title and summary. IMPORTANT: Generate the title and summary in the SAME LANGUAGE as the user's message. If the user writes in Chinese, respond in Chinese. If in English, respond in English. User message: ${userMessage} AI assistant reply: ${assistantMessage} Requirements: 1. Generate a short title (max 50 characters) that captures the conversation topic 2. Generate a summary (max 150 characters) that briefly describes the core content 3. Title should be concise and clear, avoid complete sentences 4. Summary should contain key information while staying brief 5. Use the SAME LANGUAGE as the user's message Output in the following JSON format (JSON only, no other content): { "title": "Conversation title", "summary": "Conversation summary" }`; const messages: ChatMessage[] = [ { role: 'user', content: summaryPrompt, }, ]; const response = await this.callModel(messages, abortSignal); if (!response || response.trim().length === 0) { logger.warn('Summary agent: Empty response, using fallback'); return this.generateFallbackSummary(userMessage, assistantMessage); } // Parse JSON response try { // Extract JSON from markdown code blocks if present let jsonStr = response.trim(); const jsonMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/); if (jsonMatch) { jsonStr = jsonMatch[1]!.trim(); } const parsed = JSON.parse(jsonStr); if (!parsed.title || !parsed.summary) { logger.warn('Summary agent: Invalid JSON structure, using fallback'); return this.generateFallbackSummary(userMessage, assistantMessage); } // Ensure title and summary are within length limits const title = this.truncateString(parsed.title, 50); const summary = this.truncateString(parsed.summary, 150); logger.info('Summary agent: Successfully generated summary', { title, summary, }); return {title, summary}; } catch (parseError) { logger.warn( 'Summary agent: Failed to parse JSON response, using fallback', parseError, ); return this.generateFallbackSummary(userMessage, assistantMessage); } } catch (error) { logger.error('Summary agent: Failed to generate summary', error); return this.generateFallbackSummary(userMessage, assistantMessage); } } /** * Generate fallback summary when AI generation fails * Simply truncates the user message for title and summary */ private generateFallbackSummary( userMessage: string, _assistantMessage: string, ): {title: string; summary: string} { // Clean newlines and extra spaces const cleanedUser = userMessage .replace(/[\r\n]+/g, ' ') .replace(/\s+/g, ' ') .trim(); // Use first 50 chars as title const title = this.truncateString(cleanedUser, 50); // Use first 150 chars as summary const summary = this.truncateString(cleanedUser, 150); return {title, summary}; } /** * Truncate string to specified length, adding ellipsis if truncated */ private truncateString(str: string, maxLength: number): string { if (str.length <= maxLength) { return str; } return str.slice(0, maxLength - 3) + '...'; } } // Export singleton instance export const summaryAgent = new SummaryAgent(); ================================================ FILE: source/api/anthropic.ts ================================================ import {createHash, randomUUID} from 'crypto'; import { getSnowConfig, getCustomSystemPromptForConfig, getCustomHeadersForConfig, type ThinkingConfig, } from '../utils/config/apiConfig.js'; import {getSystemPromptForMode} from '../prompt/systemPrompt.js'; import { withRetryGenerator, parseJsonWithFix, } from '../utils/core/retryUtils.js'; import { createIdleTimeoutGuard, StreamIdleTimeoutError, } from '../utils/core/streamGuards.js'; import type {ChatMessage, ChatCompletionTool, UsageInfo} from './types.js'; import {logger} from '../utils/core/logger.js'; import {addProxyToFetchOptions} from '../utils/core/proxyUtils.js'; import {saveUsageToFile} from '../utils/core/usageLogger.js'; import {isDevMode, getDevUserId} from '../utils/core/devMode.js'; import {getVersionHeader} from '../utils/core/version.js'; export interface AnthropicOptions { model: string; messages: ChatMessage[]; temperature?: number; max_tokens?: number; tools?: ChatCompletionTool[]; sessionId?: string; // Session ID for user tracking and caching includeBuiltinSystemPrompt?: boolean; // 控制是否添加内置系统提示词（默认 true） disableThinking?: boolean; // 禁用 Extended Thinking 功能（用于 agents 等场景，默认 false） planMode?: boolean; // 启用 Plan 模式（使用 Plan 模式系统提示词） vulnerabilityHuntingMode?: boolean; // 启用漏洞狩猎模式（使用漏洞狩猎模式系统提示词） teamMode?: boolean; // 启用 Team 模式（使用 Team 模式系统提示词） toolSearchDisabled?: boolean; // 工具搜索已关闭（全量加载工具） // Sub-agent configuration overrides configProfile?: string; // 子代理配置文件名（覆盖模型等设置） customSystemPromptId?: string; // 自定义系统提示词 ID customHeaders?: Record; // 自定义请求头 } export interface AnthropicStreamChunk { type: | 'content' | 'tool_calls' | 'tool_call_delta' | 'done' | 'usage' | 'reasoning_started' | 'reasoning_delta'; content?: string; tool_calls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string; }; }>; delta?: string; usage?: UsageInfo; thinking?: { type: 'thinking'; thinking: string; signature?: string; }; } export interface AnthropicTool { name: string; description: string; input_schema: any; cache_control?: {type: 'ephemeral'; ttl?: '5m' | '1h'}; } export interface AnthropicMessageParam { role: 'user' | 'assistant'; content: string | Array; } // Deprecated: No longer used, kept for backward compatibility // @ts-ignore - Variable kept for backward compatibility with resetAnthropicClient export let anthropicConfig: { apiKey: string; baseUrl: string; customHeaders: Record; anthropicBeta?: boolean; thinking?: ThinkingConfig; } | null = null; // Persistent userId that remains the same until application restart let persistentUserId: string | null = null; /** * 将图片数据转换为 Anthropic API 所需的格式 * 处理三种情况： * 1. 远程 URL (http/https): 返回 URL 类型（Anthropic 支持某些图片 URL） * 2. 已经是 data URL: 解析出 media_type 和 base64 数据 * 3. 纯 base64 数据: 使用提供的 mimeType 补齐为完整格式 */ function toAnthropicImageSource(image: { data: string; mimeType?: string; }): | {type: 'base64'; media_type: string; data: string} | {type: 'url'; url: string} | null { const data = image.data?.trim() || ''; if (!data) return null; // 远程 URL (http/https) - Anthropic 支持某些图片 URL if (/^https?:\/\//i.test(data)) { return { type: 'url', url: data, }; } // 已经是 data URL 格式，解析它 const dataUrlMatch = data.match(/^data:([^;]+);base64,(.+)$/); if (dataUrlMatch) { return { type: 'base64', media_type: dataUrlMatch[1] || image.mimeType || 'image/png', data: dataUrlMatch[2] || '', }; } // 纯 base64 数据，补齐格式 const mimeType = image.mimeType?.trim() || 'image/png'; return { type: 'base64', media_type: mimeType, data: data, }; } // Deprecated: Client reset is no longer needed with new config loading approach export function resetAnthropicClient(): void { anthropicConfig = null; persistentUserId = null; // Reset userId on client reset } /** * Generate a persistent user_id that remains the same until application restart * Format: user__account__session_ * This matches Anthropic's expected format for tracking and caching * * In dev mode (--dev flag), uses a persistent userId from ~/.snow/dev-user-id * instead of generating a new one each session */ function getPersistentUserId(): string { // Check if dev mode is enabled if (isDevMode()) { return getDevUserId(); } // Normal mode: generate userId per session if (!persistentUserId) { const sessionId = randomUUID(); const hash = createHash('sha256') .update(`anthropic_user_${sessionId}`) .digest('hex'); persistentUserId = `user_${hash}_account__session_${sessionId}`; } return persistentUserId; } /** * Convert OpenAI-style tools to Anthropic tool format * Adds cache_control to the last tool for prompt caching */ function convertToolsToAnthropic( tools?: ChatCompletionTool[], ): AnthropicTool[] | undefined { if (!tools || tools.length === 0) { return undefined; } const convertedTools = tools .filter(tool => tool.type === 'function' && 'function' in tool) .map(tool => { if (tool.type === 'function' && 'function' in tool) { return { name: tool.function.name, description: tool.function.description || '', input_schema: tool.function.parameters as any, }; } throw new Error('Invalid tool format'); }); // Do not add cache_control to tools to avoid TTL ordering issues // if (convertedTools.length > 0) { // const lastTool = convertedTools[convertedTools.length - 1]; // (lastTool as any).cache_control = {type: 'ephemeral', ttl: '5m'}; // } return convertedTools; } /** * Convert our ChatMessage format to Anthropic's message format * Adds cache_control to system prompt and last user message for prompt caching * @param messages - The messages to convert * @param includeBuiltinSystemPrompt - Whether to include builtin system prompt (default true) * @param customSystemPromptOverride - Allow override for sub-agents * @param cacheTTL - Cache TTL for prompt caching (default: '5m') */ function convertToAnthropicMessages( messages: ChatMessage[], includeBuiltinSystemPrompt: boolean = true, customSystemPromptOverride?: string[], cacheTTL: '5m' | '1h' = '5m', disableThinking: boolean = false, planMode: boolean = false, vulnerabilityHuntingMode: boolean = false, toolSearchDisabled: boolean = false, teamMode: boolean = false, ): { system?: any; messages: AnthropicMessageParam[]; } { const customSystemPrompts = customSystemPromptOverride; let systemContents: string[] | undefined; const anthropicMessages: AnthropicMessageParam[] = []; const toolResults: any[] = []; for (const msg of messages) { // Flush tool results when encountering non-tool messages if (msg.role !== 'tool' && toolResults.length > 0) { anthropicMessages.push({ role: 'user', content: [...toolResults], }); toolResults.length = 0; } if (msg.role === 'system') { systemContents = [msg.content]; continue; } if (msg.role === 'tool' && msg.tool_call_id) { // Build tool_result content - can be text or array with images let toolResultContent: string | any[]; if (msg.images && msg.images.length > 0) { // Multimodal tool result with images const contentArray: any[] = []; // Add text content first if (msg.content) { contentArray.push({ type: 'text', text: msg.content, }); } // Add images - 使用辅助函数处理各种格式的图片数据 for (const image of msg.images) { const imageSource = toAnthropicImageSource(image); if (imageSource) { if (imageSource.type === 'url') { contentArray.push({ type: 'image', source: { type: 'url', url: imageSource.url, }, }); } else { contentArray.push({ type: 'image', source: imageSource, }); } } } toolResultContent = contentArray; } else { // Text-only tool result toolResultContent = msg.content; } toolResults.push({ type: 'tool_result', tool_use_id: msg.tool_call_id, content: toolResultContent, }); continue; } if (msg.role === 'user' && msg.images && msg.images.length > 0) { const content: any[] = []; if (msg.content) { content.push({ type: 'text', text: msg.content, }); } // 使用辅助函数处理各种格式的图片数据，补齐纯 base64 数据 for (const image of msg.images) { const imageSource = toAnthropicImageSource(image); if (imageSource) { if (imageSource.type === 'url') { content.push({ type: 'image', source: { type: 'url', url: imageSource.url, }, }); } else { content.push({ type: 'image', source: imageSource, }); } } } anthropicMessages.push({ role: 'user', content, }); continue; } if ( msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0 ) { const content: any[] = []; // When thinking is enabled, thinking block must come first // Skip thinking block when disableThinking is true if (msg.thinking && !disableThinking) { // Ensure signature is always present (required by Anthropic API) content.push({ ...msg.thinking, signature: msg.thinking.signature || '', }); } if (msg.content) { content.push({ type: 'text', text: msg.content, }); } for (const toolCall of msg.tool_calls) { content.push({ type: 'tool_use', id: toolCall.id, name: toolCall.function.name, input: JSON.parse(toolCall.function.arguments), }); } anthropicMessages.push({ role: 'assistant', content, }); continue; } if (msg.role === 'user' || msg.role === 'assistant') { // For assistant messages with thinking, convert to structured format // Skip thinking block when disableThinking is true if (msg.role === 'assistant' && msg.thinking && !disableThinking) { const content: any[] = []; // Thinking block must come first - ensure signature is always present content.push({ ...msg.thinking, signature: msg.thinking.signature || '', }); // Then text content if (msg.content) { content.push({ type: 'text', text: msg.content, }); } anthropicMessages.push({ role: 'assistant', content, }); } else { anthropicMessages.push({ role: msg.role, content: msg.content, }); } } } // Flush any remaining tool results at the end of message processing if (toolResults.length > 0) { anthropicMessages.push({ role: 'user', content: [...toolResults], }); toolResults.length = 0; } // 如果配置了自定义系统提示词（最高优先级，始终添加） if (customSystemPrompts && customSystemPrompts.length > 0) { systemContents = customSystemPrompts; if (includeBuiltinSystemPrompt) { // 将默认系统提示词作为第一条用户消息 anthropicMessages.unshift({ role: 'user', content: [ { type: 'text', text: getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ), cache_control: {type: 'ephemeral', ttl: cacheTTL}, }, ] as any, }); } } else if (!systemContents && includeBuiltinSystemPrompt) { // 没有自定义系统提示词，但需要添加默认系统提示词 systemContents = [ getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ), ]; } let lastUserMessageIndex = -1; for (let i = anthropicMessages.length - 1; i >= 0; i--) { if (anthropicMessages[i]?.role === 'user') { if (customSystemPrompts && customSystemPrompts.length > 0 && i === 0) { continue; } lastUserMessageIndex = i; break; } } if (lastUserMessageIndex >= 0) { const lastMessage = anthropicMessages[lastUserMessageIndex]; if (lastMessage && lastMessage.role === 'user') { if (typeof lastMessage.content === 'string') { lastMessage.content = [ { type: 'text', text: lastMessage.content, cache_control: {type: 'ephemeral', ttl: cacheTTL}, } as any, ]; } else if (Array.isArray(lastMessage.content)) { const lastContentIndex = lastMessage.content.length - 1; if (lastContentIndex >= 0) { const lastContent = lastMessage.content[lastContentIndex] as any; lastContent.cache_control = {type: 'ephemeral', ttl: cacheTTL}; } } } } // 构造 system 字段：每个提示词作为独立的 text 对象 const system = systemContents && systemContents.length > 0 ? systemContents.map((text, index) => ({ type: 'text', text, ...(index === systemContents!.length - 1 ? {cache_control: {type: 'ephemeral', ttl: cacheTTL}} : {}), })) : undefined; return {system, messages: anthropicMessages}; } /** * Parse Server-Sent Events (SSE) stream */ async function* parseSSEStream( reader: ReadableStreamDefaultReader, abortSignal?: AbortSignal, idleTimeoutMs?: number, ): AsyncGenerator { const decoder = new TextDecoder(); let buffer = ''; let dataCount = 0; // 记录成功解析的数据块数量 let lastEventType = ''; // 记录最后一个事件类型 // 创建空闲超时保护器 const guard = createIdleTimeoutGuard({ reader, idleTimeoutMs, onTimeout: () => { throw new StreamIdleTimeoutError( `No data received for ${idleTimeoutMs}ms`, idleTimeoutMs, ); }, }); try { while (true) { // 用户主动中断时立即标记丢弃,避免延迟消息外泄 if (abortSignal?.aborted) { guard.abandon(); return; } const {done, value} = await reader.read(); // 检查是否有超时错误需要在读取循环中抛出(确保被正确的 try/catch 捕获) const timeoutError = guard.getTimeoutError(); if (timeoutError) { throw timeoutError; } // 检查是否已被丢弃(竞态条件防护) if (guard.isAbandoned()) { continue; } if (done) { // 检查buffer是否有残留数据 if (buffer.trim()) { // 连接异常中断,抛出明确错误,并包含断点信息 const errorContext = { dataCount, lastEventType, bufferLength: buffer.length, bufferPreview: buffer.substring(0, 200), }; const errorMessage = `[API_ERROR] [RETRIABLE] Anthropic stream terminated unexpectedly with incomplete data`; logger.error(errorMessage, errorContext); throw new Error( `${errorMessage}. Context: ${JSON.stringify(errorContext)}`, ); } break; // 正常结束 } buffer += decoder.decode(value, {stream: true}); const lines = buffer.split('\n'); buffer = lines.pop() || ''; for (const line of lines) { const trimmed = line.trim(); if (!trimmed || trimmed.startsWith(':')) continue; if (trimmed === 'data: [DONE]' || trimmed === 'data:[DONE]') { return; } // 处理 "event: " 和 "event:" 两种格式 if (trimmed.startsWith('event:')) { // 记录事件类型用于断点恢复 lastEventType = trimmed.startsWith('event: ') ? trimmed.slice(7) : trimmed.slice(6); continue; } // 处理 "data: " 和 "data:" 两种格式 if (trimmed.startsWith('data:')) { const data = trimmed.startsWith('data: ') ? trimmed.slice(6) : trimmed.slice(5); const parseResult = parseJsonWithFix(data, { toolName: 'SSE stream', logWarning: false, logError: true, }); if (parseResult.success) { const event = parseResult.data; const hasBusinessDelta = (event?.type === 'content_block_start' && event?.content_block?.type === 'tool_use') || (event?.type === 'content_block_delta' && ((event?.delta?.type === 'text_delta' && event?.delta?.text) || (event?.delta?.type === 'thinking_delta' && event?.delta?.thinking) || (event?.delta?.type === 'input_json_delta' && event?.delta?.partial_json))); if (hasBusinessDelta) { guard.touch(); } dataCount++; // yield前检查是否已被丢弃 if (!guard.isAbandoned()) { yield event; } } } } } } catch (error) { const {logger} = await import('../utils/core/logger.js'); // 增强错误日志,包含断点状态 const errorContext = { error: error instanceof Error ? error.message : 'Unknown error', dataCount, lastEventType, bufferLength: buffer.length, bufferPreview: buffer.substring(0, 200), }; logger.error( '[API_ERROR] [RETRIABLE] Anthropic SSE stream parsing error with checkpoint context:', errorContext, ); throw error; } finally { guard.dispose(); } } export async function* createStreamingAnthropicCompletion( options: AnthropicOptions, abortSignal?: AbortSignal, onRetry?: (error: Error, attempt: number, nextDelay: number) => void, ): AsyncGenerator { yield* withRetryGenerator( async function* () { // Load configuration: if configProfile is specified, load it; otherwise use main config let config: ReturnType; if (options.configProfile) { try { const {loadProfile} = await import( '../utils/config/configManager.js' ); const profileConfig = loadProfile(options.configProfile); if (profileConfig?.snowcfg) { config = profileConfig.snowcfg; } else { // Profile not found, fallback to main config config = getSnowConfig(); logger.warn( `Profile ${options.configProfile} not found, using main config`, ); } } catch (error) { // If loading profile fails, fallback to main config config = getSnowConfig(); logger.warn( `Failed to load profile ${options.configProfile}, using main config:`, error, ); } } else { // No configProfile specified, use main config config = getSnowConfig(); } // Get system prompt (with custom override support) let customSystemPromptContent: string[] | undefined; if (options.customSystemPromptId) { const {getSystemPromptConfig} = await import( '../utils/config/apiConfig.js' ); const systemPromptConfig = getSystemPromptConfig(); const customPrompt = systemPromptConfig?.prompts.find( p => p.id === options.customSystemPromptId, ); if (customPrompt?.content) { customSystemPromptContent = [customPrompt.content]; } } // 如果没有显式的 customSystemPromptId，则按当前配置（含 profile 覆盖）解析 customSystemPromptContent ||= getCustomSystemPromptForConfig(config); const {system, messages} = convertToAnthropicMessages( options.messages, options.includeBuiltinSystemPrompt !== false, customSystemPromptContent, config.anthropicCacheTTL || '5m', options.disableThinking || false, options.planMode || false, options.vulnerabilityHuntingMode || false, options.toolSearchDisabled || false, options.teamMode || false, ); // Use persistent userId that remains the same until application restart const userId = getPersistentUserId(); const requestBody: any = { model: options.model || config.advancedModel, max_tokens: options.max_tokens || 4096, system, messages, tools: convertToolsToAnthropic(options.tools), metadata: { user_id: userId, }, stream: true, }; if (config.anthropicSpeed) { requestBody.speed = config.anthropicSpeed; } // Add thinking configuration if enabled and not explicitly disabled // When thinking is enabled, temperature must be 1 // Note: agents and other internal tools should set disableThinking=true // Debug: Log thinking decision for troubleshooting if (config.thinking) { logger.debug('Thinking config check:', { configThinking: !!config.thinking, disableThinking: options.disableThinking, willEnableThinking: config.thinking && !options.disableThinking, }); if (config.thinking && !options.disableThinking) { if (config.thinking.type === 'adaptive') { requestBody.thinking = { type: 'adaptive', }; requestBody.output_config = { effort: config.thinking.effort || 'high', }; } else { requestBody.thinking = config.thinking; } requestBody.temperature = 1; } } // Use custom headers from options if provided, otherwise get from current config (supports profile override) const customHeaders = options.customHeaders || getCustomHeadersForConfig(config); // Prepare headers const headers: Record = { 'Content-Type': 'application/json', 'x-api-key': config.apiKey, Authorization: `Bearer ${config.apiKey}`, 'x-snow': getVersionHeader(), ...customHeaders, }; // Add beta parameter if configured // if (config.anthropicBeta) { // headers['anthropic-beta'] = 'prompt-caching-2024-07-31'; // } // Use configured baseUrl or default Anthropic URL //移除末尾斜杠，避免拼接时出现双斜杠（如 /v1//messages） const baseUrl = ( config.baseUrl && config.baseUrl !== 'https://api.openai.com/v1' ? config.baseUrl : 'https://api.anthropic.com/v1' ).replace(/\/+$/, ''); const url = config.anthropicBeta ? `${baseUrl}/messages?beta=true` : `${baseUrl}/messages`; const fetchOptions = addProxyToFetchOptions(url, { method: 'POST', headers, body: JSON.stringify(requestBody), signal: abortSignal, }); let response: Response; try { response = await fetch(url, fetchOptions); } catch (error) { // 捕获 fetch 底层错误（网络错误、连接超时等） const errorMessage = error instanceof Error ? error.message : String(error); throw new Error( `Anthropic API fetch failed: ${errorMessage}\n` + `URL: ${url}\n` + `Model: ${requestBody.model}\n` + `Error type: ${ error instanceof TypeError ? 'Network/Connection Error' : 'Unknown Error' }\n` + `Possible causes: Network unavailable, DNS resolution failed, proxy issues, or server unreachable`, ); } if (!response.ok) { const errorText = await response.text(); throw new Error( `Anthropic API error: ${response.status} ${response.statusText} - ${errorText}`, ); } if (!response.body) { throw new Error('No response body from Anthropic API'); } let contentBuffer = ''; let thinkingTextBuffer = ''; // Accumulate thinking text content let thinkingSignature = ''; // Accumulate thinking signature let toolCallsBuffer: Map< string, { id: string; type: 'function'; function: { name: string; arguments: string; }; } > = new Map(); let hasToolCalls = false; let usageData: UsageInfo | undefined; let blockIndexToId: Map = new Map(); let blockIndexToType: Map = new Map(); // Track block types (text, thinking, tool_use) let completedToolBlocks = new Set(); // Track which tool blocks have finished streaming const idleTimeoutMs = (config.streamIdleTimeoutSec ?? 180) * 1000; for await (const event of parseSSEStream( response.body.getReader(), abortSignal, idleTimeoutMs, )) { // abort 由 parseSSEStream 统一处理,避免重复分支导致行为漂移 if (event.type === 'content_block_start') { const block = event.content_block; const blockIndex = event.index; // Track block type for later reference blockIndexToType.set(blockIndex, block.type); if (block.type === 'tool_use') { hasToolCalls = true; blockIndexToId.set(blockIndex, block.id); toolCallsBuffer.set(block.id, { id: block.id, type: 'function', function: { name: block.name, arguments: '', }, }); yield { type: 'tool_call_delta', delta: block.name, }; } // Handle thinking block start (Extended Thinking feature) else if (block.type === 'thinking') { // Thinking block started - emit reasoning_started event yield { type: 'reasoning_started', }; } } else if (event.type === 'content_block_delta') { const delta = event.delta; if (delta.type === 'text_delta') { const text = delta.text; contentBuffer += text; yield { type: 'content', content: text, }; } // Handle thinking_delta (Extended Thinking feature) // Emit reasoning_delta event for thinking content if (delta.type === 'thinking_delta') { const thinkingText = delta.thinking; thinkingTextBuffer += thinkingText; // Accumulate thinking text yield { type: 'reasoning_delta', delta: thinkingText, }; } // Handle signature_delta (Extended Thinking feature) // Signature is required for thinking blocks if (delta.type === 'signature_delta') { thinkingSignature += delta.signature; // Accumulate signature } if (delta.type === 'input_json_delta') { const jsonDelta = delta.partial_json; const blockIndex = event.index; const toolId = blockIndexToId.get(blockIndex); if (toolId) { const toolCall = toolCallsBuffer.get(toolId); if (toolCall) { // Filter out any XML-like tags that might be mixed in the JSON delta // This can happen when the model output contains XML that gets interpreted as JSON const cleanedDelta = jsonDelta.replace( /<\/?parameter[^>]*>/g, '', ); if (cleanedDelta) { toolCall.function.arguments += cleanedDelta; yield { type: 'tool_call_delta', delta: cleanedDelta, }; } } } } } else if (event.type === 'content_block_stop') { // Mark this block as completed const blockIndex = event.index; const toolId = blockIndexToId.get(blockIndex); if (toolId) { completedToolBlocks.add(toolId); } } else if (event.type === 'message_start') { if (event.message.usage) { const cacheCreation = (event.message.usage as any).cache_creation_input_tokens || 0; const cacheRead = (event.message.usage as any).cache_read_input_tokens || 0; usageData = { prompt_tokens: event.message.usage.input_tokens || 0, completion_tokens: event.message.usage.output_tokens || 0, total_tokens: (event.message.usage.input_tokens || 0) + (event.message.usage.output_tokens || 0) + cacheCreation + cacheRead, cache_creation_input_tokens: cacheCreation || undefined, cache_read_input_tokens: cacheRead || undefined, }; } } else if (event.type === 'message_delta') { if (event.usage) { if (!usageData) { usageData = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0, }; } // Update prompt_tokens if present in message_delta if (event.usage.input_tokens !== undefined) { usageData.prompt_tokens = event.usage.input_tokens; } usageData.completion_tokens = event.usage.output_tokens || 0; if ( (event.usage as any).cache_creation_input_tokens !== undefined ) { usageData.cache_creation_input_tokens = ( event.usage as any ).cache_creation_input_tokens; } if ((event.usage as any).cache_read_input_tokens !== undefined) { usageData.cache_read_input_tokens = ( event.usage as any ).cache_read_input_tokens; } usageData.total_tokens = usageData.prompt_tokens + usageData.completion_tokens + (usageData.cache_creation_input_tokens || 0) + (usageData.cache_read_input_tokens || 0); } } } if (hasToolCalls && toolCallsBuffer.size > 0) { const toolCalls = Array.from(toolCallsBuffer.values()); for (const toolCall of toolCalls) { // Normalize the arguments let args = toolCall.function.arguments.trim(); // If arguments is empty, use empty object if (!args) { args = '{}'; } // Try to parse the JSON using the unified parseJsonWithFix utility if (completedToolBlocks.has(toolCall.id)) { // Tool block was completed, parse with fix and logging const parseResult = parseJsonWithFix(args, { toolName: toolCall.function.name, fallbackValue: {}, logWarning: true, logError: true, }); // Use the parsed data or fallback value toolCall.function.arguments = JSON.stringify(parseResult.data); } else { // Tool block wasn't completed, likely interrupted stream // Try to parse without logging errors (incomplete data is expected) const parseResult = parseJsonWithFix(args, { toolName: toolCall.function.name, fallbackValue: {}, logWarning: false, logError: false, }); if (!parseResult.success) { logger.warn( `Warning: Tool call ${toolCall.function.name} (${toolCall.id}) was incomplete. Using fallback data.`, ); } toolCall.function.arguments = JSON.stringify(parseResult.data); } } yield { type: 'tool_calls', tool_calls: toolCalls, }; } if (usageData) { // Save usage to file system at API layer saveUsageToFile(options.model, usageData); yield { type: 'usage', usage: usageData, }; } // Return complete thinking block with signature if thinking content exists const thinkingBlock = thinkingTextBuffer ? { type: 'thinking' as const, thinking: thinkingTextBuffer, signature: thinkingSignature || '', } : undefined; yield { type: 'done', thinking: thinkingBlock, }; }, { abortSignal, onRetry, }, ); } ================================================ FILE: source/api/chat.ts ================================================ import { getSnowConfig, getCustomHeadersForConfig, getCustomSystemPromptForConfig, } from '../utils/config/apiConfig.js'; import {getSystemPromptForMode} from '../prompt/systemPrompt.js'; import { withRetryGenerator, parseJsonWithFix, } from '../utils/core/retryUtils.js'; import { createIdleTimeoutGuard, StreamIdleTimeoutError, } from '../utils/core/streamGuards.js'; import type { ChatMessage, ChatCompletionTool, ToolCall, UsageInfo, ImageContent, } from './types.js'; import {addProxyToFetchOptions} from '../utils/core/proxyUtils.js'; import {saveUsageToFile} from '../utils/core/usageLogger.js'; import {getVersionHeader} from '../utils/core/version.js'; export type { ChatMessage, ChatCompletionTool, ToolCall, UsageInfo, ImageContent, }; export interface ChatCompletionOptions { model: string; messages: ChatMessage[]; stream?: boolean; temperature?: number; max_tokens?: number; tools?: ChatCompletionTool[]; tool_choice?: | 'auto' | 'none' | 'required' | {type: 'function'; function: {name: string}}; includeBuiltinSystemPrompt?: boolean; // 控制是否添加内置系统提示词（默认 true） disableThinking?: boolean; // 禁用思考功能（用于 agents 等场景，默认 false） planMode?: boolean; // 启用 Plan 模式（使用 Plan 模式系统提示词） vulnerabilityHuntingMode?: boolean; // 启用漏洞狩猎模式（使用漏洞狩猎模式系统提示词） teamMode?: boolean; // 启用 Team 模式（使用 Team 模式系统提示词） toolSearchDisabled?: boolean; // 工具搜索已关闭（全量加载工具） // Sub-agent configuration overrides configProfile?: string; // 子代理配置文件名（覆盖模型等设置） customSystemPromptId?: string; // 自定义系统提示词 ID customHeaders?: Record; // 自定义请求头 } export interface ChatCompletionChunk { id: string; object: 'chat.completion.chunk'; created: number; model: string; choices: Array<{ index: number; delta: { role?: string; content?: string; tool_calls?: Array<{ index?: number; id?: string; type?: 'function'; function?: { name?: string; arguments?: string; }; }>; }; finish_reason?: string | null; }>; } export interface ChatCompletionMessageParam { role: 'system' | 'user' | 'assistant' | 'tool'; content: | string | Array<{ type: 'text' | 'image_url'; text?: string; image_url?: {url: string}; }>; tool_call_id?: string; tool_calls?: ToolCall[]; } /** * Convert internal ChatMessage to OpenAI's message format * Supports both text-only and multimodal (text + images) messages * System prompt handling: * 1. If custom system prompt provided: place it as system message, default as user message * 2. If no custom system prompt: use default as system * @param messages - The messages to convert * @param includeBuiltinSystemPrompt - Whether to include builtin system prompt (default true) * @param customSystemPromptOverride - Optional custom system prompt content (for sub-agents) */ function convertToOpenAIMessages( messages: ChatMessage[], includeBuiltinSystemPrompt: boolean = true, customSystemPromptOverride?: string[], planMode: boolean = false, vulnerabilityHuntingMode: boolean = false, toolSearchDisabled: boolean = false, teamMode: boolean = false, thinkingEnabled: boolean = false, ): ChatCompletionMessageParam[] { const customSystemPrompts = customSystemPromptOverride; let result = messages.map(msg => { // 如果消息包含图片，使用 content 数组格式 if (msg.role === 'user' && msg.images && msg.images.length > 0) { const contentParts: Array<{ type: 'text' | 'image_url'; text?: string; image_url?: {url: string}; }> = []; // 添加文本内容 if (msg.content) { contentParts.push({ type: 'text', text: msg.content, }); } // 添加图片内容 for (const image of msg.images) { contentParts.push({ type: 'image_url', image_url: { url: image.data, // Base64 data URL }, }); } return { role: 'user', content: contentParts, } as ChatCompletionMessageParam; } const baseMessage = { role: msg.role, content: msg.content, }; if (msg.role === 'assistant' && msg.tool_calls) { const result: any = { ...baseMessage, tool_calls: msg.tool_calls, }; const rc = (msg as any).reasoning_content; if (rc !== undefined && rc !== null) { result.reasoning_content = rc; } else if (thinkingEnabled) { result.reasoning_content = ''; } return result as ChatCompletionMessageParam; } if (msg.role === 'tool' && msg.tool_call_id) { // Handle multimodal tool results with images if (msg.images && msg.images.length > 0) { const content: Array<{ type: 'text' | 'image_url'; text?: string; image_url?: {url: string}; }> = []; // Add text content if (msg.content) { content.push({ type: 'text', text: msg.content, }); } // Add images as base64 data URLs for (const image of msg.images) { const imageUrl = /^data:/i.test(image.data) || /^https?:\/\//i.test(image.data) ? image.data : `data:${image.mimeType};base64,${image.data}`; content.push({ type: 'image_url', image_url: { url: imageUrl, }, }); } return { role: 'tool', content, tool_call_id: msg.tool_call_id, } as ChatCompletionMessageParam; } return { role: 'tool', content: msg.content, tool_call_id: msg.tool_call_id, } as ChatCompletionMessageParam; } if (msg.role === 'assistant') { const rc = (msg as any).reasoning_content; if (rc !== undefined && rc !== null) { return { ...baseMessage, reasoning_content: rc, } as any; } if (thinkingEnabled) { return { ...baseMessage, reasoning_content: '', } as any; } } return baseMessage as ChatCompletionMessageParam; }); // 如果第一条消息已经是 system 消息，跳过 if (result.length > 0 && result[0]?.role === 'system') { return result; } // 如果配置了自定义系统提示词（最高优先级，始终添加） if (customSystemPrompts && customSystemPrompts.length > 0) { if (includeBuiltinSystemPrompt) { // 自定义系统提示词作为 system 消息（多条独立内容块），默认系统提示词作为第一条 user 消息 result = [ { role: 'system', content: customSystemPrompts.map(text => ({ type: 'text' as const, text, })), } as ChatCompletionMessageParam, { role: 'user', content: getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ), } as ChatCompletionMessageParam, ...result, ]; } else { // 只添加自定义系统提示词 result = [ { role: 'system', content: customSystemPrompts.map(text => ({ type: 'text' as const, text, })), } as ChatCompletionMessageParam, ...result, ]; } } else if (includeBuiltinSystemPrompt) { // 没有自定义系统提示词，但需要添加默认系统提示词 result = [ { role: 'system', content: getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ), } as ChatCompletionMessageParam, ...result, ]; } return result; } export function resetApiClient(): void { // No-op: kept for backward compatibility } export interface StreamChunk { type: | 'content' | 'tool_calls' | 'tool_call_delta' | 'reasoning_delta' | 'reasoning_started' | 'done' | 'usage'; content?: string; tool_calls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string; }; }>; delta?: string; // For tool call streaming chunks or reasoning content usage?: UsageInfo; // Token usage information reasoning_content?: string; // Complete reasoning content for DeepSeek R1 models } /** * Parse Server-Sent Events (SSE) stream */ async function* parseSSEStream( reader: ReadableStreamDefaultReader, abortSignal?: AbortSignal, idleTimeoutMs?: number, ): AsyncGenerator { const decoder = new TextDecoder(); let buffer = ''; let dataCount = 0; // 记录成功解析的数据块数量 let lastEventType = ''; // 记录最后一个事件类型 // 创建空闲超时保护器 const guard = createIdleTimeoutGuard({ reader, idleTimeoutMs, onTimeout: () => { throw new StreamIdleTimeoutError( `No data received for ${idleTimeoutMs}ms`, idleTimeoutMs, ); }, }); try { while (true) { // 用户主动中断时立即标记丢弃,避免延迟消息外泄 if (abortSignal?.aborted) { guard.abandon(); return; } const {done, value} = await reader.read(); // 检查是否有超时错误需要在读取循环中抛出(确保被正确的 try/catch 捕获) const timeoutError = guard.getTimeoutError(); if (timeoutError) { throw timeoutError; } // 检查是否已被丢弃(竞态条件防护) if (guard.isAbandoned()) { continue; } if (done) { // 连接异常中断时,残留半包不应被静默丢弃,应抛出可重试错误 if (buffer.trim()) { // 连接异常中断,抛出明确错误,包含更详细的断点信息 const errorContext = { dataCount, lastEventType, bufferLength: buffer.length, bufferPreview: buffer.substring(0, 200), }; const errorMessage = `[API_ERROR] [RETRIABLE] OpenAI stream terminated unexpectedly with incomplete data`; throw new Error( `${errorMessage}. Context: ${JSON.stringify(errorContext)}`, ); } break; // 正常结束 } buffer += decoder.decode(value, {stream: true}); const lines = buffer.split('\n'); buffer = lines.pop() || ''; for (const line of lines) { const trimmed = line.trim(); if (!trimmed || trimmed.startsWith(':')) continue; if (trimmed === 'data: [DONE]' || trimmed === 'data:[DONE]') { return; } // Handle both "event: " and "event:" formats if (trimmed.startsWith('event:')) { // 记录事件类型用于断点恢复 lastEventType = trimmed.startsWith('event: ') ? trimmed.slice(7) : trimmed.slice(6); continue; } // Handle both "data: " and "data:" formats if (trimmed.startsWith('data:')) { const data = trimmed.startsWith('data: ') ? trimmed.slice(6) : trimmed.slice(5); const parseResult = parseJsonWithFix(data, { toolName: 'SSE stream', logWarning: false, logError: true, }); if (parseResult.success) { const chunk = parseResult.data; const hasBusinessDelta = !!chunk?.choices?.some((choice: any) => { const delta = choice?.delta; return Boolean( delta?.content || delta?.reasoning_content || (delta?.tool_calls && delta.tool_calls.length > 0), ); }); if (hasBusinessDelta) { guard.touch(); } dataCount++; // yield 前检查是否已被丢弃(竞态条件防护) if (!guard.isAbandoned()) { yield chunk; } } } } } } catch (error) { const {logger} = await import('../utils/core/logger.js'); // 增强错误日志,包含断点状态 const errorContext = { error: error instanceof Error ? error.message : 'Unknown error', dataCount, lastEventType, bufferLength: buffer.length, bufferPreview: buffer.substring(0, 200), }; logger.error( '[API_ERROR] [RETRIABLE] OpenAI SSE stream parsing error with checkpoint context:', errorContext, ); throw error; } finally { // 清理 idle timeout 定时器 guard.dispose(); } } /** * Simple streaming chat completion - only handles OpenAI interaction * Tool execution should be handled by the caller */ export async function* createStreamingChatCompletion( options: ChatCompletionOptions, abortSignal?: AbortSignal, onRetry?: (error: Error, attempt: number, nextDelay: number) => void, ): AsyncGenerator { // Load configuration: if configProfile is specified, load it; otherwise use main config let config: ReturnType; if (options.configProfile) { try { const {loadProfile} = await import('../utils/config/configManager.js'); const profileConfig = loadProfile(options.configProfile); if (profileConfig?.snowcfg) { config = profileConfig.snowcfg; } else { // Profile not found, fallback to main config config = getSnowConfig(); const {logger} = await import('../utils/core/logger.js'); logger.warn( `Profile ${options.configProfile} not found, using main config`, ); } } catch (error) { // If loading profile fails, fallback to main config config = getSnowConfig(); const {logger} = await import('../utils/core/logger.js'); logger.warn( `Failed to load profile ${options.configProfile}, using main config:`, error, ); } } else { // No configProfile specified, use main config config = getSnowConfig(); } // Get system prompt (with custom override support) let customSystemPromptContent: string[] | undefined; if (options.customSystemPromptId) { const {getSystemPromptConfig} = await import( '../utils/config/apiConfig.js' ); const systemPromptConfig = getSystemPromptConfig(); const customPrompt = systemPromptConfig?.prompts.find( p => p.id === options.customSystemPromptId, ); if (customPrompt?.content) { customSystemPromptContent = [customPrompt.content]; } } // 如果没有显式的 customSystemPromptId，则按当前配置（含 profile 覆盖）解析 customSystemPromptContent ||= getCustomSystemPromptForConfig(config); // 使用重试包装生成器 const thinkingEnabled = !!( config.chatThinking?.enabled && !options.disableThinking ); yield* withRetryGenerator( async function* () { const requestBody: Record = { model: options.model || config.advancedModel, messages: convertToOpenAIMessages( options.messages, options.includeBuiltinSystemPrompt !== false, // 默认为 true customSystemPromptContent, options.planMode || false, options.vulnerabilityHuntingMode || false, options.toolSearchDisabled || false, options.teamMode || false, thinkingEnabled, ), stream: true, stream_options: {include_usage: true}, temperature: options.temperature || 0.7, max_tokens: options.max_tokens, tools: options.tools, tool_choice: options.tool_choice, }; if (thinkingEnabled) { requestBody['thinking'] = {type: 'enabled'}; if (config.chatThinking?.reasoning_effort) { requestBody['reasoning_effort'] = config.chatThinking.reasoning_effort; } } const url = `${config.baseUrl}/chat/completions`; // Use custom headers from options if provided, otherwise get from current config (supports profile override) const customHeaders = options.customHeaders || getCustomHeadersForConfig(config); const fetchOptions = addProxyToFetchOptions(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${config.apiKey}`, 'x-snow': getVersionHeader(), ...customHeaders, }, body: JSON.stringify(requestBody), signal: abortSignal, }); let response: Response; try { response = await fetch(url, fetchOptions); } catch (error) { // 捕获 fetch 底层错误（网络错误、连接超时等） const errorMessage = error instanceof Error ? error.message : String(error); throw new Error( `OpenAI API fetch failed: ${errorMessage}\n` + `URL: ${url}\n` + `Model: ${requestBody['model']}\n` + `Error type: ${ error instanceof TypeError ? 'Network/Connection Error' : 'Unknown Error' }\n` + `Possible causes: Network unavailable, DNS resolution failed, proxy issues, or server unreachable`, ); } if (!response.ok) { const errorText = await response.text(); throw new Error( `OpenAI API error: ${response.status} ${response.statusText} - ${errorText}`, ); } if (!response.body) { throw new Error('No response body from OpenAI API'); } let contentBuffer = ''; let toolCallsBuffer: {[index: number]: any} = {}; let hasToolCalls = false; let usageData: UsageInfo | undefined; let reasoningStarted = false; // Track if reasoning has started let reasoningContentBuffer = ''; // Accumulate complete reasoning content for saving const idleTimeoutMs = (config.streamIdleTimeoutSec ?? 180) * 1000; for await (const chunk of parseSSEStream( response.body.getReader(), abortSignal, idleTimeoutMs, )) { // abort 由 parseSSEStream 统一处理,避免重复分支导致行为漂移 // Capture usage information if available (usually in the last chunk) const usageValue = (chunk as any).usage; if (usageValue !== null && usageValue !== undefined) { usageData = { prompt_tokens: usageValue.prompt_tokens || 0, completion_tokens: usageValue.completion_tokens || 0, total_tokens: usageValue.total_tokens || 0, // OpenAI Chat API: cached_tokens in prompt_tokens_details cached_tokens: usageValue.prompt_tokens_details?.cached_tokens, }; } // Skip content processing if no choices (but usage is already captured above) const choice = chunk.choices?.[0]; if (!choice) { // If this chunk has usage but no choices, it's the final usage-only chunk // Some APIs send this as the last chunk after finish_reason if ((chunk as any).usage) { // Final chunk with usage, exit the loop break; } continue; } // Stream content chunks const content = choice.delta?.content; if (content) { contentBuffer += content; yield { type: 'content', content, }; } // Stream reasoning content (for o1 models, etc.) // Note: reasoning_content is NOT included in the response, only counted for tokens const reasoningContent = (choice.delta as any)?.reasoning_content; if (reasoningContent) { // Accumulate reasoning content for saving to message reasoningContentBuffer += reasoningContent; // Emit reasoning_started event on first reasoning content if (!reasoningStarted) { reasoningStarted = true; yield { type: 'reasoning_started', }; } yield { type: 'reasoning_delta', delta: reasoningContent, }; } // Accumulate tool calls and stream deltas const deltaToolCalls = choice.delta?.tool_calls; if (deltaToolCalls) { hasToolCalls = true; for (const deltaCall of deltaToolCalls) { const index = deltaCall.index ?? 0; if (!toolCallsBuffer[index]) { toolCallsBuffer[index] = { id: '', type: 'function', function: { name: '', arguments: '', }, }; } if (deltaCall.id) { toolCallsBuffer[index].id = deltaCall.id; } // Yield tool call deltas for token counting let deltaText = ''; if (deltaCall.function?.name) { toolCallsBuffer[index].function.name += deltaCall.function.name; deltaText += deltaCall.function.name; } if (deltaCall.function?.arguments) { toolCallsBuffer[index].function.arguments += deltaCall.function.arguments; deltaText += deltaCall.function.arguments; } // Stream the delta to frontend for real-time token counting if (deltaText) { yield { type: 'tool_call_delta', delta: deltaText, }; } } } if (choice.finish_reason) { // Continue to wait for the final usage chunk. // Some APIs send finish_reason first, then usage-only chunk. // Don't break immediately as some APIs stream usage in each chunk. continue; } } // If there are tool calls, yield them if (hasToolCalls) { yield { type: 'tool_calls', tool_calls: Object.values(toolCallsBuffer), }; } // Yield usage information if available if (usageData) { // Save usage to file system at API layer saveUsageToFile(options.model, usageData); yield { type: 'usage', usage: usageData, }; } // Signal completion with reasoning content (for DeepSeek R1, etc.) yield { type: 'done', reasoning_content: reasoningContentBuffer || undefined, }; }, { abortSignal, onRetry, }, ); } export function validateChatOptions(options: ChatCompletionOptions): string[] { const errors: string[] = []; if (!options.model || options.model.trim().length === 0) { errors.push('Model is required'); } if (!options.messages || options.messages.length === 0) { errors.push('At least one message is required'); } for (const message of options.messages || []) { if ( !message.role || !['system', 'user', 'assistant', 'tool'].includes(message.role) ) { errors.push('Invalid message role'); } // Tool messages must have tool_call_id if (message.role === 'tool' && !message.tool_call_id) { errors.push('Tool messages must have tool_call_id'); } // Content can be empty for tool calls if ( message.role !== 'tool' && (!message.content || message.content.trim().length === 0) ) { errors.push('Message content cannot be empty (except for tool messages)'); } } return errors; } ================================================ FILE: source/api/embedding.ts ================================================ import {loadCodebaseConfig} from '../utils/config/codebaseConfig.js'; import {logger} from '../utils/core/logger.js'; import {addProxyToFetchOptions} from '../utils/core/proxyUtils.js'; import {getVersionHeader} from '../utils/core/version.js'; export interface EmbeddingOptions { model?: string; input: string[]; baseUrl?: string; apiKey?: string; dimensions?: number; task?: string; } export interface EmbeddingResponse { model: string; object: string; usage: { total_tokens: number; prompt_tokens: number; }; data: Array<{ object: string; index: number; embedding: number[]; }>; } type OllamaEmbeddingsMode = 'openai' | 'ollama'; interface OllamaEmbeddingResponse { model: string; embeddings: number[][]; total_duration?: number; load_duration?: number; prompt_eval_count?: number; } interface GeminiEmbeddingResponse { embedding?: { values: number[]; }; embeddings?: Array<{ values: number[]; }>; } function isOpenAIEmbeddingsResponse(data: any): data is EmbeddingResponse { return ( Boolean(data) && data.object === 'list' && Array.isArray(data.data) && data.data.every( (item: any) => Boolean(item) && item.object === 'embedding' && typeof item.index === 'number' && Array.isArray(item.embedding), ) ); } function isOllamaEmbedResponse(data: any): data is OllamaEmbeddingResponse { return ( Boolean(data) && typeof data.model === 'string' && Array.isArray(data.embeddings) ); } function isGeminiEmbedResponse(data: any): data is GeminiEmbeddingResponse { return ( Boolean(data) && (Boolean(data.embedding?.values) || Boolean(data.embeddings)) ); } export function resolveOllamaEmbeddingsEndpoint(baseUrl: string): { url: string; mode: OllamaEmbeddingsMode; } { const trimmed = baseUrl.trim().replace(/\/+$/, ''); if (trimmed.endsWith('/v1/embeddings')) { return {url: trimmed, mode: 'openai'}; } if (trimmed.endsWith('/api/embed')) { return {url: trimmed, mode: 'ollama'}; } if (trimmed.endsWith('/v1')) { return {url: `${trimmed}/embeddings`, mode: 'openai'}; } if (trimmed.endsWith('/api')) { return {url: `${trimmed}/embed`, mode: 'ollama'}; } // If the user passes a fully-qualified endpoint, try to infer mode. if (trimmed.endsWith('/embeddings')) { return {url: trimmed, mode: 'openai'}; } if (trimmed.endsWith('/embed')) { return {url: trimmed, mode: 'ollama'}; } // Default to OpenAI-compatible endpoint for better interoperability. return {url: `${trimmed}/v1/embeddings`, mode: 'openai'}; } function resolveOpenAICompatibleEmbeddingsEndpoint(baseUrl: string): string { const trimmed = baseUrl.trim().replace(/\/+$/, ''); if (trimmed.endsWith('/v1/embeddings')) { return trimmed; } // Allow users to pass a fully-qualified endpoint. if (trimmed.endsWith('/embeddings')) { return trimmed; } if (trimmed.endsWith('/v1')) { return `${trimmed}/embeddings`; } // Most OpenAI-compatible providers use /v1/embeddings. return `${trimmed}/v1/embeddings`; } function warnOnDimensionMismatch(params: { expectedDimensions?: number; actualDimensions?: number; model: string; url: string; mode: OllamaEmbeddingsMode; }): void { const {expectedDimensions, actualDimensions, model, url, mode} = params; if (!expectedDimensions || !actualDimensions) { return; } if (expectedDimensions === actualDimensions) { return; } logger.warn( `Embedding dimension mismatch (expected ${expectedDimensions}, got ${actualDimensions}). Some providers ignore 'dimensions'.`, { model, url, mode, expectedDimensions, actualDimensions, }, ); } function normalizeOllamaResponse(params: { data: unknown; mode: OllamaEmbeddingsMode; model: string; expectedDimensions?: number; url: string; }): EmbeddingResponse { const {data, mode, model, expectedDimensions, url} = params; // Some Ollama deployments return OpenAI-compatible format from /v1/embeddings. if (isOpenAIEmbeddingsResponse(data)) { const actualDimensions = Array.isArray(data.data) && data.data.length > 0 ? data.data[0]?.embedding?.length : undefined; warnOnDimensionMismatch({ expectedDimensions, actualDimensions, model, url, mode, }); return data; } // Ollama native response format from /api/embed. if (isOllamaEmbedResponse(data)) { const actualDimensions = Array.isArray(data.embeddings) && data.embeddings.length > 0 ? data.embeddings[0]?.length : undefined; warnOnDimensionMismatch({ expectedDimensions, actualDimensions, model, url, mode, }); return { model: data.model, object: 'list', usage: { total_tokens: data.prompt_eval_count || 0, prompt_tokens: data.prompt_eval_count || 0, }, data: data.embeddings.map((embedding, index) => ({ object: 'embedding', index, embedding, })), }; } throw new Error( `Unexpected Ollama embeddings response format from ${url}. Try setting baseUrl to http://localhost:11434 (or /v1 for OpenAI-compatible mode).`, ); } function normalizeGeminiResponse(params: { data: unknown; model: string; expectedDimensions?: number; }): EmbeddingResponse { const {data, model, expectedDimensions} = params; if (!isGeminiEmbedResponse(data)) { throw new Error('Unexpected Gemini embeddings response format'); } // Handle single embedding response if (data.embedding?.values) { const actualDimensions = data.embedding.values.length; if (expectedDimensions && actualDimensions !== expectedDimensions) { logger.warn( `Gemini embedding dimension mismatch (expected ${expectedDimensions}, got ${actualDimensions})`, {model, expectedDimensions, actualDimensions}, ); } return { model, object: 'list', usage: { total_tokens: 0, prompt_tokens: 0, }, data: [ { object: 'embedding', index: 0, embedding: data.embedding.values, }, ], }; } // Handle batch embeddings response if (data.embeddings && Array.isArray(data.embeddings)) { const actualDimensions = data.embeddings.length > 0 ? data.embeddings[0]?.values?.length : undefined; if ( expectedDimensions && actualDimensions && actualDimensions !== expectedDimensions ) { logger.warn( `Gemini embedding dimension mismatch (expected ${expectedDimensions}, got ${actualDimensions})`, {model, expectedDimensions, actualDimensions}, ); } return { model, object: 'list', usage: { total_tokens: 0, prompt_tokens: 0, }, data: data.embeddings.map((emb, index) => ({ object: 'embedding', index, embedding: emb.values, })), }; } throw new Error('Gemini response missing embedding data'); } /** * Create embeddings for text array (single API call) * @param options Embedding options * @returns Embedding response with vectors */ export async function createEmbeddings( options: EmbeddingOptions, ): Promise { const config = loadCodebaseConfig(); // Use config defaults if not provided const model = options.model || config.embedding.modelName; const baseUrl = options.baseUrl || config.embedding.baseUrl; const apiKey = options.apiKey || config.embedding.apiKey; const dimensions = options.dimensions ?? config.embedding.dimensions; const {input, task} = options; if (!model) { throw new Error('Embedding model name is required'); } if (!baseUrl) { throw new Error('Embedding base URL is required'); } // API key is optional for local deployments (e.g., Ollama) // if (!apiKey) { // throw new Error('Embedding API key is required'); // } if (!input || input.length === 0) { throw new Error('Input texts are required'); } // Determine endpoint based on provider type const embeddingType = config.embedding.type || 'jina'; // Build request body based on provider type let requestBody: any; if (embeddingType === 'gemini') { // Gemini API format requestBody = { content: { parts: input.map(text => ({text})), }, }; if (task) { requestBody.taskType = task; } if (dimensions) { requestBody.output_dimensionality = dimensions; } } else { // OpenAI-compatible format (Jina, Ollama, Mistral, etc.) requestBody = { model, input, }; if (task) { requestBody.task = task; } if (dimensions) { if (embeddingType === 'mistral') { requestBody.output_dimension = dimensions; } else { requestBody.dimensions = dimensions; } } } let url: string; let ollamaMode: OllamaEmbeddingsMode | undefined; if (embeddingType === 'ollama') { const resolved = resolveOllamaEmbeddingsEndpoint(baseUrl); url = resolved.url; ollamaMode = resolved.mode; } else if (embeddingType === 'gemini') { // Gemini embeddings endpoint url = `${baseUrl.trim().replace(/\/+$/, '')}/models/${model}:embedContent`; } else { // Jina/OpenAI-compatible embeddings endpoint url = resolveOpenAICompatibleEmbeddingsEndpoint(baseUrl); } // Build headers - only include Authorization if API key is provided const headers: Record = { 'Content-Type': 'application/json', 'x-snow': getVersionHeader(), }; if (embeddingType === 'gemini') { // Gemini uses x-goog-api-key header instead of Authorization if (apiKey) { headers['x-goog-api-key'] = apiKey; } } else { if (apiKey) { headers['Authorization'] = `Bearer ${apiKey}`; } } const fetchOptions = addProxyToFetchOptions(url, { method: 'POST', headers, body: JSON.stringify(requestBody), }); const response = await fetch(url, fetchOptions); if (!response.ok) { const errorText = await response.text(); throw new Error(`Embedding API error (${response.status}): ${errorText}`); } const data = await response.json(); if (embeddingType === 'ollama') { return normalizeOllamaResponse({ data, mode: ollamaMode || 'openai', model, expectedDimensions: dimensions, url, }); } if (embeddingType === 'gemini') { return normalizeGeminiResponse({ data, model, expectedDimensions: dimensions, }); } return data as EmbeddingResponse; } /** * Create embedding for single text * @param text Single text to embed * @param options Optional embedding options * @returns Embedding vector */ export async function createEmbedding( text: string, options?: Partial, ): Promise { const response = await createEmbeddings({ input: [text], ...options, }); if (response.data.length === 0) { throw new Error('No embedding returned from API'); } return response.data[0]!.embedding; } ================================================ FILE: source/api/gemini.ts ================================================ import { getSnowConfig, getCustomSystemPromptForConfig, getCustomHeadersForConfig, } from '../utils/config/apiConfig.js'; import {getSystemPromptForMode} from '../prompt/systemPrompt.js'; import { withRetryGenerator, parseJsonWithFix, } from '../utils/core/retryUtils.js'; import { createIdleTimeoutGuard, StreamIdleTimeoutError, } from '../utils/core/streamGuards.js'; import type {ChatMessage, ChatCompletionTool, UsageInfo} from './types.js'; import {addProxyToFetchOptions} from '../utils/core/proxyUtils.js'; import {saveUsageToFile} from '../utils/core/usageLogger.js'; import {getVersionHeader} from '../utils/core/version.js'; export interface GeminiOptions { model: string; messages: ChatMessage[]; temperature?: number; tools?: ChatCompletionTool[]; includeBuiltinSystemPrompt?: boolean; // 控制是否添加内置系统提示词（默认 true） disableThinking?: boolean; // 禁用思考功能（用于 agents 等场景，默认 false） planMode?: boolean; // 启用 Plan 模式（使用 Plan 模式系统提示词） vulnerabilityHuntingMode?: boolean; // 启用漏洞狩猎模式（使用漏洞狩猎模式系统提示词） teamMode?: boolean; // 启用 Team 模式（使用 Team 模式系统提示词） toolSearchDisabled?: boolean; // 工具搜索已关闭（全量加载工具） // Sub-agent configuration overrides configProfile?: string; // 子代理配置文件名（覆盖模型等设置） customSystemPromptId?: string; // 自定义系统提示词 ID customHeaders?: Record; // 自定义请求头 } export interface GeminiStreamChunk { type: | 'content' | 'tool_calls' | 'tool_call_delta' | 'done' | 'usage' | 'reasoning_started' | 'reasoning_delta'; content?: string; tool_calls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string; }; }>; delta?: string; usage?: UsageInfo; thinking?: { type: 'thinking'; thinking: string; }; } // Deprecated: No longer used, kept for backward compatibility // @ts-ignore - Variable kept for backward compatibility with resetGeminiClient export let geminiConfig: { apiKey: string; baseUrl: string; customHeaders: Record; geminiThinking?: { enabled: boolean; budget: number; }; } | null = null; // Deprecated: Client reset is no longer needed with new config loading approach export function resetGeminiClient(): void { geminiConfig = null; } /** * 将图片数据转换为 Gemini API 所需的格式 * 处理三种情况： * 1. 远程 URL (http/https): 返回 fileData 格式 * 2. 已经是 data URL: 返回 inlineData 格式，并确保 data 带 data: 头 * 3. 纯 base64 数据: 使用提供的 mimeType 补齐 data URL 格式 */ function toGeminiImagePart(image: { data: string; mimeType?: string; }): | {inlineData: {mimeType: string; data: string}} | {fileData: {mimeType: string; fileUri: string}} | null { const data = image.data?.trim() || ''; if (!data) return null; // 远程 URL (http/https) - Gemini 支持通过 fileData 提供 if (/^https?:\/\//i.test(data)) { return { fileData: { mimeType: image.mimeType?.trim() || 'image/png', fileUri: data, }, }; } // 已经是 data URL 格式，直接使用原值作为 data const dataUrlMatch = data.match(/^data:([^;]+);base64,(.+)$/); if (dataUrlMatch) { return { inlineData: { mimeType: dataUrlMatch[1] || image.mimeType || 'image/png', data: image.data, // 保留完整的 data URL }, }; } // 纯 base64 数据，补齐 data URL 格式 const mimeType = image.mimeType?.trim() || 'image/png'; return { inlineData: { mimeType, data: `data:${mimeType};base64,${data}`, // 补齐 data: 头 }, }; } /** * Convert OpenAI-style tools to Gemini function declarations */ function convertToolsToGemini(tools?: ChatCompletionTool[]): any[] | undefined { if (!tools || tools.length === 0) { return undefined; } const functionDeclarations = tools .filter(tool => tool.type === 'function' && 'function' in tool) .map(tool => { if (tool.type === 'function' && 'function' in tool) { // Convert OpenAI parameters schema to Gemini format const params = tool.function.parameters as any; return { name: tool.function.name, description: tool.function.description || '', parametersJsonSchema: { type: 'object', properties: params.properties || {}, required: params.required || [], }, }; } throw new Error('Invalid tool format'); }); return [{functionDeclarations}]; } /** * Convert our ChatMessage format to Gemini's format * @param messages - The messages to convert * @param includeBuiltinSystemPrompt - Whether to include builtin system prompt (default true) */ function convertToGeminiMessages( messages: ChatMessage[], includeBuiltinSystemPrompt: boolean = true, customSystemPromptOverride?: string[], planMode: boolean = false, vulnerabilityHuntingMode: boolean = false, toolSearchDisabled: boolean = false, teamMode: boolean = false, ): { systemInstruction?: string[]; contents: any[]; } { const customSystemPrompts = customSystemPromptOverride; let systemInstruction: string[] | undefined; const contents: any[] = []; // Build tool_call_id to function_name mapping for parallel calls const toolCallIdToFunctionName = new Map(); for (let i = 0; i < messages.length; i++) { const msg = messages[i]; if (!msg) continue; // Extract system message as systemInstruction if (msg.role === 'system') { systemInstruction = [msg.content]; continue; } // Handle tool calls in assistant messages - build mapping first if ( msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0 ) { const parts: any[] = []; // Add thinking content first if exists (required by Gemini thinking mode) if (msg.thinking) { parts.push({ thought: true, text: msg.thinking.thinking, }); } // Add text content if exists if (msg.content) { parts.push({text: msg.content}); } // Add function calls and build mapping for (const toolCall of msg.tool_calls) { // Store tool_call_id -> function_name mapping toolCallIdToFunctionName.set(toolCall.id, toolCall.function.name); const argsParseResult = parseJsonWithFix(toolCall.function.arguments, { toolName: `Gemini function call: ${toolCall.function.name}`, fallbackValue: {}, logWarning: true, logError: true, }); const functionCallPart: any = { functionCall: { name: toolCall.function.name, args: argsParseResult.data, }, }; // Include thoughtSignature at part level (sibling to functionCall, not inside it) // According to Gemini docs, thoughtSignature is required for function calls in thinking mode const signature = (toolCall as any).thoughtSignature || (toolCall as any).thought_signature; if (signature) { functionCallPart.thoughtSignature = signature; } parts.push(functionCallPart); } contents.push({ role: 'model', parts, }); continue; } // Handle tool results - collect consecutive tool messages if (msg.role === 'tool') { // Collect all consecutive tool messages starting from current position const toolResponses: Array<{ tool_call_id: string; content: string; images?: any[]; }> = []; let j = i; while (j < messages.length && messages[j]?.role === 'tool') { const toolMsg = messages[j]; if (toolMsg) { toolResponses.push({ tool_call_id: toolMsg.tool_call_id || '', content: toolMsg.content || '', images: toolMsg.images, }); } j++; } // Update loop index to skip processed tool messages i = j - 1; // Build a single user message with multiple functionResponse parts const parts: any[] = []; for (const toolResp of toolResponses) { // Use tool_call_id to find the correct function name const functionName = toolCallIdToFunctionName.get(toolResp.tool_call_id) || 'unknown_function'; // Tool response must be a valid object for Gemini API let responseData: any; if (!toolResp.content) { responseData = {}; } else { let contentToParse = toolResp.content; // Sometimes the content is double-encoded as JSON // First, try to parse it once const firstParseResult = parseJsonWithFix(contentToParse, { toolName: 'Gemini tool response (first parse)', logWarning: false, logError: false, }); if ( firstParseResult.success && typeof firstParseResult.data === 'string' ) { // If it's a string, it might be double-encoded, try parsing again contentToParse = firstParseResult.data; } // Now parse or wrap the final content const finalParseResult = parseJsonWithFix(contentToParse, { toolName: 'Gemini tool response (final parse)', logWarning: false, logError: false, }); if (finalParseResult.success) { const parsed = finalParseResult.data; // If parsed result is an object (not array, not null), use it directly if ( typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ) { responseData = parsed; } else { // If it's a primitive, array, or null, wrap it responseData = {content: parsed}; } } else { // Not valid JSON, wrap the raw string responseData = {content: contentToParse}; } } // Add functionResponse part parts.push({ functionResponse: { name: functionName, response: responseData, }, }); // Handle images from tool result if (toolResp.images && toolResp.images.length > 0) { for (const image of toolResp.images) { const imagePart = toGeminiImagePart(image); if (imagePart) { parts.push(imagePart); } } } } // Push single user message with all function responses contents.push({ role: 'user', parts, }); continue; } // Build message parts for regular user/assistant messages const parts: any[] = []; // Add text content if (msg.content) { parts.push({text: msg.content}); } // Add images for user messages if (msg.role === 'user' && msg.images && msg.images.length > 0) { for (const image of msg.images) { const imagePart = toGeminiImagePart(image); if (imagePart) { parts.push(imagePart); } } } // Add to contents const role = msg.role === 'assistant' ? 'model' : 'user'; contents.push({role, parts}); } // Handle system instruction // 如果配置了自定义系统提示词（最高优先级，始终添加） if (customSystemPrompts && customSystemPrompts.length > 0) { systemInstruction = customSystemPrompts; if (includeBuiltinSystemPrompt) { // Prepend default system prompt as first user message contents.unshift({ role: 'user', parts: [ { text: getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ), }, ], }); } } else if (!systemInstruction && includeBuiltinSystemPrompt) { // 没有自定义系统提示词，但需要添加默认系统提示词 systemInstruction = [ getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ), ]; } return {systemInstruction, contents}; } /** * Create streaming chat completion using Gemini API */ export async function* createStreamingGeminiCompletion( options: GeminiOptions, abortSignal?: AbortSignal, onRetry?: (error: Error, attempt: number, nextDelay: number) => void, ): AsyncGenerator { // Load configuration: if configProfile is specified, load it; otherwise use main config let config: ReturnType; if (options.configProfile) { try { const {loadProfile} = await import('../utils/config/configManager.js'); const profileConfig = loadProfile(options.configProfile); if (profileConfig?.snowcfg) { config = profileConfig.snowcfg; } else { // Profile not found, fallback to main config config = getSnowConfig(); const {logger} = await import('../utils/core/logger.js'); logger.warn( `Profile ${options.configProfile} not found, using main config`, ); } } catch (error) { // If loading profile fails, fallback to main config config = getSnowConfig(); const {logger} = await import('../utils/core/logger.js'); logger.warn( `Failed to load profile ${options.configProfile}, using main config:`, error, ); } } else { // No configProfile specified, use main config config = getSnowConfig(); } // Get system prompt (with custom override support) let customSystemPromptContent: string[] | undefined; if (options.customSystemPromptId) { const {getSystemPromptConfig} = await import( '../utils/config/apiConfig.js' ); const systemPromptConfig = getSystemPromptConfig(); const customPrompt = systemPromptConfig?.prompts.find( p => p.id === options.customSystemPromptId, ); if (customPrompt?.content) { customSystemPromptContent = [customPrompt.content]; } } // 如果没有显式的 customSystemPromptId，则按当前配置（含 profile 覆盖）解析 customSystemPromptContent ||= getCustomSystemPromptForConfig(config); // 使用重试包装生成器 yield* withRetryGenerator( async function* () { const {systemInstruction, contents} = convertToGeminiMessages( options.messages, options.includeBuiltinSystemPrompt !== false, customSystemPromptContent, options.planMode || false, options.vulnerabilityHuntingMode || false, options.toolSearchDisabled || false, options.teamMode || false, ); // Build request payload const requestBody: any = { contents, systemInstruction: systemInstruction ? {parts: systemInstruction.map(text => ({text}))} : undefined, }; // Add thinking configuration if enabled and not disabled // Only include generationConfig when thinking is enabled if (config.geminiThinking?.enabled && !options.disableThinking) { requestBody.generationConfig = { thinkingConfig: { thinkingLevel: config.geminiThinking.thinkingLevel || 'high', }, }; } // Add tools if provided const geminiTools = convertToolsToGemini(options.tools); if (geminiTools) { requestBody.tools = geminiTools; } // Extract model name from options.model (e.g., "gemini-pro" or "models/gemini-pro") const effectiveModel = options.model || config.advancedModel || ''; const modelName = effectiveModel.startsWith('models/') ? effectiveModel : `models/${effectiveModel}`; // Use configured baseUrl or default Gemini URL const baseUrl = config.baseUrl && config.baseUrl !== 'https://api.openai.com/v1' ? config.baseUrl : 'https://generativelanguage.googleapis.com/v1beta'; const urlObj = new URL(`${baseUrl}/${modelName}:streamGenerateContent`); urlObj.searchParams.set('alt', 'sse'); const url = urlObj.toString(); // Use custom headers from options if provided, otherwise get from current config (supports profile override) const customHeaders = options.customHeaders || getCustomHeadersForConfig(config); const fetchOptions = addProxyToFetchOptions(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${config.apiKey}`, 'x-goog-api-key': config.apiKey, 'x-snow': getVersionHeader(), ...customHeaders, }, body: JSON.stringify(requestBody), signal: abortSignal, }); let response: Response; try { response = await fetch(url, fetchOptions); } catch (error) { // 捕获 fetch 底层错误（网络错误、连接超时等） const errorMessage = error instanceof Error ? error.message : String(error); throw new Error( `Gemini API fetch failed: ${errorMessage}\n` + `URL: ${url}\n` + `Model: ${effectiveModel}\n` + `Error type: ${ error instanceof TypeError ? 'Network/Connection Error' : 'Unknown Error' }\n` + `Possible causes: Network unavailable, DNS resolution failed, proxy issues, or server unreachable`, ); } if (!response.ok) { const errorText = await response.text(); throw new Error( `Gemini API error: ${response.status} ${response.statusText} - ${errorText}`, ); } if (!response.body) { throw new Error('No response body from Gemini API'); } let contentBuffer = ''; let thinkingTextBuffer = ''; // Accumulate thinking text content let sharedThoughtSignature: string | undefined; // Store first thoughtSignature for reuse let toolCallsBuffer: Array<{ id: string; type: 'function'; function: { name: string; arguments: string; }; thoughtSignature?: string; // For Gemini thinking mode }> = []; let hasToolCalls = false; let toolCallIndex = 0; let totalTokens = {prompt: 0, completion: 0, total: 0}; // Parse SSE stream const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ''; const idleTimeoutMs = (config.streamIdleTimeoutSec ?? 180) * 1000; // 创建空闲超时保护器 const guard = createIdleTimeoutGuard({ reader, idleTimeoutMs, onTimeout: () => { throw new StreamIdleTimeoutError( `No data received for ${idleTimeoutMs}ms`, idleTimeoutMs, ); }, }); try { while (true) { if (abortSignal?.aborted) { guard.abandon(); return; } const {done, value} = await reader.read(); // 检查是否有超时错误需要在读取循环中抛出(确保被正确的 try/catch 捕获) const timeoutError = guard.getTimeoutError(); if (timeoutError) { throw timeoutError; } // 检查是否已被丢弃(竞态条件防护) if (guard.isAbandoned()) { continue; } if (done) { // 连接异常中断时,残留半包不应被静默丢弃,应抛出可重试错误 if (buffer.trim()) { // 连接异常中断,抛出明确错误 const errorMsg = `[API_ERROR] [RETRIABLE] Gemini stream terminated unexpectedly with incomplete data`; const bufferPreview = buffer.substring(0, 100); throw new Error(`${errorMsg}: ${bufferPreview}...`); } break; // 正常结束 } buffer += decoder.decode(value, {stream: true}); const lines = buffer.split('\n'); buffer = lines.pop() || ''; for (const line of lines) { const trimmed = line.trim(); if (!trimmed || trimmed.startsWith(':')) continue; if (trimmed === 'data: [DONE]' || trimmed === 'data:[DONE]') { break; } // 处理 "event: " 和 "event:" 两种格式 if (trimmed.startsWith('event:')) { // 事件类型,后面会跟随数据 continue; } // 处理 "data: " 和 "data:" 两种格式 if (trimmed.startsWith('data:')) { const data = trimmed.startsWith('data: ') ? trimmed.slice(6) : trimmed.slice(5); const parseResult = parseJsonWithFix(data, { toolName: 'Gemini SSE stream', logWarning: false, logError: true, }); if (parseResult.success) { const chunk = parseResult.data; const hasBusinessDelta = !!chunk?.candidates?.some( (candidate: any) => candidate?.content?.parts?.some((part: any) => Boolean(part?.text || part?.functionCall), ), ); if (hasBusinessDelta) { guard.touch(); } // Process candidates if (chunk.candidates && chunk.candidates.length > 0) { const candidate = chunk.candidates[0]; if (candidate.content && candidate.content.parts) { for (const part of candidate.content.parts) { // Process thought content (Gemini thinking) // When part.thought === true, the text field contains thinking content if (part.thought === true && part.text) { thinkingTextBuffer += part.text; if (!guard.isAbandoned()) { yield { type: 'reasoning_delta', delta: part.text, }; } } // Process regular text content (when thought is not true) else if (part.text) { contentBuffer += part.text; if (!guard.isAbandoned()) { yield { type: 'content', content: part.text, }; } } // Process function calls if (part.functionCall) { hasToolCalls = true; const fc = part.functionCall; const toolCall: any = { id: `call_${toolCallIndex++}`, type: 'function' as const, function: { name: fc.name, arguments: JSON.stringify(fc.args || {}), }, }; // Capture thoughtSignature from part level (Gemini thinking mode) // According to Gemini docs, thoughtSignature is at part level, sibling to functionCall // IMPORTANT: Gemini only returns thoughtSignature on the FIRST function call // We need to save it and reuse for all subsequent function calls const partSignature = part.thoughtSignature || part.thought_signature; if (partSignature) { // Save the first signature for reuse if (!sharedThoughtSignature) { sharedThoughtSignature = partSignature; } toolCall.thoughtSignature = partSignature; } else if (sharedThoughtSignature) { // Use shared signature for subsequent function calls toolCall.thoughtSignature = sharedThoughtSignature; } toolCallsBuffer.push(toolCall); // Yield delta for token counting const deltaText = fc.name + JSON.stringify(fc.args || {}); yield { type: 'tool_call_delta', delta: deltaText, }; } } } } // Track usage info if (chunk.usageMetadata) { totalTokens = { prompt: chunk.usageMetadata.promptTokenCount || 0, completion: chunk.usageMetadata.candidatesTokenCount || 0, total: chunk.usageMetadata.totalTokenCount || 0, }; } } } } } } catch (error) { const {logger} = await import('../utils/core/logger.js'); logger.error('Gemini SSE stream parsing error:', { error: error instanceof Error ? error.message : 'Unknown error', remainingBuffer: buffer.substring(0, 200), }); throw error; } finally { guard.dispose(); } // Yield tool calls if any if (hasToolCalls && toolCallsBuffer.length > 0) { yield { type: 'tool_calls', tool_calls: toolCallsBuffer, }; } // Yield usage info if (totalTokens.total > 0) { const usageData = { prompt_tokens: totalTokens.prompt, completion_tokens: totalTokens.completion, total_tokens: totalTokens.total, }; // Save usage to file system at API layer saveUsageToFile(options.model, usageData); yield { type: 'usage', usage: usageData, }; } // Return complete thinking block if thinking content exists const thinkingBlock = thinkingTextBuffer ? { type: 'thinking' as const, thinking: thinkingTextBuffer, } : undefined; // Signal completion yield { type: 'done', thinking: thinkingBlock, }; }, { abortSignal, onRetry, }, ); } ================================================ FILE: source/api/models.ts ================================================ import { getSnowConfig, getCustomHeaders, getCustomHeadersForConfig, type ApiConfig, } from '../utils/config/apiConfig.js'; import {addProxyToFetchOptions} from '../utils/core/proxyUtils.js'; export interface Model { id: string; object: string; created: number; owned_by: string; } export interface ModelsResponse { object: string; data: Model[]; } // Gemini API response format interface GeminiModel { name: string; // Format: "models/gemini-pro" displayName: string; description?: string; supportedGenerationMethods?: string[]; } interface GeminiModelsResponse { models: GeminiModel[]; } // Anthropic API response format interface AnthropicModel { id: string; display_name?: string; created_at: string; type: string; } /** * Fetch models from OpenAI-compatible API */ async function fetchOpenAIModels( baseUrl: string, apiKey: string, customHeaders: Record, ): Promise { const url = `${baseUrl}/models`; const headers: Record = { 'Content-Type': 'application/json', ...customHeaders, }; if (apiKey) { headers['Authorization'] = `Bearer ${apiKey}`; } const fetchOptions = addProxyToFetchOptions(url, { method: 'GET', headers, }); const response = await fetch(url, fetchOptions); if (!response.ok) { throw new Error( `Failed to fetch models: ${response.status} ${response.statusText}`, ); } const data: ModelsResponse = await response.json(); return data.data || []; } /** * Fetch models from Gemini API */ async function fetchGeminiModels( baseUrl: string, apiKey: string, ): Promise { const url = `${baseUrl}/models`; const fetchOptions = addProxyToFetchOptions(url, { method: 'GET', headers: { 'Content-Type': 'application/json', 'x-goog-api-key': apiKey, }, }); const response = await fetch(url, fetchOptions); if (!response.ok) { throw new Error( `Failed to fetch models: ${response.status} ${response.statusText}`, ); } const data: GeminiModelsResponse = await response.json(); // Convert Gemini format to standard Model format return (data.models || []).map(model => ({ id: model.name.replace('models/', ''), // Remove "models/" prefix object: 'model', created: 0, owned_by: 'google', })); } /** * Fetch models from Anthropic API * Supports both Anthropic native format and OpenAI-compatible format for backward compatibility */ async function fetchAnthropicModels( baseUrl: string, apiKey: string, customHeaders: Record, ): Promise { const url = `${baseUrl}/models`; const headers: Record = { 'Content-Type': 'application/json', ...customHeaders, }; if (apiKey) { headers['x-api-key'] = apiKey; headers['Authorization'] = `Bearer ${apiKey}`; } const fetchOptions = addProxyToFetchOptions(url, { method: 'GET', headers, }); const response = await fetch(url, fetchOptions); if (!response.ok) { throw new Error( `Failed to fetch models: ${response.status} ${response.statusText}`, ); } const data: any = await response.json(); // Try to parse as Anthropic format first if (data.data && Array.isArray(data.data) && data.data.length > 0) { const firstItem = data.data[0]; // Check if it's Anthropic format (has created_at field) if ('created_at' in firstItem && typeof firstItem.created_at === 'string') { // Anthropic native format return (data.data as AnthropicModel[]).map(model => ({ id: model.id, object: 'model', created: new Date(model.created_at).getTime() / 1000, owned_by: 'anthropic', })); } // Fallback to OpenAI format (has created field as number) if ('id' in firstItem && 'object' in firstItem) { // OpenAI-compatible format return data.data as Model[]; } } // If no data array or empty, return empty array return []; } /** * Fetch available models based on configured request method */ export async function fetchAvailableModels( overrideConfig?: Partial, ): Promise { // 当传入 overrideConfig 时，使用临时合并的配置（不依赖磁盘上的 active profile / 全局 config.json） // 这样即使在编辑非激活 profile 时调用，也不会污染全局 config 与 active profile 文件。 const baseConfig = overrideConfig ? ({...getSnowConfig(), ...overrideConfig} as ApiConfig) : getSnowConfig(); const config = baseConfig; if (!config.baseUrl) { throw new Error( 'Base URL not configured. Please configure API settings first.', ); } const customHeaders = overrideConfig ? getCustomHeadersForConfig(config) : getCustomHeaders(); try { let models: Model[]; const defaultOpenAiBaseUrl = 'https://api.openai.com/v1'; const trimmedBaseUrl = config.baseUrl.replace(/\/$/, ''); const isDefaultBaseUrl = !trimmedBaseUrl || trimmedBaseUrl === defaultOpenAiBaseUrl; switch (config.requestMethod) { case 'gemini': { if (!config.apiKey) { throw new Error('API key is required for Gemini API'); } const geminiBaseUrl = isDefaultBaseUrl ? 'https://generativelanguage.googleapis.com/v1beta' : trimmedBaseUrl; models = await fetchGeminiModels(geminiBaseUrl, config.apiKey); break; } case 'anthropic': { if (!config.apiKey) { throw new Error('API key is required for Anthropic API'); } const anthropicBaseUrl = isDefaultBaseUrl ? 'https://api.anthropic.com/v1' : trimmedBaseUrl; models = await fetchAnthropicModels( anthropicBaseUrl, config.apiKey, customHeaders, ); break; } case 'chat': case 'responses': default: // OpenAI-compatible API models = await fetchOpenAIModels( config.baseUrl.replace(/\/$/, ''), config.apiKey, customHeaders, ); break; } // Sort models alphabetically by id for better UX return models.sort((a, b) => a.id.localeCompare(b.id)); } catch (error) { if (error instanceof Error) { throw new Error(`Error fetching models: ${error.message}`); } throw new Error('Unknown error occurred while fetching models'); } } export function filterModels(models: Model[], searchTerm: string): Model[] { if (!searchTerm.trim()) { return models; } const lowerSearchTerm = searchTerm.toLowerCase(); return models.filter(model => model.id.toLowerCase().includes(lowerSearchTerm), ); } ================================================ FILE: source/api/rerank.ts ================================================ import {loadCodebaseConfig} from '../utils/config/codebaseConfig.js'; import {logger} from '../utils/core/logger.js'; import {addProxyToFetchOptions} from '../utils/core/proxyUtils.js'; import {getVersionHeader} from '../utils/core/version.js'; export interface RerankOptions { model?: string; query: string; documents: string[]; topN?: number; baseUrl?: string; apiKey?: string; contextLength?: number; } export interface RerankResult { index: number; relevanceScore: number; } export interface RerankResponse { results: RerankResult[]; droppedDocuments?: number; truncatedDocuments?: number; } const MAX_RETRIES = 3; const RETRY_BASE_DELAY_MS = 500; const CONTEXT_RESERVE_RATIO = 0.95; const SINGLE_DOC_MAX_RATIO = 0.3; /** * Count tokens using tiktoken. Falls back to char-based estimation. */ async function countTokens(text: string): Promise { try { const {encoding_for_model} = await import('tiktoken'); let encoder; try { encoder = encoding_for_model('gpt-5'); } catch { encoder = encoding_for_model('gpt-3.5-turbo'); } try { return encoder.encode(text).length; } finally { encoder.free(); } } catch { return Math.ceil(text.length / 4); } } /** * Truncate text to fit within a token budget. */ async function truncateText( text: string, maxTokens: number, ): Promise { try { const {encoding_for_model} = await import('tiktoken'); let encoder; try { encoder = encoding_for_model('gpt-5'); } catch { encoder = encoding_for_model('gpt-3.5-turbo'); } try { const tokens = encoder.encode(text); if (tokens.length <= maxTokens) { return text; } const truncated = tokens.slice(0, maxTokens); const decoder = new TextDecoder(); return decoder.decode(encoder.decode(truncated)); } finally { encoder.free(); } } catch { const maxChars = maxTokens * 4; return text.length <= maxChars ? text : text.slice(0, maxChars); } } interface FitResult { documents: string[]; /** Original indices that survived (maps new index → original index) */ originalIndices: number[]; droppedCount: number; truncatedCount: number; } /** * Fit documents into the rerank model's context window. * * Strategy: * 1. Reserve tokens for query + request overhead * 2. Walk documents in order; accumulate until budget exhausted * 3. If a single document exceeds 30% of context, truncate it * 4. Drop documents that no longer fit */ async function fitDocumentsToContext( query: string, documents: string[], contextLength: number, ): Promise { const budgetTotal = Math.floor(contextLength * CONTEXT_RESERVE_RATIO); const queryTokens = await countTokens(query); const overhead = 50; let remaining = budgetTotal - queryTokens - overhead; if (remaining <= 0) { logger.warn( `Rerank context budget exhausted by query alone (${queryTokens} tokens, budget ${budgetTotal})`, ); return { documents: [], originalIndices: [], droppedCount: documents.length, truncatedCount: 0, }; } const singleDocMax = Math.floor(contextLength * SINGLE_DOC_MAX_RATIO); const fitted: string[] = []; const originalIndices: number[] = []; let droppedCount = 0; let truncatedCount = 0; for (let i = 0; i < documents.length; i++) { const doc = documents[i]!; let docTokens = await countTokens(doc); if (docTokens > singleDocMax) { const truncatedDoc = await truncateText(doc, singleDocMax); docTokens = await countTokens(truncatedDoc); truncatedCount++; if (docTokens <= remaining) { fitted.push(truncatedDoc); originalIndices.push(i); remaining -= docTokens; } else { droppedCount++; } continue; } if (docTokens <= remaining) { fitted.push(doc); originalIndices.push(i); remaining -= docTokens; } else { droppedCount++; } } if (droppedCount > 0 || truncatedCount > 0) { logger.info( `Rerank context fitting: ${documents.length} docs → ${fitted.length} kept, ${truncatedCount} truncated, ${droppedCount} dropped (context ${contextLength} tokens)`, ); } return {documents: fitted, originalIndices, droppedCount, truncatedCount}; } function resolveRerankEndpoint(baseUrl: string): string { const trimmed = baseUrl.trim().replace(/\/+$/, ''); if (trimmed.endsWith('/rerank')) { return trimmed; } if (trimmed.endsWith('/v1/rerank')) { return trimmed; } if (trimmed.endsWith('/v1')) { return `${trimmed}/rerank`; } return `${trimmed}/v1/rerank`; } /** * Normalize various rerank API response formats into a unified structure. * Supports Jina, Cohere, and OpenAI-compatible rerank responses. */ function normalizeRerankResponse(data: any): RerankResponse { if (data && Array.isArray(data.results)) { return { results: data.results.map((r: any) => ({ index: r.index ?? 0, relevanceScore: r.relevance_score ?? r.relevanceScore ?? 0, })), }; } if (Array.isArray(data)) { return { results: data.map((r: any) => ({ index: r.index ?? 0, relevanceScore: r.relevance_score ?? r.relevanceScore ?? r.score ?? 0, })), }; } throw new Error( `Unexpected rerank API response format: ${JSON.stringify(data).slice(0, 200)}`, ); } async function callRerankAPI(options: { url: string; model: string; query: string; documents: string[]; topN?: number; apiKey?: string; }): Promise { const {url, model, query, documents, topN, apiKey} = options; const requestBody: Record = { model, query, documents, }; if (topN !== undefined) { requestBody['top_n'] = topN; } const headers: Record = { 'Content-Type': 'application/json', 'x-snow': getVersionHeader(), }; if (apiKey) { headers['Authorization'] = `Bearer ${apiKey}`; } const fetchOptions = addProxyToFetchOptions(url, { method: 'POST', headers, body: JSON.stringify(requestBody), }); const response = await fetch(url, fetchOptions); if (!response.ok) { const errorText = await response.text(); throw new Error(`Rerank API error (${response.status}): ${errorText}`); } const data = await response.json(); return normalizeRerankResponse(data); } /** * Rerank documents against a query with automatic retry. * * Before calling the API, documents are fitted into the model's context window * (configured via `reranking.contextLength`). Documents that exceed the budget * are truncated or dropped, and the response maps indices back to the original * document array so callers can match results correctly. * * @returns Sorted results with relevance scores (indices refer to the original documents array). * If topN >= documents.length, all documents are returned (full ranking). */ export async function rerankDocuments( options: RerankOptions, ): Promise { const config = loadCodebaseConfig(); const rerankingConfig = config.reranking; const model = options.model || rerankingConfig.modelName; const baseUrl = options.baseUrl || rerankingConfig.baseUrl; const apiKey = options.apiKey || rerankingConfig.apiKey; const topN = options.topN ?? rerankingConfig.topN; const contextLength = options.contextLength ?? rerankingConfig.contextLength; const {query, documents} = options; if (!model) { throw new Error('Reranking model name is required'); } if (!baseUrl) { throw new Error('Reranking base URL is required'); } if (!documents || documents.length === 0) { throw new Error('Documents are required for reranking'); } // ── Context length protection ── const fitResult = await fitDocumentsToContext( query, documents, contextLength, ); if (fitResult.documents.length === 0) { logger.warn( 'All documents dropped during context fitting, returning empty results', ); return { results: [], droppedDocuments: fitResult.droppedCount, truncatedDocuments: fitResult.truncatedCount, }; } const url = resolveRerankEndpoint(baseUrl); const effectiveTopN = topN >= fitResult.documents.length ? undefined : topN; let lastError: Error | null = null; for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) { try { logger.info( `Rerank API call attempt ${attempt}/${MAX_RETRIES} (${fitResult.documents.length}/${documents.length} docs, context ${contextLength})`, ); const response = await callRerankAPI({ url, model, query, documents: fitResult.documents, topN: effectiveTopN, apiKey, }); // Map fitted indices back to original document indices const mappedResults: RerankResult[] = response.results.map(r => ({ index: fitResult.originalIndices[r.index] ?? r.index, relevanceScore: r.relevanceScore, })); logger.info( `Rerank API succeeded on attempt ${attempt}, got ${mappedResults.length} results`, ); return { results: mappedResults, droppedDocuments: fitResult.droppedCount, truncatedDocuments: fitResult.truncatedCount, }; } catch (error) { lastError = error instanceof Error ? error : new Error(String(error)); logger.warn( `Rerank API attempt ${attempt}/${MAX_RETRIES} failed: ${lastError.message}`, ); if (attempt < MAX_RETRIES) { const delay = RETRY_BASE_DELAY_MS * attempt; await new Promise(resolve => setTimeout(resolve, delay)); } } } throw new Error( `Rerank API failed after ${MAX_RETRIES} attempts: ${lastError?.message}`, ); } ================================================ FILE: source/api/responses.ts ================================================ import { getSnowConfig, getCustomSystemPromptForConfig, getCustomHeadersForConfig, } from '../utils/config/apiConfig.js'; import {getSystemPromptForMode} from '../prompt/systemPrompt.js'; import { withRetryGenerator, parseJsonWithFix, } from '../utils/core/retryUtils.js'; import { createIdleTimeoutGuard, StreamIdleTimeoutError, } from '../utils/core/streamGuards.js'; import type { ChatMessage, ToolCall, ChatCompletionTool, UsageInfo, } from './types.js'; import {addProxyToFetchOptions} from '../utils/core/proxyUtils.js'; import {saveUsageToFile} from '../utils/core/usageLogger.js'; import {getVersionHeader} from '../utils/core/version.js'; export interface ResponseOptions { model: string; messages: ChatMessage[]; stream?: boolean; temperature?: number; max_tokens?: number; tools?: ChatCompletionTool[]; tool_choice?: 'auto' | 'none' | 'required'; reasoning?: { summary?: 'auto' | 'none'; effort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh'; } | null; // null means don't pass reasoning parameter (for small models) prompt_cache_key?: string; store?: boolean; include?: string[]; includeBuiltinSystemPrompt?: boolean; // 控制是否添加内置系统提示词（默认 true） disableThinking?: boolean; // 禁用 Extended Thinking 功能（用于 agents 等场景，默认 false） planMode?: boolean; // 启用 Plan 模式（使用 Plan 模式系统提示词） vulnerabilityHuntingMode?: boolean; // 启用漏洞狩猎模式（使用漏洞狩猎模式系统提示词） teamMode?: boolean; // 启用 Team 模式（使用 Team 模式系统提示词） toolSearchDisabled?: boolean; // 工具搜索已关闭（全量加载工具） // Sub-agent configuration overrides configProfile?: string; // 子代理配置文件名（覆盖模型等设置） customSystemPromptId?: string; // 自定义系统提示词 ID customHeaders?: Record; // 自定义请求头 } /** * 确保 schema 符合 Responses API 的要求： * 1. additionalProperties: false * 2. 保持原有的 required 数组（不修改） */ function ensureStrictSchema( schema?: Record, ): Record | undefined { if (!schema) { return undefined; } // 深拷贝 schema const stringified = JSON.stringify(schema); const parseResult = parseJsonWithFix(stringified, { toolName: 'Schema deep copy', fallbackValue: schema, // 如果失败，使用原始 schema logWarning: true, logError: true, }); const strictSchema = parseResult.data as Record; if (strictSchema?.['type'] === 'object') { // 添加 additionalProperties: false strictSchema['additionalProperties'] = false; // 递归处理嵌套的 object 属性 if (strictSchema['properties']) { for (const key of Object.keys(strictSchema['properties'])) { const prop = strictSchema['properties'][key]; // 递归处理嵌套的 object if ( prop['type'] === 'object' || (Array.isArray(prop['type']) && prop['type'].includes('object')) ) { if (!('additionalProperties' in prop)) { prop['additionalProperties'] = false; } } } } // 如果 properties 为空且有 required 字段，删除它 if ( strictSchema['properties'] && Object.keys(strictSchema['properties']).length === 0 && strictSchema['required'] ) { delete strictSchema['required']; } } return strictSchema; } /** * 转换 Chat Completions 格式的工具为 Responses API 格式 * Chat Completions: {type: 'function', function: {name, description, parameters}} * Responses API: {type: 'function', name, description, parameters, strict} */ function convertToolsForResponses(tools?: ChatCompletionTool[]): | Array<{ type: 'function'; name: string; description?: string; strict?: boolean; parameters?: Record; }> | undefined { if (!tools || tools.length === 0) { return undefined; } return tools.map(tool => ({ type: 'function', name: tool.function.name, description: tool.function.description, strict: false, parameters: ensureStrictSchema(tool.function.parameters), })); } export interface ResponseStreamChunk { type: | 'content' | 'tool_calls' | 'tool_call_delta' | 'reasoning_delta' | 'reasoning_started' | 'reasoning_data' | 'done' | 'usage'; content?: string; tool_calls?: ToolCall[]; delta?: string; usage?: UsageInfo; reasoning?: { summary?: Array<{type: 'summary_text'; text: string}>; content?: any; encrypted_content?: string; }; } function getResponsesReasoningConfig(): { effort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh'; summary?: 'auto' | 'none'; } | null { const config = getSnowConfig(); const reasoningConfig = config.responsesReasoning; if (!reasoningConfig || !reasoningConfig.enabled) { return null; } return { effort: reasoningConfig.effort || 'high', summary: 'auto', }; } function getResponsesVerbosityConfig(): 'low' | 'medium' | 'high' { const config = getSnowConfig(); return config.responsesVerbosity || 'medium'; } export function resetApiClient(): void { // No-op: kept for backward compatibility } function toResponseImageUrl(image: {data: string; mimeType?: string}): string { const data = image.data?.trim() || ''; if (!data) return ''; // Keep remote URLs and existing data URLs unchanged. if (/^https?:\/\//i.test(data) || /^data:/i.test(data)) { return data; } const mimeType = image.mimeType?.trim() || 'image/png'; return `data:${mimeType};base64,${data}`; } function convertToResponseInput( messages: ChatMessage[], includeBuiltinSystemPrompt: boolean = true, customSystemPromptOverride?: string[], planMode: boolean = false, vulnerabilityHuntingMode: boolean = false, toolSearchDisabled: boolean = false, teamMode: boolean = false, ): { input: any[]; systemInstructions: string; } { const customSystemPrompts = customSystemPromptOverride; const result: any[] = []; for (const msg of messages) { if (!msg) continue; // 跳过 system 消息（不放入 input，也不放入 instructions） if (msg.role === 'system') { continue; } // 用户消息：content 必须是数组格式，使用 type: "message" 包裹 if (msg.role === 'user') { const contentParts: any[] = []; // 添加文本内容 if (msg.content) { contentParts.push({ type: 'input_text', text: msg.content, }); } // 添加图片内容 if (msg.images && msg.images.length > 0) { for (const image of msg.images) { contentParts.push({ type: 'input_image', image_url: toResponseImageUrl(image), }); } } result.push({ type: 'message', role: 'user', content: contentParts, }); continue; } // Assistant 消息（带工具调用） // 在 Responses API 中，需要将工具调用转换为 function_call 类型的独立项 if ( msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0 ) { // 如果存在自然语言说明内容，先添加文本消息 if (msg.content) { result.push({ type: 'message', role: 'assistant', content: [ { type: 'output_text', text: msg.content, }, ], }); } // 为每个工具调用添加 function_call 项 for (const toolCall of msg.tool_calls) { result.push({ type: 'function_call', name: toolCall.function.name, arguments: toolCall.function.arguments, call_id: toolCall.id, }); } continue; } // Assistant 消息（纯文本） if (msg.role === 'assistant') { result.push({ type: 'message', role: 'assistant', content: [ { type: 'output_text', text: msg.content || '', }, ], }); continue; } // Tool 消息：转换为 function_call_output if (msg.role === 'tool' && msg.tool_call_id) { // Handle multimodal tool results with images if (msg.images && msg.images.length > 0) { // For Responses API, we need to include images in a structured way // The output can be an array of content items const outputContent: any[] = []; // Add text content if (msg.content) { outputContent.push({ type: 'input_text', text: msg.content, }); } // Add images as base64 data URLs (Responses API format) for (const image of msg.images) { outputContent.push({ type: 'input_image', image_url: toResponseImageUrl(image), }); } result.push({ type: 'function_call_output', call_id: msg.tool_call_id, output: outputContent, }); } else { result.push({ type: 'function_call_output', call_id: msg.tool_call_id, output: msg.content, }); } continue; } } // 确定系统提示词：参考 anthropic.ts 的逻辑 let systemInstructions: string; // 如果配置了自定义系统提示词（最高优先级，始终添加） if (customSystemPrompts && customSystemPrompts.length > 0) { // 有自定义系统提示词：拼接多条作为 instructions systemInstructions = customSystemPrompts.join('\n\n'); if (includeBuiltinSystemPrompt) { // 默认系统提示词作为第一条用户消息 result.unshift({ type: 'message', role: 'user', content: [ { type: 'input_text', text: '' + getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ) + '', }, ], }); } } else if (includeBuiltinSystemPrompt) { // 没有自定义系统提示词，但需要添加默认系统提示词 systemInstructions = getSystemPromptForMode( planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode, ); } else { // 既没有自定义系统提示词，也不需要添加默认系统提示词 systemInstructions = 'You are a helpful assistant.'; } return {input: result, systemInstructions}; } /** * Parse Server-Sent Events (SSE) stream */ async function* parseSSEStream( reader: ReadableStreamDefaultReader, abortSignal?: AbortSignal, idleTimeoutMs?: number, ): AsyncGenerator { const decoder = new TextDecoder(); let buffer = ''; // 创建空闲超时保护器 const guard = createIdleTimeoutGuard({ reader, idleTimeoutMs, onTimeout: () => { throw new StreamIdleTimeoutError( `No data received for ${idleTimeoutMs}ms`, idleTimeoutMs, ); }, }); try { while (true) { // 用户主动中断时立即标记丢弃,避免延迟消息外泄 if (abortSignal?.aborted) { guard.abandon(); return; } const {done, value} = await reader.read(); // 检查是否有超时错误需要在读取循环中抛出(确保被正确的 try/catch 捕获) const timeoutError = guard.getTimeoutError(); if (timeoutError) { throw timeoutError; } // 检查是否已被丢弃(竞态条件防护) if (guard.isAbandoned()) { continue; } if (done) { // 连接异常中断时,残留半包不应被静默丢弃,应抛出可重试错误 if (buffer.trim()) { // 连接异常中断,抛出明确错误 throw new Error( `Stream terminated unexpectedly with incomplete data: ${buffer.substring( 0, 100, )}...`, ); } break; // 正常结束 } buffer += decoder.decode(value, {stream: true}); const lines = buffer.split('\n'); buffer = lines.pop() || ''; for (const line of lines) { const trimmed = line.trim(); if (!trimmed || trimmed.startsWith(':')) continue; if (trimmed === 'data: [DONE]' || trimmed === 'data:[DONE]') { return; } // 处理 "event: " 和 "event:" 两种格式 if (trimmed.startsWith('event:')) { // 事件类型,后面会跟随数据 continue; } // 处理 "data: " 和 "data:" 两种格式 if (trimmed.startsWith('data:')) { const data = trimmed.startsWith('data: ') ? trimmed.slice(6) : trimmed.slice(5); const parseResult = parseJsonWithFix(data, { toolName: 'Responses API SSE 流', logWarning: false, logError: true, }); if (parseResult.success) { const event = parseResult.data; const hasBusinessDelta = (event?.type === 'response.output_text.delta' && event?.delta) || (event?.type === 'response.reasoning_summary_text.delta' && event?.delta) || (event?.type === 'response.function_call_arguments.delta' && event?.delta) || (event?.type === 'response.output_item.added' && event?.item?.type === 'function_call'); if (hasBusinessDelta) { guard.touch(); } // yield 前检查是否已被丢弃 if (!guard.isAbandoned()) { yield event; } } } } } } catch (error) { const {logger} = await import('../utils/core/logger.js'); logger.error('Responses API SSE stream parsing error:', { error: error instanceof Error ? error.message : 'Unknown error', remainingBuffer: buffer.substring(0, 200), }); throw error; } finally { guard.dispose(); } } /** * 使用 Responses API 创建流式响应（带自动工具调用） */ export async function* createStreamingResponse( options: ResponseOptions, abortSignal?: AbortSignal, onRetry?: (error: Error, attempt: number, nextDelay: number) => void, ): AsyncGenerator { // Load configuration: if configProfile is specified, load it; otherwise use main config let config: ReturnType; if (options.configProfile) { try { const {loadProfile} = await import('../utils/config/configManager.js'); const profileConfig = loadProfile(options.configProfile); if (profileConfig?.snowcfg) { config = profileConfig.snowcfg; } else { // Profile not found, fallback to main config config = getSnowConfig(); const {logger} = await import('../utils/core/logger.js'); logger.warn( `Profile ${options.configProfile} not found, using main config`, ); } } catch (error) { // If loading profile fails, fallback to main config config = getSnowConfig(); const {logger} = await import('../utils/core/logger.js'); logger.warn( `Failed to load profile ${options.configProfile}, using main config:`, error, ); } } else { // No configProfile specified, use main config config = getSnowConfig(); } // Get system prompt (with custom override support) let customSystemPromptContent: string[] | undefined; if (options.customSystemPromptId) { const {getSystemPromptConfig} = await import( '../utils/config/apiConfig.js' ); const systemPromptConfig = getSystemPromptConfig(); const customPrompt = systemPromptConfig?.prompts.find( p => p.id === options.customSystemPromptId, ); if (customPrompt?.content) { customSystemPromptContent = [customPrompt.content]; } } // 如果没有显式的 customSystemPromptId，则按当前配置（含 profile 覆盖）解析 customSystemPromptContent ||= getCustomSystemPromptForConfig(config); // 提取系统提示词和转换后的消息 const {input: requestInput, systemInstructions} = convertToResponseInput( options.messages, options.includeBuiltinSystemPrompt !== false, customSystemPromptContent, options.planMode || false, options.vulnerabilityHuntingMode || false, options.toolSearchDisabled || false, options.teamMode || false, ); // 获取配置的 reasoning 设置 const configuredReasoning = getResponsesReasoningConfig(); const configuredVerbosity = getResponsesVerbosityConfig(); // 使用重试包装生成器 yield* withRetryGenerator( async function* () { const requestPayload: any = { model: options.model || config.advancedModel, instructions: systemInstructions, input: requestInput, tools: convertToolsForResponses(options.tools), tool_choice: options.tool_choice, parallel_tool_calls: true, // 只有当 reasoning 启用且未禁用思考功能时才添加 reasoning 字段 ...(configuredReasoning && !options.disableThinking && { reasoning: configuredReasoning, }), ...(config.responsesFastMode && { service_tier: 'priority', }), text: { verbosity: configuredVerbosity, }, store: false, stream: true, include: ['reasoning.encrypted_content'], prompt_cache_key: options.prompt_cache_key, }; const url = `${config.baseUrl}/responses`; // Use custom headers from options if provided, otherwise get from current config (supports profile override) const customHeaders = options.customHeaders || getCustomHeadersForConfig(config); const fetchOptions = addProxyToFetchOptions(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${config.apiKey}`, 'x-snow': getVersionHeader(), ...(options.prompt_cache_key && { conversation_id: options.prompt_cache_key, session_id: options.prompt_cache_key, }), ...customHeaders, }, body: JSON.stringify(requestPayload), signal: abortSignal, }); let response: Response; try { response = await fetch(url, fetchOptions); } catch (error) { // 捕获 fetch 底层错误（网络错误、连接超时等） const errorMessage = error instanceof Error ? error.message : String(error); throw new Error( `OpenAI Responses API fetch failed: ${errorMessage}\n` + `URL: ${url}\n` + `Model: ${requestPayload.model}\n` + `Error type: ${ error instanceof TypeError ? 'Network/Connection Error' : 'Unknown Error' }\n` + `Possible causes: Network unavailable, DNS resolution failed, proxy issues, or server unreachable`, ); } if (!response.ok) { const errorText = await response.text(); throw new Error( `OpenAI Responses API error: ${response.status} ${response.statusText} - ${errorText}`, ); } if (!response.body) { throw new Error('No response body from OpenAI Responses API'); } let contentBuffer = ''; let toolCallsBuffer: {[call_id: string]: any} = {}; let hasToolCalls = false; let currentFunctionCallId: string | null = null; let usageData: UsageInfo | undefined; let reasoningData: | { summary?: Array<{text: string; type: 'summary_text'}>; content?: any; encrypted_content?: string; } | undefined; const idleTimeoutMs = (config.streamIdleTimeoutSec ?? 180) * 1000; for await (const chunk of parseSSEStream( response.body.getReader(), abortSignal, idleTimeoutMs, )) { // abort 由 parseSSEStream 统一处理,避免重复分支导致行为漂移 // Responses API 使用 SSE 事件格式 const eventType = chunk.type; // 根据事件类型处理 if ( eventType === 'response.created' || eventType === 'response.in_progress' ) { // 响应创建/进行中 - 忽略 continue; } else if (eventType === 'response.output_item.added') { // 新输出项添加 const item = chunk.item; if (item?.type === 'reasoning') { // 推理摘要开始 - 发送 reasoning_started 事件 yield { type: 'reasoning_started', }; continue; } else if (item?.type === 'message') { // 消息开始 - 忽略 continue; } else if (item?.type === 'function_call') { // 工具调用开始 hasToolCalls = true; const callId = item.call_id || item.id; currentFunctionCallId = callId; toolCallsBuffer[callId] = { id: callId, type: 'function', function: { name: item.name || '', arguments: '', }, }; continue; } continue; } else if (eventType === 'response.function_call_arguments.delta') { // 工具调用参数增量 const delta = chunk.delta; if (delta && currentFunctionCallId) { toolCallsBuffer[currentFunctionCallId].function.arguments += delta; // 发送 delta 用于 token 计数 yield { type: 'tool_call_delta', delta: delta, }; } } else if (eventType === 'response.function_call_arguments.done') { // 工具调用参数完成 const itemId = chunk.item_id; const args = chunk.arguments; if (itemId && toolCallsBuffer[itemId]) { toolCallsBuffer[itemId].function.arguments = args; } currentFunctionCallId = null; continue; } else if (eventType === 'response.output_item.done') { // 输出项完成 const item = chunk.item; if (item?.type === 'function_call') { // 确保工具调用信息完整 const callId = item.call_id || item.id; if (toolCallsBuffer[callId]) { toolCallsBuffer[callId].function.name = item.name; toolCallsBuffer[callId].function.arguments = item.arguments; } } else if (item?.type === 'reasoning') { // 捕获完整的 reasoning 对象（包括 encrypted_content） reasoningData = { summary: item.summary, content: item.content, encrypted_content: item.encrypted_content, }; } continue; } else if (eventType === 'response.content_part.added') { // 内容部分添加 - 忽略 continue; } else if (eventType === 'response.reasoning_summary_text.delta') { // 推理摘要增量更新（仅用于 token 计数，不包含在响应内容中） const delta = chunk.delta; if (delta) { yield { type: 'reasoning_delta', delta: delta, }; } } else if (eventType === 'response.output_text.delta') { // 文本增量更新 const delta = chunk.delta; if (delta) { contentBuffer += delta; yield { type: 'content', content: delta, }; } } else if (eventType === 'response.output_text.done') { // 文本输出完成 - 忽略 continue; } else if (eventType === 'response.content_part.done') { // 内容部分完成 - 忽略 continue; } else if (eventType === 'response.completed') { // 响应完全完成 - 从 response 对象中提取 usage if (chunk.response && chunk.response.usage) { usageData = { prompt_tokens: chunk.response.usage.input_tokens || 0, completion_tokens: chunk.response.usage.output_tokens || 0, total_tokens: chunk.response.usage.total_tokens || 0, // OpenAI Responses API: cached_tokens in input_tokens_details (note: tokenS) cached_tokens: (chunk.response.usage as any).input_tokens_details ?.cached_tokens, }; } break; } else if ( eventType === 'response.failed' || eventType === 'response.cancelled' ) { // 响应失败或取消 const error = chunk.error; if (error) { const responseErrorMessage = error.message || 'Unknown error'; throw new Error(`Response failed: ${responseErrorMessage}`); } break; } } // 如果有工具调用，返回它们 if (hasToolCalls) { yield { type: 'tool_calls', tool_calls: Object.values(toolCallsBuffer), }; } // Yield reasoning data if available if (reasoningData) { yield { type: 'reasoning_data', reasoning: reasoningData, }; } // Yield usage information if available if (usageData) { // Save usage to file system at API layer saveUsageToFile(options.model, usageData); yield { type: 'usage', usage: usageData, }; } // 发送完成信号 - For Responses API, thinking content is in reasoning object, not separate thinking field yield { type: 'done', }; }, { abortSignal, onRetry, }, ); } ================================================ FILE: source/api/sse-server.ts ================================================ import {createServer, IncomingMessage, ServerResponse} from 'http'; import {parse as parseUrl} from 'url'; /** * SSE 事件类型定义 */ export type SSEEventType = | 'connected' | 'message' | 'tool_call' | 'tool_result' | 'thinking' | 'usage' | 'error' | 'complete' | 'tool_confirmation_request' | 'user_question_request' | 'rollback_request' | 'rollback_result'; /** * SSE 事件数据结构 */ export interface SSEEvent { type: SSEEventType; data: any; timestamp: string; requestId?: string; // 用于关联请求和响应 } /** * 客户端输入消息结构 */ export interface ClientMessage { type: | 'chat' | 'image' | 'tool_confirmation_response' | 'user_question_response' | 'abort' // 中断当前任务 | 'rollback'; // 回滚会话/快照 content?: string; images?: Array<{ data: string; // base64 data URI (data:image/png;base64,...) mimeType: string; }>; requestId?: string; // 响应关联的请求ID response?: any; // 响应数据 sessionId?: string; // 会话ID，用于连续对话 yoloMode?: boolean; // YOLO 模式，自动批准所有工具 rollback?: { messageIndex: number; rollbackFiles: boolean; selectedFiles?: string[]; crossSessionRollback?: boolean; originalSessionId?: string; }; } /** * SSE 客户端连接管理 */ class SSEConnection { private response: ServerResponse; private connectionId: string; constructor(response: ServerResponse, connectionId: string) { this.response = response; this.connectionId = connectionId; // 设置 SSE 响应头 this.response.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive', 'Access-Control-Allow-Origin': '*', }); // 发送初始连接事件 this.sendEvent({ type: 'connected', data: {connectionId: this.connectionId}, timestamp: new Date().toISOString(), }); } /** * 发送 SSE 事件 */ sendEvent(event: SSEEvent): void { const eventData = `data: ${JSON.stringify(event)}\n\n`; this.response.write(eventData); } /** * 关闭连接 */ close(): void { this.response.end(); } getId(): string { return this.connectionId; } } /** * SSE 服务器类 */ export class SSEServer { private server: ReturnType | null = null; private connections: Map = new Map(); private sessionConnections: Map = new Map(); // sessionId -> connectionId 映射 private port: number; private messageHandler?: ( message: ClientMessage, sendEvent: (event: SSEEvent) => void, connectionId: string, ) => Promise; private logCallback?: ( message: string, level?: 'info' | 'error' | 'success', ) => void; constructor(port: number = 3000) { this.port = port; } /** * 设置日志回调函数 */ setLogCallback( callback: (message: string, level?: 'info' | 'error' | 'success') => void, ): void { this.logCallback = callback; } /** * 记录日志 */ private log( message: string, level: 'info' | 'error' | 'success' = 'info', ): void { if (this.logCallback) { this.logCallback(message, level); } else { console.log(`[${level.toUpperCase()}] ${message}`); } } /** * 设置消息处理器 */ setMessageHandler( handler: ( message: ClientMessage, sendEvent: (event: SSEEvent) => void, connectionId: string, ) => Promise, ): void { this.messageHandler = handler; } /** * 启动 SSE 服务器 */ start(): Promise { return new Promise((resolve, reject) => { this.server = createServer( (req: IncomingMessage, res: ServerResponse) => { this.handleRequest(req, res); }, ); this.server.on('error', error => { reject(error); }); this.server.listen(this.port, () => { this.log(`SSE 服务器已启动，监听端口 ${this.port}`, 'success'); resolve(); }); }); } /** * 停止 SSE 服务器 */ stop(): Promise { return new Promise(resolve => { // 关闭所有连接 this.connections.forEach(conn => { conn.close(); }); this.connections.clear(); this.sessionConnections.clear(); if (this.server) { this.server.close(() => { this.log('SSE 服务器已停止', 'info'); resolve(); }); } else { resolve(); } }); } /** * 绑定 session 到连接 */ bindSessionToConnection(sessionId: string, connectionId: string): void { this.sessionConnections.set(sessionId, connectionId); this.log(`Session ${sessionId} 绑定到连接 ${connectionId}`, 'info'); } /** * 向特定 session 发送事件 */ sendToSession(sessionId: string, event: SSEEvent): void { const connectionId = this.sessionConnections.get(sessionId); if (connectionId) { const connection = this.connections.get(connectionId); if (connection) { connection.sendEvent(event); } } } /** * 向特定连接发送事件 */ sendToConnection(connectionId: string, event: SSEEvent): void { const connection = this.connections.get(connectionId); if (connection) { connection.sendEvent(event); } } /** * 读取 JSON 请求体 */ private async readJsonBody(req: IncomingMessage): Promise { return new Promise((resolve, reject) => { let body = ''; req.on('data', chunk => { body += chunk.toString(); }); req.on('end', () => { try { resolve(body ? (JSON.parse(body) as T) : ({} as T)); } catch (error) { reject(error); } }); }); } /** * 获取一个可用连接（优先指定 connectionId） */ private getActiveConnectionId(preferred?: string): string | undefined { if (preferred && this.connections.has(preferred)) { return preferred; } const firstConnection = this.connections.values().next().value as | SSEConnection | undefined; return firstConnection?.getId(); } /** * 处理 HTTP 请求 */ private handleRequest(req: IncomingMessage, res: ServerResponse): void { const parsedUrl = parseUrl(req.url || '', true); const pathname = parsedUrl.pathname; // 处理 CORS 预检请求 if (req.method === 'OPTIONS') { res.writeHead(200, { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type', }); res.end(); return; } // SSE 连接端点 if (pathname === '/events' && req.method === 'GET') { this.handleSSEConnection(req, res); return; } // 会话创建端点 if (pathname === '/session/create' && req.method === 'POST') { this.handleSessionCreate(req, res); return; } // 会话加载端点 if (pathname === '/session/load' && req.method === 'POST') { this.handleSessionLoad(req, res); return; } // 回滚点列表端点（demo 使用） if (pathname === '/session/rollback-points' && req.method === 'GET') { this.handleSessionRollbackPoints( res, parsedUrl.query as Record, ); return; } // 会话列表端点 if (pathname === '/session/list' && req.method === 'GET') { this.handleSessionList( req, res, parsedUrl.query as Record, ); return; } // 会话删除端点 if (pathname?.startsWith('/session/') && req.method === 'DELETE') { this.handleSessionDelete(req, res, pathname); return; } // 消息发送端点 if (pathname === '/message' && req.method === 'POST') { this.handleMessage(req, res); return; } // 健康检查端点 if (pathname === '/health' && req.method === 'GET') { res.writeHead(200, {'Content-Type': 'application/json'}); res.end( JSON.stringify({ status: 'ok', connections: this.connections.size, }), ); return; } // 上下文压缩端点 if (pathname === '/context/compress' && req.method === 'POST') { this.handleContextCompress(req, res); return; } // 未知端点 res.writeHead(404); res.end('Not Found'); } private handleSessionCreate(req: IncomingMessage, res: ServerResponse): void { void (async () => { try { const {sessionManager} = await import( '../utils/session/sessionManager.js' ); const body = await this.readJsonBody<{connectionId?: string}>(req); const connectionId = this.getActiveConnectionId(body.connectionId); if (!connectionId) { res.writeHead(400, {'Content-Type': 'application/json'}); res.end(JSON.stringify({error: 'No active connection'})); return; } const session = await sessionManager.createNewSession(); this.bindSessionToConnection(session.id, connectionId); res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: true, session})); } catch (error) { res.writeHead(500, {'Content-Type': 'application/json'}); res.end( JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error', }), ); } })(); } private handleSessionLoad(req: IncomingMessage, res: ServerResponse): void { void (async () => { try { const {sessionManager} = await import( '../utils/session/sessionManager.js' ); const body = await this.readJsonBody<{ sessionId?: string; connectionId?: string; }>(req); if (!body.sessionId) { res.writeHead(400, {'Content-Type': 'application/json'}); res.end(JSON.stringify({error: 'Missing sessionId'})); return; } const session = await sessionManager.loadSession(body.sessionId); if (!session) { res.writeHead(404, {'Content-Type': 'application/json'}); res.end(JSON.stringify({error: 'Session not found'})); return; } sessionManager.setCurrentSession(session); const connectionId = this.getActiveConnectionId(body.connectionId); if (connectionId) { this.bindSessionToConnection(session.id, connectionId); } res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: true, session})); } catch (error) { res.writeHead(500, {'Content-Type': 'application/json'}); res.end( JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error', }), ); } })(); } private handleSessionRollbackPoints( res: ServerResponse, query?: Record, ): void { void (async () => { try { const {sessionManager} = await import( '../utils/session/sessionManager.js' ); const {hashBasedSnapshotManager} = await import( '../utils/codebase/hashBasedSnapshot.js' ); const sessionIdRaw = query?.['sessionId']; const sessionId = typeof sessionIdRaw === 'string' ? sessionIdRaw.trim() : ''; if (!sessionId) { res.writeHead(400, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: false, error: 'Missing sessionId'})); return; } const session = await sessionManager.loadSession(sessionId); if (!session) { res.writeHead(404, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: false, error: 'Session not found'})); return; } const snapshots = await hashBasedSnapshotManager.listSnapshots( sessionId, ); const snapshotByIndex = new Map< number, {timestamp: number; fileCount: number} >(); for (const s of snapshots) { snapshotByIndex.set(s.messageIndex, { timestamp: s.timestamp, fileCount: s.fileCount, }); } const points: Array<{ messageIndex: number; role: 'user'; timestamp: number; summary: string; hasSnapshot: boolean; snapshot?: {timestamp: number; fileCount: number}; filesToRollbackCount: number; }> = []; const maxSummaryLen = 120; for (let i = 0; i < session.messages.length; i++) { const m: any = session.messages[i]; if (!m || m.role !== 'user') continue; const content = typeof m.content === 'string' ? m.content : ''; const normalized = content.replace(/\s+/g, ' ').trim(); const summary = normalized.length > maxSummaryLen ? normalized.slice(0, maxSummaryLen) + '…' : normalized; // Snapshot 的 messageIndex 和 session.messages 的索引并不总是一致。 // 实测快照通常对应“下一条消息写入前”的索引（例如首条 user 消息后快照会落在 1）。 const snapAtNext = snapshotByIndex.get(i + 1); const snapAtCurrent = snapshotByIndex.get(i); const snap = snapAtNext ?? snapAtCurrent; const rollbackIndex = snapAtNext ? i + 1 : i; let filesToRollbackCount = 0; if (snap && snap.fileCount > 0) { const files = await hashBasedSnapshotManager.getFilesToRollback( sessionId, rollbackIndex, ); filesToRollbackCount = Array.isArray(files) ? files.length : 0; } points.push({ messageIndex: i, role: 'user', timestamp: typeof m.timestamp === 'number' ? m.timestamp : 0, summary, hasSnapshot: !!snap && snap.fileCount > 0, snapshot: snap, filesToRollbackCount, }); // 如果快照存在但落在 i+1（常见），让前端能直接用 messageIndex 作为回滚点索引。 if ( snapAtNext && snapAtNext.fileCount > 0 && i + 1 < session.messages.length ) { // 这里不改变 messageIndex 的语义，仅用于确保 hasSnapshot 展示正确。 } } res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: true, sessionId, points})); } catch (error) { res.writeHead(500, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Unknown error', }), ); } })(); } private handleSessionList( _req: IncomingMessage, res: ServerResponse, query?: Record, ): void { void (async () => { try { const {sessionManager} = await import( '../utils/session/sessionManager.js' ); const pageRaw = query?.['page']; const pageSizeRaw = query?.['pageSize']; const searchQueryRaw = query?.['q']; const page = Math.max( 0, Number.parseInt(String(pageRaw ?? '0'), 10) || 0, ); const pageSize = Math.min( 200, Math.max(1, Number.parseInt(String(pageSizeRaw ?? '20'), 10) || 20), ); const searchQuery = typeof searchQueryRaw === 'string' && searchQueryRaw.trim() ? searchQueryRaw.trim() : undefined; const result = await sessionManager.listSessionsPaginated( page, pageSize, searchQuery, ); res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({ success: true, page, pageSize, searchQuery, ...result, }), ); } catch (error) { res.writeHead(500, {'Content-Type': 'application/json'}); res.end( JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error', }), ); } })(); } private handleSessionDelete( _req: IncomingMessage, res: ServerResponse, pathname: string, ): void { void (async () => { try { const {sessionManager} = await import( '../utils/session/sessionManager.js' ); const parts = pathname.split('/').filter(Boolean); const sessionId = parts[1]; if (!sessionId) { res.writeHead(400, {'Content-Type': 'application/json'}); res.end(JSON.stringify({error: 'Missing sessionId'})); return; } const deleted = await sessionManager.deleteSession(sessionId); res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: true, deleted})); } catch (error) { res.writeHead(500, {'Content-Type': 'application/json'}); res.end( JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error', }), ); } })(); } /** * 处理上下文压缩请求 * POST /context/compress * Body: { messages: ChatMessage[] } 或 { sessionId: string } * Response: { success: true, result: CompressionResult } 或 { success: false, error: string } */ private handleContextCompress( req: IncomingMessage, res: ServerResponse, ): void { void (async () => { try { const {compressContext} = await import( '../utils/core/contextCompressor.js' ); const {sessionManager} = await import( '../utils/session/sessionManager.js' ); const body = await this.readJsonBody<{ messages?: Array<{role: string; content: string; [key: string]: any}>; sessionId?: string; }>(req); let messages: Array<{ role: string; content: string; [key: string]: any; }>; // 支持两种方式：直接传入 messages 或通过 sessionId 获取 if (body.messages && Array.isArray(body.messages)) { messages = body.messages; } else if (body.sessionId) { const session = await sessionManager.loadSession(body.sessionId); if (!session) { res.writeHead(404, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({success: false, error: 'Session not found'}), ); return; } messages = session.messages || []; } else { res.writeHead(400, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({ success: false, error: 'Missing required field: messages or sessionId', }), ); return; } if (messages.length === 0) { res.writeHead(400, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({success: false, error: 'No messages to compress'}), ); return; } const result = await compressContext(messages as any); if (result === null) { res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({ success: true, result: null, message: 'Compression skipped (no history to compress)', }), ); return; } if (result.hookFailed) { res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({ success: false, hookFailed: true, hookErrorDetails: result.hookErrorDetails, }), ); return; } res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: true, result})); } catch (error) { res.writeHead(500, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end( JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Unknown error', }), ); } })(); } /** * 处理 SSE 连接 */ private handleSSEConnection(req: IncomingMessage, res: ServerResponse): void { const connectionId = `conn_${Date.now()}_${Math.random() .toString(36) .substring(7)}`; const connection = new SSEConnection(res, connectionId); this.connections.set(connectionId, connection); // 连接关闭时清理 req.on('close', () => { this.connections.delete(connectionId); this.log(`SSE 连接已关闭: ${connectionId}`, 'info'); }); this.log(`新的 SSE 连接: ${connectionId}`, 'success'); } /** * 处理客户端消息 */ private handleMessage(req: IncomingMessage, res: ServerResponse): void { let body = ''; req.on('data', chunk => { body += chunk.toString(); }); req.on('end', async () => { try { const message: ClientMessage = JSON.parse(body); // 验证消息格式 if (!message.type || (!message.content && message.type === 'chat')) { res.writeHead(400, {'Content-Type': 'application/json'}); res.end(JSON.stringify({error: 'Invalid message format'})); return; } // 根据 sessionId 获取对应的连接ID let targetConnectionId: string | undefined; if (message.sessionId) { targetConnectionId = this.sessionConnections.get(message.sessionId); if (!targetConnectionId) { // Session 不存在或连接已断开，使用第一个可用连接 const firstConnection = this.connections.values().next().value; if (firstConnection) { targetConnectionId = firstConnection.getId(); } } } else { // 没有指定 sessionId，使用第一个可用连接 const firstConnection = this.connections.values().next().value; if (firstConnection) { targetConnectionId = firstConnection.getId(); } } if (!targetConnectionId) { res.writeHead(400, {'Content-Type': 'application/json'}); res.end(JSON.stringify({error: 'No active connection'})); return; } // 向特定连接发送事件的函数 const sendEvent = (event: SSEEvent) => { this.sendToConnection(targetConnectionId!, event); }; // 调用消息处理器 if (this.messageHandler) { await this.messageHandler(message, sendEvent, targetConnectionId); } res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*', }); res.end(JSON.stringify({success: true})); } catch (error) { res.writeHead(500, {'Content-Type': 'application/json'}); res.end( JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error', }), ); } }); } /** * 广播事件到所有连接 */ broadcast(event: SSEEvent): void { this.connections.forEach(conn => { conn.sendEvent(event); }); } /** * 获取当前连接数 */ getConnectionCount(): number { return this.connections.size; } } ================================================ FILE: source/api/types.ts ================================================ /** * Shared API types for all AI providers */ export interface ImageContent { type: 'image'; data: string; // Base64 编码的图片数据 mimeType: string; // 图片 MIME 类型 } export interface ToolCall { id: string; type: 'function'; function: { name: string; arguments: string; }; } export interface ChatMessage { role: 'system' | 'user' | 'assistant' | 'tool'; content: string; messageStatus?: 'pending' | 'success' | 'error'; tool_call_id?: string; tool_calls?: ToolCall[]; images?: ImageContent[]; // 图片内容 subAgentInternal?: boolean; // Mark internal sub-agent messages (filtered from API requests) subAgentContent?: boolean; // Persisted sub-agent thinking/content replay message subAgent?: { agentId: string; agentName: string; isComplete?: boolean; }; // IDE editor context (VSCode workspace, active file, cursor position, selected code) // This field is stored separately and only used when sending to AI, not displayed in UI editorContext?: { workspaceFolder?: string; activeFile?: string; cursorPosition?: {line: number; character: number}; selectedText?: string; }; reasoning?: { summary?: Array<{type: 'summary_text'; text: string}>; content?: any; encrypted_content?: string; }; // Anthropic Extended Thinking - complete block with signature thinking?: { type: 'thinking'; thinking: string; // Accumulated thinking text signature?: string; // Required signature for verification }; // DeepSeek R1 Reasoning Content - complete reasoning chain reasoning_content?: string; // Complete reasoning content from DeepSeek R1 models } export interface ChatCompletionTool { type: 'function'; function: { name: string; description?: string; parameters?: Record; }; } export interface UsageInfo { prompt_tokens: number; completion_tokens: number; total_tokens: number; cache_creation_input_tokens?: number; // Tokens used to create cache (Anthropic) cache_read_input_tokens?: number; // Tokens read from cache (Anthropic) cached_tokens?: number; // Cached tokens from prompt_tokens_details (OpenAI) } ================================================ FILE: source/app.tsx ================================================ import React, {useState, useEffect, Suspense} from 'react'; import {Box, Text} from 'ink'; import {Alert} from '@inkjs/ui'; // Lazy load all page components to improve startup time // Only load components when they are actually needed const WelcomeScreen = React.lazy(() => import('./ui/pages/WelcomeScreen.js')); const ChatScreen = React.lazy(() => import('./ui/pages/ChatScreen.js')); const HeadlessModeScreen = React.lazy( () => import('./ui/pages/HeadlessModeScreen.js'), ); const TaskManagerScreen = React.lazy( () => import('./ui/pages/TaskManagerScreen.js'), ); const SystemPromptConfigScreen = React.lazy( () => import('./ui/pages/SystemPromptConfigScreen.js'), ); const CustomHeadersScreen = React.lazy( () => import('./ui/pages/CustomHeadersScreen.js'), ); const HelpScreen = React.lazy(() => import('./ui/pages/HelpScreen.js')); const ExitScreen = React.lazy(() => import('./ui/pages/ExitScreen.js')); import { useGlobalExit, ExitNotification as ExitNotificationType, } from './hooks/integration/useGlobalExit.js'; import {onNavigate} from './hooks/integration/useGlobalNavigation.js'; import {useTerminalSize} from './hooks/ui/useTerminalSize.js'; import {I18nProvider} from './i18n/index.js'; import {ThemeProvider} from './ui/contexts/ThemeContext.js'; import {gracefulExit} from './utils/core/processManager.js'; import {loadConfig} from './utils/config/apiConfig.js'; type Props = { version?: string; skipWelcome?: boolean; autoResume?: boolean; resumeSessionId?: string; headlessPrompt?: string; headlessSessionId?: string; showTaskList?: boolean; enableYolo?: boolean; enablePlan?: boolean; }; // ShowTaskListWrapper: Handles task list mode with session conversion support function ShowTaskListWrapper() { const [currentView, setCurrentView] = useState<'tasks' | 'chat' | 'exit'>( 'tasks', ); const [chatScreenKey, setChatScreenKey] = useState(0); const [exitNotification, setExitNotification] = useState({ show: false, message: '', }); const {columns: terminalWidth} = useTerminalSize(); const loadingFallback = null; // Global exit handler useGlobalExit(setExitNotification); // Listen for navigation events (including exit) useEffect(() => { const unsubscribe = onNavigate(event => { if ( event.destination === 'exit' || event.destination === 'tasks' || event.destination === 'chat' ) { setCurrentView(event.destination); } }); return unsubscribe; }, []); const renderView = () => { if (currentView === 'exit') { return ( ); } if (currentView === 'chat') { return ( ); } return ( gracefulExit()} onResumeTask={() => { // Session is already set by convertTaskToSession // Just navigate to chat view setCurrentView('chat'); setChatScreenKey(prev => prev + 1); }} /> ); }; return ( {renderView()} {exitNotification.show && currentView !== 'exit' && ( {exitNotification.message} )} ); } // Inner component that uses I18n context function AppContent({ version, skipWelcome, autoResume, resumeSessionId, enableYolo, enablePlan, }: { version?: string; skipWelcome?: boolean; autoResume?: boolean; resumeSessionId?: string; enableYolo?: boolean; enablePlan?: boolean; }) { const [currentView, setCurrentView] = useState< | 'welcome' | 'chat' | 'help' | 'settings' | 'systemprompt' | 'customheaders' | 'tasks' | 'exit' >(skipWelcome ? 'chat' : 'welcome'); // Add a key to force remount ChatScreen when returning from welcome screen // This ensures configuration changes are picked up const [chatScreenKey, setChatScreenKey] = useState(0); // Track the welcome menu index to preserve selection when returning const [welcomeMenuIndex, setWelcomeMenuIndex] = useState(0); // Explicit welcome menu choices must override CLI auto-resume defaults. const [welcomeChatAutoResume, setWelcomeChatAutoResume] = useState< boolean | null >(null); const [exitNotification, setExitNotification] = useState({ show: false, message: '', }); // Get terminal size for proper width calculation const {columns: terminalWidth} = useTerminalSize(); // Global exit handler (must be inside I18nProvider) useGlobalExit(setExitNotification); // Global navigation handler useEffect(() => { const unsubscribe = onNavigate(event => { // When navigating to welcome from chat (e.g., /home command), // increment key so next time chat is entered, it remounts with fresh config if (event.destination === 'welcome' && currentView === 'chat') { setChatScreenKey(prev => prev + 1); } // Reset the welcome choice override after leaving chat. if (event.destination !== 'chat' && currentView === 'chat') { setWelcomeChatAutoResume(null); } // 'pixel' handled as a panel inside chat, ignore direct navigation if (event.destination !== 'pixel') { setCurrentView(event.destination); } }); return unsubscribe; }, [currentView]); const handleMenuSelect = (value: string) => { if ( value === 'chat' || value === 'resume-last' || value === 'settings' || value === 'systemprompt' || value === 'customheaders' ) { // When entering chat from welcome screen, increment key to force remount // This ensures any configuration changes are picked up if ( (value === 'chat' || value === 'resume-last') && currentView === 'welcome' ) { setChatScreenKey(prev => prev + 1); // 初始化配置缓存，避免进入对话页后频繁读取硬盘 loadConfig(); } // Start Chat must force a fresh session; Resume Last Chat opts into auto-resume. setWelcomeChatAutoResume(value === 'resume-last'); // Both 'chat' and 'resume-last' go to chat view setCurrentView(value === 'resume-last' ? 'chat' : value); } else if (value === 'exit') { setCurrentView('exit'); } }; const renderView = () => { const loadingFallback = null; switch (currentView) { case 'welcome': return ( ); case 'chat': return ( ); case 'settings': return ( Settings Settings interface would be implemented here ); case 'systemprompt': return ( setCurrentView('welcome')} /> ); case 'help': return ( ); case 'customheaders': return ( setCurrentView('welcome')} /> ); case 'tasks': return ( setCurrentView('chat')} onResumeTask={() => { // Session is already set by convertTaskToSession // Just navigate to chat view setCurrentView('chat'); setChatScreenKey(prev => prev + 1); }} /> ); case 'exit': return ( ); default: return ( ); } }; return ( {renderView()} {exitNotification.show && currentView !== 'exit' && ( {exitNotification.message} )} ); } export default function App({ version, skipWelcome, autoResume, resumeSessionId, headlessPrompt, headlessSessionId, showTaskList, enableYolo, enablePlan, }: Props) { // If headless prompt is provided, use headless mode // Wrap in I18nProvider since HeadlessModeScreen might use hooks that depend on it if (headlessPrompt) { const loadingFallback = null; return ( gracefulExit()} /> ); } // If showTaskList is true, show task manager screen if (showTaskList) { return ( ); } return ( ); } ================================================ FILE: source/cli.tsx ================================================ #!/usr/bin/env node // Force color support for all chalk instances (must be set before any imports) // This ensures syntax highlighting works in cli-highlight and other color libraries // Remove NO_COLOR first to prevent conflict warning in Node.js 22+ delete process.env['NO_COLOR']; process.env['FORCE_COLOR'] = '3'; // Check Node.js version before anything else const MIN_NODE_VERSION = 16; const currentVersion = process.version; const major = parseInt(currentVersion.slice(1).split('.')[0] || '0', 10); if (major < MIN_NODE_VERSION) { console.error('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'); console.error(' Node.js Version Compatibility Error'); console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'); console.error(`Current Node.js version: ${currentVersion}`); console.error(`Required: Node.js >= ${MIN_NODE_VERSION}.x\n`); console.error('Please upgrade Node.js to continue:\n'); console.error('# Using nvm (recommended):'); console.error(` nvm install ${MIN_NODE_VERSION}`); console.error(` nvm use ${MIN_NODE_VERSION}\n`); console.error('# Or download from official website:'); console.error(' https://nodejs.org/\n'); console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'); process.exit(1); } // Sanitize NODE_OPTIONS to prevent noisy Node warnings // Some environments may inject an invalid `--localstorage-file` flag (e.g., without a path), // which causes: "Warning: `--localstorage-file` was provided without a valid path". function sanitizeNodeOptions() { const raw = process.env['NODE_OPTIONS']; if (!raw) return; const tokens = raw.split(/\s+/).filter(Boolean); const cleaned: string[] = []; for (let i = 0; i < tokens.length; i++) { const token = tokens[i]!; // Handle both `--localstorage-file ` and `--localstorage-file=` if (token === '--localstorage-file') { const next = tokens[i + 1]; // If missing/empty/looks like another flag, drop the flag entirely. if (!next || next.startsWith('-')) { continue; } // Keep as-is. cleaned.push(token, next); i++; continue; } if (token.startsWith('--localstorage-file=')) { const value = token.slice('--localstorage-file='.length); if (!value) { continue; } cleaned.push(token); continue; } cleaned.push(token); } const nextRaw = cleaned.join(' '); if (nextRaw !== raw) { process.env['NODE_OPTIONS'] = nextRaw; } } sanitizeNodeOptions(); // Some injected NODE_OPTIONS are parsed by Node before userland code runs. // If that happens (e.g. `--localstorage-file` without a path), the process may // already fail before we can sanitize. As a last resort, allow users to opt out // of inheriting NODE_OPTIONS by setting SNOW_IGNORE_NODE_OPTIONS=1. if (process.env['SNOW_IGNORE_NODE_OPTIONS'] === '1') { delete process.env['NODE_OPTIONS']; } // Suppress known deprecation warnings from dependencies const suppressedDepCodes = new Set(['DEP0040', 'DEP0169']); const originalEmitWarning = process.emitWarning; process.emitWarning = function (warning: any, ...args: any[]) { // emitWarning(msg, type, code) — positional form if (typeof args[1] === 'string' && suppressedDepCodes.has(args[1])) return; // emitWarning(msg, { code }) — options object form if ( args[0] && typeof args[0] === 'object' && suppressedDepCodes.has(args[0].code) ) return; // Suppress NO_COLOR/FORCE_COLOR conflict warning (Node.js 22+) if ( typeof warning === 'string' && warning.includes("'NO_COLOR'") && warning.includes("'FORCE_COLOR'") ) return; return (originalEmitWarning as any).apply(process, [warning, ...args]); }; // Global safety net: suppress known non-fatal stream errors (e.g. from LSP // processes exiting while vscode-jsonrpc still has queued writes) so they // don't crash the main CLI process. function isStreamDestroyedError(err: unknown): boolean { if (!(err instanceof Error)) return false; const code = (err as NodeJS.ErrnoException).code; if (code === 'ERR_STREAM_DESTROYED' || code === 'EPIPE') return true; const msg = err.message || ''; return ( msg.includes('stream was destroyed') || msg.includes('ERR_STREAM_DESTROYED') || msg.includes('write after end') || msg.includes('Cannot call write after a stream was destroyed') ); } process.on('uncaughtException', (err: Error) => { if (isStreamDestroyedError(err)) { // Silently ignore — these are expected when an LSP child process // exits while vscode-jsonrpc still has pending writes. return; } // For all other errors, preserve the default crash behaviour. console.error('Uncaught Exception:', err); process.exit(1); }); process.on('unhandledRejection', (reason: unknown) => { if (isStreamDestroyedError(reason)) { return; } // Log but don't exit — unhandled rejections are not necessarily fatal. console.error('Unhandled Rejection:', reason); }); // Check if this is a quick command that doesn't need loading indicator const args = process.argv.slice(2); const isQuickCommand = args.some( arg => arg === '--version' || arg === '-v' || arg === '--help' || arg === '-h' || arg === '--acp' || arg === '--sse' || arg === '--sse-daemon', ); // Show loading indicator only for non-quick commands if (!isQuickCommand) { process.stdout.write('\x1b[?25l'); // Hide cursor process.stdout.write('⠋ Loading...\r'); } // Import only critical dependencies synchronously import React from 'react'; import {render, Text, Box} from 'ink'; import {setUpdateNotice} from './utils/ui/updateNotice.js'; import Spinner from 'ink-spinner'; import meow from 'meow'; import {spawn} from 'child_process'; import {readFileSync} from 'fs'; import {join} from 'path'; import {fileURLToPath} from 'url'; // Read version from package.json const __dirname = fileURLToPath(new URL('.', import.meta.url)); const packageJson = JSON.parse( readFileSync(join(__dirname, '../package.json'), 'utf-8'), ); const VERSION = packageJson.version; // Load heavy dependencies asynchronously async function loadDependencies() { // Import utils/index.js to register all commands (side-effect import) await import('./utils/index.js'); //初始化全局代理（让MCP HTTP请求走代理） const {initGlobalProxy} = await import('./utils/core/proxyUtils.js'); initGlobalProxy(); const [ appModule, vscodeModule, resourceModule, configModule, processModule, devModeModule, childProcessModule, utilModule, mcpModule, ] = await Promise.all([ import('./app.js'), import('./utils/ui/vscodeConnection.js'), import('./utils/core/resourceMonitor.js'), import('./utils/config/configManager.js'), import('./utils/core/processManager.js'), import('./utils/core/devMode.js'), import('child_process'), import('util'), import('./utils/execution/mcpToolsManager.js'), ]); return { App: appModule.default, vscodeConnection: vscodeModule.vscodeConnection, resourceMonitor: resourceModule.resourceMonitor, initializeProfiles: configModule.initializeProfiles, processManager: processModule.processManager, enableDevMode: devModeModule.enableDevMode, getDevUserId: devModeModule.getDevUserId, exec: childProcessModule.exec, promisify: utilModule.promisify, closeAllMCPConnections: mcpModule.closeAllMCPConnections, }; } let execAsync: any; // Check for updates asynchronously async function checkForUpdates(currentVersion: string): Promise { try { const {stdout} = await execAsync( 'npm view snow-ai version --registry https://registry.npmjs.org', { encoding: 'utf8', }, ); const latestVersion = stdout.trim(); // Simple string comparison - force registry fetch ensures no cache issues if (latestVersion && latestVersion !== currentVersion) { setUpdateNotice({currentVersion, latestVersion}); } else { setUpdateNotice(null); } } catch { // Silently fail - don't interrupt user experience setUpdateNotice(null); } } const cli = meow( ` Usage $ snow $ snow --ask \"your prompt\" $ snow --ask \"your prompt\" $ snow --task \"your task description\" $ snow --task-list Options --help Show help --version Show version --update Update to latest version -c Skip welcome screen and resume last conversation (optionally specify sessionId) --ask Quick question mode (headless mode with single prompt, optional sessionId for continuous conversation) --task Create a background AI task (headless mode, saves session) --yolo Skip welcome screen and enable YOLO mode (auto-approve tools) --yolo-p Skip welcome screen and enable YOLO+Plan mode --c-yolo Skip welcome screen, resume last conversation, and enable YOLO mode --dev Enable developer mode with persistent userId for testing --sse Start SSE server mode for external integration (foreground) --sse-daemon Start SSE server as background daemon --sse-stop Stop SSE daemon server --sse-status Show SSE daemon server status --sse-port SSE server port (default: 3000) --sse-timeout SSE server interaction timeout in milliseconds (default: 300000, i.e. 5 minutes) --work-dir Working directory for SSE server (default: current directory) --acp Start ACP (Agent Client Protocol) server mode for external integration Uses stdin/stdout for JSON-RPC 2.0 communication `, { importMeta: import.meta, flags: { update: { type: 'boolean', default: false, }, c: { type: 'boolean', default: false, }, task: { type: 'string', }, taskList: { type: 'boolean', default: false, alias: 'task-list', }, taskExecute: { type: 'string', alias: 'task-execute', }, yolo: { type: 'boolean', default: false, }, yoloP: { type: 'boolean', default: false, alias: 'yolo-p', }, cYolo: { type: 'boolean', default: false, alias: 'c-yolo', }, dev: { type: 'boolean', default: false, }, sse: { type: 'boolean', default: false, }, sseDaemon: { type: 'boolean', default: false, alias: 'sse-daemon', }, sseDaemonMode: { type: 'boolean', default: false, alias: 'sse-daemon-mode', }, sseStop: { type: 'boolean', default: false, alias: 'sse-stop', }, sseStatus: { type: 'boolean', default: false, alias: 'sse-status', }, ssePort: { type: 'number', default: 3000, alias: 'sse-port', }, sseTimeout: { type: 'number', default: 300000, alias: 'sse-timeout', }, workDir: { type: 'string', alias: 'work-dir', }, acp: { type: 'boolean', default: false, }, }, }, ); // Handle update flag if (cli.flags.update) { console.log('Updating snow-ai to latest version...'); try { const child = spawn('npm i -g snow-ai', { stdio: 'inherit', shell: true, }); await new Promise((resolve, reject) => { child.on('close', code => { if (code === 0) { resolve(); } else { reject(new Error(`npm exited with code ${code}`)); } }); child.on('error', reject); }); console.log('Update completed successfully'); process.exit(0); } catch (error) { console.error( 'Update failed:', error instanceof Error ? error.message : error, ); console.log('\nYou can also update manually:\n npm i -g snow-ai'); process.exit(1); } } // Handle SSE daemon stop if (cli.flags.sseStop) { const {stopDaemon} = await import('./utils/sse/sseDaemon.js'); // 支持通过PID或端口停止 const target = cli.input[0] ? parseInt(cli.input[0]) : cli.flags.ssePort; stopDaemon(target); process.exit(0); } // Handle SSE daemon status if (cli.flags.sseStatus) { const {daemonStatus} = await import('./utils/sse/sseDaemon.js'); daemonStatus(); process.exit(0); } // Handle SSE daemon mode if (cli.flags.sseDaemon) { const {startDaemon} = await import('./utils/sse/sseDaemon.js'); const port = cli.flags.ssePort || 3000; const timeout = cli.flags.sseTimeout || 300000; const workDir = cli.flags.workDir; startDaemon(port, workDir, timeout); process.exit(0); } // Handle SSE server mode if (cli.flags.sse) { const {sseManager} = await import('./utils/sse/sseManager.js'); const port = cli.flags.ssePort || 3000; const timeout = cli.flags.sseTimeout || 300000; const workDir = cli.flags.workDir; const isDaemonMode = cli.flags.sseDaemonMode; // 如果指定了工作目录，切换到该目录 if (workDir) { try { process.chdir(workDir); } catch (error) { console.error(`错误: 无法切换到工作目录 ${workDir}`); console.error(error instanceof Error ? error.message : error); process.exit(1); } } // 守护进程模式：使用 DaemonLogger 纯文本日志 if (isDaemonMode) { const {DaemonLogger} = await import('./utils/sse/daemonLogger.js'); const logFilePath = process.env['SSE_DAEMON_LOG_FILE']; if (!logFilePath) { console.error('错误: 守护进程模式缺少日志文件路径'); process.exit(1); } const logger = new DaemonLogger(logFilePath); // 设置日志回调 sseManager.setLogCallback((message, level) => { logger.log(message, level); }); await sseManager.start(port, timeout); // 保持进程运行 process.on('SIGINT', async () => { logger.log('接收到 SIGINT 信号，正在停止服务器...', 'info'); await sseManager.stop(); process.exit(0); }); process.on('SIGTERM', async () => { logger.log('接收到 SIGTERM 信号，正在停止服务器...', 'info'); await sseManager.stop(); process.exit(0); }); // 阻止进程退出 await new Promise(() => {}); } else { // 前台模式：使用 Ink UI const {SSEServerStatus} = await import( './ui/components/sse/SSEServerStatus.js' ); const {I18nProvider} = await import('./i18n/I18nContext.js'); // 渲染 SSE 服务器信息组件 let logUpdater: ( message: string, level?: 'info' | 'error' | 'success', ) => void; const {unmount} = render( { logUpdater = callback; }} /> , ); // 设置日志回调 sseManager.setLogCallback((message, level) => { if (logUpdater) { logUpdater(message, level); } }); await sseManager.start(port, timeout); // 保持进程运行 process.on('SIGINT', async () => { unmount(); console.log('\nStopping SSE server...'); await sseManager.stop(); process.exit(0); }); process.on('SIGTERM', async () => { unmount(); console.log('\nStopping SSE server...'); await sseManager.stop(); process.exit(0); }); // 阻止进程退出 await new Promise(() => {}); } } // Handle ACP (Agent Client Protocol) server mode if (cli.flags.acp) { const {acpManager} = await import('./utils/acp/acpManager.js'); // Start ACP server with stdin/stdout await acpManager.start(process.stdin, process.stdout); process.exit(0); } // Handle task creation - create and execute in background if (cli.flags.task) { const {taskManager} = await import('./utils/task/taskManager.js'); const {executeTaskInBackground} = await import( './utils/task/taskExecutor.js' ); const task = await taskManager.createTask(cli.flags.task); await executeTaskInBackground(task.id, cli.flags.task); console.log(`Task created: ${task.id}`); console.log(`Title: ${task.title}`); console.log(`Use "snow --task-list" to view task status`); process.exit(0); } // Handle task execution (internal use by background process) if (cli.flags.taskExecute) { const {executeTask} = await import('./utils/task/taskExecutor.js'); const taskId = cli.flags.taskExecute; // Get prompt from remaining args after -- const promptIndex = process.argv.indexOf('--'); const prompt = promptIndex !== -1 ? process.argv.slice(promptIndex + 1).join(' ') : cli.input.join(' '); console.log( `[Task ${taskId}] Starting execution with prompt: ${prompt.slice( 0, 50, )}...`, ); await executeTask(taskId, prompt); process.exit(0); } // Startup component that shows loading spinner during update check const Startup = ({ version, skipWelcome, autoResume, resumeSessionId, headlessPrompt, headlessSessionId, showTaskList, isDevMode, enableYolo, enablePlan, }: { version: string | undefined; skipWelcome: boolean; autoResume: boolean; resumeSessionId?: string; headlessPrompt?: string; headlessSessionId?: string; showTaskList?: boolean; isDevMode: boolean; enableYolo?: boolean; enablePlan?: boolean; }) => { const [appReady, setAppReady] = React.useState(false); const [AppComponent, setAppComponent] = React.useState(null); React.useEffect(() => { let mounted = true; const init = async () => { // Load all dependencies in parallel const deps = await loadDependencies(); // Setup execAsync for checkForUpdates execAsync = deps.promisify(deps.exec); setUpdateNotice(null); // Initialize profiles system try { deps.initializeProfiles(); } catch (error) { console.error('Failed to initialize profiles:', error); } // Handle dev mode if (isDevMode) { deps.enableDevMode(); const userId = deps.getDevUserId(); console.log('Developer mode enabled'); console.log(`Using persistent userId: ${userId}`); console.log(`Stored in: ~/.snow/dev-user-id\n`); } // Start resource monitoring in development/debug mode if (process.env['NODE_ENV'] === 'development' || process.env['DEBUG']) { deps.resourceMonitor.startMonitoring(30000); setInterval(() => { const {hasLeak, reasons} = deps.resourceMonitor.checkForLeaks(); if (hasLeak) { console.error('Potential memory leak detected:'); reasons.forEach((reason: string) => console.error(` - ${reason}`)); } }, 5 * 60 * 1000); } // Store for cleanup (global as any).__deps = deps; // Render the app immediately once dependencies are ready. // The update check runs in the background to avoid blocking startup // when the network is slow/unreachable. WelcomeScreen subscribes to // onUpdateNotice and will render the notification UI once a result // is available. if (mounted) { setAppComponent(() => deps.App); setAppReady(true); } // Fire-and-forget update check — never block app entry on network IO. if (VERSION) { void checkForUpdates(VERSION); } }; init(); return () => { mounted = false; }; }, [version, isDevMode]); if (!appReady || !AppComponent) { return ( Loading... ); } return ( ); }; // Disable bracketed paste mode on startup process.stdout.write('\x1b[?2004l'); // Clear the early loading indicator process.stdout.write('\x1b[2K\r'); // Track cleanup state to prevent multiple cleanup calls let isCleaningUp = false; // Shared promise so concurrent SIGINT/SIGTERM handlers await the same cleanup let cleanupPromise: Promise | null = null; // Synchronous cleanup for 'exit' event (cannot be async) const cleanupSync = () => { process.stdout.write('\x1b[?2004l'); process.stdout.write('\x1b[?25h'); // Restore cursor visibility on exit process.stdout.write('\x1b[0 q'); // Restore cursor shape to terminal default (DECSCUSR) // If async cleanup is already running/done, skip deps to avoid double-close of // libuv handles (causes UV_HANDLE_CLOSING assertion failure on Windows) if (!isCleaningUp) { const deps = (global as any).__deps; if (deps) { // Kill all child processes synchronously deps.processManager.killAll(); deps.resourceMonitor.stopMonitoring(); deps.vscodeConnection.stop(); } } }; // Async cleanup for SIGINT/SIGTERM - waits for graceful shutdown const cleanupAsync = async () => { if (isCleaningUp) return; isCleaningUp = true; // Close the chokidar file watcher BEFORE Ink unmount, calling the agent // directly to avoid triggering React state updates that cause Ink to // re-render on handles that are about to be closed. // React effect cleanups are synchronous and cannot await chokidar's async // close(), which leaves libuv handles in a half-closed state. try { const codebaseAgent = (global as any).__codebaseAgent; if (codebaseAgent) { codebaseAgent.stopWatching(); await Promise.race([ codebaseAgent.waitForWatcherClose(), new Promise(resolve => setTimeout(resolve, 1000)), ]); } } catch { // Ignore codebase watcher close errors } // Unmount Ink so React effects cleanup (timers, stdin listeners, raw mode) // can release libuv handles before we start closing deps. try { mainInk?.unmount(); } catch { // Ignore unmount errors - already unmounted or in bad state } // On Windows, Ink unmount restores stdin raw mode and releases TTY handles. // The console reader thread needs time to stop before process.exit() can // safely close all remaining libuv handles. A single setImmediate is not // enough — use setTimeout to span multiple event loop iterations so // pending uv_close callbacks (stdin reader, chokidar IOCP) can complete. await new Promise(resolve => setTimeout(resolve, 50)); process.stdout.write('\x1b[?2004l'); process.stdout.write('\x1b[?25h'); // Restore cursor visibility on exit process.stdout.write('\x1b[0 q'); // Restore cursor shape to terminal default (DECSCUSR) // Import and cleanup command usage manager with timeout const {commandUsageManager} = await import( './utils/session/commandUsageManager.js' ); await Promise.race([ commandUsageManager.dispose(), new Promise(resolve => setTimeout(resolve, 500)), // 500ms timeout for saving usage data ]); // Cleanup global singleton resources (close browser, free encoders, etc.) try { const {cleanupGlobalResources} = await import( './utils/core/globalCleanup.js' ); await Promise.race([ cleanupGlobalResources(), new Promise(resolve => setTimeout(resolve, 2000)), ]); } catch { // Ignore cleanup errors during exit } const deps = (global as any).__deps; if (deps) { // Close MCP connections first (graceful shutdown with timeout) try { await Promise.race([ deps.closeAllMCPConnections?.(), new Promise(resolve => setTimeout(resolve, 2000)), // 2s timeout ]); } catch { // Ignore MCP close errors } // Then kill remaining processes deps.processManager.killAll(); deps.resourceMonitor.stopMonitoring(); deps.vscodeConnection.stop(); } }; process.on('exit', cleanupSync); process.on('SIGINT', async () => { // Reuse the same promise so a rapid second Ctrl+C waits for the first cleanup // instead of calling process.exit() while handles are still being torn down if (!cleanupPromise) { cleanupPromise = cleanupAsync(); } await cleanupPromise; // Don't call process.exit() synchronously — on Windows the stdin reader // thread and chokidar IOCP may still be signalling their uv_async handles. // A short delay lets libuv finish processing pending close callbacks, // preventing "Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)". setTimeout(() => process.exit(0), 50); }); process.on('SIGTERM', async () => { if (!cleanupPromise) { cleanupPromise = cleanupAsync(); } await cleanupPromise; setTimeout(() => process.exit(0), 50); }); const isResumeMode = Boolean(cli.flags.c || cli.flags.cYolo); const resumeSessionId = isResumeMode ? cli.input[0] : undefined; const mainInk = render( , { exitOnCtrlC: false, patchConsole: true, }, ); // Expose the Ink render handle so non-component code (e.g. the in-app // "Update Now" action in WelcomeScreen) can unmount Ink before handing the // terminal over to a child process such as `npm i -g snow-ai`. (global as any).__mainInk = mainInk; ================================================ FILE: source/hooks/conversation/chatLogic/types.ts ================================================ import type {Message} from '../../../ui/components/chat/MessageList.js'; export type {Message}; export interface UseChatLogicProps { messages: Message[]; setMessages: React.Dispatch>; pendingMessages: Array<{ text: string; images?: Array<{data: string; mimeType: string}>; }>; setPendingMessages: React.Dispatch< React.SetStateAction< Array<{text: string; images?: Array<{data: string; mimeType: string}>}> > >; streamingState: any; vscodeState: any; snapshotState: any; bashMode: any; yoloMode: boolean; planMode: boolean; vulnerabilityHuntingMode: boolean; teamMode: boolean; toolSearchDisabled: boolean; saveMessage: (msg: any) => Promise; clearSavedMessages: () => void; setRemountKey: React.Dispatch>; requestToolConfirmation: any; requestUserQuestion: any; isToolAutoApproved: any; addMultipleToAlwaysApproved: any; setRestoreInputContent: React.Dispatch< React.SetStateAction<{ text: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; } | null> >; isCompressing: boolean; setIsCompressing: React.Dispatch>; setCompressionError: React.Dispatch>; currentContextPercentageRef: React.MutableRefObject; userInterruptedRef: React.MutableRefObject; pendingMessagesRef: React.MutableRefObject< Array<{text: string; images?: Array<{data: string; mimeType: string}>}> >; setBashSensitiveCommand: React.Dispatch< React.SetStateAction<{ command: string; resolve: (proceed: boolean) => void; } | null> >; pendingUserQuestion: { question: string; options: string[]; toolCall: any; resolve: (result: { selected: string | string[]; customInput?: string; cancelled?: boolean; }) => void; } | null; setPendingUserQuestion: React.Dispatch< React.SetStateAction<{ question: string; options: string[]; toolCall: any; resolve: (result: { selected: string | string[]; customInput?: string; cancelled?: boolean; }) => void; } | null> >; // Session panel handlers initializeFromSession: (messages: any[]) => void; setShowSessionPanel: (show: boolean) => void; setShowReviewCommitPanel: (show: boolean) => void; // Quit and reindex handlers codebaseAgentRef: React.MutableRefObject; setCodebaseIndexing: React.Dispatch>; setCodebaseProgress: React.Dispatch< React.SetStateAction<{ totalFiles: number; processedFiles: number; totalChunks: number; currentFile: string; status: string; error?: string; } | null> >; setFileUpdateNotification: React.Dispatch< React.SetStateAction<{ file: string; timestamp: number; } | null> >; setWatcherEnabled: React.Dispatch>; exitingApplicationText: string; // New props for migrated logic commandsLoaded?: boolean; terminalExecutionState?: any; backgroundProcesses?: any; panelState?: any; setIsExecutingTerminalCommand?: React.Dispatch>; setHookError?: React.Dispatch>; hasFocus?: boolean; setSuppressLoadingIndicator?: React.Dispatch>; bashSensitiveCommand?: { command: string; resolve: (proceed: boolean) => void; } | null; handleCommandExecution?: (command: string, result: any) => void; // Tool confirmation state from useToolConfirmation hook pendingToolConfirmation?: { tool: { function: { name: string; arguments: string; }; }; allTools?: any[]; batchToolNames?: string; resolve: (result: any) => void; } | null; // Scheduler execution state for ESC interrupt handling schedulerExecutionState?: { state: { isRunning: boolean; description: string | null; totalDuration: number; remainingSeconds: number; startedAt: string | null; isCompleted: boolean; completedAt: string | null; }; resetTask: () => void; }; onCompressionStatus?: ( status: | import('../../../ui/components/compression/CompressionStatus.js').CompressionStatus | null, ) => void; setIsResumingSession?: React.Dispatch>; } ================================================ FILE: source/hooks/conversation/chatLogic/useChatHandlers.ts ================================================ import {useStdout} from 'ink'; import ansiEscapes from 'ansi-escapes'; import {useI18n} from '../../../i18n/index.js'; import type {UseChatLogicProps, Message} from './types.js'; import type {ReviewCommitSelection} from '../../../ui/components/panels/ReviewCommitPanel.js'; import {reviewAgent} from '../../../agents/reviewAgent.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {hashBasedSnapshotManager} from '../../../utils/codebase/hashBasedSnapshot.js'; import {convertSessionMessagesToUI} from '../../../utils/session/sessionConverter.js'; import {reindexCodebase} from '../../../utils/codebase/reindexCodebase.js'; import {navigateTo} from '../../integration/useGlobalNavigation.js'; interface UseChatHandlersDeps { processMessage: ( message: string, images?: Array<{data: string; mimeType: string}>, useBasicModel?: boolean, hideUserMessage?: boolean, ) => Promise; } export function useChatHandlers( props: UseChatLogicProps, deps: UseChatHandlersDeps, ) { const {stdout} = useStdout(); const {t} = useI18n(); const { setMessages, setPendingMessages, streamingState, snapshotState, clearSavedMessages, setRemountKey, pendingUserQuestion, setPendingUserQuestion, userInterruptedRef, initializeFromSession, setShowSessionPanel, setShowReviewCommitPanel, codebaseAgentRef, setCodebaseIndexing, setCodebaseProgress, setFileUpdateNotification, setWatcherEnabled, setIsResumingSession, } = props; const {processMessage} = deps; const handleUserQuestionAnswer = (result: { selected: string | string[]; customInput?: string; cancelled?: boolean; }) => { if (pendingUserQuestion) { if (result.cancelled) { const resolver = pendingUserQuestion.resolve; setPendingUserQuestion(null); userInterruptedRef.current = true; streamingState.setIsStopping(true); resolver(result); if (streamingState.abortController) { streamingState.abortController.abort(); } setPendingMessages([]); return; } pendingUserQuestion.resolve(result); setPendingUserQuestion(null); } }; const handleSessionPanelSelect = async (sessionId: string) => { setShowSessionPanel(false); setIsResumingSession?.(true); try { const session = await sessionManager.loadSession(sessionId); if (session) { const uiMessages = convertSessionMessagesToUI(session.messages); stdout.write(ansiEscapes.clearTerminal); setPendingMessages([]); streamingState.setIsStreaming(false); setMessages([]); setRemountKey(prev => prev + 1); await new Promise(resolve => setTimeout(resolve, 0)); initializeFromSession(session.messages); setMessages(uiMessages); streamingState.setContextUsage(session.contextUsage ?? null); const snapshots = await hashBasedSnapshotManager.listSnapshots( session.id, ); const counts = new Map(); for (const snapshot of snapshots) { counts.set(snapshot.messageIndex, snapshot.fileCount); } snapshotState.setSnapshotFileCount(counts); if (sessionManager.lastLoadHookWarning) { console.log(sessionManager.lastLoadHookWarning); } } else { if (sessionManager.lastLoadHookError) { const errorMessage: Message = { role: 'assistant', content: '', hookError: sessionManager.lastLoadHookError, }; setMessages(prev => [...prev, errorMessage]); } else { const errorMessage: Message = { role: 'assistant', content: 'Failed to load session.', }; setMessages(prev => [...prev, errorMessage]); } } } catch (error) { console.error('Failed to load session:', error); } finally { setIsResumingSession?.(false); } }; const handleQuit = async () => { navigateTo('exit'); }; const handleReindexCodebase = async (force?: boolean) => { const workingDirectory = process.cwd(); setCodebaseIndexing(true); try { const agent = await reindexCodebase( workingDirectory, codebaseAgentRef.current, progressData => { setCodebaseProgress({ totalFiles: progressData.totalFiles, processedFiles: progressData.processedFiles, totalChunks: progressData.totalChunks, currentFile: progressData.currentFile, status: progressData.status, error: progressData.error, }); if ( progressData.status === 'completed' || progressData.status === 'error' ) { setCodebaseIndexing(false); } }, force, ); codebaseAgentRef.current = agent; if (agent) { agent.startWatching((watcherProgressData: any) => { setCodebaseProgress({ totalFiles: watcherProgressData.totalFiles, processedFiles: watcherProgressData.processedFiles, totalChunks: watcherProgressData.totalChunks, currentFile: watcherProgressData.currentFile, status: watcherProgressData.status, error: watcherProgressData.error, }); if ( watcherProgressData.totalFiles === 0 && watcherProgressData.currentFile ) { setFileUpdateNotification({ file: watcherProgressData.currentFile, timestamp: Date.now(), }); setTimeout(() => { setFileUpdateNotification(null); }, 3000); } }); setWatcherEnabled(true); } } catch (error) { setCodebaseIndexing(false); throw error; } }; const handleToggleCodebase = async (mode?: string) => { const workingDirectory = process.cwd(); const {loadCodebaseConfig, saveCodebaseConfig} = await import( '../../../utils/config/codebaseConfig.js' ); const config = loadCodebaseConfig(workingDirectory); let newEnabled: boolean; if (mode === 'on') { newEnabled = true; } else if (mode === 'off') { newEnabled = false; } else { newEnabled = !config.enabled; } config.enabled = newEnabled; saveCodebaseConfig(config, workingDirectory); const statusMessage: Message = { role: 'command', content: newEnabled ? t.chatScreen.codebaseIndexingEnabled : t.chatScreen.codebaseIndexingDisabled, commandName: 'codebase', }; setMessages(prev => [...prev, statusMessage]); if (newEnabled) { await handleReindexCodebase(); } else { if (codebaseAgentRef.current) { await codebaseAgentRef.current.stop(); codebaseAgentRef.current.stopWatching(); codebaseAgentRef.current = null; } setCodebaseIndexing(false); setWatcherEnabled(false); setCodebaseProgress(null); setFileUpdateNotification(null); } }; const handleReviewCommitConfirm = async ( selection: ReviewCommitSelection[], notes: string, ) => { setShowReviewCommitPanel(false); try { const gitCheck = reviewAgent.checkGitRepository(); if (!gitCheck.isGitRepo || !gitCheck.gitRoot) { throw new Error(gitCheck.error || 'Not a git repository'); } const gitRoot = gitCheck.gitRoot; const parts: string[] = []; for (const item of selection) { if (item.type === 'staged') { const diff = reviewAgent.getStagedDiff(gitRoot); parts.push(diff); } else if (item.type === 'unstaged') { const diff = reviewAgent.getUnstagedDiff(gitRoot); parts.push(diff); } else { const patch = reviewAgent.getCommitPatch(gitRoot, item.sha); parts.push(patch); } } const combined = parts .map(p => p.trim()) .filter(Boolean) .join('\n\n'); if (!combined) { throw new Error( 'No changes detected. Please make some changes before running code review.', ); } const notesBlock = notes.trim() ? `\n\n**User's Additional Notes:**\n${notes.trim()}\n` : ''; const prompt = `You are a senior code reviewer. Please review the following git changes and provide feedback. **Your task:** 1. Identify potential bugs, security issues, or logic errors 2. Suggest performance optimizations 3. Point out code quality issues (readability, maintainability) 4. Check for best practices violations 5. Highlight any breaking changes or compatibility issues **Important:** - DO NOT modify the code yourself - Focus on finding issues and suggesting improvements - Ask the user if they want to fix any issues you find - Be constructive and specific in your feedback - Prioritize critical issues over minor style preferences${notesBlock} **Git Changes:** \`\`\`diff ${combined} \`\`\` Please provide your review in a clear, structured format.`; sessionManager.clearCurrentSession(); clearSavedMessages(); setMessages([]); setRemountKey(prev => prev + 1); streamingState.setContextUsage(null); const selectedWorkingTree = selection.some( s => s.type === 'staged' || s.type === 'unstaged', ); const selectedCommits = selection.filter(s => s.type === 'commit'); const commitShas = selectedCommits.map(s => s.sha).filter(Boolean); const shortCommitList = commitShas .slice(0, 6) .map(sha => sha.slice(0, 8)) .join(', '); const selectedSummary = t.chatScreen.reviewSelectedSummary .replace( '{workingTreePrefix}', selectedWorkingTree ? t.chatScreen.reviewSelectedWorkingTreePrefix : '', ) .replace('{commitCount}', selectedCommits.length.toString()); const commandLines: string[] = [ t.chatScreen.reviewStartTitle, selectedSummary, ]; if (commitShas.length > 0) { const moreSuffix = commitShas.length > 6 ? t.chatScreen.reviewCommitsMoreSuffix.replace( '{commitCount}', commitShas.length.toString(), ) : ''; commandLines.push( t.chatScreen.reviewCommitsLine .replace('{commitList}', shortCommitList) .replace('{moreSuffix}', moreSuffix), ); } if (notes.trim()) { commandLines.push( t.chatScreen.reviewNotesLine.replace('{notes}', notes.trim()), ); } commandLines.push(t.chatScreen.reviewGenerating); commandLines.push(t.chatScreen.reviewInterruptHint); const commandMessage: Message = { role: 'command', content: commandLines.join('\n'), commandName: 'review', }; setMessages([commandMessage]); await processMessage(prompt, undefined, false, true); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Failed to start review'; const errorMessage: Message = { role: 'command', content: errorMsg, commandName: 'review', }; setMessages(prev => [...prev, errorMessage]); } }; return { handleUserQuestionAnswer, handleSessionPanelSelect, handleQuit, handleReindexCodebase, handleToggleCodebase, handleReviewCommitConfirm, }; } ================================================ FILE: source/hooks/conversation/chatLogic/useMessageProcessing.ts ================================================ import {useRef, useEffect} from 'react'; import type {UseChatLogicProps, Message} from './types.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {handleConversationWithTools} from '../useConversation.js'; import { parseAndValidateFileReferences, createMessageWithFileInstructions, } from '../../../utils/core/fileUtils.js'; import { shouldAutoCompress, performAutoCompression, } from '../../../utils/core/autoCompress.js'; import { getSnowConfig, DEFAULT_AUTO_COMPRESS_THRESHOLD, } from '../../../utils/config/apiConfig.js'; import {runningSubAgentTracker} from '../../../utils/execution/runningSubAgentTracker.js'; import {teamTracker} from '../../../utils/execution/teamTracker.js'; import {compressionCoordinator} from '../../../utils/core/compressionCoordinator.js'; interface MessageTarget { instanceId: string; agentName: string; type: 'subagent' | 'teammate'; } /** * Parse "# SubAgentTarget:instanceId:agentName" and "# TeamTarget:instanceId:agentName" * markers from a message. * These are injected by the running-agents picker via TextBuffer placeholders. * Returns the target info and the clean message (markers stripped). */ function parseMessageTargets(message: string): { targets: MessageTarget[]; cleanMessage: string; } { const targets: MessageTarget[] = []; const lines = message.split('\n'); const cleanLines: string[] = []; for (const line of lines) { if (line.startsWith('# SubAgentTarget:')) { const rest = line.slice('# SubAgentTarget:'.length); const colonIdx = rest.indexOf(':'); if (colonIdx !== -1) { targets.push({ instanceId: rest.slice(0, colonIdx), agentName: rest.slice(colonIdx + 1), type: 'subagent', }); } } else if (line.startsWith('# TeamTarget:')) { const rest = line.slice('# TeamTarget:'.length); const colonIdx = rest.indexOf(':'); if (colonIdx !== -1) { targets.push({ instanceId: rest.slice(0, colonIdx), agentName: rest.slice(colonIdx + 1), type: 'teammate', }); } } else { cleanLines.push(line); } } const cleanMessage = cleanLines.join('\n').trim(); return {targets, cleanMessage}; } export function useMessageProcessing(props: UseChatLogicProps) { const { messages, setMessages, setPendingMessages, streamingState, vscodeState, snapshotState, bashMode, yoloMode, planMode, vulnerabilityHuntingMode, teamMode, toolSearchDisabled, saveMessage, clearSavedMessages, setRemountKey, requestToolConfirmation, requestUserQuestion, isToolAutoApproved, addMultipleToAlwaysApproved, setRestoreInputContent, setIsCompressing, setCompressionError, currentContextPercentageRef, userInterruptedRef, pendingMessagesRef, setBashSensitiveCommand, } = props; const processMessageRef = useRef< | (( message: string, images?: Array<{data: string; mimeType: string}>, useBasicModel?: boolean, hideUserMessage?: boolean, ) => Promise) | null >(null); const yoloModeRef = useRef(yoloMode); useEffect(() => { yoloModeRef.current = yoloMode; }, [yoloMode]); const appendAiCompletionTimeMessage = () => { setMessages(prev => [ ...prev, { role: 'assistant', content: '', streaming: false, aiCompletionTime: new Date(), }, ]); }; const processMessage = async ( message: string, images?: Array<{data: string; mimeType: string}>, useBasicModel?: boolean, hideUserMessage?: boolean, ) => { const autoCompressConfig = getSnowConfig(); if ( autoCompressConfig.enableAutoCompress !== false && shouldAutoCompress( currentContextPercentageRef.current, autoCompressConfig.autoCompressThreshold ?? DEFAULT_AUTO_COMPRESS_THRESHOLD, ) ) { setIsCompressing(true); streamingState.setIsAutoCompressing(true); setCompressionError(null); await compressionCoordinator.acquireLock('main'); try { const compressingMessage: Message = { role: 'assistant', content: '✵ Auto-compressing context due to token limit...', streaming: false, }; setMessages(prev => [...prev, compressingMessage]); const session = sessionManager.getCurrentSession(); const compressionResult = await performAutoCompression(session?.id); if (compressionResult) { clearSavedMessages(); setMessages(compressionResult.uiMessages); setRemountKey(prev => prev + 1); streamingState.setContextUsage(compressionResult.usage); snapshotState.setSnapshotFileCount(new Map()); } else { setMessages(prev => prev.filter(m => m !== compressingMessage)); } } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown error'; setCompressionError(errorMsg); const errorMessage: Message = { role: 'assistant', content: `**Auto-compression Failed**`, streaming: false, }; setMessages(prev => [...prev, errorMessage]); setIsCompressing(false); streamingState.setIsAutoCompressing(false); return; } finally { compressionCoordinator.releaseLock('main'); setIsCompressing(false); streamingState.setIsAutoCompressing(false); } } streamingState.setRetryStatus(null); const {cleanContent, validFiles} = await parseAndValidateFileReferences( message, ); const imageFiles = validFiles.filter( f => f.isImage && f.imageData && f.mimeType, ); const regularFiles = validFiles.filter(f => !f.isImage); const imageContents = [ ...(images || []).map(img => ({ type: 'image' as const, data: img.data, mimeType: img.mimeType, })), ...imageFiles.map(f => ({ type: 'image' as const, data: f.imageData!, mimeType: f.mimeType!, })), ]; if (!hideUserMessage) { const userMessage: Message = { role: 'user', content: cleanContent, files: validFiles.length > 0 ? validFiles : undefined, images: imageContents.length > 0 ? imageContents : undefined, }; setMessages(prev => [...prev, userMessage]); } streamingState.setIsStreaming(true); const controller = new AbortController(); streamingState.setAbortController(controller); let originalMessage = message; let optimizedMessage = message; let optimizedCleanContent = cleanContent; try { const messageForAI = createMessageWithFileInstructions( optimizedCleanContent, regularFiles, vscodeState.vscodeConnected ? vscodeState.editorContext : undefined, ); const saveMessageWithOriginal = async (msg: any) => { if (msg.role === 'user' && optimizedMessage !== originalMessage) { await saveMessage({ ...msg, originalContent: originalMessage, editorContext: messageForAI.editorContext, }); } else { await saveMessage({ ...msg, editorContext: msg.role === 'user' ? messageForAI.editorContext : undefined, }); } }; try { await handleConversationWithTools({ userContent: messageForAI.content, editorContext: messageForAI.editorContext, imageContents, controller, messages, saveMessage: saveMessageWithOriginal, setMessages, setStreamTokenCount: streamingState.setStreamTokenCount, requestToolConfirmation, requestUserQuestion, isToolAutoApproved, addMultipleToAlwaysApproved, yoloModeRef, planMode, vulnerabilityHuntingMode, teamMode, toolSearchDisabled, setContextUsage: streamingState.setContextUsage, useBasicModel, getPendingMessages: () => pendingMessagesRef.current, clearPendingMessages: () => setPendingMessages([]), setIsStreaming: streamingState.setIsStreaming, setIsReasoning: streamingState.setIsReasoning, setRetryStatus: streamingState.setRetryStatus, clearSavedMessages, setRemountKey, setSnapshotFileCount: snapshotState.setSnapshotFileCount, getCurrentContextPercentage: () => currentContextPercentageRef.current, setCurrentModel: streamingState.setCurrentModel, onCompressionStatus: props.onCompressionStatus, setIsAutoCompressing: streamingState.setIsAutoCompressing, }); } finally { // On-demand backup system - snapshot management is automatic } } catch (error) { if (!controller.signal.aborted && !userInterruptedRef.current) { const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'; const finalMessage: Message = { role: 'assistant', content: `Error: ${errorMessage}`, streaming: false, messageStatus: 'error', }; setMessages(prev => [...prev, finalMessage]); } } finally { if (userInterruptedRef.current) { const session = sessionManager.getCurrentSession(); if (session && session.messages.length > 0) { (async () => { try { const messages = session.messages; let truncateIndex = messages.length; for (let i = messages.length - 1; i >= 0; i--) { const msg = messages[i]; if (!msg) continue; if ( msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0 ) { const toolCallIds = new Set(msg.tool_calls.map(tc => tc.id)); for (let j = i + 1; j < messages.length; j++) { const followMsg = messages[j]; if ( followMsg && followMsg.role === 'tool' && followMsg.tool_call_id ) { toolCallIds.delete(followMsg.tool_call_id); } } if (toolCallIds.size > 0) { let hasLaterAssistantWithTools = false; for (let k = i + 1; k < messages.length; k++) { const laterMsg = messages[k]; if ( laterMsg?.role === 'assistant' && laterMsg?.tool_calls && laterMsg.tool_calls.length > 0 ) { hasLaterAssistantWithTools = true; break; } } if (!hasLaterAssistantWithTools) { truncateIndex = i; break; } } } if (msg.role === 'assistant' && !msg.tool_calls) { break; } } if (truncateIndex < messages.length) { await sessionManager.truncateMessages(truncateIndex); clearSavedMessages(); } } catch (error) { console.error( 'Failed to clean up incomplete conversation:', error, ); } })(); } setMessages(prev => [ ...prev, { role: 'assistant', content: '', streaming: false, discontinued: true, }, ]); userInterruptedRef.current = false; streamingState.setIsStopping(false); } appendAiCompletionTimeMessage(); streamingState.setIsStreaming(false); streamingState.setAbortController(null); streamingState.setStreamTokenCount(0); streamingState.setIsStreaming(false); streamingState.setAbortController(null); streamingState.setStreamTokenCount(0); } }; processMessageRef.current = processMessage; const handleMessageSubmit = async ( message: string, images?: Array<{data: string; mimeType: string}>, ) => { const {targets: messageTargets, cleanMessage: messageWithoutTargets} = parseMessageTargets(message); if (messageTargets.length > 0 && messageWithoutTargets) { const injectedTargets: Array<{ agentName: string; promptSnippet: string; }> = []; for (const target of messageTargets) { let success = false; let rawPrompt = ''; if (target.type === 'teammate') { success = teamTracker.sendMessageToTeammate( 'lead', target.instanceId, `[User Message]\n${messageWithoutTargets}`, ); if (success) { const teammate = teamTracker.getTeammate(target.instanceId); rawPrompt = teammate?.prompt || ''; } } else { success = runningSubAgentTracker.enqueueMessage( target.instanceId, messageWithoutTargets, ); if (success) { const agentInfo = runningSubAgentTracker .getRunningAgents() .find(a => a.instanceId === target.instanceId); rawPrompt = agentInfo?.prompt || ''; } } if (success) { const snippet = rawPrompt .replace(/[\r\n]+/g, ' ') .replace(/\s+/g, ' ') .trim(); const maxLen = 30; const promptSnippet = snippet.length > maxLen ? snippet.slice(0, maxLen) + '…' : snippet; injectedTargets.push({ agentName: target.agentName, promptSnippet, }); } } if (injectedTargets.length > 0) { setMessages(prev => [ ...prev, { role: 'user', content: messageWithoutTargets, subAgentDirected: { targets: injectedTargets, }, }, ]); return; } message = messageWithoutTargets; } else if (messageTargets.length > 0) { message = messageWithoutTargets; } if (streamingState.streamStatus !== 'idle') { setPendingMessages(prev => [...prev, {text: message, images}]); return; } try { const {unifiedHooksExecutor} = await import( '../../../utils/execution/unifiedHooksExecutor.js' ); const {interpretHookResult} = await import( '../../../utils/execution/hookResultInterpreter.js' ); const hookResult = await unifiedHooksExecutor.executeHooks( 'onUserMessage', {message, imageCount: images?.length || 0, source: 'normal'}, ); const interpreted = interpretHookResult( 'onUserMessage', hookResult, message, ); if (interpreted.action === 'block' && interpreted.errorDetails) { setMessages(prev => [ ...prev, { role: 'assistant', content: '', timestamp: new Date(), hookError: interpreted.errorDetails, }, ]); return; } if (interpreted.action === 'replace' && interpreted.replacedContent) { message = interpreted.replacedContent; } } catch (error) { console.error('Failed to execute onUserMessage hook:', error); } // 先检查纯 Bash 模式（双感叹号） try { const pureBashResult = await bashMode.processPureBashMessage( message, async (command: string) => { return new Promise(resolve => { setBashSensitiveCommand({command, resolve}); }); }, ); if (pureBashResult.hasCommands) { if (pureBashResult.hasRejectedCommands) { setRestoreInputContent({ text: message, images: images?.map(img => ({type: 'image' as const, ...img})), }); return; } const formatted = pureBashResult.results .map( (r: { stdout: string; stderr: string; command: string; exitCode: number | null; }) => { const stdout = (r.stdout || '').trim(); const stderr = (r.stderr || '').trim(); const combined = [stdout, stderr].filter(Boolean).join('\n'); const output = combined.length > 0 ? combined : '(no output)'; const exitInfo = r.exitCode === null || r.exitCode === undefined ? 'exit: (unknown)' : `exit: ${r.exitCode}`; return [ '```text', `$ ${r.command}`, output, `(${exitInfo})`, '```', ].join('\n'); }, ) .join('\n\n'); const bashOutputMessage: Message = { role: 'assistant', content: formatted || '```text\n(no output)\n```', }; setMessages(prev => [...prev, bashOutputMessage]); try { await saveMessage(bashOutputMessage); } catch (error) { console.error('Failed to save pure bash output message:', error); } return; } } catch (error) { console.error('Failed to process pure bash commands:', error); } // 再检查命令注入模式（单感叹号） try { const result = await bashMode.processBashMessage( message, async (command: string) => { return new Promise(resolve => { setBashSensitiveCommand({command, resolve}); }); }, ); if (result.hasRejectedCommands) { setRestoreInputContent({ text: message, images: images?.map(img => ({type: 'image' as const, ...img})), }); return; } message = result.processedMessage; } catch (error) { console.error('Failed to process bash commands:', error); } const currentSession = sessionManager.getCurrentSession(); if (!currentSession) { await sessionManager.createNewSession(); } await processMessage(message, images); }; const processPendingMessages = async () => { const pendingMessages = pendingMessagesRef.current; if (pendingMessages.length === 0) return; streamingState.setRetryStatus(null); const messagesToProcess = [...pendingMessages]; setPendingMessages([]); const combinedMessage = messagesToProcess.map(m => m.text).join('\n\n'); let messageToSend = combinedMessage; try { const {unifiedHooksExecutor} = await import( '../../../utils/execution/unifiedHooksExecutor.js' ); const {interpretHookResult} = await import( '../../../utils/execution/hookResultInterpreter.js' ); const allImages = messagesToProcess.flatMap(m => m.images || []); const hookResult = await unifiedHooksExecutor.executeHooks( 'onUserMessage', { message: combinedMessage, imageCount: allImages.length, source: 'pending', }, ); const interpreted = interpretHookResult( 'onUserMessage', hookResult, combinedMessage, ); if (interpreted.action === 'block' && interpreted.errorDetails) { setMessages(prev => [ ...prev, { role: 'assistant', content: '', timestamp: new Date(), hookError: interpreted.errorDetails, }, ]); return; } if (interpreted.action === 'replace' && interpreted.replacedContent) { messageToSend = interpreted.replacedContent; } } catch (error) { console.error('Failed to execute onUserMessage hook:', error); } const {cleanContent, validFiles} = await parseAndValidateFileReferences( messageToSend, ); const imageFiles = validFiles.filter( f => f.isImage && f.imageData && f.mimeType, ); const regularFiles = validFiles.filter(f => !f.isImage); const allImages = messagesToProcess .flatMap(m => m.images || []) .concat( imageFiles.map(f => ({ data: f.imageData!, mimeType: f.mimeType!, })), ); const imageContents = allImages.length > 0 ? allImages.map(img => ({ type: 'image' as const, data: img.data, mimeType: img.mimeType, })) : undefined; const userMessage: Message = { role: 'user', content: cleanContent, files: validFiles.length > 0 ? validFiles : undefined, images: imageContents, }; setMessages(prev => [...prev, userMessage]); streamingState.setIsStreaming(true); const controller = new AbortController(); streamingState.setAbortController(controller); try { const messageForAI = createMessageWithFileInstructions( cleanContent, regularFiles, vscodeState.vscodeConnected ? vscodeState.editorContext : undefined, ); try { await handleConversationWithTools({ userContent: messageForAI.content, editorContext: messageForAI.editorContext, imageContents, controller, messages, saveMessage, setMessages, setStreamTokenCount: streamingState.setStreamTokenCount, requestToolConfirmation, requestUserQuestion, isToolAutoApproved, addMultipleToAlwaysApproved, yoloModeRef, planMode, vulnerabilityHuntingMode, teamMode, toolSearchDisabled, setContextUsage: streamingState.setContextUsage, getPendingMessages: () => pendingMessagesRef.current, clearPendingMessages: () => setPendingMessages([]), setIsStreaming: streamingState.setIsStreaming, setIsReasoning: streamingState.setIsReasoning, setRetryStatus: streamingState.setRetryStatus, clearSavedMessages, setRemountKey, setSnapshotFileCount: snapshotState.setSnapshotFileCount, getCurrentContextPercentage: () => currentContextPercentageRef.current, setCurrentModel: streamingState.setCurrentModel, onCompressionStatus: props.onCompressionStatus, setIsAutoCompressing: streamingState.setIsAutoCompressing, }); } finally { // Snapshots are now created on-demand during file operations } } catch (error) { if (!controller.signal.aborted && !userInterruptedRef.current) { const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'; const finalMessage: Message = { role: 'assistant', content: `Error: ${errorMessage}`, streaming: false, messageStatus: 'error', }; setMessages(prev => [...prev, finalMessage]); } } finally { if (userInterruptedRef.current) { const session = sessionManager.getCurrentSession(); if (session && session.messages.length > 0) { (async () => { try { const messages = session.messages; let truncateIndex = messages.length; for (let i = messages.length - 1; i >= 0; i--) { const msg = messages[i]; if (!msg) continue; if ( msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0 ) { const toolCallIds = new Set(msg.tool_calls.map(tc => tc.id)); for (let j = i + 1; j < messages.length; j++) { const followMsg = messages[j]; if ( followMsg && followMsg.role === 'tool' && followMsg.tool_call_id ) { toolCallIds.delete(followMsg.tool_call_id); } } if (toolCallIds.size > 0) { truncateIndex = i; break; } } if (msg.role === 'assistant' && !msg.tool_calls) { break; } } if (truncateIndex < messages.length) { await sessionManager.truncateMessages(truncateIndex); clearSavedMessages(); } } catch (error) { console.error( 'Failed to clean up incomplete conversation:', error, ); } })(); } setMessages(prev => [ ...prev, { role: 'assistant', content: '', streaming: false, discontinued: true, }, ]); userInterruptedRef.current = false; streamingState.setIsStopping(false); } appendAiCompletionTimeMessage(); streamingState.setIsStreaming(false); streamingState.setAbortController(null); streamingState.setStreamTokenCount(0); } }; return { handleMessageSubmit, processMessage, processMessageRef, processPendingMessages, }; } ================================================ FILE: source/hooks/conversation/chatLogic/useRemoteEvents.ts ================================================ import {useEffect} from 'react'; import type {UseChatLogicProps} from './types.js'; import type {RollbackMode} from '../../../ui/components/tools/FileRollbackConfirmation.js'; import {connectionManager} from '../../../utils/connection/ConnectionManager.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {performAutoCompression} from '../../../utils/core/autoCompress.js'; interface UseRemoteEventsHandlers { handleMessageSubmit: ( message: string, images?: Array<{data: string; mimeType: string}>, ) => Promise; handleUserQuestionAnswer: (result: { selected: string | string[]; customInput?: string; cancelled?: boolean; }) => void; handleHistorySelect: ( selectedIndex: number, message: string, images?: Array<{type: 'image'; data: string; mimeType: string}>, ) => Promise; handleRollbackConfirm: ( mode: RollbackMode | null, selectedFiles?: string[], ) => Promise; } export function useRemoteEvents( props: UseChatLogicProps, handlers: UseRemoteEventsHandlers, ) { const { messages, setMessages, setPendingMessages, streamingState, snapshotState, userInterruptedRef, pendingToolConfirmation, pendingUserQuestion, handleCommandExecution, setIsCompressing, setCompressionError, clearSavedMessages, setRemountKey, } = props; const { handleMessageSubmit, handleUserQuestionAnswer, handleHistorySelect, handleRollbackConfirm, } = handlers; // Remote message useEffect(() => { const unsubscribeRemoteMessage = connectionManager.onMessage( 'remote_message', (data: any) => { if (data?.message && typeof data.message === 'string') { setMessages(prev => [ ...prev, { role: 'assistant', content: 'Remote message received from Web', streaming: false, }, ]); handleMessageSubmit(data.message); } }, ); return () => { unsubscribeRemoteMessage(); }; }, [handleMessageSubmit]); // Tool confirmation from remote useEffect(() => { const unsubscribeToolConfirmation = connectionManager.onMessage( 'tool_confirmation_result', (data: any) => { if (!pendingToolConfirmation) { return; } const result = data?.result; if ( result !== 'approve' && result !== 'approve_always' && result !== 'reject' && result !== 'reject_with_reply' ) { return; } if (result === 'reject_with_reply') { pendingToolConfirmation.resolve({ type: 'reject_with_reply', reason: data?.reason || '', }); return; } pendingToolConfirmation.resolve(result); }, ); return () => { unsubscribeToolConfirmation(); }; }, [pendingToolConfirmation]); // User question answer from remote useEffect(() => { const unsubscribeUserQuestion = connectionManager.onMessage( 'user_question_result', (data: any) => { if (!pendingUserQuestion) { return; } let selected: string | string[] = data?.selected; if (typeof selected === 'string') { const trimmed = selected.trim(); if (trimmed.startsWith('[') && trimmed.endsWith(']')) { try { const parsed = JSON.parse(trimmed); if (Array.isArray(parsed)) { selected = parsed.filter(item => typeof item === 'string'); } } catch { // Keep original selected value if parsing fails } } } handleUserQuestionAnswer({ selected, customInput: typeof data?.customInput === 'string' ? data.customInput : undefined, cancelled: Boolean(data?.cancelled), }); }, ); return () => { unsubscribeUserQuestion(); }; }, [pendingUserQuestion, handleUserQuestionAnswer]); // Interrupt from remote useEffect(() => { const unsubscribeInterrupt = connectionManager.onMessage( 'interrupt_message_processing', () => { if (!streamingState.isStreaming || !streamingState.abortController) { return; } userInterruptedRef.current = true; streamingState.setIsStopping(true); streamingState.setRetryStatus(null); streamingState.setCodebaseSearchStatus(null); streamingState.abortController.abort(); setMessages(prev => prev.filter(msg => !msg.toolPending)); setPendingMessages([]); }, ); return () => { unsubscribeInterrupt(); }; }, [streamingState, setMessages, setPendingMessages]); // Clear session from remote useEffect(() => { const unsubscribeClearSession = connectionManager.onMessage( 'clear_session', () => { import('../../../utils/execution/commandExecutor.js').then( ({executeCommand}) => { executeCommand('clear') .then(result => { if (handleCommandExecution) { handleCommandExecution('clear', result); } }) .catch(() => { // Ignore command execution errors }); }, ); }, ); return () => { unsubscribeClearSession(); }; }, [handleCommandExecution]); // Resume session from remote useEffect(() => { const unsubscribeResumeSession = connectionManager.onMessage( 'resume_session', (data: any) => { const sessionId = typeof data?.sessionId === 'string' ? data.sessionId.trim() : ''; if (!sessionId) { return; } import('../../../utils/execution/commandExecutor.js').then( ({executeCommand}) => { executeCommand('resume', sessionId) .then(result => { if (handleCommandExecution) { handleCommandExecution('resume', result); } }) .catch(() => { // Ignore command execution errors }); }, ); }, ); return () => { unsubscribeResumeSession(); }; }, [handleCommandExecution]); // Rollback from remote useEffect(() => { const unsubscribeRollback = connectionManager.onMessage( 'rollback_message', (data: any) => { if (streamingState.isStreaming) { return; } const userMessageOrder = Number(data?.userMessageOrder); if (!Number.isInteger(userMessageOrder) || userMessageOrder <= 0) { return; } const userMessageEntries = messages .map((msg, index) => ({msg, index})) .filter(entry => entry.msg.role === 'user'); const targetEntry = userMessageEntries[userMessageOrder - 1]; if (!targetEntry) { return; } handleHistorySelect( targetEntry.index, targetEntry.msg.content || '', targetEntry.msg.images, ).catch(() => { // Ignore rollback errors from remote trigger }); }, ); return () => { unsubscribeRollback(); }; }, [messages, streamingState.isStreaming, handleHistorySelect]); // Rollback confirmation from remote useEffect(() => { const unsubscribeRollbackConfirm = connectionManager.onMessage( 'rollback_confirmation_result', (data: any) => { if (!snapshotState.pendingRollback) { return; } let mode: RollbackMode | null = null; if (typeof data?.rollbackMode === 'string') { mode = data.rollbackMode as RollbackMode; } else if (typeof data?.rollbackFiles === 'boolean') { mode = data.rollbackFiles ? 'both' : 'conversation'; } const selectedFiles = Array.isArray(data?.selectedFiles) ? data.selectedFiles.filter( (x: unknown): x is string => typeof x === 'string', ) : undefined; void handleRollbackConfirm(mode, selectedFiles); }, ); return () => { unsubscribeRollbackConfirm(); }; }, [snapshotState.pendingRollback, handleRollbackConfirm]); // Compact request from Web client useEffect(() => { const unsubscribeCompactRequest = connectionManager.onMessage( 'compact_request', async () => { if (streamingState.isStreaming) { return; } setIsCompressing(true); setCompressionError(null); try { await connectionManager.notifyCompactStarted(); const currentSession = sessionManager.getCurrentSession(); const compressionResult = await performAutoCompression( currentSession?.id, (status) => { props.onCompressionStatus?.(status); }, ); if (compressionResult && (compressionResult as any).hookFailed) { setCompressionError('Blocked by beforeCompress hook'); await connectionManager.notifyCompactCompleted({ success: false, error: 'Blocked by beforeCompress hook', }); return; } if (!compressionResult) { await connectionManager.notifyCompactCompleted({ success: false, error: 'Compression failed after retries', }); return; } props.onCompressionStatus?.(null); clearSavedMessages(); setMessages(compressionResult.uiMessages); setRemountKey(prev => prev + 1); await connectionManager.notifyCompactCompleted({ success: true, messageCount: compressionResult.uiMessages.length, }); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown compression error'; props.onCompressionStatus?.({ step: 'failed', message: errorMsg, }); setCompressionError(errorMsg); setTimeout(() => { props.onCompressionStatus?.(null); }, 5000); await connectionManager.notifyCompactCompleted({ success: false, error: errorMsg, }); } finally { setIsCompressing(false); } }, ); return () => { unsubscribeCompactRequest(); }; }, [ streamingState.isStreaming, setIsCompressing, setCompressionError, clearSavedMessages, setMessages, setRemountKey, ]); } ================================================ FILE: source/hooks/conversation/chatLogic/useRollback.ts ================================================ import {useEffect, useCallback} from 'react'; import {useStdout} from 'ink'; import ansiEscapes from 'ansi-escapes'; import type {UseChatLogicProps} from './types.js'; import type {RollbackMode} from '../../../ui/components/tools/FileRollbackConfirmation.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {hashBasedSnapshotManager} from '../../../utils/codebase/hashBasedSnapshot.js'; import {convertSessionMessagesToUI} from '../../../utils/session/sessionConverter.js'; import {connectionManager} from '../../../utils/connection/ConnectionManager.js'; import {cleanIDEContext} from '../../../utils/core/fileUtils.js'; import { getNotebookRollbackCount, rollbackNotebooks, deleteNotebookSnapshotsFromIndex, clearAllNotebookSnapshots, } from '../../../utils/core/notebookManager.js'; import { getTeamRollbackCount, rollbackTeamState, deleteTeamSnapshotsFromIndex, clearAllTeamSnapshots, } from '../../../utils/team/teamSnapshot.js'; import { clearAllTeammateStreamEntries, clearAllSubAgentStreamEntries, } from '../core/subAgentMessageHandler.js'; import type {Message} from '../../../ui/components/chat/MessageList.js'; import type {ChatMessage} from '../../../api/chat.js'; /** * Convert a live messages array index to a snapshot-compatible index. * * During streaming, assistant responses are emitted as individual * `streamingLine` messages (one per line), while `convertSessionMessagesToUI` * collapses each assistant turn into a single message. This discrepancy * causes the live array to have more elements than the converted array, * shifting subsequent user-message positions and breaking the comparison * `snapshotMessageIndex >= liveSelectedIndex` used during rollback. * * The fix: count which *user-message ordinal* the live index corresponds to, * then locate the same ordinal in `convertSessionMessagesToUI` output. */ function resolveSnapshotIndex( liveMessages: Message[], liveIndex: number, sessionMessages: ChatMessage[], ): number { const uiMessages = convertSessionMessagesToUI(sessionMessages); let userMsgOrdinal = 0; for (let i = 0; i <= liveIndex && i < liveMessages.length; i++) { const msg = liveMessages[i]; if (msg?.role === 'user' && msg.content?.trim() && !msg.subAgentDirected) { userMsgOrdinal++; } } if (userMsgOrdinal === 0) { return 0; } let count = 0; for (let i = 0; i < uiMessages.length; i++) { const msg = uiMessages[i]; if (msg?.role === 'user' && msg.content?.trim() && !msg.subAgentDirected) { count++; if (count === userMsgOrdinal) { return i; } } } return liveIndex; } export function useRollback(props: UseChatLogicProps) { const { messages, setMessages, snapshotState, clearSavedMessages, setRemountKey, setRestoreInputContent, currentContextPercentageRef, streamingState, } = props; const {stdout} = useStdout(); // Notify VSCode/Web when a rollback confirmation is needed useEffect(() => { const pendingRollback = snapshotState.pendingRollback; if (!pendingRollback) { return; } void connectionManager.notifyRollbackConfirmationNeeded({ filePaths: pendingRollback.filePaths || [], notebookCount: pendingRollback.notebookCount || 0, teamCount: pendingRollback.teamCount || 0, }); }, [snapshotState.pendingRollback]); const getSnapshotIndex = useCallback( (liveIndex: number) => { const currentSession = sessionManager.getCurrentSession(); if (!currentSession) return liveIndex; return resolveSnapshotIndex(messages, liveIndex, currentSession.messages); }, [messages], ); const performRollback = async ( selectedIndex: number, rollbackFiles: boolean, rollbackConversation: boolean, selectedFiles?: string[], ) => { const currentSession = sessionManager.getCurrentSession(); const sIdx = getSnapshotIndex(selectedIndex); if (rollbackFiles && currentSession) { if (selectedFiles && selectedFiles.length > 0) { await hashBasedSnapshotManager.rollbackToMessageIndex( currentSession.id, sIdx, selectedFiles, ); } else { await hashBasedSnapshotManager.rollbackToMessageIndex( currentSession.id, sIdx, ); } try { rollbackNotebooks(currentSession.id, sIdx); } catch (error) { console.error('Failed to rollback notebooks:', error); } } // Always clean up team state when rolling back (regardless of file rollback choice) if (currentSession) { try { await rollbackTeamState(currentSession.id, sIdx); } catch (error) { console.error('Failed to rollback team state:', error); } } clearAllTeammateStreamEntries(); clearAllSubAgentStreamEntries(); if (!rollbackConversation) { if (rollbackFiles && currentSession) { await hashBasedSnapshotManager.deleteSnapshotsFromIndex( currentSession.id, sIdx, ); const snapshots = await hashBasedSnapshotManager.listSnapshots( currentSession.id, ); const counts = new Map(); for (const snapshot of snapshots) { counts.set(snapshot.messageIndex, snapshot.fileCount); } snapshotState.setSnapshotFileCount(counts); } snapshotState.setPendingRollback(null); return; } if (currentSession) { const messagesAfterSelected = messages.slice(selectedIndex); const uiUserMessagesToDelete = messagesAfterSelected.filter( msg => msg.role === 'user', ).length; const selectedMessage = messages[selectedIndex]; const isUncommittedUserMessage = selectedMessage?.role === 'user' && uiUserMessagesToDelete === 1 && (selectedIndex === messages.length - 1 || (selectedIndex === messages.length - 2 && messages[messages.length - 1]?.discontinued)); if (isUncommittedUserMessage) { const lastSessionMsg = currentSession.messages[currentSession.messages.length - 1]; const sessionEndsWithAssistant = lastSessionMsg?.role === 'assistant' && !lastSessionMsg?.tool_calls; if (sessionEndsWithAssistant) { setMessages(prev => prev.slice(0, selectedIndex)); clearSavedMessages(); stdout.write(ansiEscapes.clearTerminal); setTimeout(() => { setRemountKey(prev => prev + 1); snapshotState.setPendingRollback(null); }, 0); return; } } let sessionTruncateIndex = currentSession.messages.length; if (selectedIndex === 0) { sessionTruncateIndex = 0; } else { let sessionUserMessageCount = 0; for (let i = currentSession.messages.length - 1; i >= 0; i--) { const msg = currentSession.messages[i]; if (msg && msg.role === 'user') { sessionUserMessageCount++; if (sessionUserMessageCount === uiUserMessagesToDelete) { sessionTruncateIndex = i; break; } } } } if (sessionTruncateIndex === 0 && currentSession) { await hashBasedSnapshotManager.clearAllSnapshots(currentSession.id); clearAllNotebookSnapshots(currentSession.id); clearAllTeamSnapshots(currentSession.id); await sessionManager.deleteSession(currentSession.id); sessionManager.clearCurrentSession(); setMessages([]); clearSavedMessages(); snapshotState.setSnapshotFileCount(new Map()); stdout.write(ansiEscapes.clearTerminal); setTimeout(() => { setRemountKey(prev => prev + 1); snapshotState.setPendingRollback(null); }, 0); return; } await hashBasedSnapshotManager.deleteSnapshotsFromIndex( currentSession.id, sIdx, ); if (!rollbackFiles) { deleteNotebookSnapshotsFromIndex(currentSession.id, sIdx); } deleteTeamSnapshotsFromIndex(currentSession.id, sIdx); const snapshots = await hashBasedSnapshotManager.listSnapshots( currentSession.id, ); const counts = new Map(); for (const snapshot of snapshots) { counts.set(snapshot.messageIndex, snapshot.fileCount); } snapshotState.setSnapshotFileCount(counts); await sessionManager.truncateMessages(sessionTruncateIndex); } setMessages(prev => prev.slice(0, selectedIndex)); clearSavedMessages(); stdout.write(ansiEscapes.clearTerminal); setTimeout(() => { setRemountKey(prev => prev + 1); snapshotState.setPendingRollback(null); }, 0); }; const switchToOriginalCompressedSession = async ( originalSessionId: string, compressedSessionId?: string, ) => { try { const originalSession = await sessionManager.loadSession( originalSessionId, ); if (!originalSession) { console.error('Failed to load original session for rollback'); return false; } sessionManager.setCurrentSession(originalSession); const uiMessages = convertSessionMessagesToUI(originalSession.messages); clearSavedMessages(); setMessages(uiMessages); streamingState.setContextUsage(originalSession.contextUsage ?? null); const snapshots = await hashBasedSnapshotManager.listSnapshots( originalSession.id, ); const counts = new Map(); for (const snapshot of snapshots) { counts.set(snapshot.messageIndex, snapshot.fileCount); } snapshotState.setSnapshotFileCount(counts); if (compressedSessionId && compressedSessionId !== originalSessionId) { try { await hashBasedSnapshotManager.clearAllSnapshots(compressedSessionId); clearAllNotebookSnapshots(compressedSessionId); const deleted = await sessionManager.deleteSession( compressedSessionId, ); if (!deleted) { console.warn( `Failed to delete compressed session after rollback: ${compressedSessionId}`, ); } } catch (cleanupError) { console.error( 'Failed to clean up compressed session after rollback:', cleanupError, ); } } console.log( `Switched to original session (before compression) with ${originalSession.messageCount} messages`, ); return true; } catch (error) { console.error('Failed to switch to original session:', error); return false; } }; const handleHistorySelect = async ( selectedIndex: number, message: string, images?: Array<{type: 'image'; data: string; mimeType: string}>, ) => { streamingState.setContextUsage(null); currentContextPercentageRef.current = 0; const currentSession = sessionManager.getCurrentSession(); if (!currentSession) return; const sIdx = getSnapshotIndex(selectedIndex); if ( selectedIndex === 0 && currentSession.compressedFrom !== undefined && currentSession.compressedFrom !== null ) { const filePaths = await hashBasedSnapshotManager.getFilesToRollback( currentSession.id, sIdx, ); const nbCount = getNotebookRollbackCount(currentSession.id, sIdx); const tmCount = getTeamRollbackCount(currentSession.id, sIdx); if (filePaths.length > 0 || nbCount > 0 || tmCount > 0) { snapshotState.setPendingRollback({ messageIndex: selectedIndex, fileCount: filePaths.length, filePaths, notebookCount: nbCount, teamCount: tmCount, message: cleanIDEContext(message), images, crossSessionRollback: true, originalSessionId: currentSession.compressedFrom, }); return; } const originalSessionId = currentSession.compressedFrom; const switchedToOriginalSession = await switchToOriginalCompressedSession( originalSessionId, currentSession.id, ); if (switchedToOriginalSession) { stdout.write(ansiEscapes.clearTerminal); setTimeout(() => { setRemountKey(prev => prev + 1); }, 0); return; } } const filePaths = await hashBasedSnapshotManager.getFilesToRollback( currentSession.id, sIdx, ); const nbCount = getNotebookRollbackCount(currentSession.id, sIdx); const tmCount = getTeamRollbackCount(currentSession.id, sIdx); if (filePaths.length > 0 || nbCount > 0 || tmCount > 0) { snapshotState.setPendingRollback({ messageIndex: selectedIndex, fileCount: filePaths.length, filePaths, notebookCount: nbCount, teamCount: tmCount, message: cleanIDEContext(message), images, }); } else { // Show confirmation even when no files to rollback snapshotState.setPendingRollback({ messageIndex: selectedIndex, fileCount: 0, filePaths: [], notebookCount: 0, teamCount: 0, message: cleanIDEContext(message), images, }); } }; const handleRollbackConfirm = async ( mode: RollbackMode | null, selectedFiles?: string[], ) => { if (mode === null) { snapshotState.setPendingRollback(null); return; } const shouldRollbackFiles = mode === 'both' || mode === 'files'; const shouldRollbackConversation = mode === 'both' || mode === 'conversation'; if (snapshotState.pendingRollback) { if (shouldRollbackConversation && snapshotState.pendingRollback.message) { setRestoreInputContent({ text: snapshotState.pendingRollback.message, images: snapshotState.pendingRollback.images, }); } if (snapshotState.pendingRollback.crossSessionRollback) { const {originalSessionId} = snapshotState.pendingRollback; const compressedSessionId = sessionManager.getCurrentSession()?.id; if (shouldRollbackFiles) { await performRollback( snapshotState.pendingRollback.messageIndex, true, shouldRollbackConversation, selectedFiles, ); } if (shouldRollbackConversation && originalSessionId) { const switchedToOriginalSession = await switchToOriginalCompressedSession( originalSessionId, shouldRollbackFiles ? undefined : compressedSessionId, ); if (switchedToOriginalSession) { stdout.write(ansiEscapes.clearTerminal); setTimeout(() => { setRemountKey(prev => prev + 1); snapshotState.setPendingRollback(null); }, 0); } else { snapshotState.setPendingRollback(null); } } else { snapshotState.setPendingRollback(null); } } else { await performRollback( snapshotState.pendingRollback.messageIndex, shouldRollbackFiles, shouldRollbackConversation, selectedFiles, ); } } }; const rollbackViaSSE = async (params: { serverUrl: string; sessionId: string; messageIndex: number; rollbackFiles: boolean; selectedFiles?: string[]; requestId?: string; }) => { const response = await fetch(`${params.serverUrl}/message`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ type: 'rollback', sessionId: params.sessionId, requestId: params.requestId, rollback: { messageIndex: params.messageIndex, rollbackFiles: params.rollbackFiles, selectedFiles: params.selectedFiles, }, }), }); if (!response.ok) { let detail: any = undefined; try { detail = await response.json(); } catch { // ignore } throw new Error( `Rollback request failed: ${response.status} ${response.statusText}` + (detail ? ` (${JSON.stringify(detail)})` : ''), ); } }; return { handleHistorySelect, performRollback, handleRollbackConfirm, rollbackViaSSE, }; } ================================================ FILE: source/hooks/conversation/core/autoCompressHandler.ts ================================================ import type {Message} from '../../../ui/components/chat/MessageList.js'; import type {CompressionStatus} from '../../../ui/components/compression/CompressionStatus.js'; import { getSnowConfig, DEFAULT_AUTO_COMPRESS_THRESHOLD, } from '../../../utils/config/apiConfig.js'; import { shouldAutoCompress, performAutoCompression, } from '../../../utils/core/autoCompress.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {compressionCoordinator} from '../../../utils/core/compressionCoordinator.js'; export type AutoCompressOptions = { getCurrentContextPercentage?: () => number; setMessages: React.Dispatch>; clearSavedMessages?: () => void; setRemountKey?: React.Dispatch>; setContextUsage: React.Dispatch>; setSnapshotFileCount?: React.Dispatch< React.SetStateAction> >; setIsStreaming?: React.Dispatch>; freeEncoder: () => void; compressingLabel?: string; onCompressionStatus?: (status: CompressionStatus | null) => void; setIsAutoCompressing?: (value: boolean) => void; }; export type AutoCompressResult = { compressed: boolean; hookFailed: boolean; hookErrorDetails?: any; updatedConversationMessages?: any[]; accumulatedUsage?: any; }; /** * Check if auto-compression is needed and perform it. * This logic is reused in two places: after tool execution and before pending messages. */ export async function handleAutoCompression( options: AutoCompressOptions, ): Promise { const config = getSnowConfig(); if ( config.enableAutoCompress === false || !options.getCurrentContextPercentage || !shouldAutoCompress( options.getCurrentContextPercentage(), config.autoCompressThreshold ?? DEFAULT_AUTO_COMPRESS_THRESHOLD, ) ) { return {compressed: false, hookFailed: false}; } options.setIsAutoCompressing?.(true); // Acquire the compression lock so teammates / sub-agents pause at // their next loop boundary and don't mutate shared state concurrently. await compressionCoordinator.acquireLock('main'); try { const compressingMessage: Message = { role: 'assistant', content: options.compressingLabel || '✵ Auto-compressing context...', streaming: false, }; options.setMessages(prev => [...prev, compressingMessage]); const session = sessionManager.getCurrentSession(); // Set up status callback for UI display const onStatusUpdate = (status: CompressionStatus | null) => { options.onCompressionStatus?.(status); }; const compressionResult = await performAutoCompression( session?.id, onStatusUpdate, ); // Only clear status on success/hookFailed; // failed status will auto-dismiss after 5s (handled by performAutoCompression) if (compressionResult) { options.onCompressionStatus?.(null); } // Check if beforeCompress hook failed if (compressionResult && (compressionResult as any).hookFailed) { options.setIsAutoCompressing?.(false); return { compressed: false, hookFailed: true, hookErrorDetails: (compressionResult as any).hookErrorDetails, }; } if (compressionResult && options.clearSavedMessages) { options.clearSavedMessages(); options.setMessages(compressionResult.uiMessages); if (options.setRemountKey) { options.setRemountKey(prev => prev + 1); } let accumulatedUsage: any; if (compressionResult.usage) { options.setContextUsage(compressionResult.usage); accumulatedUsage = compressionResult.usage; } if (options.setSnapshotFileCount) { options.setSnapshotFileCount(new Map()); } // Rebuild conversation messages from new session const updatedSession = sessionManager.getCurrentSession(); const updatedConversationMessages: any[] = []; if (updatedSession && updatedSession.messages.length > 0) { updatedConversationMessages.push(...updatedSession.messages); } options.setIsAutoCompressing?.(false); return { compressed: true, hookFailed: false, updatedConversationMessages, accumulatedUsage, }; } } catch (error) { options.onCompressionStatus?.({ step: 'failed', message: error instanceof Error ? error.message : 'Unknown error', }); setTimeout(() => { options.onCompressionStatus?.(null); }, 5000); } finally { compressionCoordinator.releaseLock('main'); } options.setIsAutoCompressing?.(false); return {compressed: false, hookFailed: false}; } ================================================ FILE: source/hooks/conversation/core/conversationSetup.ts ================================================ import type {ChatMessage} from '../../../api/chat.js'; import { collectAllMCPTools, getMCPServicesInfo, type MCPTool, } from '../../../utils/execution/mcpToolsManager.js'; import {toolSearchService} from '../../../utils/execution/toolSearchService.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {initializeConversationSession} from './sessionInitializer.js'; import {buildEditorContextContent} from './editorContextBuilder.js'; import {cleanOrphanedToolCalls} from '../utils/messageCleanup.js'; import type {ConversationHandlerOptions} from './conversationTypes.js'; export type PreparedConversationSetup = { conversationMessages: ChatMessage[]; activeTools: MCPTool[]; discoveredToolNames: Set; useToolSearch: boolean; }; export async function prepareConversationSetup( options: Pick< ConversationHandlerOptions, 'planMode' | 'vulnerabilityHuntingMode' | 'teamMode' | 'toolSearchDisabled' >, ): Promise { let {conversationMessages} = await initializeConversationSession( options.planMode || false, options.vulnerabilityHuntingMode || false, options.toolSearchDisabled || false, options.teamMode || false, ); const allMCPTools = await collectAllMCPTools(); const servicesInfo = await getMCPServicesInfo(); toolSearchService.updateRegistry(allMCPTools, servicesInfo); let activeTools: MCPTool[]; let discoveredToolNames: Set; const useToolSearch = !options.toolSearchDisabled; if (useToolSearch) { discoveredToolNames = toolSearchService.extractUsedToolNames( conversationMessages as any[], ); activeTools = toolSearchService.buildActiveTools(discoveredToolNames); } else { discoveredToolNames = new Set(); activeTools = allMCPTools; } cleanOrphanedToolCalls(conversationMessages); return { conversationMessages, activeTools, discoveredToolNames, useToolSearch, }; } export async function appendUserMessageAndSyncContext(options: { conversationMessages: ChatMessage[]; userContent: string; editorContext: ConversationHandlerOptions['editorContext']; imageContents: ConversationHandlerOptions['imageContents']; saveMessage: ConversationHandlerOptions['saveMessage']; }): Promise { const { conversationMessages, userContent, editorContext, imageContents, saveMessage, } = options; const finalUserContent = buildEditorContextContent(editorContext, userContent); conversationMessages.push({ role: 'user', content: finalUserContent, images: imageContents, }); try { await saveMessage({ role: 'user', content: userContent, images: imageContents, }); } catch (error) { console.error('Failed to save user message:', error); } try { const {setConversationContext} = await import( '../../../utils/codebase/conversationContext.js' ); const updatedSession = sessionManager.getCurrentSession(); if (updatedSession) { const {convertSessionMessagesToUI} = await import( '../../../utils/session/sessionConverter.js' ); const uiMessages = convertSessionMessagesToUI(updatedSession.messages); setConversationContext(updatedSession.id, uiMessages.length); } } catch (error) { console.error('Failed to set conversation context:', error); } } ================================================ FILE: source/hooks/conversation/core/conversationTypes.ts ================================================ import type {ConfirmationResult} from '../../../ui/components/tools/ToolConfirmation.js'; import type {CompressionStatus} from '../../../ui/components/compression/CompressionStatus.js'; import type {Message} from '../../../ui/components/chat/MessageList.js'; import type {ToolCall} from '../../../utils/execution/toolExecutor.js'; export type UserQuestionResult = { selected: string | string[]; customInput?: string; }; export type ConversationUsage = { prompt_tokens: number; completion_tokens: number; total_tokens: number; cache_creation_input_tokens?: number; cache_read_input_tokens?: number; cached_tokens?: number; }; export type ConversationHandlerOptions = { userContent: string; editorContext?: { workspaceFolder?: string; activeFile?: string; cursorPosition?: {line: number; character: number}; selectedText?: string; }; imageContents: | Array<{type: 'image'; data: string; mimeType: string}> | undefined; controller: AbortController; messages: Message[]; saveMessage: (message: any) => Promise; setMessages: React.Dispatch>; setStreamTokenCount: React.Dispatch>; requestToolConfirmation: ( toolCall: ToolCall, batchToolNames?: string, allTools?: ToolCall[], ) => Promise; requestUserQuestion: ( question: string, options: string[], toolCall: ToolCall, multiSelect?: boolean, ) => Promise; isToolAutoApproved: (toolName: string) => boolean; addMultipleToAlwaysApproved: (toolNames: string[]) => void; yoloModeRef: React.MutableRefObject; planMode?: boolean; vulnerabilityHuntingMode?: boolean; teamMode?: boolean; toolSearchDisabled?: boolean; setContextUsage: React.Dispatch>; useBasicModel?: boolean; getPendingMessages?: () => Array<{ text: string; images?: Array<{data: string; mimeType: string}>; }>; clearPendingMessages?: () => void; setIsStreaming?: React.Dispatch>; setIsReasoning?: React.Dispatch>; setRetryStatus?: React.Dispatch< React.SetStateAction<{ isRetrying: boolean; attempt: number; nextDelay: number; remainingSeconds?: number; errorMessage?: string; } | null> >; clearSavedMessages?: () => void; setRemountKey?: React.Dispatch>; setSnapshotFileCount?: React.Dispatch< React.SetStateAction> >; getCurrentContextPercentage?: () => number; setCurrentModel?: React.Dispatch>; onCompressionStatus?: (status: CompressionStatus | null) => void; setIsAutoCompressing?: (value: boolean) => void; }; export type TokenEncoder = { encode: (text: string) => number[]; }; export type StreamRoundResult = { streamedContent: string; receivedToolCalls: ToolCall[] | undefined; receivedReasoning: any; receivedThinking: | {type: 'thinking'; thinking: string; signature?: string} | undefined; receivedReasoningContent: string | undefined; roundUsage: ConversationUsage | null; hasStreamedLines: boolean; }; export type ToolCallRoundResult = | {type: 'continue'; accumulatedUsage?: ConversationUsage | null} | {type: 'break'; accumulatedUsage?: ConversationUsage | null} | {type: 'return'; accumulatedUsage: ConversationUsage | null}; ================================================ FILE: source/hooks/conversation/core/editorContextBuilder.ts ================================================ /** * Editor context structure */ export interface EditorContext { workspaceFolder?: string; activeFile?: string; cursorPosition?: {line: number; character: number}; selectedText?: string; } /** * Build editor context string for AI * * Formats VSCode/IDE context information into a readable string * that will be prepended to user messages before sending to AI. * * @param editorContext - IDE context information * @param userContent - Original user message * @returns Final content with editor context prepended */ export function buildEditorContextContent( editorContext: EditorContext | undefined, userContent: string, ): string { if (!editorContext) { return userContent; } const editorLines: string[] = []; if (editorContext.workspaceFolder) { editorLines.push(`└─ VSCode Workspace: ${editorContext.workspaceFolder}`); } if (editorContext.activeFile) { editorLines.push(`└─ Active File: ${editorContext.activeFile}`); } if (editorContext.cursorPosition) { editorLines.push( `└─ Cursor: Line ${editorContext.cursorPosition.line + 1}, Column ${ editorContext.cursorPosition.character + 1 }`, ); } if (editorContext.selectedText) { editorLines.push( `└─ Selected Code:\n\`\`\`\n${editorContext.selectedText}\n\`\`\``, ); } if (editorLines.length > 0) { return editorLines.join('\n') + '\n\n' + userContent; } return userContent; } ================================================ FILE: source/hooks/conversation/core/encoderManager.ts ================================================ import {encoding_for_model} from 'tiktoken'; import {resourceMonitor} from '../../../utils/core/resourceMonitor.js'; /** * Encoder manager for token counting */ export class EncoderManager { private encoder: any; private freed = false; constructor() { try { this.encoder = encoding_for_model('gpt-5'); resourceMonitor.trackEncoderCreated(); } catch (e) { this.encoder = encoding_for_model('gpt-3.5-turbo'); resourceMonitor.trackEncoderCreated(); } } /** * Encode text to tokens */ encode(text: string): number[] { if (this.freed) { throw new Error('Encoder has been freed'); } return this.encoder.encode(text); } /** * Free encoder resources */ free(): void { if (!this.freed && this.encoder) { try { this.encoder.free(); this.freed = true; resourceMonitor.trackEncoderFreed(); } catch (e) { console.error('Failed to free encoder:', e); } } } /** * Check if encoder has been freed */ isFreed(): boolean { return this.freed; } } ================================================ FILE: source/hooks/conversation/core/onStopHookHandler.ts ================================================ import type {ChatMessage} from '../../../api/chat.js'; import type {Message} from '../../../ui/components/chat/MessageList.js'; import {unifiedHooksExecutor} from '../../../utils/execution/unifiedHooksExecutor.js'; import {interpretHookResult} from '../../../utils/execution/hookResultInterpreter.js'; export type OnStopHookOptions = { conversationMessages: ChatMessage[]; saveMessage: (message: any) => Promise; setMessages: React.Dispatch>; }; export type OnStopHookResult = { shouldContinue: boolean; }; /** * Execute onStop hooks after conversation completes (non-aborted). */ export async function handleOnStopHooks( options: OnStopHookOptions, ): Promise { const {conversationMessages, saveMessage, setMessages} = options; try { const hookResult = await unifiedHooksExecutor.executeHooks('onStop', { messages: conversationMessages, }); const interpreted = interpretHookResult('onStop', hookResult); if (!interpreted.injectedMessages || interpreted.injectedMessages.length === 0) { return {shouldContinue: interpreted.shouldContinueConversation || false}; } for (const injected of interpreted.injectedMessages) { const chatMsg: ChatMessage = { role: injected.role as 'user' | 'assistant', content: injected.content, }; if (injected.role === 'user') { conversationMessages.push(chatMsg); await saveMessage(chatMsg); } setMessages(prev => [ ...prev, { role: injected.role, content: injected.content, streaming: false, }, ]); } return {shouldContinue: interpreted.shouldContinueConversation || false}; } catch (error) { console.error('onStop hook execution failed:', error); return {shouldContinue: false}; } } ================================================ FILE: source/hooks/conversation/core/pendingMessagesHandler.ts ================================================ import type {Message} from '../../../ui/components/chat/MessageList.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {handleAutoCompression, type AutoCompressOptions} from './autoCompressHandler.js'; export type PendingMessagesOptions = { getPendingMessages?: () => Array<{ text: string; images?: Array<{data: string; mimeType: string}>; }>; clearPendingMessages?: () => void; conversationMessages: any[]; saveMessage: (message: any) => Promise; setMessages: React.Dispatch>; autoCompressOptions: AutoCompressOptions; }; export type PendingMessagesResult = { hasPending: boolean; hookFailed: boolean; hookErrorDetails?: any; updatedConversationMessages?: any[]; accumulatedUsage?: any; }; type BasicConversationMessage = { role?: string; tool_call_id?: string; tool_calls?: Array<{id: string}>; }; /** * PendingMessage 安全发送信号： * 仅当当前会话尾部不存在未闭合的 tool_call 轮次时返回 true。 */ export function isPendingSendTimingReady( messages: BasicConversationMessage[], ): boolean { const resolvedToolCallIds = new Set(); for (let i = messages.length - 1; i >= 0; i--) { const m = messages[i]; if (!m) continue; if (m.role === 'tool' && m.tool_call_id) { resolvedToolCallIds.add(m.tool_call_id); continue; } if (m.role === 'assistant' && m.tool_calls && m.tool_calls.length > 0) { const hasUnresolvedCall = m.tool_calls.some( tc => !resolvedToolCallIds.has(tc.id), ); if (hasUnresolvedCall) { return false; } } } return true; } /** * 等待 PendingMessage 发送时机（与 handlePendingMessages 一致的信号语义）。 * - 已就绪：立即返回 * - 未就绪：订阅消息变更，直到就绪 / 超时 / 中断 */ export async function waitForPendingSendSignal(options?: { abortSignal?: AbortSignal; timeoutMs?: number; }): Promise { const {abortSignal, timeoutMs = 3000} = options || {}; const initialSession = sessionManager.getCurrentSession(); if (!initialSession) return; if (isPendingSendTimingReady(initialSession.messages as BasicConversationMessage[])) { return; } await new Promise(resolve => { let finished = false; let timeout: ReturnType | undefined; let unsubscribe: (() => void) | undefined; const cleanup = () => { if (finished) return; finished = true; if (timeout) clearTimeout(timeout); if (unsubscribe) unsubscribe(); resolve(); }; const tryResolve = () => { if (abortSignal?.aborted) { cleanup(); return; } const session = sessionManager.getCurrentSession(); if (!session) { cleanup(); return; } if (isPendingSendTimingReady(session.messages as BasicConversationMessage[])) { cleanup(); } }; unsubscribe = sessionManager.onMessagesChanged(tryResolve); timeout = setTimeout(cleanup, timeoutMs); tryResolve(); }); } /** * Handle pending user messages that arrived during tool execution. * Also performs auto-compression before injecting if needed. */ export async function handlePendingMessages( options: PendingMessagesOptions, ): Promise { const { getPendingMessages, clearPendingMessages, conversationMessages, saveMessage, setMessages, } = options; if (!getPendingMessages || !clearPendingMessages) { return {hasPending: false, hookFailed: false}; } const pendingMessages = getPendingMessages(); if (pendingMessages.length === 0) { return {hasPending: false, hookFailed: false}; } // Auto-compress before inserting pending messages if needed const compressResult = await handleAutoCompression({ ...options.autoCompressOptions, compressingLabel: '✵ Auto-compressing context before processing pending messages...', }); if (compressResult.hookFailed) { return { hasPending: true, hookFailed: true, hookErrorDetails: compressResult.hookErrorDetails, }; } let activeConversationMessages = conversationMessages; let accumulatedUsage = compressResult.accumulatedUsage; if (compressResult.compressed && compressResult.updatedConversationMessages) { // Replace conversation messages with post-compression messages conversationMessages.length = 0; conversationMessages.push(...compressResult.updatedConversationMessages); activeConversationMessages = conversationMessages; } clearPendingMessages(); const combinedMessage = pendingMessages.map(m => m.text).join('\n\n'); const allPendingImages = pendingMessages .flatMap(m => m.images || []) .map(img => ({ type: 'image' as const, data: img.data, mimeType: img.mimeType, })); // Add user message to UI const userMessage: Message = { role: 'user', content: combinedMessage, images: allPendingImages.length > 0 ? allPendingImages : undefined, }; setMessages(prev => [...prev, userMessage]); // Add to conversation history activeConversationMessages.push({ role: 'user', content: combinedMessage, images: allPendingImages.length > 0 ? allPendingImages : undefined, }); // Save and set conversation context try { await saveMessage({ role: 'user', content: combinedMessage, images: allPendingImages.length > 0 ? allPendingImages : undefined, }); const {setConversationContext} = await import( '../../../utils/codebase/conversationContext.js' ); const updatedSession = sessionManager.getCurrentSession(); if (updatedSession) { const {convertSessionMessagesToUI} = await import( '../../../utils/session/sessionConverter.js' ); const uiMessages = convertSessionMessagesToUI( updatedSession.messages, ); setConversationContext(updatedSession.id, uiMessages.length); } } catch (error) { console.error('Failed to save pending user message:', error); } return { hasPending: true, hookFailed: false, updatedConversationMessages: compressResult.compressed ? compressResult.updatedConversationMessages : undefined, accumulatedUsage, }; } ================================================ FILE: source/hooks/conversation/core/sessionInitializer.ts ================================================ import type {ChatMessage} from '../../../api/chat.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {getTodoService} from '../../../utils/execution/mcpToolsManager.js'; import {formatTodoContext} from '../../../utils/core/todoPreprocessor.js'; import {getSystemPromptForMode} from '../../../prompt/systemPrompt.js'; /** * Initialize conversation session and TODO context * * @param planMode - Plan mode flag * @param vulnerabilityHuntingMode - Vulnerability hunting mode flag * @param toolSearchDisabled - Whether tool search is disabled * @returns Initialized conversation messages and session info */ export async function initializeConversationSession( planMode: boolean, vulnerabilityHuntingMode: boolean, toolSearchDisabled = false, teamMode = false, ): Promise<{ conversationMessages: ChatMessage[]; currentSession: any; existingTodoList: any; }> { // Step 1: Ensure session exists and get existing TODOs let currentSession = sessionManager.getCurrentSession(); if (!currentSession) { // Check if running in task mode (temporary session) const isTaskMode = process.env['SNOW_TASK_MODE'] === 'true'; currentSession = await sessionManager.createNewSession(isTaskMode); } const todoService = getTodoService(); const existingTodoList = await todoService.getTodoList(currentSession.id); // Build conversation history with TODO context as pinned user message const conversationMessages: ChatMessage[] = [ { role: 'system', content: getSystemPromptForMode(planMode, vulnerabilityHuntingMode, toolSearchDisabled, teamMode), }, ]; // If there are TODOs, add pinned context message at the front if (existingTodoList && existingTodoList.todos.length > 0) { const todoContext = formatTodoContext(existingTodoList.todos); conversationMessages.push({ role: 'user', content: todoContext, }); } // Add history messages from session (includes tool_calls and tool results) // Filter out internal sub-agent messages (marked with subAgentInternal: true) const session = sessionManager.getCurrentSession(); if (session && session.messages.length > 0) { const filteredMessages = session.messages.filter( msg => !msg.subAgentInternal, ); conversationMessages.push(...filteredMessages); } return {conversationMessages, currentSession, existingTodoList}; } ================================================ FILE: source/hooks/conversation/core/streamFactory.ts ================================================ import { createStreamingChatCompletion, type ChatMessage, } from '../../../api/chat.js'; import {createStreamingResponse} from '../../../api/responses.js'; import {createStreamingGeminiCompletion} from '../../../api/gemini.js'; import {createStreamingAnthropicCompletion} from '../../../api/anthropic.js'; import type {MCPTool} from '../../../utils/execution/mcpToolsManager.js'; export type StreamFactoryOptions = { config: any; model: string; conversationMessages: ChatMessage[]; activeTools: MCPTool[]; sessionId?: string; useBasicModel?: boolean; planMode?: boolean; vulnerabilityHuntingMode?: boolean; teamMode?: boolean; toolSearchDisabled?: boolean; signal: AbortSignal; onRetry: (error: Error, attempt: number, nextDelay: number) => void; }; export function createStreamGenerator(options: StreamFactoryOptions) { const { config, model, conversationMessages, activeTools, sessionId, signal, onRetry, } = options; const tools = activeTools.length > 0 ? activeTools : undefined; if (config.requestMethod === 'anthropic') { return createStreamingAnthropicCompletion( { model, messages: conversationMessages, temperature: 0, max_tokens: config.maxTokens || 4096, tools, sessionId, disableThinking: options.useBasicModel, planMode: options.planMode, vulnerabilityHuntingMode: options.vulnerabilityHuntingMode, teamMode: options.teamMode, toolSearchDisabled: options.toolSearchDisabled, }, signal, onRetry, ); } if (config.requestMethod === 'gemini') { return createStreamingGeminiCompletion( { model, messages: conversationMessages, temperature: 0, tools, planMode: options.planMode, vulnerabilityHuntingMode: options.vulnerabilityHuntingMode, teamMode: options.teamMode, toolSearchDisabled: options.toolSearchDisabled, }, signal, onRetry, ); } if (config.requestMethod === 'responses') { return createStreamingResponse( { model, messages: conversationMessages, temperature: 0, tools, tool_choice: 'auto', prompt_cache_key: sessionId, reasoning: options.useBasicModel ? null : undefined, planMode: options.planMode, vulnerabilityHuntingMode: options.vulnerabilityHuntingMode, teamMode: options.teamMode, toolSearchDisabled: options.toolSearchDisabled, }, signal, onRetry, ); } return createStreamingChatCompletion( { model, messages: conversationMessages, temperature: 0, tools, planMode: options.planMode, vulnerabilityHuntingMode: options.vulnerabilityHuntingMode, teamMode: options.teamMode, toolSearchDisabled: options.toolSearchDisabled, }, signal, onRetry, ); } ================================================ FILE: source/hooks/conversation/core/streamProcessor.ts ================================================ import type {ChatMessage} from '../../../api/chat.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import type {MCPTool} from '../../../utils/execution/mcpToolsManager.js'; import type {Message} from '../../../ui/components/chat/MessageList.js'; import {createStreamGenerator} from './streamFactory.js'; import type { ConversationHandlerOptions, ConversationUsage, StreamRoundResult, TokenEncoder, } from './conversationTypes.js'; const TOKEN_UPDATE_INTERVAL = 100; const STREAM_FLUSH_INTERVAL = 80; const THINKING_TAG_PATTERN = /\s*<\/?think(?:ing)?>\s*/gi; const LIST_ITEM_PATTERN = /^\s*\d+[.)]\s|^\s*[-*+]\s/; const LIST_CONTINUATION_PATTERN = /^\s{2,}/; function cleanThinkingContent(content: string): string { return content.replace(THINKING_TAG_PATTERN, ''); } function isTableRow(line: string): boolean { const trimmed = line.trim(); return trimmed.startsWith('|') && trimmed.endsWith('|') && trimmed.length > 2; } function isListItemLine(line: string): boolean { return LIST_ITEM_PATTERN.test(line); } export async function processStreamRound(ctx: { config: any; model: string; conversationMessages: ChatMessage[]; activeTools: MCPTool[]; controller: AbortController; encoder: TokenEncoder; setStreamTokenCount: React.Dispatch>; setMessages: React.Dispatch>; setIsReasoning?: React.Dispatch>; setRetryStatus?: React.Dispatch>; setContextUsage: React.Dispatch>; options: ConversationHandlerOptions; }): Promise { const { config, model, conversationMessages, activeTools, controller, encoder, setStreamTokenCount, setMessages, setIsReasoning, setRetryStatus, setContextUsage, options, } = ctx; let streamedContent = ''; let receivedToolCalls: StreamRoundResult['receivedToolCalls']; let receivedReasoning: StreamRoundResult['receivedReasoning']; let receivedThinking: StreamRoundResult['receivedThinking']; let receivedReasoningContent: string | undefined; let hasStartedReasoning = false; let currentTokenCount = 0; let lastTokenUpdateTime = 0; let chunkCount = 0; let roundUsage: ConversationUsage | null = null; const streamingEnabled = config.streamingDisplay !== false; let thinkingLineBuffer = ''; let contentLineBuffer = ''; let isFirstStreamLine = true; let hasReceivedContentChunk = false; let hasStartedContent = false; let hasStreamedLines = false; let inCodeBlock = false; let codeBlockBuffer = ''; let tableBuffer = ''; let listBuffer = ''; const pendingStreamLines: Message[] = []; let lastFlushTime = 0; const flushStreamLines = () => { if (pendingStreamLines.length === 0) { return; } const batch = [...pendingStreamLines]; pendingStreamLines.length = 0; setMessages(prev => [...prev, ...batch]); lastFlushTime = Date.now(); }; const emitStreamLine = (content: string, isThinking: boolean) => { if (!streamingEnabled) { return; } const isFirst = isFirstStreamLine; const isFirstContent = !isThinking && !hasStartedContent; if (isFirst) { isFirstStreamLine = false; } if (isFirstContent) { hasStartedContent = true; } hasStreamedLines = true; pendingStreamLines.push({ role: 'assistant', content, streamingLine: true, isThinkingLine: isThinking, isFirstStreamLine: isFirst, isFirstContentLine: isFirstContent, }); const now = Date.now(); if (now - lastFlushTime >= STREAM_FLUSH_INTERVAL) { flushStreamLines(); } }; const flushThinkingBufferToStream = () => { if (hasReceivedContentChunk || !thinkingLineBuffer) { thinkingLineBuffer = ''; return; } const cleaned = cleanThinkingContent(thinkingLineBuffer); if (cleaned.trim()) { emitStreamLine(cleaned, true); } thinkingLineBuffer = ''; }; const flushListBuffer = () => { if (!listBuffer) { return; } emitStreamLine(listBuffer.trimEnd(), false); listBuffer = ''; }; const flushTableBuffer = () => { if (!tableBuffer) { return; } emitStreamLine(tableBuffer.trimEnd(), false); tableBuffer = ''; }; const processContentLine = (line: string) => { if (inCodeBlock) { codeBlockBuffer += line + '\n'; if (line.trimStart().startsWith('```')) { inCodeBlock = false; emitStreamLine(codeBlockBuffer.trimEnd(), false); codeBlockBuffer = ''; } return; } if (line.trimStart().startsWith('```')) { flushTableBuffer(); flushListBuffer(); inCodeBlock = true; codeBlockBuffer = line + '\n'; return; } if (isTableRow(line)) { flushListBuffer(); tableBuffer += line + '\n'; return; } flushTableBuffer(); if (isListItemLine(line)) { listBuffer += line + '\n'; return; } if (listBuffer && (line.trim() === '' || LIST_CONTINUATION_PATTERN.test(line))) { listBuffer += line + '\n'; return; } flushListBuffer(); emitStreamLine(line, false); }; const countTokens = (text: string) => { try { const deltaTokens = encoder.encode(text); currentTokenCount += deltaTokens.length; const now = Date.now(); if (now - lastTokenUpdateTime >= TOKEN_UPDATE_INTERVAL) { setStreamTokenCount(currentTokenCount); lastTokenUpdateTime = now; } } catch { // Ignore encoding errors } }; const currentSession = sessionManager.getCurrentSession(); let retryInProgress = false; const onRetry = (error: Error, attempt: number, nextDelay: number) => { retryInProgress = true; if (setRetryStatus) { setRetryStatus({ isRetrying: true, attempt, nextDelay, errorMessage: error.message, }); } }; const streamGenerator = createStreamGenerator({ config, model, conversationMessages, activeTools, sessionId: currentSession?.id, useBasicModel: options.useBasicModel, planMode: options.planMode, vulnerabilityHuntingMode: options.vulnerabilityHuntingMode, teamMode: options.teamMode, toolSearchDisabled: options.toolSearchDisabled, signal: controller.signal, onRetry, }); for await (const chunk of streamGenerator) { if (controller.signal.aborted) { break; } chunkCount++; if (retryInProgress && setRetryStatus) { retryInProgress = false; setTimeout(() => setRetryStatus(null), 500); } if (chunk.type === 'reasoning_started') { if (!hasReceivedContentChunk) { setIsReasoning?.(true); } continue; } if (chunk.type === 'reasoning_delta' && chunk.delta) { if (!hasStartedReasoning) { hasStartedReasoning = true; if (!hasReceivedContentChunk) { setIsReasoning?.(true); } } countTokens(chunk.delta); if (hasReceivedContentChunk) { continue; } thinkingLineBuffer += chunk.delta; const thinkLines = thinkingLineBuffer.split('\n'); for (let i = 0; i < thinkLines.length - 1; i++) { const cleaned = cleanThinkingContent(thinkLines[i] ?? ''); if (cleaned || hasStreamedLines) { emitStreamLine(cleaned, true); } } thinkingLineBuffer = thinkLines[thinkLines.length - 1] ?? ''; continue; } if (chunk.type === 'content' && chunk.content) { if (!hasReceivedContentChunk) { hasReceivedContentChunk = true; flushThinkingBufferToStream(); } setIsReasoning?.(false); streamedContent += chunk.content; countTokens(chunk.content); contentLineBuffer += chunk.content; const contentLines = contentLineBuffer.split('\n'); for (let i = 0; i < contentLines.length - 1; i++) { processContentLine(contentLines[i] ?? ''); } contentLineBuffer = contentLines[contentLines.length - 1] ?? ''; continue; } if (chunk.type === 'tool_call_delta' && chunk.delta) { setIsReasoning?.(false); countTokens(chunk.delta); continue; } if (chunk.type === 'tool_calls' && chunk.tool_calls) { receivedToolCalls = chunk.tool_calls; continue; } if (chunk.type === 'reasoning_data' && chunk.reasoning) { receivedReasoning = chunk.reasoning; continue; } if (chunk.type === 'done') { if ((chunk as any).thinking) { receivedThinking = (chunk as any).thinking; } if ((chunk as any).reasoning_content) { receivedReasoningContent = (chunk as any).reasoning_content; } continue; } if (chunk.type === 'usage' && chunk.usage) { setContextUsage(chunk.usage); roundUsage = { prompt_tokens: chunk.usage.prompt_tokens || 0, completion_tokens: chunk.usage.completion_tokens || 0, total_tokens: chunk.usage.total_tokens || 0, cache_creation_input_tokens: chunk.usage.cache_creation_input_tokens, cache_read_input_tokens: chunk.usage.cache_read_input_tokens, cached_tokens: chunk.usage.cached_tokens, }; } } if (!hasReceivedContentChunk) { flushThinkingBufferToStream(); } else { thinkingLineBuffer = ''; } if (contentLineBuffer.trim()) { processContentLine(contentLineBuffer); } if (codeBlockBuffer) { emitStreamLine(codeBlockBuffer.trimEnd(), false); } flushTableBuffer(); flushListBuffer(); flushStreamLines(); return { streamedContent, receivedToolCalls, receivedReasoning, receivedThinking, receivedReasoningContent, roundUsage, hasStreamedLines, }; } ================================================ FILE: source/hooks/conversation/core/subAgentMessageHandler.ts ================================================ import type {Message} from '../../../ui/components/chat/MessageList.js'; import type {SubAgentMessage} from '../../../utils/execution/subAgentExecutor.js'; import {formatToolCallMessage} from '../../../utils/ui/messageFormatter.js'; import { extractFilesystemEditDiffDataForPersistence, isToolNeedTwoStepDisplay, } from '../../../utils/config/toolDisplayConfig.js'; // ── Module-level store: per-teammate streaming data (useSyncExternalStore compatible) ── export interface TeammateCtxUsage { percentage: number; inputTokens: number; maxTokens: number; } export interface TeammateStreamInfo { agentId: string; agentName: string; tokenCount: number; isReasoning: boolean; ctxUsage?: TeammateCtxUsage; } export interface SubAgentStreamInfo { agentId: string; agentName: string; tokenCount: number; isReasoning: boolean; ctxUsage?: TeammateCtxUsage; } const _teammateStreamMap = new Map(); const _teammateStreamListeners = new Set<() => void>(); let _teammateStreamSnapshot: TeammateStreamInfo[] = []; let _notifyTimer: ReturnType | null = null; const _NOTIFY_THROTTLE_MS = 200; const _subAgentStreamMap = new Map(); const _subAgentStreamListeners = new Set<() => void>(); let _subAgentStreamSnapshot: SubAgentStreamInfo[] = []; let _subAgentNotifyTimer: ReturnType | null = null; function notifyTeammateStreamListeners(): void { for (const listener of _teammateStreamListeners) { try { listener(); } catch { /* noop */ } } } function notifySubAgentStreamListeners(): void { for (const listener of _subAgentStreamListeners) { try { listener(); } catch { /* noop */ } } } function rebuildTeammateSnapshot(): void { _teammateStreamSnapshot = Array.from(_teammateStreamMap.values()); if (!_notifyTimer) { _notifyTimer = setTimeout(() => { _notifyTimer = null; notifyTeammateStreamListeners(); }, _NOTIFY_THROTTLE_MS); } } function rebuildSubAgentSnapshot(): void { _subAgentStreamSnapshot = Array.from(_subAgentStreamMap.values()); if (!_subAgentNotifyTimer) { _subAgentNotifyTimer = setTimeout(() => { _subAgentNotifyTimer = null; notifySubAgentStreamListeners(); }, _NOTIFY_THROTTLE_MS); } } function setTeammateStreamEntry(agentId: string, agentName: string, tokenCount: number, isReasoning: boolean, ctxUsage?: TeammateCtxUsage): void { const prev = _teammateStreamMap.get(agentId); if (prev && prev.tokenCount === tokenCount && prev.isReasoning === isReasoning && prev.ctxUsage?.percentage === ctxUsage?.percentage) return; _teammateStreamMap.set(agentId, {agentId, agentName, tokenCount, isReasoning, ctxUsage}); rebuildTeammateSnapshot(); } function removeTeammateStreamEntry(agentId: string): void { if (_teammateStreamMap.delete(agentId)) { rebuildTeammateSnapshot(); } } function setSubAgentStreamEntry( agentId: string, agentName: string, tokenCount: number, isReasoning: boolean, ctxUsage?: TeammateCtxUsage, ): void { const prev = _subAgentStreamMap.get(agentId); if ( prev && prev.tokenCount === tokenCount && prev.isReasoning === isReasoning && prev.ctxUsage?.percentage === ctxUsage?.percentage ) { return; } _subAgentStreamMap.set(agentId, { agentId, agentName, tokenCount, isReasoning, ctxUsage, }); rebuildSubAgentSnapshot(); } function removeSubAgentStreamEntry(agentId: string): void { if (_subAgentStreamMap.delete(agentId)) { rebuildSubAgentSnapshot(); } } export function subscribeTeammateStream(listener: () => void): () => void { _teammateStreamListeners.add(listener); return () => { _teammateStreamListeners.delete(listener); }; } export function getTeammateStreamSnapshot(): TeammateStreamInfo[] { return _teammateStreamSnapshot; } export function subscribeSubAgentStream(listener: () => void): () => void { _subAgentStreamListeners.add(listener); return () => { _subAgentStreamListeners.delete(listener); }; } export function getSubAgentStreamSnapshot(): SubAgentStreamInfo[] { return _subAgentStreamSnapshot; } export function clearAllTeammateStreamEntries(): void { if (_teammateStreamMap.size === 0) return; _teammateStreamMap.clear(); _teammateStreamSnapshot = []; notifyTeammateStreamListeners(); } export function clearAllSubAgentStreamEntries(): void { if (_subAgentStreamMap.size === 0) return; _subAgentStreamMap.clear(); _subAgentStreamSnapshot = []; notifySubAgentStreamListeners(); } // ── Types ── type CtxUsage = {percentage: number; inputTokens: number; maxTokens: number}; type StreamState = { tokenCount: number; lastTokenFlushTime: number; thinkingLineBuffer: string; contentLineBuffer: string; fullThinkingContent: string; fullContent: string; hasReceivedContentChunk: boolean; isFirstStreamLine: boolean; hasStartedContent: boolean; hasEmittedStreamLine: boolean; inCodeBlock: boolean; codeBlockBuffer: string; tableBuffer: string; listBuffer: string; }; /** * Format token count for display (e.g., 1234 → "1.2K", 123456 → "123K") */ function formatTokenCount(tokens: number | undefined): string { if (!tokens) return '0'; if (tokens >= 1000) { return `${(tokens / 1000).toFixed(1)}K`; } return String(tokens); } function extractRejectionReason(content: string): string | undefined { const match = content.match( /^Error: Tool execution rejected by user:([\s\S]+)$/, ); return match?.[1]?.trim() || undefined; } /** * Manages sub-agent message handling with internal streaming state. * Encapsulates the token counting accumulators and context usage tracking * that were previously closure variables in useConversation. */ export class SubAgentUIHandler { readonly latestCtxUsage: Record = {}; private readonly streamStates: Record = {}; private readonly activeReasoningAgents = new Set(); private readonly agentNameMap: Record = {}; private readonly FLUSH_INTERVAL = 100; /** Sequential display queue: only one agent streams visible content at a time */ private activeDisplayAgentId: string | null = null; private readonly displayQueue: string[] = []; private readonly bufferedStreamLines = new Map(); constructor( private encoder: any, private saveMessage: (msg: any) => Promise, private setIsReasoning?: (isReasoning: boolean) => void, private streamingEnabled: boolean = true, ) {} /** * Process a sub-agent message and return the updated messages array. * Designed to be called inside setMessages(prev => handler.handleMessage(prev, msg)). */ handleMessage(prev: Message[], subAgentMessage: SubAgentMessage): Message[] { const {message} = subAgentMessage; if (subAgentMessage.agentId.startsWith('teammate-')) { this.agentNameMap[subAgentMessage.agentId] = subAgentMessage.agentName; } switch (message.type) { case 'context_usage': return this.handleContextUsage(prev, subAgentMessage); case 'context_compressing': return this.handleContextCompressing(prev, subAgentMessage); case 'context_compress_retrying': return this.handleContextCompressRetrying(prev, subAgentMessage); case 'context_compressed': return this.handleContextCompressed(prev, subAgentMessage); case 'inter_agent_sent': return this.handleInterAgentSent(prev, subAgentMessage); case 'inter_agent_received': return prev; case 'agent_spawned': return this.handleAgentSpawned(prev, subAgentMessage); case 'spawned_agent_completed': return this.handleSpawnedAgentCompleted(prev, subAgentMessage); case 'reasoning_started': return this.handleReasoningStarted(prev, subAgentMessage); case 'reasoning_delta': return this.handleReasoningDelta(prev, subAgentMessage); case 'tool_call_delta': return this.handleToolCallDelta(prev, subAgentMessage); case 'tool_calls': return this.handleToolCalls(prev, subAgentMessage); case 'tool_result': return this.handleToolResult(prev, subAgentMessage); case 'content': return this.handleContent(prev, subAgentMessage); case 'done': return this.handleDone(prev, subAgentMessage); default: return prev; } } private createInitialStreamState(): StreamState { return { tokenCount: 0, lastTokenFlushTime: 0, thinkingLineBuffer: '', contentLineBuffer: '', fullThinkingContent: '', fullContent: '', hasReceivedContentChunk: false, isFirstStreamLine: true, hasStartedContent: false, hasEmittedStreamLine: false, inCodeBlock: false, codeBlockBuffer: '', tableBuffer: '', listBuffer: '', }; } private getStreamState(agentId: string): StreamState { if (!this.streamStates[agentId]) { this.streamStates[agentId] = this.createInitialStreamState(); } return this.streamStates[agentId]!; } private clearStreamState(agentId: string): void { delete this.streamStates[agentId]; this.updateGlobalTokenCount(); removeTeammateStreamEntry(agentId); removeSubAgentStreamEntry(agentId); } private updateGlobalTokenCount(): void { for (const [agentId, state] of Object.entries(this.streamStates)) { if (agentId.startsWith('teammate-')) { setTeammateStreamEntry( agentId, this.agentNameMap[agentId] || agentId, state.tokenCount, this.activeReasoningAgents.has(agentId), this.latestCtxUsage[agentId] as TeammateCtxUsage | undefined, ); } else { setSubAgentStreamEntry( agentId, this.agentNameMap[agentId] || agentId, state.tokenCount, this.activeReasoningAgents.has(agentId), this.latestCtxUsage[agentId] as TeammateCtxUsage | undefined, ); } } } private setAgentReasoning(agentId: string, isReasoning: boolean): void { if (isReasoning) { this.activeReasoningAgents.add(agentId); } else { this.activeReasoningAgents.delete(agentId); } this.setIsReasoning?.(this.activeReasoningAgents.size > 0); if (agentId.startsWith('teammate-')) { const state = this.streamStates[agentId]; if (state) { setTeammateStreamEntry( agentId, this.agentNameMap[agentId] || agentId, state.tokenCount, isReasoning, this.latestCtxUsage[agentId] as TeammateCtxUsage | undefined, ); } } else { const state = this.streamStates[agentId]; if (state) { setSubAgentStreamEntry( agentId, this.agentNameMap[agentId] || agentId, state.tokenCount, isReasoning, this.latestCtxUsage[agentId] as TeammateCtxUsage | undefined, ); } } } private addTokens(agentId: string, text: string): void { const state = this.getStreamState(agentId); try { const deltaTokens = this.encoder.encode(text); state.tokenCount += deltaTokens.length; } catch { // Ignore encoding errors } } private shouldFlush(state: StreamState, now: number): boolean { return now - state.lastTokenFlushTime >= this.FLUSH_INTERVAL; } private flushTokenCount(agentId: string, now: number): void { const state = this.getStreamState(agentId); this.updateGlobalTokenCount(); state.lastTokenFlushTime = now; } private emitStreamLine( lines: Message[], state: StreamState, subAgentMessage: SubAgentMessage, content: string, isThinking: boolean, ): void { if (!this.streamingEnabled) return; const isFirst = state.isFirstStreamLine; const isFirstContent = !isThinking && !state.hasStartedContent; if (isFirst) state.isFirstStreamLine = false; if (isFirstContent) state.hasStartedContent = true; state.hasEmittedStreamLine = true; const msg: Message = { role: 'assistant' as const, content, streamingLine: true, isThinkingLine: isThinking, isFirstStreamLine: isFirst, isFirstContentLine: isFirstContent, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }; const agentId = subAgentMessage.agentId; if (this.activeDisplayAgentId === null) { this.activeDisplayAgentId = agentId; this.emitAgentTitle(lines, subAgentMessage); lines.push(msg); } else if (agentId === this.activeDisplayAgentId) { lines.push(msg); } else { if (!this.displayQueue.includes(agentId)) { this.displayQueue.push(agentId); } const buf = this.bufferedStreamLines.get(agentId) || []; buf.push(msg); this.bufferedStreamLines.set(agentId, buf); } } private emitAgentTitle(lines: Message[], subAgentMessage: SubAgentMessage): void { const name = subAgentMessage.agentName; lines.push({ role: 'subagent' as const, content: `\x1b[36m⚇ ${name}\x1b[0m`, streaming: false, subAgent: { agentId: subAgentMessage.agentId, agentName: name, isComplete: false, }, subAgentInternal: true, }); } /** * When the active display agent finishes, flush the next queued agent(s). * If the next agent already completed, flush its buffer entirely and move on. */ private flushNextQueuedAgent(): Message[] { const flushed: Message[] = []; while (this.displayQueue.length > 0) { const nextId = this.displayQueue.shift()!; this.activeDisplayAgentId = nextId; const agentName = this.agentNameMap[nextId] || nextId; flushed.push({ role: 'subagent' as const, content: `\x1b[36m⚇ ${agentName}\x1b[0m`, streaming: false, subAgent: {agentId: nextId, agentName, isComplete: false}, subAgentInternal: true, }); const buffered = this.bufferedStreamLines.get(nextId) || []; flushed.push(...buffered); this.bufferedStreamLines.delete(nextId); // If this agent is still streaming, stop here — future content will flow normally if (this.streamStates[nextId]) break; } if (this.displayQueue.length === 0 && this.activeDisplayAgentId && !this.streamStates[this.activeDisplayAgentId]) { this.activeDisplayAgentId = null; } return flushed; } private cleanThinkingContent(content: string): string { return content.replace(/\s*<\/?think(?:ing)?>\s*/gi, ''); } private flushThinkingBuffer( state: StreamState, lines: Message[], subAgentMessage: SubAgentMessage, ): void { if (state.hasReceivedContentChunk || !state.thinkingLineBuffer) { state.thinkingLineBuffer = ''; return; } const cleaned = this.cleanThinkingContent(state.thinkingLineBuffer); if (cleaned.trim()) { this.emitStreamLine(lines, state, subAgentMessage, cleaned, true); } state.thinkingLineBuffer = ''; } private isTableRow(line: string): boolean { const trimmedLine = line.trim(); return ( trimmedLine.startsWith('|') && trimmedLine.endsWith('|') && trimmedLine.length > 2 ); } private isListItemLine(line: string): boolean { return /^\s*\d+[.)]\s/.test(line) || /^\s*[-*+]\s/.test(line); } private processContentLine( state: StreamState, lines: Message[], line: string, subAgentMessage: SubAgentMessage, ): void { if (state.inCodeBlock) { state.codeBlockBuffer += line + '\n'; if (line.trimStart().startsWith('```')) { state.inCodeBlock = false; this.emitStreamLine( lines, state, subAgentMessage, state.codeBlockBuffer.trimEnd(), false, ); state.codeBlockBuffer = ''; } return; } if (line.trimStart().startsWith('```')) { if (state.tableBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.tableBuffer.trimEnd(), false, ); state.tableBuffer = ''; } if (state.listBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.listBuffer.trimEnd(), false, ); state.listBuffer = ''; } state.inCodeBlock = true; state.codeBlockBuffer = line + '\n'; return; } if (this.isTableRow(line)) { if (state.listBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.listBuffer.trimEnd(), false, ); state.listBuffer = ''; } state.tableBuffer += line + '\n'; return; } if (state.tableBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.tableBuffer.trimEnd(), false, ); state.tableBuffer = ''; } if (this.isListItemLine(line)) { state.listBuffer += line + '\n'; return; } if (state.listBuffer && (line.trim() === '' || /^\s{2,}/.test(line))) { state.listBuffer += line + '\n'; return; } if (state.listBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.listBuffer.trimEnd(), false, ); state.listBuffer = ''; } this.emitStreamLine(lines, state, subAgentMessage, line, false); } private flushRemainingContentBuffers( state: StreamState, lines: Message[], subAgentMessage: SubAgentMessage, ): void { if (state.contentLineBuffer.trim()) { this.processContentLine( state, lines, state.contentLineBuffer, subAgentMessage, ); state.contentLineBuffer = ''; } if (state.codeBlockBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.codeBlockBuffer.trimEnd(), false, ); state.codeBlockBuffer = ''; } if (state.tableBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.tableBuffer.trimEnd(), false, ); state.tableBuffer = ''; } if (state.listBuffer) { this.emitStreamLine( lines, state, subAgentMessage, state.listBuffer.trimEnd(), false, ); state.listBuffer = ''; } } private persistCompletedResponse( state: StreamState, subAgentMessage: SubAgentMessage, ): void { const hasContent = state.fullContent.trim().length > 0; const hasThinking = this.cleanThinkingContent(state.fullThinkingContent).trim().length > 0; if (!hasContent && !hasThinking) { return; } const sessionMsg = { role: 'assistant' as const, content: hasContent ? state.fullContent : '', thinking: hasThinking ? { type: 'thinking' as const, thinking: state.fullThinkingContent.trim(), } : undefined, subAgentInternal: true, subAgentContent: true, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: true, }, }; this.saveMessage(sessionMsg).catch(err => console.error('Failed to save sub-agent content:', err), ); } private resetRoundState(state: StreamState): void { state.tokenCount = 0; state.lastTokenFlushTime = 0; state.thinkingLineBuffer = ''; state.contentLineBuffer = ''; state.fullThinkingContent = ''; state.fullContent = ''; state.hasReceivedContentChunk = false; state.isFirstStreamLine = true; state.hasStartedContent = false; state.hasEmittedStreamLine = false; state.inCodeBlock = false; state.codeBlockBuffer = ''; state.tableBuffer = ''; state.listBuffer = ''; this.updateGlobalTokenCount(); } private handleReasoningStarted( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const state = this.getStreamState(subAgentMessage.agentId); if (!state.hasReceivedContentChunk) { this.setAgentReasoning(subAgentMessage.agentId, true); } return prev; } private handleReasoningDelta( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const state = this.getStreamState(subAgentMessage.agentId); if (!state.hasReceivedContentChunk) { this.setAgentReasoning(subAgentMessage.agentId, true); } const incomingDelta = subAgentMessage.message.delta; if (!incomingDelta) { return prev; } state.fullThinkingContent += incomingDelta; this.addTokens(subAgentMessage.agentId, incomingDelta); const now = Date.now(); if (this.shouldFlush(state, now)) { this.flushTokenCount(subAgentMessage.agentId, now); } if (state.hasReceivedContentChunk || !this.streamingEnabled) { return prev; } const newLines: Message[] = []; state.thinkingLineBuffer += incomingDelta; const thinkLines = state.thinkingLineBuffer.split('\n'); for (let i = 0; i < thinkLines.length - 1; i++) { const cleaned = this.cleanThinkingContent(thinkLines[i] ?? ''); if (cleaned || state.hasEmittedStreamLine) { this.emitStreamLine(newLines, state, subAgentMessage, cleaned, true); } } state.thinkingLineBuffer = thinkLines[thinkLines.length - 1] ?? ''; return newLines.length > 0 ? [...prev, ...newLines] : prev; } private handleToolCallDelta( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const state = this.getStreamState(subAgentMessage.agentId); this.setAgentReasoning(subAgentMessage.agentId, false); const incomingDelta = subAgentMessage.message.delta; if (!incomingDelta) { return prev; } this.addTokens(subAgentMessage.agentId, incomingDelta); const now = Date.now(); if (this.shouldFlush(state, now)) { this.flushTokenCount(subAgentMessage.agentId, now); } return prev; } private handleContextUsage( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const ctxData: TeammateCtxUsage = { percentage: subAgentMessage.message.percentage, inputTokens: subAgentMessage.message.inputTokens, maxTokens: subAgentMessage.message.maxTokens, }; this.latestCtxUsage[subAgentMessage.agentId] = ctxData; if (subAgentMessage.agentId.startsWith('teammate-')) { const state = this.streamStates[subAgentMessage.agentId]; setTeammateStreamEntry( subAgentMessage.agentId, this.agentNameMap[subAgentMessage.agentId] || subAgentMessage.agentName, state?.tokenCount ?? 0, this.activeReasoningAgents.has(subAgentMessage.agentId), ctxData, ); } else { const state = this.streamStates[subAgentMessage.agentId]; setSubAgentStreamEntry( subAgentMessage.agentId, this.agentNameMap[subAgentMessage.agentId] || subAgentMessage.agentName, state?.tokenCount ?? 0, this.activeReasoningAgents.has(subAgentMessage.agentId), ctxData, ); } let targetIndex = -1; for (let i = prev.length - 1; i >= 0; i--) { const m = prev[i]; if ( m && m.role === 'subagent' && m.subAgent?.agentId === subAgentMessage.agentId ) { targetIndex = i; break; } } if (targetIndex !== -1) { const updated = [...prev]; const existing = updated[targetIndex]; if (existing) { updated[targetIndex] = {...existing, subAgentContextUsage: ctxData}; } return updated; } return prev; } private handleContextCompressing( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { return [ ...prev, { role: 'subagent' as const, content: `\x1b[36m⚇ ${subAgentMessage.agentName}\x1b[0m \x1b[33m✵ Auto-compressing context (${subAgentMessage.message.percentage}%)...\x1b[0m`, streaming: false, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } private handleContextCompressRetrying( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const msg = subAgentMessage.message as any; return [ ...prev, { role: 'subagent' as const, content: `\x1b[36m⚇ ${subAgentMessage.agentName}\x1b[0m \x1b[33m⟳ Compression retry (${msg.attempt}/${msg.maxRetries})...\x1b[0m${msg.error ? ` \x1b[90m${msg.error}\x1b[0m` : ''}`, streaming: false, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } private handleContextCompressed( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const msg = subAgentMessage.message as any; return [ ...prev, { role: 'subagent' as const, content: `\x1b[36m⚇ ${ subAgentMessage.agentName }\x1b[0m \x1b[32m✵ Context compressed (~${formatTokenCount( msg.beforeTokens, )} → ~${formatTokenCount(msg.afterTokensEstimate)})\x1b[0m`, streaming: false, messageStatus: 'success' as const, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } private handleInterAgentSent( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const msg = subAgentMessage.message as any; const statusIcon = msg.success ? '→' : '✗'; const targetName = msg.targetAgentName || msg.targetAgentId; const truncatedContent = msg.content.length > 80 ? msg.content.substring(0, 80) + '...' : msg.content; return [ ...prev, { role: 'subagent' as const, content: `\x1b[38;2;255;165;0m⚇${statusIcon} [${subAgentMessage.agentName}] → [${targetName}]\x1b[0m: ${truncatedContent}`, streaming: false, messageStatus: msg.success ? ('success' as const) : ('error' as const), subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } private handleAgentSpawned( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const msg = subAgentMessage.message as any; const promptText = msg.spawnedPrompt ? msg.spawnedPrompt .replace(/[\r\n]+/g, ' ') .replace(/\s+/g, ' ') .trim() : ''; const truncatedPrompt = promptText.length > 100 ? promptText.substring(0, 100) + '...' : promptText; const promptLine = truncatedPrompt ? `\n \x1b[2m└─ prompt: "${truncatedPrompt}"\x1b[0m` : ''; return [ ...prev, { role: 'subagent' as const, content: `\x1b[38;2;150;120;255m⚇⊕ [${subAgentMessage.agentName}] spawned [${msg.spawnedAgentName}]\x1b[0m${promptLine}`, streaming: false, messageStatus: 'success' as const, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } private handleSpawnedAgentCompleted( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const msg = subAgentMessage.message as any; const statusIcon = msg.success ? '✓' : '✗'; return [ ...prev, { role: 'subagent' as const, content: `\x1b[38;2;150;120;255m⚇${statusIcon} Spawned [${msg.spawnedAgentName}] completed\x1b[0m (parent: ${subAgentMessage.agentName})`, streaming: false, messageStatus: msg.success ? ('success' as const) : ('error' as const), subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } private handleToolCalls( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { this.setAgentReasoning(subAgentMessage.agentId, false); const state = this.getStreamState(subAgentMessage.agentId); const pendingStreamLines: Message[] = []; if (!state.hasReceivedContentChunk) { this.flushThinkingBuffer(state, pendingStreamLines, subAgentMessage); } else { state.thinkingLineBuffer = ''; } this.flushRemainingContentBuffers( state, pendingStreamLines, subAgentMessage, ); const toolCalls = subAgentMessage.message.tool_calls; if (!toolCalls || toolCalls.length === 0) { return pendingStreamLines.length > 0 ? [...prev, ...pendingStreamLines] : prev; } this.persistCompletedResponse(state, subAgentMessage); this.resetRoundState(state); const internalAgentTools = new Set([ 'send_message_to_agent', 'query_agents_status', 'spawn_sub_agent', ]); const displayableToolCalls = toolCalls.filter( (tc: any) => !internalAgentTools.has(tc.function.name), ); if (displayableToolCalls.length === 0) { return pendingStreamLines.length > 0 ? [...prev, ...pendingStreamLines] : prev; } const timeConsumingTools = displayableToolCalls.filter((tc: any) => isToolNeedTwoStepDisplay(tc.function.name), ); const quickTools = displayableToolCalls.filter( (tc: any) => !isToolNeedTwoStepDisplay(tc.function.name), ); const newMessages: Message[] = []; const inheritedCtxUsage = this.latestCtxUsage[subAgentMessage.agentId]; // Time-consuming tools: individual messages with full details for (const toolCall of timeConsumingTools) { const toolDisplay = formatToolCallMessage(toolCall); let toolArgs; try { toolArgs = JSON.parse(toolCall.function.arguments); } catch { toolArgs = {}; } let paramDisplay = ''; if (toolCall.function.name === 'terminal-execute' && toolArgs.command) { paramDisplay = ` "${toolArgs.command}"`; } else if (toolDisplay.args.length > 0) { const params = toolDisplay.args .map((arg: any) => `${arg.key}: ${arg.value}`) .join(', '); paramDisplay = ` (${params})`; } newMessages.push({ role: 'subagent' as const, content: `\x1b[38;2;184;122;206m⚇⚡ ${toolDisplay.toolName}${paramDisplay}\x1b[0m`, streaming: false, toolCall: {name: toolCall.function.name, arguments: toolArgs}, toolCallId: toolCall.id, toolPending: true, messageStatus: 'pending', subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, subAgentContextUsage: inheritedCtxUsage, }); } // Quick tools: compact tree display if (quickTools.length > 0) { const toolLines = quickTools.map((tc: any, index: any) => { const display = formatToolCallMessage(tc); const isLast = index === quickTools.length - 1; const prefix = isLast ? '└─' : '├─'; const params = display.args .map((arg: any) => `${arg.key}: ${arg.value}`) .join(', '); return `\n \x1b[2m${prefix} ${display.toolName}${ params ? ` (${params})` : '' }\x1b[0m`; }); newMessages.push({ role: 'subagent' as const, content: `\x1b[36m⚇ ${subAgentMessage.agentName}\x1b[0m${toolLines.join( '', )}`, streaming: false, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, pendingToolIds: quickTools.map((tc: any) => tc.id), subAgentContextUsage: inheritedCtxUsage, }); } // Fire-and-forget save const sessionMsg = { role: 'assistant' as const, content: toolCalls .map((tc: any) => { const display = formatToolCallMessage(tc); return isToolNeedTwoStepDisplay(tc.function.name) ? `⚇⚡ ${display.toolName}` : `⚇ ${display.toolName}`; }) .join(', '), subAgentInternal: true, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, tool_calls: toolCalls, }; this.saveMessage(sessionMsg).catch(err => console.error('Failed to save sub-agent tool call:', err), ); const combinedMessages = [...pendingStreamLines, ...newMessages]; return combinedMessages.length > 0 ? [...prev, ...combinedMessages] : prev; } private handleToolResult( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const msg = subAgentMessage.message as any; const isError = msg.content.startsWith('Error:'); const isTimeConsuming = isToolNeedTwoStepDisplay(msg.tool_name); const rejectionReason = isError ? msg.rejection_reason || extractRejectionReason(msg.content) : undefined; const editDiffData = extractFilesystemEditDiffDataForPersistence( msg.tool_name, msg.content, ); // Fire-and-forget save const sessionMsg = { role: 'tool' as const, tool_call_id: msg.tool_call_id, content: msg.content, messageStatus: isError ? 'error' : 'success', subAgentInternal: true, ...(editDiffData ? {editDiffData} : {}), }; this.saveMessage(sessionMsg).catch(err => console.error('Failed to save sub-agent tool result:', err), ); if (isTimeConsuming) { return this.handleTimeConsumingToolResult( prev, subAgentMessage, msg, isError, ); } // Quick tool: error → new message, success → update pending if (isError) { const statusText = rejectionReason ? `\n └─ Rejection reason: ${rejectionReason}` : ''; return [ ...prev, { role: 'subagent' as const, content: `\x1b[38;2;255;100;100m⚇✗ ${msg.tool_name}\x1b[0m${statusText}`, streaming: false, messageStatus: 'error' as const, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } // Success: remove from pendingToolIds const pendingMsgIndex = prev.findIndex( m => m.role === 'subagent' && m.subAgent?.agentId === subAgentMessage.agentId && !m.subAgent?.isComplete && m.pendingToolIds?.includes(msg.tool_call_id), ); if (pendingMsgIndex !== -1) { const updated = [...prev]; const pendingMsg = updated[pendingMsgIndex]; if (pendingMsg?.pendingToolIds) { updated[pendingMsgIndex] = { ...pendingMsg, pendingToolIds: pendingMsg.pendingToolIds.filter( id => id !== msg.tool_call_id, ), }; } return updated; } return prev; } private handleTimeConsumingToolResult( prev: Message[], subAgentMessage: SubAgentMessage, msg: any, isError: boolean, ): Message[] { const statusIcon = isError ? '✗' : '✓'; const rejectionReason = isError ? extractRejectionReason(msg.content) : undefined; let terminalResultData: any; if (msg.tool_name === 'terminal-execute' && !isError) { try { const resultData = JSON.parse(msg.content); if ( resultData.stdout !== undefined || resultData.stderr !== undefined ) { terminalResultData = { stdout: resultData.stdout, stderr: resultData.stderr, exitCode: resultData.exitCode, command: resultData.command, }; } } catch { // show regular result } } let fileToolData: any; if ( !isError && (msg.tool_name === 'filesystem-create' || msg.tool_name === 'filesystem-edit' || msg.tool_name === 'filesystem-replaceedit') ) { if ( msg.editDiffData && (typeof msg.editDiffData.oldContent === 'string' || Array.isArray(msg.editDiffData.batchResults)) ) { fileToolData = { name: msg.tool_name, arguments: msg.editDiffData, }; } try { const resultData = JSON.parse(msg.content); if (resultData.content) { fileToolData = { name: msg.tool_name, arguments: { content: resultData.content, path: resultData.path || resultData.filename, }, }; } else if (resultData.oldContent && resultData.newContent) { fileToolData = { name: msg.tool_name, arguments: { oldContent: resultData.oldContent, newContent: resultData.newContent, filename: resultData.filePath || resultData.path || resultData.filename, completeOldContent: resultData.completeOldContent, completeNewContent: resultData.completeNewContent, contextStartLine: resultData.contextStartLine, }, }; } else if (resultData.results && Array.isArray(resultData.results)) { fileToolData = { name: msg.tool_name, arguments: { isBatch: true, batchResults: resultData.results, }, }; } else if ( resultData.batchResults && Array.isArray(resultData.batchResults) ) { fileToolData = { name: msg.tool_name, arguments: { isBatch: true, batchResults: resultData.batchResults, }, }; } } catch { // show regular result } } const statusText = rejectionReason ? `\n └─ Rejection reason: ${rejectionReason}` : ''; return [ ...prev, { role: 'subagent' as const, content: `\x1b[38;2;0;186;255m⚇${statusIcon} ${msg.tool_name}\x1b[0m${statusText}`, streaming: false, messageStatus: isError ? 'error' : 'success', toolResult: !isError ? msg.content : undefined, terminalResult: terminalResultData, toolCall: terminalResultData ? {name: msg.tool_name, arguments: terminalResultData} : fileToolData || undefined, subAgent: { agentId: subAgentMessage.agentId, agentName: subAgentMessage.agentName, isComplete: false, }, subAgentInternal: true, }, ]; } private handleContent( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const state = this.getStreamState(subAgentMessage.agentId); this.setAgentReasoning(subAgentMessage.agentId, false); const incomingContent = subAgentMessage.message.content; if (!incomingContent) { return prev; } state.fullContent += incomingContent; this.addTokens(subAgentMessage.agentId, incomingContent); const now = Date.now(); if (this.shouldFlush(state, now)) { this.flushTokenCount(subAgentMessage.agentId, now); } const isFirstContentChunk = !state.hasReceivedContentChunk; state.hasReceivedContentChunk = true; if (!this.streamingEnabled) { return prev; } const newLines: Message[] = []; if (isFirstContentChunk) { this.flushThinkingBuffer(state, newLines, subAgentMessage); } state.contentLineBuffer += incomingContent; const contentLines = state.contentLineBuffer.split('\n'); for (let i = 0; i < contentLines.length - 1; i++) { this.processContentLine( state, newLines, contentLines[i] ?? '', subAgentMessage, ); } state.contentLineBuffer = contentLines[contentLines.length - 1] ?? ''; return newLines.length > 0 ? [...prev, ...newLines] : prev; } private handleDone( prev: Message[], subAgentMessage: SubAgentMessage, ): Message[] { const state = this.getStreamState(subAgentMessage.agentId); this.setAgentReasoning(subAgentMessage.agentId, false); const finalLines: Message[] = []; if (!state.hasReceivedContentChunk) { this.flushThinkingBuffer(state, finalLines, subAgentMessage); } else { state.thinkingLineBuffer = ''; } this.flushRemainingContentBuffers(state, finalLines, subAgentMessage); this.persistCompletedResponse(state, subAgentMessage); this.clearStreamState(subAgentMessage.agentId); // Display queue: when the active agent finishes, flush next queued agent(s) if (subAgentMessage.agentId === this.activeDisplayAgentId) { const flushed = this.flushNextQueuedAgent(); if (flushed.length > 0) finalLines.push(...flushed); } return finalLines.length > 0 ? [...prev, ...finalLines] : prev; } } ================================================ FILE: source/hooks/conversation/core/toolCallProcessor.ts ================================================ import type {ChatMessage} from '../../../api/chat.js'; import type {Message} from '../../../ui/components/chat/MessageList.js'; import type {ToolCall} from '../../../utils/execution/toolExecutor.js'; import {formatToolCallMessage} from '../../../utils/ui/messageFormatter.js'; import {isToolNeedTwoStepDisplay} from '../../../utils/config/toolDisplayConfig.js'; import {extractThinkingContent} from '../utils/thinkingExtractor.js'; export type ProcessToolCallsOptions = { receivedToolCalls: ToolCall[]; streamedContent: string; receivedReasoning: any; receivedThinking: | {type: 'thinking'; thinking: string; signature?: string} | undefined; receivedReasoningContent: string | undefined; conversationMessages: any[]; saveMessage: (message: any) => Promise; setMessages: React.Dispatch>; extractThinkingContent: typeof extractThinkingContent; hasStreamedLines?: boolean; }; export async function processToolCallsAfterStream( options: ProcessToolCallsOptions, ): Promise<{parallelGroupId: string | undefined}> { const { receivedToolCalls, streamedContent, receivedReasoning, receivedThinking, receivedReasoningContent, conversationMessages, saveMessage, setMessages, } = options; const sharedThoughtSignature = ( receivedToolCalls.find(tc => (tc as any).thoughtSignature) as any )?.thoughtSignature as string | undefined; const assistantMessage: ChatMessage = { role: 'assistant', content: streamedContent || '', tool_calls: receivedToolCalls.map(tc => ({ id: tc.id, type: 'function' as const, function: { name: tc.function.name, arguments: tc.function.arguments, }, ...(((tc as any).thoughtSignature || sharedThoughtSignature) && { thoughtSignature: (tc as any).thoughtSignature || sharedThoughtSignature, }), })), reasoning: receivedReasoning, thinking: receivedThinking, reasoning_content: receivedReasoningContent, } as any; conversationMessages.push(assistantMessage); try { await saveMessage(assistantMessage); } catch (error) { console.error('Failed to save assistant message:', error); } const thinkingContent = extractThinkingContent( receivedThinking, receivedReasoning, receivedReasoningContent, ); if (!options.hasStreamedLines) { if ((streamedContent && streamedContent.trim()) || thinkingContent) { setMessages(prev => [ ...prev, { role: 'assistant', content: streamedContent?.trim() || '', streaming: false, thinking: thinkingContent, }, ]); } } const parallelGroupId = receivedToolCalls.length > 1 ? `parallel-${Date.now()}-${Math.random()}` : undefined; // Batch all two-step display messages into a single setMessages call // to avoid triggering multiple re-renders in rapid succession const pendingDisplayMessages: Message[] = []; for (const toolCall of receivedToolCalls) { const toolDisplay = formatToolCallMessage(toolCall); let toolArgs; try { toolArgs = JSON.parse(toolCall.function.arguments); } catch (e) { toolArgs = {}; } if (isToolNeedTwoStepDisplay(toolCall.function.name)) { pendingDisplayMessages.push({ role: 'assistant', content: `⚡ ${toolDisplay.toolName}`, streaming: false, toolCall: { name: toolCall.function.name, arguments: toolArgs, }, toolDisplay, toolCallId: toolCall.id, toolPending: true, messageStatus: 'pending', parallelGroup: parallelGroupId, }); } } if (pendingDisplayMessages.length > 0) { setMessages(prev => [...prev, ...pendingDisplayMessages]); } return {parallelGroupId}; } ================================================ FILE: source/hooks/conversation/core/toolCallRoundHandler.ts ================================================ import { executeToolCalls, type ToolCall, } from '../../../utils/execution/toolExecutor.js'; import {toolSearchService} from '../../../utils/execution/toolSearchService.js'; import type {Message} from '../../../ui/components/chat/MessageList.js'; import {extractThinkingContent} from '../utils/thinkingExtractor.js'; import {processToolCallsAfterStream} from './toolCallProcessor.js'; import {resolveToolConfirmations} from './toolConfirmationFlow.js'; import {handleAutoCompression} from './autoCompressHandler.js'; import {buildToolResultMessages} from './toolResultDisplay.js'; import {SubAgentUIHandler} from './subAgentMessageHandler.js'; import {handlePendingMessages} from './pendingMessagesHandler.js'; import {connectionManager} from '../../../utils/connection/ConnectionManager.js'; import type { ConversationHandlerOptions, StreamRoundResult, ToolCallRoundResult, UserQuestionResult, ConversationUsage, TokenEncoder, } from './conversationTypes.js'; import type {MCPTool} from '../../../utils/execution/mcpToolsManager.js'; import type {ConfirmationResult} from '../../../ui/components/tools/ToolConfirmation.js'; export async function handleToolCallRound(ctx: { streamResult: StreamRoundResult; conversationMessages: any[]; activeTools: MCPTool[]; discoveredToolNames: Set; useToolSearch: boolean; controller: AbortController; encoder: TokenEncoder; accumulatedUsage: ConversationUsage | null; sessionApprovedTools: Set; freeEncoder: () => void; saveMessage: (message: any) => Promise; setMessages: React.Dispatch>; setStreamTokenCount: React.Dispatch>; setContextUsage: React.Dispatch>; requestToolConfirmation: ( toolCall: ToolCall, batchToolNames?: string, allTools?: ToolCall[], ) => Promise; requestUserQuestion: ( question: string, options: string[], toolCall: ToolCall, multiSelect?: boolean, ) => Promise; isToolAutoApproved: (toolName: string) => boolean; addMultipleToAlwaysApproved: (toolNames: string[]) => void; addToAlwaysApproved: (toolName: string) => void; yoloModeRef: React.MutableRefObject; streamingEnabled: boolean; options: ConversationHandlerOptions; }): Promise { const { streamResult, conversationMessages, activeTools, discoveredToolNames, useToolSearch, controller, encoder, sessionApprovedTools, freeEncoder, saveMessage, setMessages, setStreamTokenCount, setContextUsage, requestToolConfirmation, requestUserQuestion, isToolAutoApproved, addMultipleToAlwaysApproved, addToAlwaysApproved, yoloModeRef, streamingEnabled, options, } = ctx; let {accumulatedUsage} = ctx; const receivedToolCalls = streamResult.receivedToolCalls!; const {parallelGroupId} = await processToolCallsAfterStream({ receivedToolCalls, streamedContent: streamResult.streamedContent, receivedReasoning: streamResult.receivedReasoning, receivedThinking: streamResult.receivedThinking, receivedReasoningContent: streamResult.receivedReasoningContent, conversationMessages, saveMessage, setMessages, extractThinkingContent, hasStreamedLines: streamResult.hasStreamedLines, }); const confirmResult = await resolveToolConfirmations({ receivedToolCalls, isToolAutoApproved, sessionApprovedTools, yoloMode: yoloModeRef.current, requestToolConfirmation, addMultipleToAlwaysApproved, conversationMessages, accumulatedUsage, saveMessage, setMessages, setIsStreaming: options.setIsStreaming ? (value: boolean) => options.setIsStreaming!(value) : undefined, freeEncoder, abortSignal: controller.signal, }); if (confirmResult.type === 'rejected') { if (confirmResult.shouldContinue) { return {type: 'continue'}; } return {type: 'return', accumulatedUsage: confirmResult.accumulatedUsage}; } const approvedTools = confirmResult.approvedTools; if (controller.signal.aborted) { for (const toolCall of approvedTools) { const abortedResult = { role: 'tool' as const, tool_call_id: toolCall.id, content: 'Tool execution aborted by user', messageStatus: 'error' as const, }; conversationMessages.push(abortedResult); await saveMessage(abortedResult); } freeEncoder(); return {type: 'break'}; } const subAgentHandler = new SubAgentUIHandler( encoder, saveMessage, options.setIsReasoning ? (isReasoning: boolean) => options.setIsReasoning!(isReasoning) : undefined, streamingEnabled, ); const toolResults = await executeToolCalls( approvedTools, controller.signal, setStreamTokenCount, async subAgentMessage => { setMessages(prev => subAgentHandler.handleMessage(prev, subAgentMessage)); }, async (toolCall, batchToolNames, allTools) => { if (connectionManager.isConnected()) { await connectionManager.notifyToolConfirmationNeeded( toolCall.function.name, toolCall.function.arguments, toolCall.id, allTools?.map(tool => ({ name: tool.function.name, arguments: tool.function.arguments, })), ); } return requestToolConfirmation(toolCall, batchToolNames, allTools); }, isToolAutoApproved, yoloModeRef.current, addToAlwaysApproved, async (question: string, opts: string[], multiSelect?: boolean) => { if (connectionManager.isConnected()) { await connectionManager.notifyUserInteractionNeeded( question, opts, 'fake-tool-call', multiSelect, ); } return requestUserQuestion( question, opts, { id: 'fake-tool-call', type: 'function', function: {name: 'askuser', arguments: '{}'}, }, multiSelect, ); }, ); if (controller.signal.aborted) { for (const toolCall of receivedToolCalls) { const abortedResult = { role: 'tool' as const, tool_call_id: toolCall.id, content: 'Error: Tool execution aborted by user', messageStatus: 'error' as const, }; conversationMessages.push(abortedResult); try { await saveMessage(abortedResult); } catch (error) { console.error('Failed to save aborted tool result:', error); } } freeEncoder(); return {type: 'break'}; } const hookFailedResult = toolResults.find(result => result.hookFailed); if (hookFailedResult) { for (const result of toolResults) { const {hookFailed, ...resultWithoutFlag} = result; conversationMessages.push(resultWithoutFlag); saveMessage(resultWithoutFlag).catch(error => { console.error('Failed to save tool result:', error); }); } setMessages(prev => [ ...prev, { role: 'assistant', content: '', streaming: false, hookError: hookFailedResult.hookErrorDetails, }, ]); options.setIsStreaming?.(false); freeEncoder(); return {type: 'break'}; } if (useToolSearch) { for (const toolCall of receivedToolCalls) { if (toolCall.function.name !== 'tool_search') { continue; } try { const searchArgs = JSON.parse(toolCall.function.arguments || '{}'); const {matchedToolNames} = toolSearchService.search( searchArgs.query || '', ); for (const name of matchedToolNames) { if (discoveredToolNames.has(name)) { continue; } discoveredToolNames.add(name); const tool = toolSearchService.getToolByName(name); if (tool) { activeTools.push(tool); } } } catch { // Ignore parse errors } } } for (const result of toolResults) { const isError = result.content.startsWith('Error:'); const resultToSave = { ...result, messageStatus: isError ? 'error' : 'success', }; conversationMessages.push(resultToSave as any); try { await saveMessage(resultToSave as any); } catch (error) { console.error('Failed to save tool result before compression:', error); } } const autoCompressOpts = { getCurrentContextPercentage: options.getCurrentContextPercentage, setMessages, clearSavedMessages: options.clearSavedMessages, setRemountKey: options.setRemountKey, setContextUsage, setSnapshotFileCount: options.setSnapshotFileCount, setIsStreaming: options.setIsStreaming, freeEncoder, compressingLabel: '✵ Auto-compressing context before sending tool results...', onCompressionStatus: options.onCompressionStatus, setIsAutoCompressing: options.setIsAutoCompressing, }; const compressResult = await handleAutoCompression(autoCompressOpts); if (compressResult.hookFailed) { setMessages(prev => [ ...prev, { role: 'assistant', content: '', streaming: false, hookError: compressResult.hookErrorDetails, }, ]); options.setIsStreaming?.(false); freeEncoder(); return {type: 'break'}; } if (compressResult.compressed && compressResult.updatedConversationMessages) { conversationMessages.length = 0; conversationMessages.push(...compressResult.updatedConversationMessages); if (compressResult.accumulatedUsage) { accumulatedUsage = compressResult.accumulatedUsage; } } setMessages(prev => prev.filter( message => message.role !== 'subagent' || message.toolCall !== undefined || message.toolResult !== undefined || message.subAgentInternal === true, ), ); const resultMessages = buildToolResultMessages( toolResults, receivedToolCalls, parallelGroupId, ); if (resultMessages.length > 0) { setMessages(prev => [...prev, ...resultMessages]); } try { const {runningSubAgentTracker} = await import( '../../../utils/execution/runningSubAgentTracker.js' ); const spawnedResults = runningSubAgentTracker.drainSpawnedResults(); if (spawnedResults.length > 0) { for (const spawnedResult of spawnedResults) { const statusIcon = spawnedResult.success ? '✓' : '✗'; const resultSummary = spawnedResult.success ? spawnedResult.result.length > 500 ? spawnedResult.result.substring(0, 500) + '...' : spawnedResult.result : spawnedResult.error || 'Unknown error'; const spawnedContent = `[Spawned Sub-Agent Result] ${statusIcon} ${spawnedResult.agentName} (${spawnedResult.agentId}) — spawned by ${spawnedResult.spawnedBy.agentName}\nPrompt: ${spawnedResult.prompt}\nResult: ${resultSummary}`; conversationMessages.push({role: 'user', content: spawnedContent}); try { await saveMessage({role: 'user', content: spawnedContent}); } catch (error) { console.error('Failed to save spawned agent result:', error); } const uiMessage: Message = { role: 'subagent', content: `\x1b[38;2;150;120;255m⚇${statusIcon} Spawned ${spawnedResult.agentName}\x1b[0m (by ${spawnedResult.spawnedBy.agentName}): ${spawnedResult.success ? 'completed' : 'failed'}`, streaming: false, messageStatus: spawnedResult.success ? 'success' : 'error', subAgent: { agentId: spawnedResult.agentId, agentName: spawnedResult.agentName, isComplete: true, }, subAgentInternal: true, }; setMessages(prev => [...prev, uiMessage]); } } } catch (error) { console.error('Failed to process spawned agent results:', error); } const pendingResult = await handlePendingMessages({ getPendingMessages: options.getPendingMessages, clearPendingMessages: options.clearPendingMessages, conversationMessages, saveMessage, setMessages, autoCompressOptions: autoCompressOpts, }); if (pendingResult.hookFailed) { setMessages(prev => [ ...prev, { role: 'assistant', content: '', streaming: false, hookError: pendingResult.hookErrorDetails, }, ]); options.setIsStreaming?.(false); freeEncoder(); return {type: 'break'}; } if (pendingResult.accumulatedUsage) { accumulatedUsage = pendingResult.accumulatedUsage; } return {type: 'continue', accumulatedUsage}; } ================================================ FILE: source/hooks/conversation/core/toolConfirmationFlow.ts ================================================ import type {ToolCall} from '../../../utils/execution/toolExecutor.js'; import type {ConfirmationResult} from '../../../ui/components/tools/ToolConfirmation.js'; import type {Message} from '../../../ui/components/chat/MessageList.js'; import {filterToolsBySensitivity} from '../../../utils/execution/yoloPermissionChecker.js'; import {connectionManager} from '../../../utils/connection/ConnectionManager.js'; import {handleToolRejection} from './toolRejectionHandler.js'; export type ToolConfirmationFlowOptions = { receivedToolCalls: ToolCall[]; isToolAutoApproved: (toolName: string) => boolean; sessionApprovedTools: Set; yoloMode: boolean; requestToolConfirmation: ( toolCall: ToolCall, batchToolNames?: string, allTools?: ToolCall[], ) => Promise; addMultipleToAlwaysApproved: (toolNames: string[]) => void; conversationMessages: any[]; accumulatedUsage: any; saveMessage: (message: any) => Promise; setMessages: React.Dispatch>; setIsStreaming?: (isStreaming: boolean) => void; freeEncoder: () => void; abortSignal?: AbortSignal; }; export type ToolConfirmationFlowResult = | {type: 'approved'; approvedTools: ToolCall[]} | {type: 'rejected'; shouldContinue: boolean; accumulatedUsage: any}; async function notifyAndRequestConfirmation( tools: ToolCall[], requestToolConfirmation: ToolConfirmationFlowOptions['requestToolConfirmation'], abortSignal?: AbortSignal, ): Promise { const firstTool = tools[0]!; const allTools = tools.length > 1 ? tools : undefined; if (connectionManager.isConnected()) { await connectionManager.notifyToolConfirmationNeeded( firstTool.function.name, firstTool.function.arguments, firstTool.id, allTools?.map(t => ({ name: t.function.name, arguments: t.function.arguments, })), ); } // Check abort before showing confirmation if (abortSignal?.aborted) { return 'reject'; } // Race between confirmation and abort signal return Promise.race([ requestToolConfirmation(firstTool, undefined, allTools), new Promise((_, reject) => { if (abortSignal) { const onAbort = () => reject(new Error('Tool confirmation aborted')); if (abortSignal.aborted) { onAbort(); } else { abortSignal.addEventListener('abort', onAbort, {once: true}); } } }), ]).catch(error => { if (error.message === 'Tool confirmation aborted') { return 'reject'; } throw error; }); } function isRejection(confirmation: ConfirmationResult): boolean { return ( confirmation === 'reject' || (typeof confirmation === 'object' && confirmation.type === 'reject_with_reply') ); } /** * Classify tool calls into auto-approved and needs-confirmation buckets, * then resolve confirmation with the user (or auto-approve in YOLO mode). */ export async function resolveToolConfirmations( options: ToolConfirmationFlowOptions, ): Promise { const { receivedToolCalls, isToolAutoApproved, sessionApprovedTools, yoloMode, requestToolConfirmation, addMultipleToAlwaysApproved, abortSignal, } = options; // Check abort at the start if (abortSignal?.aborted) { return { type: 'rejected', shouldContinue: false, accumulatedUsage: options.accumulatedUsage, }; } // Classify each tool call const toolsNeedingConfirmation: ToolCall[] = []; const autoApprovedTools: ToolCall[] = []; for (const toolCall of receivedToolCalls) { const isApproved = isToolAutoApproved(toolCall.function.name) || sessionApprovedTools.has(toolCall.function.name); let isSensitiveCommand = false; if (toolCall.function.name === 'terminal-execute') { try { const args = JSON.parse(toolCall.function.arguments); const {isSensitiveCommand: checkSensitiveCommand} = await import( '../../../utils/execution/sensitiveCommandManager.js' ).then(m => ({isSensitiveCommand: m.isSensitiveCommand})); const sensitiveCheck = checkSensitiveCommand(args.command); isSensitiveCommand = sensitiveCheck.isSensitive; } catch { // treat as normal command } } if (isSensitiveCommand) { toolsNeedingConfirmation.push(toolCall); } else if (isApproved) { autoApprovedTools.push(toolCall); } else { toolsNeedingConfirmation.push(toolCall); } } const approvedTools: ToolCall[] = [...autoApprovedTools]; // YOLO mode: auto-approve non-sensitive, confirm sensitive only if (yoloMode) { const {sensitiveTools, nonSensitiveTools} = await filterToolsBySensitivity( toolsNeedingConfirmation, yoloMode, ); approvedTools.push(...nonSensitiveTools); if (sensitiveTools.length > 0) { const confirmation = await notifyAndRequestConfirmation( sensitiveTools, requestToolConfirmation, abortSignal, ); if (isRejection(confirmation)) { const result = await handleToolRejection({ confirmation, toolsNeedingConfirmation: sensitiveTools, autoApprovedTools, nonSensitiveTools, conversationMessages: options.conversationMessages, accumulatedUsage: options.accumulatedUsage, saveMessage: options.saveMessage, setMessages: options.setMessages, setIsStreaming: options.setIsStreaming, freeEncoder: options.freeEncoder, }); return { type: 'rejected', shouldContinue: result.shouldContinue, accumulatedUsage: result.accumulatedUsage, }; } approvedTools.push(...sensitiveTools); } } else if (toolsNeedingConfirmation.length > 0) { const confirmation = await notifyAndRequestConfirmation( toolsNeedingConfirmation, requestToolConfirmation, abortSignal, ); if (isRejection(confirmation)) { const result = await handleToolRejection({ confirmation, toolsNeedingConfirmation, autoApprovedTools, conversationMessages: options.conversationMessages, accumulatedUsage: options.accumulatedUsage, saveMessage: options.saveMessage, setMessages: options.setMessages, setIsStreaming: options.setIsStreaming, freeEncoder: options.freeEncoder, }); return { type: 'rejected', shouldContinue: result.shouldContinue, accumulatedUsage: result.accumulatedUsage, }; } if (confirmation === 'approve_always') { const toolNamesToAdd = toolsNeedingConfirmation.map(t => t.function.name); addMultipleToAlwaysApproved(toolNamesToAdd); toolNamesToAdd.forEach(name => sessionApprovedTools.add(name)); } approvedTools.push(...toolsNeedingConfirmation); } return {type: 'approved', approvedTools}; } ================================================ FILE: source/hooks/conversation/core/toolRejectionHandler.ts ================================================ import type {Message} from '../../../ui/components/chat/MessageList.js'; import type {ConfirmationResult} from '../../../ui/components/tools/ToolConfirmation.js'; import type {ToolCall} from '../../../utils/execution/toolExecutor.js'; import {formatToolCallMessage} from '../../../utils/ui/messageFormatter.js'; export type ToolRejectionResult = { shouldContinue: boolean; shouldEndSession: boolean; accumulatedUsage: any; }; export type ToolRejectionHandlerOptions = { confirmation: ConfirmationResult; toolsNeedingConfirmation: ToolCall[]; autoApprovedTools: ToolCall[]; nonSensitiveTools?: ToolCall[]; conversationMessages: any[]; accumulatedUsage: any; saveMessage: (message: any) => Promise; setMessages: React.Dispatch>; setIsStreaming?: (isStreaming: boolean) => void; freeEncoder: () => void; }; export async function handleToolRejection( options: ToolRejectionHandlerOptions, ): Promise { const { confirmation, toolsNeedingConfirmation, autoApprovedTools, nonSensitiveTools = [], conversationMessages, accumulatedUsage, saveMessage, setMessages, setIsStreaming, freeEncoder, } = options; setMessages(prev => prev.filter(msg => !msg.toolPending)); const rejectMessage = typeof confirmation === 'object' ? `Tool execution rejected by user: ${confirmation.reason}` : 'Error: Tool execution rejected by user'; const rejectedToolUIMessages: Message[] = []; for (const toolCall of toolsNeedingConfirmation) { const rejectionMessage = { role: 'tool' as const, tool_call_id: toolCall.id, content: rejectMessage, messageStatus: 'error' as const, }; conversationMessages.push(rejectionMessage); saveMessage(rejectionMessage).catch(error => { console.error('Failed to save tool rejection message:', error); }); const toolDisplay = formatToolCallMessage(toolCall); const statusIcon = '✗'; let statusText = ''; if (typeof confirmation === 'object' && confirmation.reason) { statusText = `\n └─ Rejection reason: ${confirmation.reason}`; } else { statusText = `\n └─ ${rejectMessage}`; } rejectedToolUIMessages.push({ role: 'assistant' as const, content: `${statusIcon} ${toolDisplay.toolName}${statusText}`, streaming: false, messageStatus: 'error' as const, }); } for (const toolCall of [...autoApprovedTools, ...nonSensitiveTools]) { const rejectionMessage = { role: 'tool' as const, tool_call_id: toolCall.id, content: rejectMessage, messageStatus: 'error' as const, }; conversationMessages.push(rejectionMessage); saveMessage(rejectionMessage).catch(error => { console.error( 'Failed to save auto-approved tool rejection message:', error, ); }); } if (rejectedToolUIMessages.length > 0) { setMessages(prev => [...prev, ...rejectedToolUIMessages]); } if ( typeof confirmation === 'object' && confirmation.type === 'reject_with_reply' ) { return { shouldContinue: true, shouldEndSession: false, accumulatedUsage, }; } else { setMessages(prev => [ ...prev, { role: 'assistant', content: 'Tool call rejected, session ended', streaming: false, }, ]); if (setIsStreaming) { setIsStreaming(false); } freeEncoder(); return { shouldContinue: false, shouldEndSession: true, accumulatedUsage, }; } } ================================================ FILE: source/hooks/conversation/core/toolResultDisplay.ts ================================================ import type {Message} from '../../../ui/components/chat/MessageList.js'; import type {ToolCall, ToolResult} from '../../../utils/execution/toolExecutor.js'; import {formatToolCallMessage} from '../../../utils/ui/messageFormatter.js'; import {isToolNeedTwoStepDisplay} from '../../../utils/config/toolDisplayConfig.js'; /** * Build UI messages for tool execution results. */ export function buildToolResultMessages( toolResults: ToolResult[], receivedToolCalls: ToolCall[], parallelGroupId: string | undefined, ): Message[] { const resultMessages: Message[] = []; for (const result of toolResults) { const toolCall = receivedToolCalls.find( tc => tc.id === result.tool_call_id, ); if (!toolCall) continue; const isError = result.content.startsWith('Error:'); const statusIcon = isError ? '✗' : '✓'; // Sub-agent tools if (toolCall.function.name.startsWith('subagent-')) { let usage: any = undefined; if (!isError) { try { const subAgentResult = JSON.parse(result.content); usage = subAgentResult.usage; } catch { // Ignore parsing errors } } resultMessages.push({ role: 'assistant', content: `${statusIcon} ${toolCall.function.name}`, streaming: false, messageStatus: isError ? 'error' : 'success', toolResult: !isError ? result.content : undefined, subAgentUsage: usage, }); continue; } // Edit tool diff data let editDiffData = extractEditDiffData(toolCall, result); const toolDisplay = formatToolCallMessage(toolCall); const isNonTimeConsuming = !isToolNeedTwoStepDisplay( toolCall.function.name, ); resultMessages.push({ role: 'assistant', content: `${statusIcon} ${toolCall.function.name}`, streaming: false, messageStatus: isError ? 'error' : 'success', toolCall: editDiffData ? {name: toolCall.function.name, arguments: editDiffData} : undefined, toolDisplay: isNonTimeConsuming ? toolDisplay : undefined, toolResult: !isError ? result.content : undefined, parallelGroup: parallelGroupId, }); } return resultMessages; } function extractEditDiffData( toolCall: ToolCall, result: ToolResult, ): Record | undefined { if ( toolCall.function.name !== 'filesystem-edit' && toolCall.function.name !== 'filesystem-replaceedit' ) { return undefined; } const isError = result.content.startsWith('Error:'); if (isError) return undefined; // Prefer pre-extracted diff data (survives token truncation) if (result.editDiffData) { return result.editDiffData; } // Fallback: parse from content string try { const resultData = JSON.parse(result.content); if (resultData.oldContent && resultData.newContent) { return { oldContent: resultData.oldContent, newContent: resultData.newContent, filename: JSON.parse(toolCall.function.arguments).filePath, completeOldContent: resultData.completeOldContent, completeNewContent: resultData.completeNewContent, contextStartLine: resultData.contextStartLine, }; } if (resultData.results && Array.isArray(resultData.results)) { return { batchResults: resultData.results, isBatch: true, }; } } catch { // If parsing fails, show regular result } return undefined; } ================================================ FILE: source/hooks/conversation/useChatLogic.ts ================================================ import {useRef, useEffect, useCallback} from 'react'; import type {UseChatLogicProps} from './chatLogic/types.js'; import {vscodeConnection} from '../../utils/ui/vscodeConnection.js'; import {codebaseSearchEvents} from '../../utils/codebase/codebaseSearchEvents.js'; import {useMessageProcessing} from './chatLogic/useMessageProcessing.js'; import {useRollback} from './chatLogic/useRollback.js'; import {useChatHandlers} from './chatLogic/useChatHandlers.js'; import {useRemoteEvents} from './chatLogic/useRemoteEvents.js'; import {useI18n} from '../../i18n/index.js'; import {teamTracker} from '../../utils/execution/teamTracker.js'; import { clearAllTeammateStreamEntries, clearAllSubAgentStreamEntries, } from './core/subAgentMessageHandler.js'; export type {UseChatLogicProps}; export function useChatLogic(props: UseChatLogicProps) { const { pendingMessages, streamingState, setMessages, setPendingMessages, setRestoreInputContent, userInterruptedRef, isCompressing, vscodeState, commandsLoaded, terminalExecutionState, backgroundProcesses, schedulerExecutionState, hasFocus, } = props; // i18n const {t} = useI18n(); // Sub-hook: message processing (submit, process, pending) const { handleMessageSubmit, processMessage, processMessageRef, processPendingMessages, } = useMessageProcessing(props); // Sub-hook: rollback logic const {handleHistorySelect, handleRollbackConfirm, rollbackViaSSE} = useRollback(props); // Sub-hook: misc handlers (quit, reindex, review, session, user question) const { handleUserQuestionAnswer, handleSessionPanelSelect, handleQuit, handleReindexCodebase, handleToggleCodebase, handleReviewCommitConfirm, } = useChatHandlers(props, {processMessage}); // Sub-hook: remote event subscriptions (SignalR/connectionManager) useRemoteEvents(props, { handleMessageSubmit, handleUserQuestionAnswer, handleHistorySelect, handleRollbackConfirm, }); // VSCode auto-connect logic const hasAttemptedAutoVscodeConnect = useRef(false); useEffect(() => { if (!commandsLoaded) { return; } if (hasAttemptedAutoVscodeConnect.current) { return; } if (vscodeState.vscodeConnectionStatus !== 'disconnected') { hasAttemptedAutoVscodeConnect.current = true; return; } hasAttemptedAutoVscodeConnect.current = true; // Skip auto-connect if no matching workspace (like Claude Code) if (!vscodeConnection.hasMatchingWorkspace()) { return; } const timer = setTimeout(() => { (async () => { try { if ( vscodeConnection.isConnected() || vscodeConnection.isClientRunning() ) { vscodeConnection.stop(); vscodeConnection.resetReconnectAttempts(); await new Promise(resolve => setTimeout(resolve, 100)); } vscodeState.setVscodeConnectionStatus('connecting'); await vscodeConnection.start(); } catch (error) { // Workspace mismatch or connection failure — stay disconnected quietly vscodeState.setVscodeConnectionStatus('disconnected'); } })(); }, 0); return () => clearTimeout(timer); }, [commandsLoaded, vscodeState]); // Auto-send pending messages when streaming stops useEffect(() => { if (streamingState.streamStatus === 'idle' && pendingMessages.length > 0) { const timer = setTimeout(() => { streamingState.setIsStreaming(true); processPendingMessages(); }, 100); return () => clearTimeout(timer); } return undefined; }, [streamingState.streamStatus, pendingMessages.length]); // Codebase search events const setCodebaseSearchStatus = streamingState.setCodebaseSearchStatus; useEffect(() => { const handleSearchEvent = (event: { type: 'search-start' | 'search-retry' | 'search-complete'; attempt: number; maxAttempts: number; currentTopN: number; message: string; query?: string; originalResultsCount?: number; suggestion?: string; }) => { if (event.type === 'search-complete') { setCodebaseSearchStatus(null); } else { setCodebaseSearchStatus({ isSearching: true, attempt: event.attempt, maxAttempts: event.maxAttempts, currentTopN: event.currentTopN, message: event.message, query: event.query, originalResultsCount: event.originalResultsCount, suggestion: undefined, }); } }; codebaseSearchEvents.onSearchEvent(handleSearchEvent); return () => { codebaseSearchEvents.removeSearchEventListener(handleSearchEvent); }; }, [setCodebaseSearchStatus]); // ESC interrupt handler const handleInterrupt = useCallback(() => { if (!streamingState.isStreaming || !streamingState.abortController) { return false; } if (streamingState.isAutoCompressing) { streamingState.setCompressBlockToast(t.chatScreen.compressionBlockToast); return true; } userInterruptedRef.current = true; streamingState.setIsStopping(true); streamingState.setRetryStatus(null); streamingState.setCodebaseSearchStatus(null); streamingState.abortController.abort(); teamTracker.abortAllTeammates(); clearAllTeammateStreamEntries(); clearAllSubAgentStreamEntries(); setMessages(prev => prev.filter(msg => !msg.toolPending)); setPendingMessages([]); return true; }, [streamingState, setMessages, setPendingMessages, t]); // Consolidated ESC key handler const handleEscKey = useCallback( (key: {escape: boolean; ctrl: boolean}, input: string) => { if (backgroundProcesses?.showPanel) { if (key.escape) { backgroundProcesses.hidePanel(); return true; } return false; } if ( key.ctrl && input === 'b' && terminalExecutionState?.state.isExecuting && !terminalExecutionState?.state.isBackgrounded ) { Promise.all([ import('../../mcp/bash.js'), import('../../hooks/execution/useBackgroundProcesses.js'), ]).then(([{markCommandAsBackgrounded}, {showBackgroundPanel}]) => { markCommandAsBackgrounded(); showBackgroundPanel(); }); terminalExecutionState.moveToBackground(); return true; } if (!key.escape) return false; // Block ESC during auto-compression (including pre-message compression) if (streamingState.isAutoCompressing) { streamingState.setCompressBlockToast( t.chatScreen.compressionBlockToast, ); return true; } // Block ESC during /compact command compression if (isCompressing) { streamingState.setCompressBlockToast( t.chatScreen.compressionBlockToast, ); return true; } // Handle scheduler task interruption if (schedulerExecutionState?.state.isRunning) { schedulerExecutionState.resetTask(); // Also abort streaming if active if (streamingState.isStreaming && streamingState.abortController) { userInterruptedRef.current = true; streamingState.setIsStopping(true); streamingState.abortController.abort(); } teamTracker.abortAllTeammates(); clearAllTeammateStreamEntries(); clearAllSubAgentStreamEntries(); return true; } if (streamingState.isStopping && !streamingState.isStreaming) { streamingState.setIsStopping(false); return true; } // Abort background teammates even when lead has stopped streaming if (!streamingState.isStreaming && teamTracker.getCount() > 0) { teamTracker.abortAllTeammates(); clearAllTeammateStreamEntries(); clearAllSubAgentStreamEntries(); return true; } if ( streamingState.isStreaming && streamingState.abortController && hasFocus ) { if (pendingMessages.length > 0) { const mergedText = pendingMessages .map(m => (m.text || '').trim()) .filter(Boolean) .join('\n\n'); const mergedImages = pendingMessages.flatMap(m => m.images ?? []); setRestoreInputContent({ text: mergedText, images: mergedImages.length > 0 ? mergedImages.map(img => ({ type: 'image' as const, data: img.data, mimeType: img.mimeType, })) : undefined, }); setPendingMessages([]); return true; } return handleInterrupt(); } return false; }, [ backgroundProcesses, terminalExecutionState, streamingState, isCompressing, hasFocus, pendingMessages, handleInterrupt, setRestoreInputContent, setPendingMessages, schedulerExecutionState, t, ], ); return { handleMessageSubmit, processMessage: processMessageRef.current!, processPendingMessages, handleHistorySelect, handleRollbackConfirm, handleUserQuestionAnswer, handleSessionPanelSelect, handleQuit, handleReindexCodebase, handleToggleCodebase, handleReviewCommitConfirm, rollbackViaSSE, handleInterrupt, handleEscKey, }; } export type UseChatLogicReturn = ReturnType; ================================================ FILE: source/hooks/conversation/useCommandHandler.ts ================================================ import {useStdout} from 'ink'; import {useCallback} from 'react'; import type {Message} from '../../ui/components/chat/MessageList.js'; import type {CompressionStatus} from '../../ui/components/compression/CompressionStatus.js'; import {sessionManager} from '../../utils/session/sessionManager.js'; import {compressContext} from '../../utils/core/contextCompressor.js'; import {performHybridCompression} from '../../utils/core/subAgentContextCompressor.js'; import {getSnowConfig} from '../../utils/config/apiConfig.js'; import {getHybridCompressEnabled} from '../../utils/config/projectSettings.js'; import {getTodoService} from '../../utils/execution/mcpToolsManager.js'; import {navigateTo} from '../integration/useGlobalNavigation.js'; import type {UsageInfo} from '../../api/chat.js'; import {resetTerminal} from '../../utils/execution/terminal.js'; import { showSaveDialog, isFileDialogSupported, } from '../../utils/ui/fileDialog.js'; import {exportMessagesToFile} from '../../utils/session/chatExporter.js'; import {copyToClipboard} from '../../utils/core/clipboard.js'; import {useI18n} from '../../i18n/index.js'; import {getCurrentLanguage} from '../../utils/config/languageConfig.js'; import {translations} from '../../i18n/index.js'; /** * Helper function to get export command messages */ function getExportMessages() { const currentLanguage = getCurrentLanguage(); return translations[currentLanguage].commandPanel.commandOutput.export; } /** * 执行上下文压缩 * @param sessionId - 可选的会话ID，如果提供则使用该ID加载会话进行压缩 * @param onStatusUpdate - 可选的状态更新回调，用于在UI中显示压缩进度 * @returns 返回压缩后的UI消息列表和token使用信息，如果失败返回null */ export async function executeContextCompression( sessionId?: string, onStatusUpdate?: (status: CompressionStatus) => void, ): Promise<{ uiMessages: Message[]; usage: UsageInfo; } | null> { try { // 必须提供 sessionId 才能执行压缩，避免压缩错误的会话 if (!sessionId) { onStatusUpdate?.({ step: 'skipped', message: 'No active session ID available', }); return null; } // CRITICAL: Save current session to disk BEFORE loading for compression // This ensures all recently added messages (including tool_calls) are persisted // Otherwise loadSession might read stale data, causing compressed session to miss tool_calls onStatusUpdate?.({step: 'saving', sessionId}); const currentSessionBeforeSave = sessionManager.getCurrentSession(); if (currentSessionBeforeSave && currentSessionBeforeSave.id === sessionId) { await sessionManager.saveSession(currentSessionBeforeSave); } // 使用提供的 sessionId 加载会话（从文件读取，确保数据完整） onStatusUpdate?.({step: 'loading', sessionId}); const currentSession = await sessionManager.loadSession(sessionId); if (!currentSession) { onStatusUpdate?.({ step: 'failed', message: `Failed to load session ${sessionId}`, sessionId, }); return null; } if (currentSession.messages.length === 0) { onStatusUpdate?.({ step: 'skipped', message: 'No messages to compress', sessionId, }); return null; } // 使用会话文件中的消息进行压缩（这是真实的对话记录） const sessionMessages = currentSession.messages; // 转换为 ChatMessage 格式（保留所有关键字段） const chatMessages = sessionMessages.map(msg => ({ role: msg.role, content: msg.content, tool_call_id: msg.tool_call_id, tool_calls: msg.tool_calls, images: msg.images, reasoning: msg.reasoning, thinking: msg.thinking, // 保留 thinking 字段（Anthropic Extended Thinking） subAgentInternal: msg.subAgentInternal, })); // Check if Hybrid Compress mode is enabled const useHybridCompress = getHybridCompressEnabled(); onStatusUpdate?.({step: 'compressing', sessionId}); // ── Hybrid Compress path: AI summary + preserved rounds with truncated tool results ── if (useHybridCompress) { const apiConfig = getSnowConfig(); const hybridResult = await performHybridCompression(chatMessages, { model: apiConfig.advancedModel || 'gpt-5', requestMethod: apiConfig.requestMethod, maxTokens: apiConfig.maxTokens, }); if (!hybridResult.compressed) { onStatusUpdate?.({ step: 'skipped', message: 'Not enough history to compress', sessionId, }); return null; } // Build session messages preserving structure (tool_calls, tool_call_id, etc.) const newSessionMessages: Array = hybridResult.messages.map(msg => ({ ...msg, timestamp: Date.now(), })); // Create new session const compressedSession = await sessionManager.createNewSession( false, true, ); compressedSession.messages = newSessionMessages; compressedSession.messageCount = newSessionMessages.length; compressedSession.updatedAt = Date.now(); compressedSession.title = currentSession.title; compressedSession.summary = currentSession.summary; compressedSession.compressedFrom = currentSession.id; compressedSession.compressedAt = Date.now(); await sessionManager.saveSession(compressedSession); // Inherit TODO list try { const todoService = getTodoService(); await todoService.copyTodoList(currentSession.id, compressedSession.id); } catch { // Non-critical } // Reload session onStatusUpdate?.({step: 'loading', sessionId: compressedSession.id}); const reloadedSession = await sessionManager.loadSession( compressedSession.id, ); if (reloadedSession) { sessionManager.setCurrentSession(reloadedSession); } else { sessionManager.setCurrentSession(compressedSession); } onStatusUpdate?.({step: 'completed', sessionId: compressedSession.id}); // Build UI messages (skip tool messages) const newUIMessages: Message[] = newSessionMessages .filter((msg: any) => msg.role !== 'tool') .map((msg: any) => ({ role: msg.role as any, content: msg.content || '', streaming: false, })); const apiUsage = hybridResult.compressionApiUsage; const afterEstimate = hybridResult.afterTokensEstimate || 0; return { uiMessages: newUIMessages, usage: { prompt_tokens: afterEstimate, completion_tokens: apiUsage?.completion_tokens || 0, total_tokens: afterEstimate, }, }; } // ── Standard full compression path ── const compressionResult = await compressContext(chatMessages); if (!compressionResult) { onStatusUpdate?.({ step: 'skipped', message: 'Not enough history to compress', sessionId, }); return null; } // Check if beforeCompress hook failed if (compressionResult.hookFailed) { onStatusUpdate?.({ step: 'failed', message: 'Blocked by beforeCompress hook', sessionId, }); return { uiMessages: [], hookFailed: true, hookErrorDetails: compressionResult.hookErrorDetails, } as any; } // 构建新的会话消息列表 const newSessionMessages: Array = []; let finalContent = `[Context Summary from Previous Conversation]\n\n${compressionResult.summary}`; if ( compressionResult.preservedMessages && compressionResult.preservedMessages.length > 0 ) { finalContent += '\n\n---\n\n[Last Interaction - Preserved for Continuity]\n\n'; for (const msg of compressionResult.preservedMessages) { if (msg.role === 'user') { finalContent += `**User:**\n${msg.content}\n\n`; } else if (msg.role === 'assistant') { finalContent += `**Assistant:**\n${msg.content}`; if (msg.tool_calls && msg.tool_calls.length > 0) { finalContent += '\n\n**[Tool Calls Initiated]:**\n```json\n'; finalContent += JSON.stringify(msg.tool_calls, null, 2); finalContent += '\n```\n\n'; } else { finalContent += '\n\n'; } } else if (msg.role === 'tool') { finalContent += `**[Tool Result - ${msg.tool_call_id}]:**\n`; try { const parsed = JSON.parse(msg.content); finalContent += '```json\n' + JSON.stringify(parsed, null, 2) + '\n```\n\n'; } catch { finalContent += `${msg.content}\n\n`; } } } } newSessionMessages.push({ role: 'user', content: finalContent, timestamp: Date.now(), }); // 创建新会话而不是覆盖旧会话 // 这样可以保留压缩前的完整历史，支持回滚到压缩前的任意快照点 // skipEmptyTodo=true: 跳过自动创建空TODO，因为后面会继承原会话的TODO const compressedSession = await sessionManager.createNewSession( false, true, ); // 设置新会话的消息 compressedSession.messages = newSessionMessages; compressedSession.messageCount = newSessionMessages.length; compressedSession.updatedAt = Date.now(); // 保留原会话的标题和摘要 compressedSession.title = currentSession.title; compressedSession.summary = currentSession.summary; // 记录压缩关系 compressedSession.compressedFrom = currentSession.id; compressedSession.compressedAt = Date.now(); compressedSession.originalMessageIndex = compressionResult.preservedMessageStartIndex; // 保存新会话 await sessionManager.saveSession(compressedSession); // 继承原会话的 TODO 列表到新会话 try { const todoService = getTodoService(); await todoService.copyTodoList(currentSession.id, compressedSession.id); onStatusUpdate?.({ step: 'saving', message: `TODO list inherited from session ${currentSession.id}`, sessionId: compressedSession.id, }); } catch (error) { // TODO 继承失败不应该影响压缩流程，记录日志即可 onStatusUpdate?.({ step: 'skipped', message: 'Failed to inherit TODO list', sessionId: compressedSession.id, }); } // CRITICAL: Reload the new session from disk after compression // This ensures the in-memory session object is fully synchronized with the persisted data // Without this, subsequent saveMessage calls might save to the old session file onStatusUpdate?.({ step: 'loading', message: `Reloading compressed session from disk...`, sessionId: compressedSession.id, }); const reloadedSession = await sessionManager.loadSession( compressedSession.id, ); if (reloadedSession) { // Set the reloaded session as current (with fresh data from disk) sessionManager.setCurrentSession(reloadedSession); onStatusUpdate?.({ step: 'completed', message: `Session reloaded and set as current`, sessionId: compressedSession.id, }); } else { // Fallback: set the in-memory session if reload fails sessionManager.setCurrentSession(compressedSession); onStatusUpdate?.({ step: 'completed', message: `Using in-memory version (reload failed)`, sessionId: compressedSession.id, }); } // 新会话有独立的快照系统，不需要重映射旧会话的快照 // 旧会话的快照保持不变，如果需要回滚到压缩前，可以切换回旧会话 // 同步更新UI消息列表：从会话消息转换为UI Message格式 const newUIMessages: Message[] = []; for (const sessionMsg of newSessionMessages) { // 跳过 tool 角色的消息（工具执行结果），避免UI显示大量JSON if (sessionMsg.role === 'tool') { continue; } const uiMessage: Message = { role: sessionMsg.role as any, content: sessionMsg.content, streaming: false, }; // 如果有 tool_calls，显示工具调用信息（但不显示详细参数） if (sessionMsg.tool_calls && sessionMsg.tool_calls.length > 0) { // 在内容中添加简洁的工具调用摘要 const toolSummary = sessionMsg.tool_calls .map((tc: any) => `[Tool: ${tc.function.name}]`) .join(', '); // 如果内容为空或很短，显示工具调用摘要 if (!uiMessage.content || uiMessage.content.length < 10) { uiMessage.content = toolSummary; } } newUIMessages.push(uiMessage); } return { uiMessages: newUIMessages, usage: { prompt_tokens: compressionResult.usage.prompt_tokens, completion_tokens: compressionResult.usage.completion_tokens, total_tokens: compressionResult.usage.total_tokens, }, }; } catch (error) { onStatusUpdate?.({ step: 'failed', message: error instanceof Error ? error.message : 'Context compression failed', }); return null; } } type CommandHandlerOptions = { messages: Message[]; setMessages: React.Dispatch>; setPendingMessages?: React.Dispatch< React.SetStateAction< Array<{ text: string; images?: Array<{data: string; mimeType: string}>; }> > >; streamStatus?: 'idle' | 'streaming' | 'stopping'; setRemountKey: React.Dispatch>; clearSavedMessages: () => void; setIsCompressing: React.Dispatch>; setCompressionError: React.Dispatch>; setShowSessionPanel: React.Dispatch>; onResumeSessionById?: (sessionId: string) => Promise; setShowConnectionPanel: React.Dispatch>; setConnectionPanelApiUrl: React.Dispatch< React.SetStateAction >; setShowMcpPanel: React.Dispatch>; setShowHelpPanel: React.Dispatch>; onCompressionStatus?: ( status: | import('../../ui/components/compression/CompressionStatus.js').CompressionStatus | null, ) => void; setShowTodoListPanel: React.Dispatch>; setShowPixelEditor: React.Dispatch>; setShowUsagePanel: React.Dispatch>; setShowModelsPanel: React.Dispatch>; setShowSubAgentDepthPanel: React.Dispatch>; setShowCustomCommandConfig: React.Dispatch>; setShowSkillsCreation: React.Dispatch>; setShowSkillsListPanel: React.Dispatch>; setShowRoleCreation: React.Dispatch>; setShowRoleDeletion: React.Dispatch>; setShowRoleList: React.Dispatch>; setShowRoleSubagentCreation: React.Dispatch>; setShowRoleSubagentDeletion: React.Dispatch>; setShowRoleSubagentList: React.Dispatch>; setShowWorkingDirPanel: React.Dispatch>; setShowReviewCommitPanel: React.Dispatch>; setShowDiffReviewPanel: React.Dispatch>; setShowPermissionsPanel: React.Dispatch>; setShowBranchPanel: React.Dispatch>; setShowIdeSelectPanel: React.Dispatch>; setShowNewPromptPanel: React.Dispatch>; setShowBackgroundPanel: () => void; onSwitchProfile: () => void; setYoloMode: React.Dispatch>; setPlanMode: React.Dispatch>; setVulnerabilityHuntingMode: React.Dispatch>; setToolSearchDisabled: React.Dispatch>; setHybridCompressEnabled: React.Dispatch>; setTeamMode: React.Dispatch>; setContextUsage: React.Dispatch>; setCurrentContextPercentage: React.Dispatch>; currentContextPercentageRef: React.MutableRefObject; setVscodeConnectionStatus: React.Dispatch< React.SetStateAction<'disconnected' | 'connecting' | 'connected' | 'error'> >; setIsExecutingTerminalCommand: React.Dispatch>; setCustomCommandExecution: React.Dispatch< React.SetStateAction<{ commandName: string; command: string; isRunning: boolean; output: string[]; exitCode?: number | null; error?: string; } | null> >; processMessage: ( message: string, images?: Array<{data: string; mimeType: string}>, useBasicModel?: boolean, hideUserMessage?: boolean, ) => Promise; setBtwPrompt: React.Dispatch>; onQuit?: () => void; onReindexCodebase?: (force?: boolean) => Promise; onToggleCodebase?: (mode?: string) => Promise; }; export function useCommandHandler(options: CommandHandlerOptions) { const {stdout} = useStdout(); const {t} = useI18n(); const handleCommandExecution = useCallback( async (commandName: string, result: any) => { // Handle /compact command if ( commandName === 'compact' && result.success && result.action === 'compact' ) { options.setIsCompressing(true); options.setCompressionError(null); try { const {performAutoCompression} = await import( '../../utils/core/autoCompress.js' ); const currentSession = sessionManager.getCurrentSession(); const compressionResult = await performAutoCompression( currentSession?.id, (status: CompressionStatus | null) => { options.onCompressionStatus?.(status); }, ); if (compressionResult && (compressionResult as any).hookFailed) { const errorMsg = 'Blocked by beforeCompress hook'; options.setCompressionError(errorMsg); return; } if (!compressionResult) { return; } options.onCompressionStatus?.(null); options.clearSavedMessages(); options.setMessages(compressionResult.uiMessages); options.setRemountKey(prev => prev + 1); options.setContextUsage(compressionResult.usage); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown compression error'; options.onCompressionStatus?.({ step: 'failed', message: errorMsg, }); options.setCompressionError(errorMsg); setTimeout(() => { options.onCompressionStatus?.(null); }, 5000); } finally { options.setIsCompressing(false); } return; } // Handle /ide command — open selection panel if (commandName === 'ide') { if (result.success && result.action === 'showIdeSelectPanel') { options.setShowIdeSelectPanel(true); } return; } if (result.success && result.action === 'clear') { // Execute onSessionStart hook BEFORE clearing session (async () => { try { const {unifiedHooksExecutor} = await import( '../../utils/execution/unifiedHooksExecutor.js' ); const {interpretHookResult} = await import( '../../utils/execution/hookResultInterpreter.js' ); const hookResult = await unifiedHooksExecutor.executeHooks( 'onSessionStart', {messages: [], messageCount: 0}, ); const interpreted = interpretHookResult( 'onSessionStart', hookResult, ); if (interpreted.action === 'block' && interpreted.errorDetails) { const errorMessage: Message = { role: 'assistant', content: '', hookError: interpreted.errorDetails, }; options.setMessages(prev => [...prev, errorMessage]); return; } const warningMessage = interpreted.action === 'warn' ? interpreted.warningMessage : null; // Hook passed, now clear session resetTerminal(stdout); sessionManager.clearCurrentSession(); options.clearSavedMessages(); options.setMessages([]); options.setRemountKey(prev => prev + 1); options.setContextUsage(null); options.setCurrentContextPercentage(0); // CRITICAL: Also reset the ref immediately to prevent auto-compress trigger // before useEffect syncs the state to ref options.currentContextPercentageRef.current = 0; // Clean up global singleton resources to reclaim memory import('../../utils/core/globalCleanup.js') .then(({cleanupGlobalResources}) => cleanupGlobalResources()) .catch(() => {}); // Add command message const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages([commandMessage]); // Display warning AFTER clearing screen if (warningMessage) { console.log(warningMessage); } } catch (error) { console.error('Failed to execute onSessionStart hook:', error); // On exception, still clear session resetTerminal(stdout); sessionManager.clearCurrentSession(); options.clearSavedMessages(); options.setMessages([]); options.setRemountKey(prev => prev + 1); options.setContextUsage(null); options.setCurrentContextPercentage(0); // CRITICAL: Also reset the ref immediately to prevent auto-compress trigger // before useEffect syncs the state to ref options.currentContextPercentageRef.current = 0; // Clean up global singleton resources to reclaim memory import('../../utils/core/globalCleanup.js') .then(({cleanupGlobalResources}) => cleanupGlobalResources()) .catch(() => {}); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages([commandMessage]); } })(); } else if (result.success && result.action === 'showReviewCommitPanel') { options.setShowReviewCommitPanel(true); // 面板唤醒时不输出 command 消息；避免在用户确认选择前污染消息区 // 真正开始 review 的摘要会在 onConfirm 后由 handleReviewCommitConfirm 输出 } else if ( result.success && result.action === 'resume' && result.sessionId ) { if (options.onResumeSessionById) { await options.onResumeSessionById(result.sessionId); } else { const commandMessage: Message = { role: 'command', content: result.message || '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } } else if (result.success && result.action === 'showSessionPanel') { options.setShowSessionPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showDiffReviewPanel') { options.setShowDiffReviewPanel(true); } else if (result.success && result.action === 'showConnectionPanel') { options.setConnectionPanelApiUrl(result.apiUrl); options.setShowConnectionPanel(true); } else if (result.success && result.action === 'showMcpPanel') { options.setShowMcpPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showUsagePanel') { options.setShowUsagePanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showModelsPanel') { options.setShowModelsPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showBackgroundPanel') { options.setShowBackgroundPanel(); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showProfilePanel') { // Open profile switching panel (same logic as shortcut) options.onSwitchProfile(); // Don't add command message to keep UI clean } else if (result.success && result.action === 'home') { // Clear session BEFORE navigating to prevent stale session leaking into new chat sessionManager.clearCurrentSession(); options.clearSavedMessages(); // Reset terminal before navigating to welcome screen resetTerminal(stdout); navigateTo('welcome'); } else if (result.success && result.action === 'showUsagePanel') { options.setShowUsagePanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'help') { // Help shown as an in-chat panel, ESC closes panel without resetting terminal. options.setShowHelpPanel(true); // Don't add command message to keep UI clean } else if (result.success && result.action === 'pixel') { // Pixel editor shown as an overlay panel options.setShowPixelEditor(true); // Don't add command message to keep UI clean } else if ( result.success && result.action === 'showCustomCommandConfig' ) { options.setShowCustomCommandConfig(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showSkillsCreation') { options.setShowSkillsCreation(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showSkillsListPanel') { options.setShowSkillsListPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showRoleCreation') { options.setShowRoleCreation(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showRoleDeletion') { options.setShowRoleDeletion(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showRoleList') { options.setShowRoleList(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if ( result.success && result.action === 'showRoleSubagentCreation' ) { options.setShowRoleSubagentCreation(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if ( result.success && result.action === 'showRoleSubagentDeletion' ) { options.setShowRoleSubagentDeletion(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showRoleSubagentList') { options.setShowRoleSubagentList(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showWorkingDirPanel') { options.setShowWorkingDirPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showReviewCommitPanel') { options.setShowReviewCommitPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showPermissionsPanel') { options.setShowPermissionsPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showBranchPanel') { options.setShowBranchPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'forkSession') { const currentSession = sessionManager.getCurrentSession(); if (!currentSession) { const errorMessage: Message = { role: 'command', content: t.commandPanel.commandOutput.branchFork?.noActiveSession || 'No active session to fork.', commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); return; } try { await sessionManager.saveSession(currentSession); const forkedSession = await sessionManager.createNewSession( false, true, ); const branchName = result.prompt || undefined; forkedSession.messages = currentSession.messages.map(msg => ({ ...msg, })); forkedSession.messageCount = currentSession.messageCount; forkedSession.title = branchName ? `${currentSession.title} [${branchName}]` : currentSession.title; forkedSession.summary = currentSession.summary; forkedSession.branchedFrom = currentSession.id; forkedSession.branchName = branchName; forkedSession.updatedAt = Date.now(); await sessionManager.saveSession(forkedSession); try { const {getTodoService} = await import( '../../utils/execution/mcpToolsManager.js' ); const todoService = getTodoService(); await todoService.copyTodoList(currentSession.id, forkedSession.id); } catch { // Non-critical } if (options.onResumeSessionById) { await options.onResumeSessionById(forkedSession.id); } else { sessionManager.setCurrentSession(forkedSession); } const displayName = branchName ? `"${branchName}"` : forkedSession.id.slice(0, 8); const originalId = currentSession.id; const successContent = ( t.commandPanel.commandOutput.branchFork?.success || 'Conversation forked into branch {name}. To return to the original session:\n/resume {originalId}' ) .replace('{name}', displayName) .replace('{originalId}', originalId); const commandMessage: Message = { role: 'command', content: successContent, commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown error'; const errorMessage: Message = { role: 'command', content: `${ t.commandPanel.commandOutput.branchFork?.failed || 'Failed to fork session' }: ${errorMsg}`, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); } } else if (result.success && result.action === 'showNewPromptPanel') { options.setShowNewPromptPanel(true); } else if (result.success && result.action === 'showSubAgentDepthPanel') { options.setShowSubAgentDepthPanel(true); const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } else if (result.success && result.action === 'showTaskManager') { navigateTo('tasks'); } else if (result.success && result.action === 'showTodoListPanel') { options.setShowTodoListPanel(true); } else if ( result.success && result.action === 'executeCustomCommand' && result.prompt ) { // Execute custom command (prompt type - send to AI or queue as pending) const commandMessage: Message = { role: 'command', content: result.message || '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); if ( options.streamStatus && options.streamStatus !== 'idle' && options.setPendingMessages ) { options.setPendingMessages(prev => [ ...prev, {text: result.prompt as string}, ]); } else { options.processMessage(result.prompt, undefined, false, false); } } else if ( result.success && result.action === 'executeTerminalCommand' && result.prompt ) { // Execute terminal command (execute type - run in terminal) // Use customCommandExecution state for real-time output display in dynamic area options.setIsExecutingTerminalCommand(true); options.setCustomCommandExecution({ commandName: commandName, command: result.prompt, isRunning: true, output: [], exitCode: null, }); // Execute the command using spawn const {spawn} = require('child_process'); const isWindows = process.platform === 'win32'; const shell = isWindows ? 'cmd' : 'sh'; const shellArgs = isWindows ? ['/c', result.prompt] : ['-c', result.prompt]; const child = spawn(shell, shellArgs, { timeout: 30000, }); let outputLines: string[] = []; // PERFORMANCE: Batch output updates to avoid excessive re-renders let cmdOutputFlushTimer: ReturnType | null = null; const CMD_OUTPUT_FLUSH_DELAY = 80; const flushCmdOutput = () => { if (cmdOutputFlushTimer) { clearTimeout(cmdOutputFlushTimer); cmdOutputFlushTimer = null; } const snapshot = outputLines; options.setCustomCommandExecution(prev => prev ? {...prev, output: snapshot} : null, ); }; const scheduleCmdOutputFlush = () => { if (cmdOutputFlushTimer) { clearTimeout(cmdOutputFlushTimer); } cmdOutputFlushTimer = setTimeout( flushCmdOutput, CMD_OUTPUT_FLUSH_DELAY, ); }; // Stream stdout child.stdout.on('data', (data: Buffer) => { const text = data.toString(); const newLines = text .split('\n') .filter((line: string) => line.length > 0); outputLines = [...outputLines, ...newLines].slice(-20); // Keep last 20 lines scheduleCmdOutputFlush(); }); // Stream stderr child.stderr.on('data', (data: Buffer) => { const text = data.toString(); const newLines = text .split('\n') .filter((line: string) => line.length > 0); outputLines = [...outputLines, ...newLines].slice(-20); scheduleCmdOutputFlush(); }); // Handle completion child.on('close', (code: number | null) => { // Flush any remaining output before closing flushCmdOutput(); options.setIsExecutingTerminalCommand(false); options.setCustomCommandExecution(prev => prev ? {...prev, isRunning: false, exitCode: code} : null, ); // Clear after 3 seconds setTimeout(() => { options.setCustomCommandExecution(null); }, 3000); }); // Handle error child.on('error', (error: any) => { options.setIsExecutingTerminalCommand(false); options.setCustomCommandExecution(prev => prev ? {...prev, isRunning: false, exitCode: -1, error: error.message} : null, ); // Clear after 5 seconds for errors setTimeout(() => { options.setCustomCommandExecution(null); }, 5000); }); } else if ( result.success && result.action === 'deleteCustomCommand' && result.prompt ) { // Delete custom command const { deleteCustomCommand, registerCustomCommands, } = require('../../utils/commands/custom.js'); try { // Use the location from result, default to 'global' if not provided const location = result.location || 'global'; const projectRoot = location === 'project' ? process.cwd() : undefined; await deleteCustomCommand(result.prompt, location, projectRoot); await registerCustomCommands(projectRoot); const successMessage: Message = { role: 'command', content: `Custom command '${result.prompt}' deleted successfully`, commandName: commandName, }; options.setMessages(prev => [...prev, successMessage]); } catch (error: any) { const errorMessage: Message = { role: 'command', content: `Failed to delete command: ${error.message}`, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); } } else if (result.success && result.action === 'home') { // Clear session BEFORE navigating to prevent stale session leaking into new chat sessionManager.clearCurrentSession(); options.clearSavedMessages(); // Reset terminal before navigating to welcome screen resetTerminal(stdout); navigateTo('welcome'); } else if (result.success && result.action === 'toggleYolo') { // Toggle YOLO mode without adding command message options.setYoloMode(prev => !prev); // Don't add command message to keep UI clean } else if (result.success && result.action === 'togglePlan') { options.setPlanMode(prev => { const newValue = !prev; if (newValue) { options.setVulnerabilityHuntingMode(false); options.setTeamMode(false); } return newValue; }); } else if (result.success && result.action === 'toggleSimple') { // /simple 切换简易模式后，ChatHeader 等位于 区域的组件 // 不会随 simpleMode 变化自动重绘，必须强制清屏并 bump remountKey // 让 重新挂载，按新模式重绘静态区域。 resetTerminal(stdout); options.setRemountKey(prev => prev + 1); } else if ( result.success && result.action === 'toggleVulnerabilityHunting' ) { options.setVulnerabilityHuntingMode(prev => { const newValue = !prev; if (newValue) { options.setPlanMode(false); options.setTeamMode(false); } return newValue; }); } else if (result.success && result.action === 'toggleToolSearch') { options.setToolSearchDisabled(prev => !prev); } else if (result.success && result.action === 'toggleHybridCompress') { options.setHybridCompressEnabled(prev => !prev); } else if (result.success && result.action === 'toggleTeam') { options.setTeamMode(prev => { const newValue = !prev; if (newValue) { options.setPlanMode(false); options.setVulnerabilityHuntingMode(false); } return newValue; }); } else if ( result.success && result.action === 'initProject' && result.prompt ) { // Add command execution feedback const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); // Auto-send the prompt using basicModel, hide the prompt from UI options.processMessage(result.prompt, undefined, true, true); } else if ( result.success && result.action === 'review' && result.prompt ) { // Clear current session and start new one for code review sessionManager.clearCurrentSession(); options.clearSavedMessages(); options.setMessages([]); options.setRemountKey(prev => prev + 1); // Reset context usage (token statistics) options.setContextUsage(null); // Add command execution feedback const commandMessage: Message = { role: 'command', content: '', commandName: commandName, }; options.setMessages([commandMessage]); // Auto-send the review prompt using advanced model (not basic model), hide the prompt from UI options.processMessage(result.prompt, undefined, false, true); } else if ( result.success && result.action === 'deepResearch' && result.prompt ) { // Deep Research command: run as a normal advanced-model task while // hiding the (very long) embedded prompt from the chat history. // Show the original (truncated) user request under the command tree // node — `result.message` is set by deepresearch.ts to the truncated // user prompt, which formatCommandResultLines() renders as `└─ ...`. const commandMessage: Message = { role: 'command', content: result.message || '', commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); // Use advanced model (basicModel=false) and hide the prompt from UI options.processMessage(result.prompt, undefined, false, true); } else if (result.success && result.action === 'exportChat') { // Handle export chat command // Show loading message first const loadingMessage: Message = { role: 'command', content: getExportMessages().openingDialog, commandName: commandName, }; options.setMessages(prev => [...prev, loadingMessage]); try { // Check if file dialog is supported if (!isFileDialogSupported()) { const errorMessage: Message = { role: 'command', content: 'File dialog not supported on this platform. Export cancelled.', commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); return; } // Generate default filename with timestamp const timestamp = new Date() .toISOString() .replace(/[:.]/g, '-') .split('.')[0]; const defaultFilename = `snow-chat-${timestamp}.txt`; // Show native save dialog const filePath = await showSaveDialog( defaultFilename, 'Export Chat Conversation', ); if (!filePath) { // User cancelled const cancelMessage: Message = { role: 'command', content: getExportMessages().cancelledByUser, commandName: commandName, }; options.setMessages(prev => [...prev, cancelMessage]); return; } // Export messages to file await exportMessagesToFile(options.messages, filePath); // Show success message const successMessage: Message = { role: 'command', content: `✓ Chat exported successfully to:\n${filePath}`, commandName: commandName, }; options.setMessages(prev => [...prev, successMessage]); } catch (error) { // Show error message const errorMsg = error instanceof Error ? error.message : 'Unknown error'; const errorMessage: Message = { role: 'command', content: `✗ Export failed: ${errorMsg}`, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); } } else if (result.success && result.action === 'quit') { // Handle quit command - exit the application cleanly if (options.onQuit) { options.onQuit(); } } else if (result.success && result.action === 'reindexCodebase') { // Handle reindex codebase command - silent execution if (options.onReindexCodebase) { try { await options.onReindexCodebase(result.forceReindex); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown error'; const errorMessage: Message = { role: 'command', content: `Failed to rebuild codebase index: ${errorMsg}`, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); } } } else if (result.success && result.action === 'copyLastMessage') { try { const currentSession = sessionManager.getCurrentSession(); let lastAssistantContent: string | undefined; if (currentSession && !currentSession.isTemporary) { await sessionManager.saveSession(currentSession); const lastAssistantMessage = await sessionManager.getLastAssistantMessageFromSession( currentSession.id, ); lastAssistantContent = lastAssistantMessage?.content; } else if (currentSession) { for (let i = currentSession.messages.length - 1; i >= 0; i--) { const msg = currentSession.messages[i]; if (msg && msg.role === 'assistant' && !msg.subAgentInternal) { lastAssistantContent = msg.content; break; } } } if (lastAssistantContent === undefined) { const errorMessage: Message = { role: 'command', content: t.commandPanel.copyLastFeedback.noAssistantMessage, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); return; } if (!lastAssistantContent) { const errorMessage: Message = { role: 'command', content: t.commandPanel.copyLastFeedback.emptyAssistantMessage, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); return; } await copyToClipboard(lastAssistantContent); const successMessage: Message = { role: 'command', content: t.commandPanel.copyLastFeedback.copySuccess, commandName: commandName, }; options.setMessages(prev => [...prev, successMessage]); } catch (error) { const errorMsg = error instanceof Error ? error.message : t.commandPanel.copyLastFeedback.unknownError; const errorMessage: Message = { role: 'command', content: `${t.commandPanel.copyLastFeedback.copyFailedPrefix}: ${errorMsg}`, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); } } else if (result.success && result.action === 'btw' && result.prompt) { options.setBtwPrompt(result.prompt); } else if (result.success && result.action === 'toggleCodebase') { // Handle toggle codebase command if (options.onToggleCodebase) { try { await options.onToggleCodebase(result.prompt); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown error'; const errorMessage: Message = { role: 'command', content: `Failed to toggle codebase: ${errorMsg}`, commandName: commandName, }; options.setMessages(prev => [...prev, errorMessage]); } } } else if (result.message) { // Display the message as a command message const commandMessage: Message = { role: 'command', content: result.message, commandName: commandName, }; options.setMessages(prev => [...prev, commandMessage]); } }, [stdout, options, t], ); return {handleCommandExecution}; } ================================================ FILE: source/hooks/conversation/useConversation.ts ================================================ import type {ChatMessage} from '../../api/chat.js'; import {getSnowConfig} from '../../utils/config/apiConfig.js'; import type {Message} from '../../ui/components/chat/MessageList.js'; import {connectionManager} from '../../utils/connection/ConnectionManager.js'; import {extractThinkingContent} from './utils/thinkingExtractor.js'; import {EncoderManager} from './core/encoderManager.js'; import { appendUserMessageAndSyncContext, prepareConversationSetup, } from './core/conversationSetup.js'; import {processStreamRound} from './core/streamProcessor.js'; import {handleToolCallRound} from './core/toolCallRoundHandler.js'; import {handleOnStopHooks} from './core/onStopHookHandler.js'; import type { ConversationHandlerOptions, ConversationUsage, } from './core/conversationTypes.js'; export type { ConversationHandlerOptions, UserQuestionResult, } from './core/conversationTypes.js'; /** * Handle conversation with streaming and tool calls. * Returns the usage data collected during the conversation. */ export async function handleConversationWithTools( options: ConversationHandlerOptions, ): Promise<{usage: ConversationUsage | null}> { const { userContent, editorContext, imageContents, controller, saveMessage, setMessages, setStreamTokenCount, requestToolConfirmation, requestUserQuestion, isToolAutoApproved, addMultipleToAlwaysApproved, yoloModeRef, setContextUsage, setIsReasoning, setRetryStatus, } = options; const addToAlwaysApproved = (toolName: string) => { addMultipleToAlwaysApproved([toolName]); }; const { conversationMessages, activeTools, discoveredToolNames, useToolSearch, } = await prepareConversationSetup({ planMode: options.planMode, vulnerabilityHuntingMode: options.vulnerabilityHuntingMode, teamMode: options.teamMode, toolSearchDisabled: options.toolSearchDisabled, }); await appendUserMessageAndSyncContext({ conversationMessages, userContent, editorContext, imageContents, saveMessage, }); const encoderManager = new EncoderManager(); const freeEncoder = () => { encoderManager.free(); }; setStreamTokenCount(0); const config = getSnowConfig(); const model = options.useBasicModel ? config.basicModel || config.advancedModel || 'gpt-5' : config.advancedModel || 'gpt-5'; options.setCurrentModel?.(model); let accumulatedUsage: ConversationUsage | null = null; const sessionApprovedTools = new Set(); try { while (true) { if (controller.signal.aborted) { freeEncoder(); break; } const streamResult = await processStreamRound({ config, model, conversationMessages, activeTools, controller, encoder: encoderManager, setStreamTokenCount, setMessages, setIsReasoning, setRetryStatus, setContextUsage, options, }); setStreamTokenCount(0); accumulatedUsage = mergeUsage(accumulatedUsage, streamResult.roundUsage); if ( streamResult.receivedToolCalls && streamResult.receivedToolCalls.length > 0 ) { const toolLoopResult = await handleToolCallRound({ streamResult, conversationMessages, activeTools, discoveredToolNames, useToolSearch, controller, encoder: encoderManager, accumulatedUsage, sessionApprovedTools, freeEncoder, saveMessage, setMessages, setStreamTokenCount, setContextUsage, requestToolConfirmation, requestUserQuestion, isToolAutoApproved, addMultipleToAlwaysApproved, addToAlwaysApproved, yoloModeRef, streamingEnabled: config.streamingDisplay !== false, options, }); if (toolLoopResult.type === 'break') { if (toolLoopResult.accumulatedUsage !== undefined) { accumulatedUsage = toolLoopResult.accumulatedUsage; } freeEncoder(); break; } if (toolLoopResult.type === 'return') { return {usage: toolLoopResult.accumulatedUsage}; } if (toolLoopResult.accumulatedUsage !== undefined) { accumulatedUsage = toolLoopResult.accumulatedUsage; } continue; } if (streamResult.streamedContent.trim()) { if (!streamResult.hasStreamedLines) { const finalAssistantMessage: Message = { role: 'assistant', content: streamResult.streamedContent.trim(), streaming: false, discontinued: controller.signal.aborted, thinking: extractThinkingContent( streamResult.receivedThinking, streamResult.receivedReasoning, streamResult.receivedReasoningContent, ), }; setMessages(prev => [...prev, finalAssistantMessage]); } const assistantMessage: ChatMessage = { role: 'assistant', content: streamResult.streamedContent.trim(), reasoning: streamResult.receivedReasoning, thinking: streamResult.receivedThinking, reasoning_content: streamResult.receivedReasoningContent, }; conversationMessages.push(assistantMessage); saveMessage(assistantMessage).catch(error => { console.error('Failed to save assistant message:', error); }); } if (!controller.signal.aborted) { const hookResult = await handleOnStopHooks({ conversationMessages, saveMessage, setMessages, }); if (hookResult.shouldContinue) { continue; } } break; } freeEncoder(); } finally { options.setIsStreaming?.(false); try { await connectionManager.notifyMessageProcessingCompleted(); } catch { // Ignore notification errors } try { const {clearConversationContext} = await import( '../../utils/codebase/conversationContext.js' ); clearConversationContext(); } catch { // Ignore errors during cleanup } freeEncoder(); } return {usage: accumulatedUsage}; } function mergeUsage( accumulated: ConversationUsage | null, round: ConversationUsage | null, ): ConversationUsage | null { if (!round) { return accumulated; } if (!accumulated) { return round; } return { prompt_tokens: accumulated.prompt_tokens + (round.prompt_tokens || 0), completion_tokens: accumulated.completion_tokens + (round.completion_tokens || 0), total_tokens: accumulated.total_tokens + (round.total_tokens || 0), cache_creation_input_tokens: round.cache_creation_input_tokens !== undefined ? (accumulated.cache_creation_input_tokens || 0) + round.cache_creation_input_tokens : accumulated.cache_creation_input_tokens, cache_read_input_tokens: round.cache_read_input_tokens !== undefined ? (accumulated.cache_read_input_tokens || 0) + round.cache_read_input_tokens : accumulated.cache_read_input_tokens, cached_tokens: round.cached_tokens !== undefined ? (accumulated.cached_tokens || 0) + round.cached_tokens : accumulated.cached_tokens, }; } ================================================ FILE: source/hooks/conversation/useStreamingState.ts ================================================ import {useState, useEffect} from 'react'; import type {UsageInfo} from '../../api/chat.js'; export type RetryStatus = { isRetrying: boolean; attempt: number; nextDelay: number; remainingSeconds?: number; errorMessage?: string; }; export type CodebaseSearchStatus = { isSearching: boolean; attempt: number; maxAttempts: number; currentTopN: number; message: string; query?: string; originalResultsCount?: number; suggestion?: string; }; export type StreamStatus = 'idle' | 'streaming' | 'stopping'; export function useStreamingState() { const [streamStatus, setStreamStatus] = useState('idle'); const isStreaming = streamStatus === 'streaming'; const isStopping = streamStatus === 'stopping'; const setIsStreaming: React.Dispatch< React.SetStateAction > = action => { setStreamStatus(prev => { const currentIsStreaming = prev === 'streaming'; const nextIsStreaming = typeof action === 'function' ? action(currentIsStreaming) : action; if (nextIsStreaming) return 'streaming'; // When streaming ends (setIsStreaming(false)), always go to idle. // This includes the 'stopping' state - if stream has ended, we're done. return 'idle'; }); }; const setIsStopping: React.Dispatch< React.SetStateAction > = action => { setStreamStatus(prev => { const currentIsStopping = prev === 'stopping'; const nextIsStopping = typeof action === 'function' ? action(currentIsStopping) : action; if (nextIsStopping) return 'stopping'; if (prev === 'stopping') return 'idle'; return prev; }); }; const [streamTokenCount, setStreamTokenCount] = useState(0); const [isReasoning, setIsReasoning] = useState(false); const [abortController, setAbortController] = useState(null); const [contextUsage, setContextUsage] = useState(null); const [elapsedSeconds, setElapsedSeconds] = useState(0); const [timerStartTime, setTimerStartTime] = useState(null); const [retryStatus, setRetryStatus] = useState(null); const [animationFrame, setAnimationFrame] = useState(0); const [codebaseSearchStatus, setCodebaseSearchStatus] = useState(null); const [currentModel, setCurrentModel] = useState(null); const [isAutoCompressing, setIsAutoCompressing] = useState(false); const [compressBlockToast, setCompressBlockToast] = useState( null, ); // Auto-clear compress block toast after 2 seconds useEffect(() => { if (!compressBlockToast) return; const timeoutId = setTimeout(() => { setCompressBlockToast(null); }, 2000); return () => clearTimeout(timeoutId); }, [compressBlockToast]); // Animation for streaming/saving indicator useEffect(() => { if (!isStreaming) return; const interval = setInterval(() => { setAnimationFrame(prev => (prev + 1) % 2); }, 500); return () => { clearInterval(interval); setAnimationFrame(0); }; }, [isStreaming]); // Timer for tracking request duration useEffect(() => { if (isStreaming && timerStartTime === null) { // Start timer when streaming begins setTimerStartTime(Date.now()); setElapsedSeconds(0); } else if (!isStreaming && timerStartTime !== null) { // Stop timer when streaming ends setTimerStartTime(null); } }, [isStreaming, timerStartTime]); // Update elapsed time every second useEffect(() => { if (timerStartTime === null) return; const interval = setInterval(() => { const elapsed = Math.floor((Date.now() - timerStartTime) / 1000); setElapsedSeconds(elapsed); }, 1000); return () => clearInterval(interval); }, [timerStartTime]); // Initialize remaining seconds when retry starts useEffect(() => { if (!retryStatus?.isRetrying) return; if (retryStatus.remainingSeconds !== undefined) return; // Initialize remaining seconds from nextDelay (only once) setRetryStatus(prev => prev ? { ...prev, remainingSeconds: Math.ceil(prev.nextDelay / 1000), } : null, ); }, [retryStatus?.isRetrying]); // Only depend on isRetrying flag // Countdown timer for retry delays useEffect(() => { if (!retryStatus || !retryStatus.isRetrying) return; if (retryStatus.remainingSeconds === undefined) return; // Countdown every second const interval = setInterval(() => { setRetryStatus(prev => { if (!prev || prev.remainingSeconds === undefined) return prev; const newRemaining = prev.remainingSeconds - 1; if (newRemaining <= 0) { return { ...prev, remainingSeconds: 0, }; } return { ...prev, remainingSeconds: newRemaining, }; }); }, 1000); return () => clearInterval(interval); }, [retryStatus?.isRetrying]); // ✅ 移除 remainingSeconds 避免循环 return { streamStatus, setStreamStatus, isStreaming, setIsStreaming, isStopping, setIsStopping, streamTokenCount, setStreamTokenCount, isReasoning, setIsReasoning, abortController, setAbortController, contextUsage, setContextUsage, elapsedSeconds, retryStatus, setRetryStatus, animationFrame, codebaseSearchStatus, setCodebaseSearchStatus, currentModel, setCurrentModel, isAutoCompressing, setIsAutoCompressing, compressBlockToast, setCompressBlockToast, }; } ================================================ FILE: source/hooks/conversation/useToolConfirmation.ts ================================================ import {useState, useRef, useCallback, useEffect} from 'react'; import type {ToolCall} from '../../utils/execution/toolExecutor.js'; import type {ConfirmationResult} from '../../ui/components/tools/ToolConfirmation.js'; import { loadPermissionsConfig, addToolToPermissions, addMultipleToolsToPermissions, removeToolFromPermissions, clearAllPermissions, } from '../../utils/config/permissionsConfig.js'; export type PendingConfirmation = { tool: ToolCall; batchToolNames?: string; // Deprecated: kept for backward compatibility allTools?: ToolCall[]; // All tools when confirming multiple tools resolve: (result: ConfirmationResult) => void; }; /** * Hook for managing tool confirmation state and logic * @param workingDirectory - Current working directory for permissions persistence */ export function useToolConfirmation(workingDirectory: string) { const [pendingToolConfirmation, setPendingToolConfirmation] = useState(null); // Use ref for always-approved tools to ensure closure functions always see latest state const alwaysApprovedToolsRef = useRef>(new Set()); const [alwaysApprovedTools, setAlwaysApprovedTools] = useState>( new Set(), ); // Load persisted permissions on mount useEffect(() => { const config = loadPermissionsConfig(workingDirectory); const loadedTools = new Set(config.alwaysApprovedTools); alwaysApprovedToolsRef.current = loadedTools; setAlwaysApprovedTools(loadedTools); }, [workingDirectory]); /** * Request user confirmation for tool execution */ const requestToolConfirmation = async ( toolCall: ToolCall, batchToolNames?: string, allTools?: ToolCall[], ): Promise => { return new Promise(resolve => { setPendingToolConfirmation({ tool: toolCall, batchToolNames, allTools, resolve: (result: ConfirmationResult) => { setPendingToolConfirmation(null); resolve(result); }, }); }); }; /** * Check if a tool is auto-approved * Uses ref to ensure it always sees the latest approved tools */ const isToolAutoApproved = useCallback( (toolName: string): boolean => { return ( alwaysApprovedToolsRef.current.has(toolName) || toolName.startsWith('todo-') || toolName === 'askuser-ask_question' || toolName === 'tool_search' ); }, [], // No dependencies - ref is always stable ); /** * Add a tool to the always-approved list */ const addToAlwaysApproved = useCallback( (toolName: string) => { // Update ref immediately (for closure functions) alwaysApprovedToolsRef.current.add(toolName); // Update state (for UI reactivity) setAlwaysApprovedTools(prev => new Set([...prev, toolName])); // Persist to disk addToolToPermissions(workingDirectory, toolName); }, [workingDirectory], ); /** * Add multiple tools to the always-approved list */ const addMultipleToAlwaysApproved = useCallback( (toolNames: string[]) => { // Update ref immediately (for closure functions) toolNames.forEach(name => alwaysApprovedToolsRef.current.add(name)); // Update state (for UI reactivity) setAlwaysApprovedTools(prev => new Set([...prev, ...toolNames])); // Persist to disk addMultipleToolsToPermissions(workingDirectory, toolNames); }, [workingDirectory], ); /** * Remove a tool from the always-approved list */ const removeFromAlwaysApproved = useCallback( (toolName: string) => { // Update ref immediately (for closure functions) alwaysApprovedToolsRef.current.delete(toolName); // Update state (for UI reactivity) setAlwaysApprovedTools(prev => { const next = new Set(prev); next.delete(toolName); return next; }); // Persist to disk removeToolFromPermissions(workingDirectory, toolName); }, [workingDirectory], ); /** * Clear all always-approved tools */ const clearAllAlwaysApproved = useCallback(() => { // Update ref immediately (for closure functions) alwaysApprovedToolsRef.current.clear(); // Update state (for UI reactivity) setAlwaysApprovedTools(new Set()); // Persist to disk clearAllPermissions(workingDirectory); }, [workingDirectory]); return { pendingToolConfirmation, alwaysApprovedTools, requestToolConfirmation, isToolAutoApproved, addToAlwaysApproved, addMultipleToAlwaysApproved, removeFromAlwaysApproved, clearAllAlwaysApproved, }; } ================================================ FILE: source/hooks/conversation/utils/messageCleanup.ts ================================================ import type {ChatMessage} from '../../../api/chat.js'; /** * LAYER 3 PROTECTION: Clean orphaned tool_calls from conversation messages * * Removes two types of problematic messages: * 1. Assistant messages with tool_calls that have no corresponding tool results * 2. Tool result messages that have no corresponding tool_calls * * This prevents OpenAI API errors when sessions have incomplete tool_calls * due to force quit (Ctrl+C/ESC) during tool execution. * * @param messages - Array of conversation messages (will be modified in-place) */ export function cleanOrphanedToolCalls(messages: ChatMessage[]): void { // Build map of tool_call_ids that have results const toolResultIds = new Set(); for (const msg of messages) { if (msg.role === 'tool' && msg.tool_call_id) { toolResultIds.add(msg.tool_call_id); } } // Build map of tool_call_ids that are declared in assistant messages const declaredToolCallIds = new Set(); for (const msg of messages) { if (msg.role === 'assistant' && msg.tool_calls) { for (const tc of msg.tool_calls) { declaredToolCallIds.add(tc.id); } } } // Find indices to remove (iterate backwards for safe removal) const indicesToRemove: number[] = []; for (let i = messages.length - 1; i >= 0; i--) { const msg = messages[i]; if (!msg) continue; // Skip undefined messages (should never happen, but TypeScript requires check) // Check for orphaned assistant messages with tool_calls if (msg.role === 'assistant' && msg.tool_calls) { const hasAllResults = msg.tool_calls.every(tc => toolResultIds.has(tc.id), ); if (!hasAllResults) { // const orphanedIds = msg.tool_calls // .filter(tc => !toolResultIds.has(tc.id)) // .map(tc => tc.id); // console.warn( // '[cleanOrphanedToolCalls] Removing assistant message with orphaned tool_calls', // { // messageIndex: i, // toolCallIds: msg.tool_calls.map(tc => tc.id), // orphanedIds, // }, // ); indicesToRemove.push(i); } } // Check for orphaned tool result messages if (msg.role === 'tool' && msg.tool_call_id) { if (!declaredToolCallIds.has(msg.tool_call_id)) { // console.warn('[cleanOrphanedToolCalls] Removing orphaned tool result', { // messageIndex: i, // toolCallId: msg.tool_call_id, // }); indicesToRemove.push(i); } } } // Remove messages in reverse order (from end to start) to preserve indices for (const idx of indicesToRemove) { messages.splice(idx, 1); } if (indicesToRemove.length > 0) { // console.log( // `[cleanOrphanedToolCalls] Removed ${indicesToRemove.length} orphaned messages from conversation`, // ); } } ================================================ FILE: source/hooks/conversation/utils/thinkingExtractor.ts ================================================ /** * Reasoning data structure from Responses API */ interface ReasoningData { summary?: Array<{type: 'summary_text'; text: string}>; content?: any; encrypted_content?: string; } /** * Thinking data structure from Anthropic */ interface ThinkingData { type: 'thinking'; thinking: string; signature?: string; } /** * Clean thinking content by removing XML-like tags * Some third-party APIs (e.g., DeepSeek R1) may include or tags * in the reasoning content that should be stripped * * @param content - Raw thinking content * @returns Cleaned thinking content */ function cleanThinkingContent(content: string): string { // Remove , , , tags (with surrounding whitespace/newlines) return content .replace(/\s*<\/?think(?:ing)?>\s*/gi, '') .trim(); } /** * Extract thinking content from various sources * * Supports multiple reasoning formats: * 1. Anthropic Extended Thinking * 2. Responses API reasoning summary * 3. DeepSeek R1 reasoning content * * @param receivedThinking - Anthropic thinking data * @param receivedReasoning - Responses API reasoning data * @param receivedReasoningContent - DeepSeek R1 reasoning content * @returns Extracted thinking content or undefined */ export function extractThinkingContent( receivedThinking?: ThinkingData, receivedReasoning?: ReasoningData, receivedReasoningContent?: string, ): string | undefined { // 1. Anthropic Extended Thinking if (receivedThinking?.thinking) { return cleanThinkingContent(receivedThinking.thinking); } // 2. Responses API reasoning summary if (receivedReasoning?.summary && receivedReasoning.summary.length > 0) { const content = receivedReasoning.summary.map(item => item.text).join('\n'); return cleanThinkingContent(content); } // 3. DeepSeek R1 reasoning content if (receivedReasoningContent) { return cleanThinkingContent(receivedReasoningContent); } return undefined; } ================================================ FILE: source/hooks/execution/useBackgroundProcesses.ts ================================================ import {useState, useCallback} from 'react'; import {exec} from 'child_process'; export interface BackgroundProcess { id: string; command: string; pid: number; status: 'running' | 'completed' | 'failed'; startedAt: Date; completedAt?: Date; exitCode?: number; } // Global state for background processes (shared across components) let globalProcesses: BackgroundProcess[] = []; let globalSetProcesses: ((processes: BackgroundProcess[]) => void) | null = null; let globalSetShowPanel: ((show: boolean) => void) | null = null; /** * Hook to manage background processes * Used by ChatScreen to display and manage background processes */ export function useBackgroundProcesses() { const [processes, setProcesses] = useState([]); const [showPanel, setShowPanel] = useState(false); // Always update global setters globalSetProcesses = setProcesses; globalSetShowPanel = setShowPanel; const addProcess = useCallback((command: string, pid: number) => { const process: BackgroundProcess = { id: `${pid}-${Date.now()}`, command, pid, status: 'running', startedAt: new Date(), }; globalProcesses = [...globalProcesses, process]; if (globalSetProcesses) { globalSetProcesses(globalProcesses); } return process.id; }, []); const updateProcessStatus = useCallback( (id: string, status: 'completed' | 'failed', exitCode?: number) => { globalProcesses = globalProcesses.map(p => p.id === id ? { ...p, status, completedAt: new Date(), exitCode, } : p, ); if (globalSetProcesses) { globalSetProcesses(globalProcesses); } }, [], ); const killProcess = useCallback( (id: string) => { const process = globalProcesses.find(p => p.id === id); if (!process || process.status !== 'running') { return; } const {pid} = process; const isWindows = global.process.platform === 'win32'; if (isWindows) { // Windows: Use taskkill to kill entire process tree exec(`taskkill /PID ${pid} /T /F 2>NUL`, {windowsHide: true}, () => { // Update status after kill updateProcessStatus(id, 'failed', 130); }); } else { // Unix: Send SIGTERM first, then SIGKILL as fallback try { global.process.kill(pid, 'SIGTERM'); // Force SIGKILL after a short delay to ensure termination // This handles processes that may ignore or delay responding to SIGTERM setTimeout(() => { try { // Check if process is still running by sending signal 0 global.process.kill(pid, 0); // If we get here, process is still alive, send SIGKILL global.process.kill(pid, 'SIGKILL'); } catch { // Process already dead or no permission, ignore } }, 100); // Update status after kill updateProcessStatus(id, 'failed', 130); } catch { // Process already dead or no permission } } }, [updateProcessStatus], ); const removeProcess = useCallback((id: string) => { globalProcesses = globalProcesses.filter(p => p.id !== id); if (globalSetProcesses) { globalSetProcesses(globalProcesses); } }, []); const clearCompleted = useCallback(() => { globalProcesses = globalProcesses.filter(p => p.status === 'running'); if (globalSetProcesses) { globalSetProcesses(globalProcesses); } }, []); const enablePanel = useCallback(() => { if (globalSetShowPanel) { globalSetShowPanel(true); } }, []); const hidePanel = useCallback(() => { if (globalSetShowPanel) { globalSetShowPanel(false); } }, []); return { processes, showPanel, addProcess, updateProcessStatus, killProcess, removeProcess, clearCompleted, enablePanel, hidePanel, }; } /** * Add a background process from anywhere (e.g., bash.ts) * This allows non-React code to add processes */ export function addBackgroundProcess(command: string, pid: number): string { const process: BackgroundProcess = { id: `${pid}-${Date.now()}`, command, pid, status: 'running', startedAt: new Date(), }; globalProcesses = [...globalProcesses, process]; if (globalSetProcesses) { globalSetProcesses(globalProcesses); } return process.id; } /** * Update background process status from anywhere */ export function updateBackgroundProcessStatus( id: string, status: 'completed' | 'failed', exitCode?: number, ) { globalProcesses = globalProcesses.map(p => p.id === id ? { ...p, status, completedAt: new Date(), exitCode, } : p, ); if (globalSetProcesses) { globalSetProcesses(globalProcesses); } } /** * Show the background process panel (called when Ctrl+B is pressed) */ export function showBackgroundPanel() { if (globalSetShowPanel) { globalSetShowPanel(true); } } ================================================ FILE: source/hooks/execution/useSchedulerExecutionState.ts ================================================ import {useState, useCallback} from 'react'; export interface SchedulerExecutionState { /** 是否正在执行倒计时 */ isRunning: boolean; /** 任务描述 */ description: string | null; /** 总等待时长（秒） */ totalDuration: number; /** 剩余时间（秒） */ remainingSeconds: number; /** 任务开始时间 */ startedAt: string | null; /** 任务是否已完成 */ isCompleted: boolean; /** 完成时间 */ completedAt: string | null; } // Global state for scheduler execution (shared across components) let globalSetState: ((state: SchedulerExecutionState) => void) | null = null; let globalState: SchedulerExecutionState | null = null; /** * Hook to manage scheduler execution state * Used by ChatScreen to display countdown UI */ export function useSchedulerExecutionState() { const [state, setState] = useState({ isRunning: false, description: null, totalDuration: 0, remainingSeconds: 0, startedAt: null, isCompleted: false, completedAt: null, }); // Always update global setter to ensure it's current globalSetState = setState; globalState = state; const startTask = useCallback((description: string, duration: number) => { const now = new Date().toISOString(); setState({ isRunning: true, description, totalDuration: duration, remainingSeconds: duration, startedAt: now, isCompleted: false, completedAt: null, }); }, []); const updateRemainingTime = useCallback((seconds: number) => { if (globalSetState && globalState) { globalSetState({ ...globalState, remainingSeconds: Math.max(0, seconds), }); } }, []); const completeTask = useCallback(() => { const now = new Date().toISOString(); setState(prev => ({ ...prev, isRunning: false, isCompleted: true, completedAt: now, remainingSeconds: 0, })); }, []); const resetTask = useCallback(() => { setState({ isRunning: false, description: null, totalDuration: 0, remainingSeconds: 0, startedAt: null, isCompleted: false, completedAt: null, }); }, []); return { state, startTask, updateRemainingTime, completeTask, resetTask, }; } /** * Set scheduler execution state from anywhere (e.g., tool executor) * This allows non-React code to update the UI state */ export function setSchedulerExecutionState(state: SchedulerExecutionState) { if (globalSetState) { globalSetState(state); } } /** * Start a scheduler task from anywhere */ export function startSchedulerTask(description: string, duration: number) { if (globalSetState) { const now = new Date().toISOString(); globalSetState({ isRunning: true, description, totalDuration: duration, remainingSeconds: duration, startedAt: now, isCompleted: false, completedAt: null, }); } } /** * Update remaining time from anywhere */ export function updateSchedulerRemainingTime(seconds: number) { if (globalSetState && globalState) { globalSetState({ ...globalState, remainingSeconds: Math.max(0, seconds), }); } } /** * Mark task as completed from anywhere */ export function completeSchedulerTask() { if (globalSetState && globalState) { const now = new Date().toISOString(); globalSetState({ ...globalState, isRunning: false, isCompleted: true, completedAt: now, remainingSeconds: 0, }); } } /** * Reset scheduler state from anywhere */ export function resetSchedulerState() { if (globalSetState) { globalSetState({ isRunning: false, description: null, totalDuration: 0, remainingSeconds: 0, startedAt: null, isCompleted: false, completedAt: null, }); } } /** * Get current scheduler state */ export function getSchedulerState(): SchedulerExecutionState | null { return globalState; } ================================================ FILE: source/hooks/execution/useTerminalExecutionState.ts ================================================ import {useState, useCallback} from 'react'; export interface TerminalExecutionState { isExecuting: boolean; command: string | null; timeout: number | null; isBackgrounded: boolean; output: string[]; /** Whether the command is waiting for user input (interactive mode) */ needsInput: boolean; /** Prompt text shown when waiting for input (e.g., "Password:", "[Y/n]") */ inputPrompt: string | null; } // Global state for terminal execution (shared across components) let globalSetState: ((state: TerminalExecutionState) => void) | null = null; let globalState: TerminalExecutionState | null = null; /** * Hook to manage terminal execution state * Used by ChatScreen to display execution status */ export function useTerminalExecutionState() { const [state, setState] = useState({ isExecuting: false, command: null, timeout: null, isBackgrounded: false, output: [], needsInput: false, inputPrompt: null, }); // Always update global setter to ensure it's current // This prevents race conditions where setState might be stale or null globalSetState = setState; globalState = state; const startExecution = useCallback((command: string, timeout: number) => { setState({ isExecuting: true, command, timeout, isBackgrounded: false, output: [], needsInput: false, inputPrompt: null, }); }, []); const endExecution = useCallback(() => { // Flush any remaining buffered output before ending execution flushOutputBuffer(); setState({ isExecuting: false, command: null, timeout: null, isBackgrounded: false, output: [], needsInput: false, inputPrompt: null, }); }, []); const moveToBackground = useCallback(() => { setState(prev => ({ ...prev, isBackgrounded: true, })); }, []); return { state, startExecution, endExecution, moveToBackground, }; } /** * Set terminal execution state from anywhere (e.g., tool executor) * This allows non-React code to update the UI state */ export function setTerminalExecutionState(state: TerminalExecutionState) { if (globalSetState) { globalSetState(state); } } // Batch buffer for output lines to reduce state updates let outputBuffer: string[] = []; let outputFlushTimer: ReturnType | null = null; const OUTPUT_BATCH_SIZE = 10; // Flush every 10 lines const OUTPUT_FLUSH_DELAY = 50; // Or flush after 50ms of inactivity /** * Flush buffered output lines to state * Exported to allow manual flushing when needed (e.g., before command ends) */ export function flushOutputBuffer() { if (outputFlushTimer) { clearTimeout(outputFlushTimer); outputFlushTimer = null; } if (outputBuffer.length === 0 || !globalSetState || !globalState) { return; } const linesToFlush = outputBuffer.splice(0, outputBuffer.length); globalSetState({ ...globalState, output: [...globalState.output, ...linesToFlush], }); } /** * Append output line to terminal execution state * Called from bash.ts during command execution * PERFORMANCE: Batches multiple lines to reduce state updates */ export function appendTerminalOutput(line: string) { if (!globalSetState || !globalState) { return; } outputBuffer.push(line); // Flush immediately if buffer is full if (outputBuffer.length >= OUTPUT_BATCH_SIZE) { flushOutputBuffer(); return; } // Otherwise, debounce flush if (outputFlushTimer) { clearTimeout(outputFlushTimer); } outputFlushTimer = setTimeout(flushOutputBuffer, OUTPUT_FLUSH_DELAY); } /** * Set terminal input needed state * Called from bash.ts when interactive input is detected */ export function setTerminalNeedsInput(needsInput: boolean, prompt?: string) { if (globalSetState && globalState) { globalSetState({ ...globalState, needsInput, inputPrompt: prompt || null, }); } } // Global callback for sending input to the running process let globalInputCallback: ((input: string) => void) | null = null; /** * Register a callback to receive user input * Called from bash.ts to set up input handling */ export function registerInputCallback( callback: ((input: string) => void) | null, ) { globalInputCallback = callback; } /** * Send user input to the running process * Called from UI when user submits input */ export function sendTerminalInput(input: string) { if (globalInputCallback) { globalInputCallback(input); } } ================================================ FILE: source/hooks/input/keyboard/context.ts ================================================ import type {Key} from 'ink'; import {TextBuffer} from '../../../utils/ui/textBuffer.js'; import type { HandlerContext, HandlerHelpers, HandlerRefs, KeyboardInputOptions, } from './types.js'; import {findWordBoundary} from './utils/wordBoundary.js'; export function createHelpers( buffer: TextBuffer, options: KeyboardInputOptions, refs: HandlerRefs, ): HandlerHelpers { const { updateFilePickerState, updateAgentPickerState, updateRunningAgentsPickerState, updateCommandPanelState, forceUpdate, } = options; // Force immediate state update for critical operations like backspace const forceStateUpdate = () => { const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); updateCommandPanelState(text); forceUpdate({}); }; const flushPendingInput = () => { if (!refs.inputBuffer.current) return; if (refs.inputTimer.current) { clearTimeout(refs.inputTimer.current); refs.inputTimer.current = null; } // Invalidate any queued timer work from older input batches. refs.inputSessionId.current += 1; const accumulated = refs.inputBuffer.current; const savedCursorPosition = refs.inputStartCursorPos.current; refs.inputBuffer.current = ''; // Keep these flags consistent; otherwise a single-char insert can race a pending flush. refs.isPasting.current = false; refs.isProcessingInput.current = false; buffer.setCursorPosition(savedCursorPosition); buffer.insert(accumulated); refs.inputStartCursorPos.current = buffer.getCursorPosition(); }; return { forceStateUpdate, flushPendingInput, findWordBoundary, }; } export function createContext( input: string, key: Key, buffer: TextBuffer, options: KeyboardInputOptions, refs: HandlerRefs, helpers: HandlerHelpers, ): HandlerContext { return {input, key, buffer, options, refs, helpers}; } ================================================ FILE: source/hooks/input/keyboard/handlers/arrowKeys.ts ================================================ import type {HandlerContext} from '../types.js'; export function arrowKeysHandler(ctx: HandlerContext): boolean { const {key, buffer, options, helpers} = ctx; const { showCommands, showFilePicker, disableKeyboardNavigation, updateFilePickerState, updateAgentPickerState, updateRunningAgentsPickerState, currentHistoryIndex, navigateHistoryUp, navigateHistoryDown, triggerUpdate, } = options; // Arrow keys for cursor movement if (key.leftArrow) { helpers.flushPendingInput(); buffer.moveLeft(); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); // No need to call triggerUpdate() - buffer.moveLeft() already triggers update via scheduleUpdate() return true; } if (key.rightArrow) { helpers.flushPendingInput(); buffer.moveRight(); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); // No need to call triggerUpdate() - buffer.moveRight() already triggers update via scheduleUpdate() return true; } if ( key.upArrow && !showCommands && !showFilePicker && !disableKeyboardNavigation ) { helpers.flushPendingInput(); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); const isEmpty = text.trim() === ''; // Allow history navigation whenever the cursor is at the very beginning // of the input (position 0). For multi-line content this means the cursor // is on the first visual line at column 0 — pressing Up there cannot move // further up, so we fall through to history navigation instead. if (isEmpty || cursorPos === 0) { const navigated = navigateHistoryUp(); if (navigated) { updateFilePickerState(buffer.getFullText(), buffer.getCursorPosition()); updateAgentPickerState( buffer.getFullText(), buffer.getCursorPosition(), ); updateRunningAgentsPickerState( buffer.getFullText(), buffer.getCursorPosition(), ); triggerUpdate(); return true; } } buffer.moveUp(); updateFilePickerState(buffer.getFullText(), buffer.getCursorPosition()); updateAgentPickerState(buffer.getFullText(), buffer.getCursorPosition()); updateRunningAgentsPickerState( buffer.getFullText(), buffer.getCursorPosition(), ); triggerUpdate(); return true; } if ( key.downArrow && !showCommands && !showFilePicker && !disableKeyboardNavigation ) { helpers.flushPendingInput(); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); const isEmpty = text.trim() === ''; // Allow history navigation whenever the cursor is at the very end of the // input (position text.length). For multi-line content this means the // cursor is on the last visual line at the final column — pressing Down // there cannot move further down, so we fall through to history navigation // (only when already in history mode, matching the original behavior). if ((isEmpty || cursorPos === text.length) && currentHistoryIndex !== -1) { const navigated = navigateHistoryDown(); if (navigated) { updateFilePickerState(buffer.getFullText(), buffer.getCursorPosition()); updateAgentPickerState( buffer.getFullText(), buffer.getCursorPosition(), ); updateRunningAgentsPickerState( buffer.getFullText(), buffer.getCursorPosition(), ); triggerUpdate(); return true; } } buffer.moveDown(); updateFilePickerState(buffer.getFullText(), buffer.getCursorPosition()); updateAgentPickerState(buffer.getFullText(), buffer.getCursorPosition()); updateRunningAgentsPickerState( buffer.getFullText(), buffer.getCursorPosition(), ); triggerUpdate(); return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/clipboard.ts ================================================ import type {HandlerContext} from '../types.js'; export function clipboardHandler(ctx: HandlerContext): boolean { const {input, key, options, refs} = ctx; const {pasteFromClipboard} = options; // Windows: Alt+V, macOS: Ctrl+V - Paste from clipboard (including images) const isPasteShortcut = process.platform === 'darwin' ? key.ctrl && input === 'v' : key.meta && input === 'v'; if (isPasteShortcut) { refs.lastPasteShortcutAt.current = Date.now(); pasteFromClipboard(); return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/deleteAndBackspace.ts ================================================ import type {HandlerContext} from '../types.js'; export function deleteAndBackspaceHandler(ctx: HandlerContext): boolean { const {input, key, buffer, refs, helpers} = ctx; // Delete key - delete character after cursor // Detected via raw stdin listener because ink doesn't distinguish Delete from Backspace if (refs.deleteKeyPressed.current) { refs.deleteKeyPressed.current = false; helpers.flushPendingInput(); buffer.delete(); helpers.forceStateUpdate(); return true; } // Backspace - delete character before cursor // Check both ink's key detection and raw input codes const isBackspace = key.backspace || key.delete || input === '\x7f' || input === '\x08'; if (isBackspace) { helpers.flushPendingInput(); buffer.backspace(); helpers.forceStateUpdate(); return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/editing.ts ================================================ import {editTextWithNotepad} from '../../../../utils/ui/externalEditor.js'; import {copyToClipboard} from '../../../../utils/core/clipboard.js'; import type {HandlerContext} from '../types.js'; export function editingHandler(ctx: HandlerContext): boolean { const {input, key, buffer, options, helpers} = ctx; const { showFilePicker, fileListRef, forceUpdate, triggerUpdate, onCopyInputSuccess, onCopyInputError, } = options; // Ctrl+T - Toggle file picker display mode when active, otherwise toggle pasted text view if (key.ctrl && input === 't') { if (showFilePicker && fileListRef.current?.toggleDisplayMode()) { forceUpdate({}); return true; } helpers.flushPendingInput(); buffer.toggleExpandedView(); forceUpdate({}); return true; } // Ctrl+A - Move to beginning of line if (key.ctrl && input === 'a') { helpers.flushPendingInput(); const text = buffer.text; const cursorPos = buffer.getCursorPosition(); // Find start of current line const lineStart = text.lastIndexOf('\n', cursorPos - 1) + 1; buffer.setCursorPosition(lineStart); triggerUpdate(); return true; } // Ctrl+E - Move to end of line if (key.ctrl && input === 'e') { helpers.flushPendingInput(); const text = buffer.text; const cursorPos = buffer.getCursorPosition(); // Find end of current line let lineEnd = text.indexOf('\n', cursorPos); if (lineEnd === -1) lineEnd = text.length; buffer.setCursorPosition(lineEnd); triggerUpdate(); return true; } // Ctrl+G - 使用外部编辑器编辑输入内容（Windows: Notepad） if (key.ctrl && input === 'g') { helpers.flushPendingInput(); // 非 Windows 平台安全降级：吞掉快捷键但不执行任何操作 if (process.platform !== 'win32') { return true; } const initialText = buffer.getFullText(); // useInput 回调不是 async，这里用 Promise 链处理。 editTextWithNotepad(initialText) .then(editedText => { // 完全覆盖输入：先清空以清理占位符/图片残留，再恢复文本（避免触发 [Paste ...]） buffer.setText(''); if (editedText) { buffer.insertRestoredText(editedText); buffer.setCursorPosition(editedText.length); } else { buffer.setCursorPosition(0); } helpers.forceStateUpdate(); }) .catch(() => { // 失败时不阻断输入，只做一次刷新避免 UI 卡住 helpers.forceStateUpdate(); }); return true; } // Ctrl+O - Copy current input content to system clipboard if (key.ctrl && input === 'o') { helpers.flushPendingInput(); const contentToCopy = buffer.getFullText(); void copyToClipboard(contentToCopy) .then(() => { onCopyInputSuccess?.(); }) .catch(error => { console.error('Failed to copy current input to clipboard:', error); onCopyInputError?.( error instanceof Error ? error.message : 'Unknown error', ); }); return true; } // Alt+F - Forward one word if (key.meta && input === 'f') { helpers.flushPendingInput(); const text = buffer.text; const cursorPos = buffer.getCursorPosition(); const newPos = helpers.findWordBoundary(text, cursorPos, 'forward'); buffer.setCursorPosition(newPos); triggerUpdate(); return true; } // Ctrl+K - Delete from cursor to end of line (readline compatible) if (key.ctrl && input === 'k') { helpers.flushPendingInput(); const text = buffer.text; const cursorPos = buffer.getCursorPosition(); // Find end of current line let lineEnd = text.indexOf('\n', cursorPos); if (lineEnd === -1) lineEnd = text.length; // Delete from cursor to end of line const beforeCursor = text.slice(0, cursorPos); const afterLine = text.slice(lineEnd); buffer.setText(beforeCursor + afterLine); helpers.forceStateUpdate(); return true; } // Ctrl+U - Delete from cursor to beginning of line (readline compatible) if (key.ctrl && input === 'u') { helpers.flushPendingInput(); const text = buffer.text; const cursorPos = buffer.getCursorPosition(); // Find start of current line const lineStart = text.lastIndexOf('\n', cursorPos - 1) + 1; // Delete from line start to cursor const beforeLine = text.slice(0, lineStart); const afterCursor = text.slice(cursorPos); buffer.setText(beforeLine + afterCursor); buffer.setCursorPosition(lineStart); helpers.forceStateUpdate(); return true; } // Ctrl+W - Delete word before cursor if (key.ctrl && input === 'w') { helpers.flushPendingInput(); const text = buffer.text; const cursorPos = buffer.getCursorPosition(); const wordStart = helpers.findWordBoundary(text, cursorPos, 'backward'); // Delete from word start to cursor const beforeWord = text.slice(0, wordStart); const afterCursor = text.slice(cursorPos); buffer.setText(beforeWord + afterCursor); buffer.setCursorPosition(wordStart); helpers.forceStateUpdate(); return true; } // Ctrl+D - Delete character at cursor (readline compatible) if (key.ctrl && input === 'd') { helpers.flushPendingInput(); const text = buffer.text; const cursorPos = buffer.getCursorPosition(); if (cursorPos < text.length) { const beforeCursor = text.slice(0, cursorPos); const afterChar = text.slice(cursorPos + 1); buffer.setText(beforeCursor + afterChar); helpers.forceStateUpdate(); } return true; } // Ctrl+L - Clear from cursor to beginning (legacy, kept for compatibility) if (key.ctrl && input === 'l') { helpers.flushPendingInput(); const displayText = buffer.text; const cursorPos = buffer.getCursorPosition(); const afterCursor = displayText.slice(cursorPos); buffer.setText(afterCursor); helpers.forceStateUpdate(); return true; } // Ctrl+R - Clear from cursor to end (legacy, kept for compatibility) if (key.ctrl && input === 'r') { helpers.flushPendingInput(); const displayText = buffer.text; const cursorPos = buffer.getCursorPosition(); const beforeCursor = displayText.slice(0, cursorPos); buffer.setText(beforeCursor); helpers.forceStateUpdate(); return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/escape.ts ================================================ import {setPickerActive} from '../../../../utils/ui/pickerState.js'; import type {HandlerContext} from '../types.js'; export function escapeHandler(ctx: HandlerContext): boolean { const {key, buffer, options, helpers} = ctx; const { showArgsPicker, setShowArgsPicker, setArgsSelectedIndex, showProfilePicker, setShowProfilePicker, setProfileSelectedIndex, setProfileSearchQuery, showSkillsPicker, closeSkillsPicker, showGitLinePicker, closeGitLinePicker, showRunningAgentsPicker, closeRunningAgentsPicker, showTodoPicker, setShowTodoPicker, setTodoSelectedIndex, showAgentPicker, setShowAgentPicker, setAgentSelectedIndex, showFilePicker, setShowFilePicker, setFileSelectedIndex, setFileQuery, setAtSymbolPosition, showCommands, setShowCommands, setCommandSelectedIndex, showHistoryMenu, setShowHistoryMenu, setHistorySelectedIndex, escapeKeyCount, setEscapeKeyCount, escapeKeyTimer, getUserMessages, } = options; if (!key.escape) return false; if (showArgsPicker) { setShowArgsPicker(false); setArgsSelectedIndex(0); setPickerActive(true); return true; } if (showProfilePicker) { setShowProfilePicker(false); setProfileSelectedIndex(0); setProfileSearchQuery(''); setPickerActive(true); return true; } if (showSkillsPicker) { closeSkillsPicker(); setPickerActive(true); return true; } if (showGitLinePicker) { closeGitLinePicker(); setPickerActive(true); return true; } if (showRunningAgentsPicker) { closeRunningAgentsPicker(); setPickerActive(true); return true; } if (showTodoPicker) { setShowTodoPicker(false); setTodoSelectedIndex(0); setPickerActive(true); return true; } if (showAgentPicker) { setShowAgentPicker(false); setAgentSelectedIndex(0); setPickerActive(true); return true; } if (showFilePicker) { setShowFilePicker(false); setFileSelectedIndex(0); setFileQuery(''); setAtSymbolPosition(-1); setPickerActive(true); return true; } if (showCommands) { setShowCommands(false); setCommandSelectedIndex(0); setPickerActive(true); return true; } setPickerActive(false); if (showHistoryMenu) { setShowHistoryMenu(false); return true; } setEscapeKeyCount(prev => prev + 1); if (escapeKeyTimer.current) { clearTimeout(escapeKeyTimer.current); } escapeKeyTimer.current = setTimeout(() => { setEscapeKeyCount(0); }, 500); if (escapeKeyCount >= 1) { setEscapeKeyCount(0); if (escapeKeyTimer.current) { clearTimeout(escapeKeyTimer.current); escapeKeyTimer.current = null; } const text = buffer.getFullText(); if (text.trim().length > 0) { buffer.setText(''); helpers.forceStateUpdate(); } else { const userMessages = getUserMessages(); if (userMessages.length > 0) { setShowHistoryMenu(true); setHistorySelectedIndex(userMessages.length - 1); } } } return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/focusFilter.ts ================================================ import type {HandlerContext} from '../types.js'; export function focusFilterHandler(ctx: HandlerContext): boolean { const {input, refs} = ctx; // Ignore focus events during the first 500ms after component mount // This prevents [I[I artifacts when switching from WelcomeScreen to ChatScreen const timeSinceMount = Date.now() - refs.componentMountTime.current; if (timeSinceMount < 500) { // During initial mount period, aggressively filter any input that could be focus events if ( input.includes('[I') || input.includes('[O') || input === '\x1b[I' || input === '\x1b[O' || /^[\s\x1b\[IO]+$/.test(input) ) { return true; } } // Filter out focus events more robustly // Focus events: ESC[I (focus in) or ESC[O (focus out) // Some terminals may send these with or without ESC, and they might appear // anywhere in the input string (especially during drag-and-drop with Shift held) // We need to filter them out but NOT remove legitimate user input const focusEventPattern = /(\s|^)\[(?:I|O)(?=(?:\s|$|["'~\\/]|[A-Za-z]:))/; if ( // Complete escape sequences input === '\x1b[I' || input === '\x1b[O' || // Standalone sequences (exact match only) input === '[I' || input === '[O' || // Filter if input ONLY contains focus events, whitespace, and optional ESC prefix (/^[\s\x1b\[IO]+$/.test(input) && focusEventPattern.test(input)) ) { return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/modeToggle.ts ================================================ import type {HandlerContext} from '../types.js'; function cycleModes(ctx: HandlerContext): void { const {options} = ctx; const { yoloMode, planMode, teamMode: _teamMode, setYoloMode, setPlanMode, setTeamMode, setVulnerabilityHuntingMode, } = options; if (yoloMode && !planMode && !_teamMode) { // YOLO only -> YOLO + Plan setPlanMode(true); setVulnerabilityHuntingMode(false); setTeamMode(false); } else if (yoloMode && planMode && !_teamMode) { // YOLO + Plan -> Plan only setYoloMode(false); } else if (!yoloMode && planMode && !_teamMode) { // Plan only -> YOLO + Team setYoloMode(true); setPlanMode(false); setTeamMode(true); setVulnerabilityHuntingMode(false); } else if (yoloMode && !planMode && _teamMode) { // YOLO + Team -> Team only setYoloMode(false); } else if (!yoloMode && !planMode && _teamMode) { // Team only -> All off setTeamMode(false); } else { // All off -> YOLO only setYoloMode(true); setPlanMode(false); setTeamMode(false); setVulnerabilityHuntingMode(false); } } export function modeToggleHandler(ctx: HandlerContext): boolean { const {input, key} = ctx; // Shift+Tab - Toggle modes in cycle if (key.shift && key.tab) { cycleModes(ctx); return true; } // Ctrl+Y - Toggle modes in cycle if (key.ctrl && input === 'y') { cycleModes(ctx); return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/newline.ts ================================================ import type {HandlerContext} from '../types.js'; export function newlineHandler(ctx: HandlerContext): boolean { const {key, buffer, options, helpers} = ctx; const { updateCommandPanelState, updateFilePickerState, updateAgentPickerState, updateRunningAgentsPickerState, } = options; // Ctrl+Enter (Win/Linux) or Option+Enter (macOS) - Insert newline // Must be checked before any picker/panel key.return handlers to avoid interception if ((key.ctrl || key.meta) && key.return) { helpers.flushPendingInput(); buffer.insert('\n'); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/agentPicker.ts ================================================ import type {HandlerContext} from '../../types.js'; export function agentPickerHandler(ctx: HandlerContext): boolean { const {key, options} = ctx; const { showAgentPicker, getFilteredAgents, setAgentSelectedIndex, agentSelectedIndex, handleAgentSelect, setShowAgentPicker, } = options; if (!showAgentPicker) return false; const filteredAgents = getFilteredAgents(); // Up arrow in agent picker - 循环导航:第一项 → 最后一项 if (key.upArrow) { setAgentSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, filteredAgents.length - 1), ); return true; } // Down arrow in agent picker - 循环导航:最后一项 → 第一项 if (key.downArrow) { const maxIndex = Math.max(0, filteredAgents.length - 1); setAgentSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Enter - select agent if (key.return) { if ( filteredAgents.length > 0 && agentSelectedIndex < filteredAgents.length ) { const selectedAgent = filteredAgents[agentSelectedIndex]; if (selectedAgent) { handleAgentSelect(selectedAgent); setShowAgentPicker(false); setAgentSelectedIndex(0); } } return true; } // Allow typing to filter - don't block regular input // The input will be processed below and updateAgentPickerState will be called // which will update the filter automatically return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/argsPicker.ts ================================================ import {setPickerActive} from '../../../../../utils/ui/pickerState.js'; import type {HandlerContext} from '../../types.js'; export function argsPickerHandler(ctx: HandlerContext): boolean { const {key, buffer, options} = ctx; const { showArgsPicker, argsPickerContext, argsSelectedIndex, setArgsSelectedIndex, setShowArgsPicker, triggerUpdate, } = options; if (!showArgsPicker) return false; const argOptions = argsPickerContext.options; if (key.upArrow) { setArgsSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, argOptions.length - 1), ); return true; } if (key.downArrow) { const maxIndex = Math.max(0, argOptions.length - 1); setArgsSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Tab closes the panel if (key.tab) { setShowArgsPicker(false); setArgsSelectedIndex(0); setPickerActive(true); return true; } if (key.return) { if (argOptions.length > 0 && argsSelectedIndex < argOptions.length) { const selected = argOptions[argsSelectedIndex]; if (selected) { const text = buffer.text; const hasTrailingSpace = /^\/[a-zA-Z0-9_-]+\s+$/.test(text); const suffix = hasTrailingSpace ? selected : ' ' + selected; buffer.insert(suffix); buffer.setCursorPosition(buffer.text.length); setShowArgsPicker(false); setArgsSelectedIndex(0); triggerUpdate(); } } return true; } // Backspace silently closes (not shown in hint text) if (key.backspace || key.delete) { setShowArgsPicker(false); setArgsSelectedIndex(0); return true; } return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/commandPanel.ts ================================================ import {executeCommand} from '../../../../../utils/execution/commandExecutor.js'; import {commandUsageManager} from '../../../../../utils/session/commandUsageManager.js'; import {COMMAND_ARGS_OPTIONS} from '../../../../ui/useCommandPanel.js'; import type {HandlerContext} from '../../types.js'; export function commandPanelHandler(ctx: HandlerContext): boolean { const {key, buffer, options} = ctx; const { showCommands, getFilteredCommands, commandSelectedIndex, setCommandSelectedIndex, setShowCommands, setShowArgsPicker, setArgsSelectedIndex, setShowTodoPicker, setShowAgentPicker, setShowSkillsPicker, setShowGitLinePicker, isProcessing, getAllCommands, onCommand, triggerUpdate, } = options; if (!showCommands) return false; const filteredCommands = getFilteredCommands(); // Up arrow in command panel - 循环导航:第一项 → 最后一项 if (key.upArrow) { setCommandSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, filteredCommands.length - 1), ); return true; } // Down arrow in command panel - 循环导航:最后一项 → 第一项 if (key.downArrow) { const maxIndex = Math.max(0, filteredCommands.length - 1); setCommandSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Tab - autocomplete command to input if (key.tab) { if ( filteredCommands.length > 0 && commandSelectedIndex < filteredCommands.length ) { const selectedCommand = filteredCommands[commandSelectedIndex]; if (selectedCommand) { buffer.setText('/' + selectedCommand.name); buffer.setCursorPosition(buffer.text.length); setShowCommands(false); setCommandSelectedIndex(0); const cmdArgsOptions = COMMAND_ARGS_OPTIONS[selectedCommand.name]; if (cmdArgsOptions && cmdArgsOptions.length > 0) { setShowArgsPicker(true); setArgsSelectedIndex(0); } triggerUpdate(); return true; } } return true; } // Enter - select command if (key.return) { if ( filteredCommands.length > 0 && commandSelectedIndex < filteredCommands.length ) { const selectedCommand = filteredCommands[commandSelectedIndex]; if (selectedCommand) { // Special handling for todo- command if (selectedCommand.name === 'todo-') { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowTodoPicker(true); triggerUpdate(); return true; } // Special handling for agent- command if (selectedCommand.name === 'agent-') { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowAgentPicker(true); triggerUpdate(); return true; } // Special handling for skills- command if (selectedCommand.name === 'skills-') { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowSkillsPicker(true); triggerUpdate(); return true; } if (selectedCommand.name === 'gitline') { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowGitLinePicker(true); triggerUpdate(); return true; } // Block command execution if AI is processing if (isProcessing && getAllCommands) { const matchedCommand = getAllCommands().find( cmd => cmd.name === selectedCommand.name, ); if (matchedCommand && matchedCommand.type !== 'prompt') { // Keep non-prompt commands blocked while AI is already processing. buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); triggerUpdate(); return true; } } // Execute command instead of inserting text // If the user has typed args after the command name (e.g. "/role -l"), // pass them through so sub-commands work from the command panel. const fullText = buffer.getFullText(); const commandMatch = fullText.match(/^\/([^\s]+)(?:\s+(.+))?$/); const commandArgs = commandMatch?.[2]; executeCommand(selectedCommand.name, commandArgs).then(result => { // Record command usage for frequency-based sorting commandUsageManager.recordUsage(selectedCommand.name); if (onCommand) { // Ensure onCommand errors are caught Promise.resolve(onCommand(selectedCommand.name, result)).catch( error => { console.error('Command execution error:', error); }, ); } }); buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); triggerUpdate(); return true; } } // If no commands available, fall through to normal Enter handling return false; } // Other keys (regular characters) must fall through so they're inserted // into the buffer and updateCommandPanelState can re-filter the panel. return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/filePicker.ts ================================================ import type {HandlerContext} from '../../types.js'; export function filePickerHandler(ctx: HandlerContext): boolean { const {key, options} = ctx; const { showFilePicker, filteredFileCount, fileSelectedIndex, setFileSelectedIndex, fileListRef, handleFileSelect, } = options; if (!showFilePicker) return false; // Up arrow in file picker - 循环导航:第一项 → 最后一项 if (key.upArrow) { setFileSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, filteredFileCount - 1), ); return true; } // Down arrow in file picker // 便捷深度检索：只要光标已停在最后一项（无论有多少结果），且还有未扫描的深层目录， // 再按 ⬇️ 就把扫描深度加深一层，避免被表层结果误以为已经搜索完毕。 // 触发不成功（已扫到底 / 仍在扫描中）时，回退为原有的循环导航行为。 if (key.downArrow) { const maxIndex = Math.max(0, filteredFileCount - 1); if ( filteredFileCount > 0 && fileSelectedIndex >= maxIndex && fileListRef.current?.triggerDeeperSearch?.() ) { return true; } setFileSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Tab or Enter - select file if (key.tab || key.return) { if (filteredFileCount > 0 && fileSelectedIndex < filteredFileCount) { const selectedFile = fileListRef.current?.getSelectedFile(); if (selectedFile) { handleFileSelect(selectedFile); } } return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/gitLinePicker.ts ================================================ import type {HandlerContext} from '../../types.js'; export function gitLinePickerHandler(ctx: HandlerContext): boolean { const {input, key, options} = ctx; const { showGitLinePicker, gitLineCommits, setGitLineSelectedIndex, toggleGitLineCommitSelection, confirmGitLineSelection, gitLineSearchQuery, setGitLineSearchQuery, triggerUpdate, } = options; if (!showGitLinePicker) return false; if (key.upArrow) { setGitLineSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, gitLineCommits.length - 1), ); return true; } if (key.downArrow) { const maxIndex = Math.max(0, gitLineCommits.length - 1); setGitLineSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } if (input === ' ') { toggleGitLineCommitSelection(); return true; } if (key.return) { confirmGitLineSelection(); return true; } if (key.backspace || key.delete) { if (gitLineSearchQuery.length > 0) { setGitLineSearchQuery(gitLineSearchQuery.slice(0, -1)); setGitLineSelectedIndex(0); triggerUpdate(); } return true; } if ( input && !key.ctrl && !key.meta && !key.escape && input !== '\\x1b' && input !== '\\u001b' && !/[\\x00-\\x1F]/.test(input) ) { setGitLineSearchQuery(gitLineSearchQuery + input); setGitLineSelectedIndex(0); triggerUpdate(); return true; } return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/historyMenu.ts ================================================ import type {HandlerContext} from '../../types.js'; export function historyMenuHandler(ctx: HandlerContext): boolean { const {key, options} = ctx; const { showHistoryMenu, getUserMessages, setHistorySelectedIndex, historySelectedIndex, handleHistorySelect, } = options; if (!showHistoryMenu) return false; const userMessages = getUserMessages(); // Up arrow in history menu - 循环导航:第一项 → 最后一项 if (key.upArrow) { setHistorySelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, userMessages.length - 1), ); return true; } // Down arrow in history menu - 循环导航:最后一项 → 第一项 if (key.downArrow) { const maxIndex = Math.max(0, userMessages.length - 1); setHistorySelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Enter - select history item if (key.return) { if ( userMessages.length > 0 && historySelectedIndex < userMessages.length ) { const selectedMessage = userMessages[historySelectedIndex]; if (selectedMessage) { handleHistorySelect(selectedMessage.value); } } return true; } // For any other key in history menu, just return to prevent interference return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/profilePicker.ts ================================================ import type {HandlerContext} from '../../types.js'; export function profilePickerHandler(ctx: HandlerContext): boolean { const {input, key, options} = ctx; const { showProfilePicker, getFilteredProfiles, setProfileSelectedIndex, profileSelectedIndex, handleProfileSelect, handleProfileEdit, profileSearchQuery, setProfileSearchQuery, triggerUpdate, } = options; if (!showProfilePicker) return false; const filteredProfiles = getFilteredProfiles(); if (key.upArrow) { setProfileSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, filteredProfiles.length - 1), ); return true; } if (key.downArrow) { const maxIndex = Math.max(0, filteredProfiles.length - 1); setProfileSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Tab 键：打开当前光标焦点 profile 的编辑面板（不切换 active） if (key.tab && handleProfileEdit) { if ( filteredProfiles.length > 0 && profileSelectedIndex < filteredProfiles.length ) { const focusedProfile = filteredProfiles[profileSelectedIndex]; if (focusedProfile) { handleProfileEdit(focusedProfile.name); } } return true; } if (key.return) { if ( filteredProfiles.length > 0 && profileSelectedIndex < filteredProfiles.length ) { const selectedProfile = filteredProfiles[profileSelectedIndex]; if (selectedProfile) { handleProfileSelect(selectedProfile.name); } } return true; } if (key.backspace || key.delete) { if (profileSearchQuery.length > 0) { setProfileSearchQuery(profileSearchQuery.slice(0, -1)); setProfileSelectedIndex(0); triggerUpdate(); } return true; } if ( input && !key.ctrl && !key.meta && !key.escape && input !== '\x1b' && input !== '\u001b' && !/[\x00-\x1F]/.test(input) ) { setProfileSearchQuery(profileSearchQuery + input); setProfileSelectedIndex(0); triggerUpdate(); return true; } return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/runningAgentsPicker.ts ================================================ import type {HandlerContext} from '../../types.js'; export function runningAgentsPickerHandler(ctx: HandlerContext): boolean { const {input, key, options, helpers} = ctx; const { showRunningAgentsPicker, runningAgents, setRunningAgentsSelectedIndex, toggleRunningAgentSelection, confirmRunningAgentsSelection, } = options; if (!showRunningAgentsPicker) return false; // Up arrow - circular navigation if (key.upArrow) { setRunningAgentsSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, runningAgents.length - 1), ); return true; } // Down arrow - circular navigation if (key.downArrow) { const maxIndex = Math.max(0, runningAgents.length - 1); setRunningAgentsSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Space - toggle multi-selection if (input === ' ') { toggleRunningAgentSelection(); return true; } // Enter - confirm selection and insert visual tags. if (key.return) { confirmRunningAgentsSelection(); helpers.forceStateUpdate(); return true; } // Backspace / Delete — let it through so >> can be deleted // and updateRunningAgentsPickerState will auto-close the panel. if (key.backspace || key.delete) { // Don't return — fall through to normal backspace handling below return false; } // For any other key in running agents picker, block to prevent interference return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/skillsPicker.ts ================================================ import type {HandlerContext} from '../../types.js'; export function skillsPickerHandler(ctx: HandlerContext): boolean { const {input, key, options} = ctx; const { showSkillsPicker, skills, setSkillsSelectedIndex, toggleSkillsFocus, confirmSkillsSelection, backspaceSkillsField, appendSkillsChar, } = options; if (!showSkillsPicker) return false; // Up arrow - 循环导航:第一项 → 最后一项 if (key.upArrow) { setSkillsSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, skills.length - 1), ); return true; } // Down arrow - 循环导航:最后一项 → 第一项 if (key.downArrow) { const maxIndex = Math.max(0, skills.length - 1); setSkillsSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Tab - toggle focus between search/append if (key.tab) { toggleSkillsFocus(); return true; } // Enter - confirm selection if (key.return) { confirmSkillsSelection(); return true; } // Backspace/Delete - remove last character from focused field if (key.backspace || key.delete) { backspaceSkillsField(); return true; } // Type - update focused field (accept multi-byte like Chinese) if ( input && !key.ctrl && !key.meta && !key.escape && input !== '\\x1b' && input !== '\\u001b' && !/[\\x00-\\x1F]/.test(input) ) { appendSkillsChar(input); return true; } return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/pickers/todoPicker.ts ================================================ import type {HandlerContext} from '../../types.js'; export function todoPickerHandler(ctx: HandlerContext): boolean { const {input, key, options} = ctx; const { showTodoPicker, todos, setTodoSelectedIndex, toggleTodoSelection, confirmTodoSelection, todoSearchQuery, setTodoSearchQuery, triggerUpdate, } = options; if (!showTodoPicker) return false; // Up arrow in todo picker - 循环导航:第一项 → 最后一项 if (key.upArrow) { setTodoSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, todos.length - 1), ); return true; } // Down arrow in todo picker - 循环导航:最后一项 → 第一项 if (key.downArrow) { const maxIndex = Math.max(0, todos.length - 1); setTodoSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return true; } // Space - toggle selection if (input === ' ') { toggleTodoSelection(); return true; } // Enter - confirm selection if (key.return) { confirmTodoSelection(); return true; } // Backspace - remove last character from search if (key.backspace || key.delete) { if (todoSearchQuery.length > 0) { setTodoSearchQuery(todoSearchQuery.slice(0, -1)); setTodoSelectedIndex(0); // Reset to first item triggerUpdate(); } return true; } // Type to search - alphanumeric and common characters // Accept complete characters (including multi-byte like Chinese) // but filter out control sequences and incomplete input if ( input && !key.ctrl && !key.meta && !key.escape && input !== '\x1b' && // Ignore escape sequences input !== '\u001b' && // Additional escape check !/[\x00-\x1F]/.test(input) // Ignore other control characters ) { setTodoSearchQuery(todoSearchQuery + input); setTodoSelectedIndex(0); // Reset to first item triggerUpdate(); return true; } // For any other key in todo picker, just return to prevent interference return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/profileShortcut.ts ================================================ import type {HandlerContext} from '../types.js'; export function profileShortcutHandler(ctx: HandlerContext): boolean { const {input, key, options} = ctx; const {onSwitchProfile} = options; // Windows/Linux: Alt+P, macOS: Ctrl+P - Switch to next profile const isProfileSwitchShortcut = process.platform === 'darwin' ? key.ctrl && input === 'p' : key.meta && input === 'p'; if (isProfileSwitchShortcut) { if (onSwitchProfile) { onSwitchProfile(); } return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/regularInput.ts ================================================ import type {HandlerContext} from '../types.js'; export function regularInputHandler(ctx: HandlerContext): boolean { const {input, key, buffer, options, refs} = ctx; const { currentHistoryIndex, resetHistoryNavigation, ensureFocus, updateCommandPanelState, updateFilePickerState, updateAgentPickerState, updateRunningAgentsPickerState, pasteShortcutTimeoutMs = 800, pasteFlushDebounceMs = 250, pasteIndicatorThreshold = 300, triggerUpdate, } = options; // Regular character input if (input && !key.ctrl && !key.meta && !key.escape) { // Reset history navigation when user starts typing if (currentHistoryIndex !== -1) { resetHistoryNavigation(); } // Ensure focus is active when user is typing (handles delayed focus events) // This is especially important for drag-and-drop operations where focus // events may arrive out of order or be filtered by sanitizeInput ensureFocus(); const now = Date.now(); const isPasteShortcutActive = now - refs.lastPasteShortcutAt.current <= pasteShortcutTimeoutMs; // ink 在 IME 场景下可能一次性提交多个字符（通常很短），这不是“粘贴”。 // 如果仍按“多字符=粘贴/IME，延迟缓冲”处理，用户在提交前移动光标会让插入位置/显示状态产生竞态， // 表现为光标插入错位、内容渲染像“总是显示末尾”。 // 因此：短的多字符输入直接落盘；只对明显的粘贴/大输入走缓冲。 const isSingleCharInput = input.length === 1; const isSmallMultiCharInput = input.length > 1 && !input.includes('\n'); // 单字符：正常键入，直接插入 if (isSingleCharInput && !refs.isProcessingInput.current) { // This prevents the "disappearing text" issue at line start buffer.insert(input); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); return true; } // IME commit / 小段粘贴（无换行、长度不大）统一直接落盘，避免进入 100ms 缓冲。 // 这能避免“先移动光标再输入”场景下仍走缓冲，导致插入位置/内容被错误合并。 if ( isSmallMultiCharInput && !refs.isProcessingInput.current && !isPasteShortcutActive ) { ctx.helpers.flushPendingInput(); buffer.insert(input); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); return true; } // 其余（含换行/已有缓冲会话/大段输入）：使用缓冲机制 // Save cursor position when starting new input accumulation const isStartingNewInput = refs.inputBuffer.current === ''; if (isStartingNewInput) { refs.inputStartCursorPos.current = buffer.getCursorPosition(); refs.isProcessingInput.current = true; // Mark that we're processing multi-char input refs.inputSessionId.current += 1; } // Accumulate input for paste detection refs.inputBuffer.current += input; // Clear existing timer if (refs.inputTimer.current) { clearTimeout(refs.inputTimer.current); } const activeSessionId = refs.inputSessionId.current; const currentLength = refs.inputBuffer.current.length; const shouldShowIndicator = isPasteShortcutActive || currentLength > pasteIndicatorThreshold; // Show pasting indicator for large text or explicit paste // Simple static message - no progress animation if (shouldShowIndicator && !refs.isPasting.current) { refs.isPasting.current = true; buffer.insertPastingIndicator(); // Trigger UI update to show the indicator const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); triggerUpdate(); } // Set timer to process accumulated input const flushDelay = isPasteShortcutActive ? pasteShortcutTimeoutMs : pasteFlushDebounceMs; refs.inputTimer.current = setTimeout(() => { if (activeSessionId !== refs.inputSessionId.current) { return; } const accumulated = refs.inputBuffer.current; const savedCursorPosition = refs.inputStartCursorPos.current; const wasPasting = refs.isPasting.current; // Save pasting state before clearing refs.inputBuffer.current = ''; refs.isPasting.current = false; // Reset pasting state refs.isProcessingInput.current = false; // Reset processing flag // If we accumulated input, insert it at the saved cursor position // The insert() method will automatically remove the pasting indicator if (accumulated) { // Get current cursor position to calculate if user moved cursor during input const currentCursor = buffer.getCursorPosition(); // If cursor hasn't moved from where we started (or only moved due to pasting indicator), // insert at the saved position // Otherwise, insert at current position (user deliberately moved cursor) // Note: wasPasting check uses saved state, not current isPasting.current if ( currentCursor === savedCursorPosition || (wasPasting && currentCursor > savedCursorPosition) ) { // Temporarily set cursor to saved position for insertion // This is safe because we're in a timeout, not during active cursor movement buffer.setCursorPosition(savedCursorPosition); buffer.insert(accumulated); // No need to restore cursor - insert() moves it naturally } else { // User moved cursor during input, insert at current position buffer.insert(accumulated); } // Reset inputStartCursorPos after processing to prevent stale position refs.inputStartCursorPos.current = buffer.getCursorPosition(); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, cursorPos); updateAgentPickerState(text, cursorPos); updateRunningAgentsPickerState(text, cursorPos); triggerUpdate(); } }, flushDelay); return true; } return false; } ================================================ FILE: source/hooks/input/keyboard/handlers/submit.ts ================================================ import {executeCommand} from '../../../../utils/execution/commandExecutor.js'; import {commandUsageManager} from '../../../../utils/session/commandUsageManager.js'; import type {HandlerContext} from '../types.js'; export function submitHandler(ctx: HandlerContext): boolean { const {key, buffer, options, refs, helpers} = ctx; const { updateCommandPanelState, updateFilePickerState, updateAgentPickerState, updateRunningAgentsPickerState, currentHistoryIndex, resetHistoryNavigation, isProcessing, getAllCommands, setShowCommands, setCommandSelectedIndex, setShowTodoPicker, setShowAgentPicker, setShowSkillsPicker, setShowGitLinePicker, onCommand, saveToHistory, onSubmit, triggerUpdate, forceUpdate, } = options; if (!key.return) return false; helpers.flushPendingInput(); // Prevent submission if multi-char input (paste/IME) is still being processed if (refs.isProcessingInput.current) { return true; // Ignore Enter key while processing } // Check if we should insert newline instead of submitting // Condition: If text ends with '/' and there's non-whitespace content before it const fullText = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); // Check if cursor is right after a '/' character if (cursorPos > 0 && fullText[cursorPos - 1] === '/') { // Find the text before '/' (ignoring the '/' itself) const textBeforeSlash = fullText.slice(0, cursorPos - 1); // If there's any non-whitespace content before '/', insert newline // This prevents conflict with command panel trigger at line start if (textBeforeSlash.trim().length > 0) { buffer.insert('\n'); const text = buffer.getFullText(); const newCursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, newCursorPos); updateAgentPickerState(text, newCursorPos); updateRunningAgentsPickerState(text, newCursorPos); return true; } } // Reset history navigation on submit if (currentHistoryIndex !== -1) { resetHistoryNavigation(); } const message = buffer.getFullText().trim(); const markedMessage = buffer.hasTextPlaceholders() ? buffer.getFullTextWithPasteMarkers().trim() : message; if (message) { // Check if message is a command with arguments (e.g., /review [note]) if (message.startsWith('/')) { // Support namespaced slash commands like /folder:command const commandMatch = message.match(/^\/([^\s]+)(?:\s+(.+))?$/); if (commandMatch && commandMatch[1]) { const commandName = commandMatch[1]; const commandArgs = commandMatch[2]; // Special handling for picker-style commands. // These commands are UI interactions and should open the picker panel // instead of going through the generic command execution flow. if (commandName === 'todo-' && !commandArgs) { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowTodoPicker(true); triggerUpdate(); return true; } if (commandName === 'agent-' && !commandArgs) { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowAgentPicker(true); triggerUpdate(); return true; } if (commandName === 'skills-' && !commandArgs) { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowSkillsPicker(true); triggerUpdate(); return true; } if (commandName === 'gitline' && !commandArgs) { buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); setShowGitLinePicker(true); triggerUpdate(); return true; } // Block command execution if AI is processing if (isProcessing && getAllCommands) { const matchedCommand = getAllCommands().find( cmd => cmd.name === commandName, ); if (matchedCommand && matchedCommand.type !== 'prompt') { // Keep non-prompt commands blocked while AI is already processing. buffer.setText(''); triggerUpdate(); return true; } } // Execute command with arguments executeCommand(commandName, commandArgs).then(result => { // If command is unknown, send the original message as a normal message if (result.action === 'sendAsMessage') { // Get images data for the message const currentText = buffer.text; const allImages = buffer.getImages(); const validImages = allImages .filter(img => currentText.includes(img.placeholder)) .map(img => ({ data: img.data, mimeType: img.mimeType, })); // Save to persistent history saveToHistory(message); // Send as normal message (use marked version to preserve paste boundaries) onSubmit( markedMessage, validImages.length > 0 ? validImages : undefined, ); return; } // Record command usage for frequency-based sorting commandUsageManager.recordUsage(commandName); if (onCommand) { // Ensure onCommand errors are caught Promise.resolve(onCommand(commandName, result)).catch(error => { console.error('Command execution error:', error); }); } }); buffer.setText(''); setShowCommands(false); setCommandSelectedIndex(0); triggerUpdate(); return true; } } // Get images data, but only include images whose placeholders still exist const currentText = buffer.text; // Use internal text (includes placeholders) const allImages = buffer.getImages(); const validImages = allImages .filter(img => currentText.includes(img.placeholder)) .map(img => ({ data: img.data, mimeType: img.mimeType, })); buffer.setText(''); forceUpdate({}); // Save to persistent history saveToHistory(message); onSubmit( markedMessage, validImages.length > 0 ? validImages : undefined, ); } return true; } ================================================ FILE: source/hooks/input/keyboard/handlers/tabArgsPicker.ts ================================================ import {COMMAND_ARGS_OPTIONS} from '../../../ui/useCommandPanel.js'; import type {HandlerContext} from '../types.js'; export function tabArgsPickerHandler(ctx: HandlerContext): boolean { const {key, buffer, options} = ctx; const { showCommands, showFilePicker, showArgsPicker, setShowArgsPicker, setArgsSelectedIndex, } = options; // Tab to open command args picker when hints are visible if (key.tab && !showCommands && !showFilePicker && !showArgsPicker) { const text = buffer.text; const cmdMatch = text.match(/^\/([a-zA-Z0-9_-]+)\s*$/); if (cmdMatch) { const cmdName = cmdMatch[1] ?? ''; const cmdOpts = COMMAND_ARGS_OPTIONS[cmdName]; if (cmdOpts && cmdOpts.length > 0) { setShowArgsPicker(true); setArgsSelectedIndex(0); return true; } } } return false; } ================================================ FILE: source/hooks/input/keyboard/types.ts ================================================ import type {Key} from 'ink'; import type React from 'react'; import {TextBuffer} from '../../../utils/ui/textBuffer.js'; import type {SubAgent} from '../../../utils/config/subAgentConfig.js'; export type KeyboardInputOptions = { buffer: TextBuffer; disabled: boolean; disableKeyboardNavigation?: boolean; isProcessing?: boolean; // Prevent command execution during AI response/tool execution triggerUpdate: () => void; forceUpdate: React.Dispatch>; // Mode state yoloMode: boolean; setYoloMode: (value: boolean) => void; planMode: boolean; setPlanMode: (value: boolean) => void; vulnerabilityHuntingMode: boolean; setVulnerabilityHuntingMode: (value: boolean) => void; teamMode: boolean; setTeamMode: (value: boolean) => void; // Command panel showCommands: boolean; setShowCommands: (show: boolean) => void; commandSelectedIndex: number; setCommandSelectedIndex: (index: number | ((prev: number) => number)) => void; getFilteredCommands: () => Array<{ name: string; description: string; type: 'builtin' | 'execute' | 'prompt'; }>; updateCommandPanelState: (text: string) => void; onCommand?: (commandName: string, result: any) => void; getAllCommands?: () => Array<{ name: string; description: string; type: 'builtin' | 'execute' | 'prompt'; }>; // Get all available commands for validation showFilePicker: boolean; setShowFilePicker: (show: boolean) => void; fileSelectedIndex: number; setFileSelectedIndex: (index: number | ((prev: number) => number)) => void; fileQuery: string; setFileQuery: (query: string) => void; atSymbolPosition: number; setAtSymbolPosition: (pos: number) => void; filteredFileCount: number; updateFilePickerState: (text: string, cursorPos: number) => void; handleFileSelect: (filePath: string) => Promise; fileListRef: React.RefObject<{ getSelectedFile: () => string | null; toggleDisplayMode: () => boolean; triggerDeeperSearch: () => boolean; } | null>; showHistoryMenu: boolean; setShowHistoryMenu: (show: boolean) => void; historySelectedIndex: number; setHistorySelectedIndex: (index: number | ((prev: number) => number)) => void; escapeKeyCount: number; setEscapeKeyCount: (count: number | ((prev: number) => number)) => void; escapeKeyTimer: React.MutableRefObject; getUserMessages: () => Array<{ label: string; value: string; infoText: string; }>; handleHistorySelect: (value: string) => void; // Terminal-style history navigation currentHistoryIndex: number; navigateHistoryUp: () => boolean; navigateHistoryDown: () => boolean; resetHistoryNavigation: () => void; saveToHistory: (content: string) => Promise; // Clipboard pasteFromClipboard: () => Promise; onCopyInputSuccess?: () => void; onCopyInputError?: (errorMessage: string) => void; // Paste detection pasteShortcutTimeoutMs?: number; pasteFlushDebounceMs?: number; pasteIndicatorThreshold?: number; // Submit onSubmit: ( message: string, images?: Array<{data: string; mimeType: string}>, ) => void; // Focus management ensureFocus: () => void; // Agent picker showAgentPicker: boolean; setShowAgentPicker: (show: boolean) => void; agentSelectedIndex: number; setAgentSelectedIndex: (index: number | ((prev: number) => number)) => void; updateAgentPickerState: (text: string, cursorPos: number) => void; getFilteredAgents: () => SubAgent[]; handleAgentSelect: (agent: SubAgent) => void; // Todo picker showTodoPicker: boolean; setShowTodoPicker: (show: boolean) => void; todoSelectedIndex: number; setTodoSelectedIndex: (index: number | ((prev: number) => number)) => void; todos: Array<{id: string; file: string; line: number; content: string}>; selectedTodos: Set; toggleTodoSelection: () => void; confirmTodoSelection: () => void; todoSearchQuery: string; setTodoSearchQuery: (query: string) => void; // Skills picker showSkillsPicker: boolean; setShowSkillsPicker: (show: boolean) => void; skillsSelectedIndex: number; setSkillsSelectedIndex: (index: number | ((prev: number) => number)) => void; skills: Array<{ id: string; name: string; description: string; location: string; }>; skillsIsLoading: boolean; skillsSearchQuery: string; skillsAppendText: string; skillsFocus: 'search' | 'append'; toggleSkillsFocus: () => void; appendSkillsChar: (ch: string) => void; backspaceSkillsField: () => void; confirmSkillsSelection: () => void; closeSkillsPicker: () => void; // GitLine picker showGitLinePicker: boolean; setShowGitLinePicker: (show: boolean) => void; gitLineSelectedIndex: number; setGitLineSelectedIndex: (index: number | ((prev: number) => number)) => void; gitLineCommits: Array<{ sha: string; subject: string; authorName: string; dateIso: string; }>; selectedGitLineCommits: Set; gitLineIsLoading: boolean; gitLineSearchQuery: string; setGitLineSearchQuery: (query: string) => void; gitLineError?: string | null; toggleGitLineCommitSelection: () => void; confirmGitLineSelection: () => void; closeGitLinePicker: () => void; // Profile picker showProfilePicker: boolean; setShowProfilePicker: (show: boolean) => void; profileSelectedIndex: number; setProfileSelectedIndex: (index: number | ((prev: number) => number)) => void; getFilteredProfiles: () => Array<{ name: string; displayName: string; isActive: boolean; }>; handleProfileSelect: (profileName: string) => void; /** * 在 ProfilePanel 中按右方向键时调用：进入 ProfileEditPanel 编辑该 profile。 * 可选：未提供时按右方向键无效（向后兼容）。 */ handleProfileEdit?: (profileName: string) => void; profileSearchQuery: string; setProfileSearchQuery: (query: string) => void; // Profile switching onSwitchProfile?: () => void; // Running agents picker showRunningAgentsPicker: boolean; setShowRunningAgentsPicker: (show: boolean) => void; runningAgentsSelectedIndex: number; setRunningAgentsSelectedIndex: ( index: number | ((prev: number) => number), ) => void; runningAgents: Array<{ instanceId: string; agentId: string; agentName: string; prompt: string; startedAt: Date; }>; selectedRunningAgents: Set; toggleRunningAgentSelection: () => void; confirmRunningAgentsSelection: () => any[]; closeRunningAgentsPicker: () => void; updateRunningAgentsPickerState: (text: string, cursorPos: number) => void; // Command args picker showArgsPicker: boolean; setShowArgsPicker: (show: boolean) => void; argsSelectedIndex: number; setArgsSelectedIndex: (index: number | ((prev: number) => number)) => void; argsPickerContext: {commandName: string; options: string[]}; }; export type HandlerRefs = { inputBuffer: React.MutableRefObject; inputTimer: React.MutableRefObject; isPasting: React.MutableRefObject; inputStartCursorPos: React.MutableRefObject; isProcessingInput: React.MutableRefObject; inputSessionId: React.MutableRefObject; lastPasteShortcutAt: React.MutableRefObject; componentMountTime: React.MutableRefObject; deleteKeyPressed: React.MutableRefObject; }; export type HandlerHelpers = { forceStateUpdate: () => void; flushPendingInput: () => void; findWordBoundary: ( text: string, start: number, direction: 'forward' | 'backward', ) => number; }; export type HandlerContext = { input: string; key: Key; buffer: TextBuffer; options: KeyboardInputOptions; refs: HandlerRefs; helpers: HandlerHelpers; }; ================================================ FILE: source/hooks/input/keyboard/utils/wordBoundary.ts ================================================ // Helper function: find word boundaries (space and punctuation) export function findWordBoundary( text: string, start: number, direction: 'forward' | 'backward', ): number { if (direction === 'forward') { // Skip current whitespace/punctuation let pos = start; while (pos < text.length && /[\s\p{P}]/u.test(text[pos] || '')) { pos++; } // Find next whitespace/punctuation while (pos < text.length && !/[\s\p{P}]/u.test(text[pos] || '')) { pos++; } return pos; } else { // Skip current whitespace/punctuation let pos = start; while (pos > 0 && /[\s\p{P}]/u.test(text[pos - 1] || '')) { pos--; } // Find previous whitespace/punctuation while (pos > 0 && !/[\s\p{P}]/u.test(text[pos - 1] || '')) { pos--; } return pos; } } ================================================ FILE: source/hooks/input/useBashMode.ts ================================================ import {useState, useCallback} from 'react'; import {isSensitiveCommand} from '../../utils/execution/sensitiveCommandManager.js'; import {isSelfDestructiveCommand} from '../../mcp/utils/bash/security.utils.js'; export interface BashCommand { id: string; command: string; startIndex: number; endIndex: number; timeout?: number; // 超时时间（毫秒），默认30000 } export interface CommandExecutionResult { success: boolean; stdout: string; stderr: string; command: string; exitCode: number | null; signal: NodeJS.Signals | null; } export interface BashModeState { isExecuting: boolean; currentCommand: string | null; currentTimeout: number | null; // 当前命令的超时时间 output: string[]; // 实时输出行 executionResults: Map; } export function useBashMode() { const [state, setState] = useState({ isExecuting: false, currentCommand: null, currentTimeout: null, output: [], executionResults: new Map(), }); /** * 解析用户消息中的命令注入模式命令 * 格式：!`command` 或 !`command` * timeout 单位：毫秒，可选，默认30000 * 严格语法：感叹号和反引号必须全部存在 */ const parseBashCommands = useCallback((message: string): BashCommand[] => { const commands: BashCommand[] = []; // 匹配 !`...` 或 !`...` 格式（命令注入模式） const regex = /!`([^`]+)`(?:<(\d+)>)?/g; let match; while ((match = regex.exec(message)) !== null) { const command = match[1]?.trim(); const timeoutStr = match[2]; const timeout = timeoutStr ? parseInt(timeoutStr, 10) : 30000; if (command) { commands.push({ id: `cmd-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`, command, startIndex: match.index, endIndex: match.index + match[0].length, timeout, }); } } return commands; }, []); /** * 解析用户消息中的 Bash 模式命令 * 格式：!!`command` 或 !!`command` * timeout 单位：毫秒，可选，默认30000 * 严格语法：双感叹号和反引号必须全部存在 */ const parsePureBashCommands = useCallback( (message: string): BashCommand[] => { const commands: BashCommand[] = []; // 匹配 !!`...` 或 !!`...` 格式（纯 Bash 模式） const regex = /!!`([^`]+)`(?:<(\d+)>)?/g; let match; while ((match = regex.exec(message)) !== null) { const command = match[1]?.trim(); const timeoutStr = match[2]; const timeout = timeoutStr ? parseInt(timeoutStr, 10) : 30000; if (command) { commands.push({ id: `cmd-${Date.now()}-${Math.random() .toString(36) .substring(2, 9)}`, command, startIndex: match.index, endIndex: match.index + match[0].length, timeout, }); } } return commands; }, [], ); /** * 检查命令是否为敏感命令 */ const checkSensitiveCommand = useCallback((command: string) => { return isSensitiveCommand(command); }, []); /** * 执行单个命令 */ const executeCommand = useCallback( async ( command: string, timeout: number = 30000, ): Promise => { // Self-protection: block commands that would kill the CLI process const selfDestruct = isSelfDestructiveCommand(command); if (selfDestruct.isSelfDestructive) { setState(prev => ({...prev, isExecuting: false})); return { success: false, stdout: '', stderr: `[SELF-PROTECTION] ${selfDestruct.reason}\n${selfDestruct.suggestion}`, command, exitCode: 1, signal: null, }; } setState(prev => ({ ...prev, isExecuting: true, currentCommand: command, currentTimeout: timeout, output: [], })); return new Promise(resolve => { const {spawn} = require('child_process'); const isWindows = process.platform === 'win32'; // Windows 默认优先使用 PowerShell（pwsh/powershell），避免 cmd.exe 的 codepage 导致中文乱码。 // 如果 PowerShell 不可用，则回退到 cmd /c，并尽量切到 UTF-8 codepage。 const shellCandidates: Array<{ shell: string; args: string[]; decode: (buf: Buffer) => string; }> = isWindows ? [ { shell: 'pwsh', args: [ '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', [ // 通过环境变量传递命令，避免包含空格时参数绑定/转义导致被截断。 '$cmd = $env:SNOW_CLI_BASH_COMMAND', 'if ([string]::IsNullOrWhiteSpace($cmd)) { throw "Missing SNOW_CLI_BASH_COMMAND" }', 'try {', ' $utf8 = [System.Text.UTF8Encoding]::new()', ' [Console]::OutputEncoding = $utf8', ' $OutputEncoding = $utf8', '} catch {}', 'Invoke-Expression $cmd', ].join('\n'), ], decode: (buf: Buffer) => buf.toString('utf8'), }, { shell: 'powershell', args: [ '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', [ // 通过环境变量传递命令，避免包含空格时参数绑定/转义导致被截断。 '$cmd = $env:SNOW_CLI_BASH_COMMAND', 'if ([string]::IsNullOrWhiteSpace($cmd)) { throw "Missing SNOW_CLI_BASH_COMMAND" }', 'try {', ' $utf8 = [System.Text.UTF8Encoding]::new()', ' [Console]::OutputEncoding = $utf8', ' $OutputEncoding = $utf8', '} catch {}', 'Invoke-Expression $cmd', ].join('\n'), ], decode: (buf: Buffer) => buf.toString('utf8'), }, { shell: 'cmd', args: ['/d', '/s', '/c', `chcp 65001 >NUL & ${command}`], decode: (buf: Buffer) => { // cmd.exe 的默认输出通常是 CP936/GBK；这里尽力用 GB18030 解码，避免中文乱码。 try { const {TextDecoder} = require('util'); const decoder = new TextDecoder('gb18030'); return decoder.decode(buf); } catch { return buf.toString('utf8'); } }, }, ] : [ { shell: 'sh', args: ['-c', command], decode: (buf: Buffer) => buf.toString('utf8'), }, ]; const spawnWithFallback = (index: number) => { const selected = shellCandidates[index]; if (!selected) { resolve({ success: false, stdout: '', stderr: isWindows ? 'No available shell found (tried pwsh, powershell, cmd)' : 'No available shell found', command, exitCode: null, signal: null, }); return; } const child = spawn(selected.shell, selected.args, { cwd: process.cwd(), env: { ...process.env, SNOW_CLI_BASH_COMMAND: command, }, windowsHide: true, }); let stdout = ''; let stderr = ''; let settled = false; let timeoutTimer: NodeJS.Timeout | null = null; const safeCleanup = () => { if (timeoutTimer) { clearTimeout(timeoutTimer); timeoutTimer = null; } }; const safeResolve = (result: CommandExecutionResult) => { if (settled) return; settled = true; safeCleanup(); setState(prev => { const newResults = new Map(prev.executionResults); newResults.set(command, result); return { ...prev, isExecuting: false, currentCommand: null, currentTimeout: null, output: [], executionResults: newResults, }; }); resolve(result); }; const killProcessTree = () => { if (!child.pid || child.killed) return; try { if (process.platform === 'win32') { // /T: kill child processes; /F: force const {exec} = require('child_process'); exec(`taskkill /PID ${child.pid} /T /F 2>NUL`, { windowsHide: true, }); } else { child.kill('SIGTERM'); } } catch { // Ignore. } }; const triggerTimeout = () => { // 超时后：杀进程树 + 返回一个失败结果，避免 UI 一直卡在 isExecuting=true。 killProcessTree(); safeResolve({ success: false, stdout: stdout.trim(), stderr: `Command timed out after ${timeout}ms: ${command}`, command, exitCode: null, signal: 'SIGTERM', }); }; if (typeof timeout === 'number' && timeout > 0) { timeoutTimer = setTimeout(triggerTimeout, timeout); } // PERFORMANCE: Batch output lines to avoid excessive setState calls // When commands produce output extremely fast (e.g. recursive dir listing), // unbatched setState per data event can trigger "Maximum update depth exceeded". const outputBuffer: string[] = []; let outputFlushTimer: ReturnType | null = null; const OUTPUT_BATCH_SIZE = 15; // Flush every 15 lines const OUTPUT_FLUSH_DELAY = 80; // Or flush after 80ms of inactivity const flushOutputBuffer = () => { if (outputFlushTimer) { clearTimeout(outputFlushTimer); outputFlushTimer = null; } if (outputBuffer.length === 0) return; const linesToFlush = outputBuffer.splice(0, outputBuffer.length); setState(prev => ({ ...prev, output: [...prev.output, ...linesToFlush], })); }; const appendOutputLines = (lines: string[]) => { outputBuffer.push(...lines); if (outputBuffer.length >= OUTPUT_BATCH_SIZE) { flushOutputBuffer(); return; } if (outputFlushTimer) { clearTimeout(outputFlushTimer); } outputFlushTimer = setTimeout( flushOutputBuffer, OUTPUT_FLUSH_DELAY, ); }; child.stdout?.on('data', (data: Buffer) => { const text = selected.decode(data); stdout += text; // 实时更新输出到 UI（批处理） const lines = text .split('\n') .map((line: string) => line.replace(/\r$/, '')) .filter((line: string) => line.trim()); if (lines.length > 0) { appendOutputLines(lines); } }); child.stderr?.on('data', (data: Buffer) => { const text = selected.decode(data); stderr += text; // 实时更新输出到 UI（批处理） const lines = text .split('\n') .map((line: string) => line.replace(/\r$/, '')) .filter((line: string) => line.trim()); if (lines.length > 0) { appendOutputLines(lines); } }); child.on( 'close', (code: number | null, signal: NodeJS.Signals | null) => { // Flush any remaining buffered output before resolving flushOutputBuffer(); // 正常退出：返回真实 code/signal safeResolve({ success: code === 0, stdout: stdout.trim(), stderr: stderr.trim(), command, exitCode: code, signal, }); }, ); child.on('error', (error: any) => { if ( isWindows && error && (error.code === 'ENOENT' || String(error.message || '').includes('ENOENT')) ) { settled = true; safeCleanup(); spawnWithFallback(index + 1); return; } safeResolve({ success: false, stdout: '', stderr: error?.message || 'Command execution failed', command, exitCode: null, signal: null, }); }); }; spawnWithFallback(0); }); }, [], ); /** * 处理用户消息，解析并执行命令注入模式命令，返回替换后的消息 */ const processBashMessage = useCallback( async ( message: string, onSensitiveCommand?: (command: string) => Promise, ): Promise<{ processedMessage: string; hasCommands: boolean; hasRejectedCommands: boolean; // 是否有命令被用户拒绝 results: CommandExecutionResult[]; }> => { const commands = parseBashCommands(message); if (commands.length === 0) { return { processedMessage: message, hasCommands: false, hasRejectedCommands: false, results: [], }; } const results: CommandExecutionResult[] = []; let processedMessage = message; let offset = 0; // 跟踪替换导致的位置偏移 let hasRejectedCommands = false; // 按顺序执行所有命令 for (const cmd of commands) { // 检查敏感命令 const sensitiveCheck = checkSensitiveCommand(cmd.command); if (sensitiveCheck.isSensitive && onSensitiveCommand) { const shouldContinue = await onSensitiveCommand(cmd.command); if (!shouldContinue) { // 用户拒绝执行，标记并跳过 hasRejectedCommands = true; continue; } } // 执行命令 const result = await executeCommand(cmd.command, cmd.timeout || 30000); results.push(result); // 构建替换文本 // 成功时合并 stdout 和 stderr：许多工具（如 cargo、npm）把输出写到 stderr const successOutput = [result.stdout, result.stderr] .filter(Boolean) .join('\n'); const output = result.success ? successOutput || '(no output)' : (() => { const lines: string[] = []; lines.push('Command execution failed.'); if (typeof result.exitCode === 'number') { lines.push(`Exit code: ${result.exitCode}`); } else { lines.push('Exit code: (unknown)'); } if (result.signal) { lines.push(`Signal: ${result.signal}`); } lines.push(''); lines.push('STDOUT:'); lines.push(result.stdout || '(empty)'); lines.push(''); lines.push('STDERR:'); lines.push(result.stderr || '(empty)'); return lines.join('\n'); })(); const replacement = `\n--- Command: ${cmd.command} ---\n${output}\n--- End of output ---\n`; // 替换原始命令位置 const adjustedStart = cmd.startIndex + offset; const adjustedEnd = cmd.endIndex + offset; processedMessage = processedMessage.slice(0, adjustedStart) + replacement + processedMessage.slice(adjustedEnd); // 更新偏移量 offset += replacement.length - (cmd.endIndex - cmd.startIndex); } return { processedMessage, hasCommands: true, hasRejectedCommands, results, }; }, [parseBashCommands, checkSensitiveCommand, executeCommand], ); /** * 处理纯 Bash 模式消息，执行命令但不发送给 AI */ const processPureBashMessage = useCallback( async ( message: string, onSensitiveCommand?: (command: string) => Promise, ): Promise<{ shouldSendToAI: boolean; // 是否应该发送给 AI hasCommands: boolean; hasRejectedCommands: boolean; results: CommandExecutionResult[]; }> => { const commands = parsePureBashCommands(message); if (commands.length === 0) { return { shouldSendToAI: true, hasCommands: false, hasRejectedCommands: false, results: [], }; } const results: CommandExecutionResult[] = []; let hasRejectedCommands = false; // 按顺序执行所有命令 for (const cmd of commands) { // 检查敏感命令 const sensitiveCheck = checkSensitiveCommand(cmd.command); if (sensitiveCheck.isSensitive && onSensitiveCommand) { const shouldContinue = await onSensitiveCommand(cmd.command); if (!shouldContinue) { // 用户拒绝执行，标记并跳过 hasRejectedCommands = true; continue; } } // 执行命令 const result = await executeCommand(cmd.command, cmd.timeout || 30000); results.push(result); } return { shouldSendToAI: false, // 纯 Bash 模式不发送给 AI hasCommands: true, hasRejectedCommands, results, }; }, [parsePureBashCommands, checkSensitiveCommand, executeCommand], ); /** * 重置状态 */ const resetState = useCallback(() => { setState({ isExecuting: false, currentCommand: null, currentTimeout: null, output: [], executionResults: new Map(), }); }, []); return { state, parseBashCommands, parsePureBashCommands, checkSensitiveCommand, executeCommand, processBashMessage, processPureBashMessage, resetState, }; } ================================================ FILE: source/hooks/input/useClipboard.ts ================================================ import {useCallback} from 'react'; import {execSync} from 'child_process'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import {logger} from '../../utils/core/logger.js'; import {isWSL} from '../../mcp/utils/websearch/browser.utils.js'; export function useClipboard( buffer: TextBuffer, updateCommandPanelState: (text: string) => void, updateFilePickerState: (text: string, cursorPos: number) => void, triggerUpdate: () => void, ) { const pasteFromClipboard = useCallback(async () => { try { const isWslEnv = process.platform === 'linux' && isWSL(); const psCmd = isWslEnv ? 'powershell.exe' : 'powershell'; // Try to read image from clipboard if (process.platform === 'win32' || isWslEnv) { // Windows / WSL: Use PowerShell to read image from clipboard try { // Optimized PowerShell script with compression for large images const psScript = 'Add-Type -AssemblyName System.Windows.Forms; ' + 'Add-Type -AssemblyName System.Drawing; ' + '$clipboard = [System.Windows.Forms.Clipboard]::GetImage(); ' + 'if ($clipboard -ne $null) { ' + '$ms = New-Object System.IO.MemoryStream; ' + '$width = $clipboard.Width; ' + '$height = $clipboard.Height; ' + '$maxSize = 2048; ' + 'if ($width -gt $maxSize -or $height -gt $maxSize) { ' + '$ratio = [Math]::Min($maxSize / $width, $maxSize / $height); ' + '$newWidth = [int]($width * $ratio); ' + '$newHeight = [int]($height * $ratio); ' + '$resized = New-Object System.Drawing.Bitmap($newWidth, $newHeight); ' + '$graphics = [System.Drawing.Graphics]::FromImage($resized); ' + '$graphics.CompositingQuality = [System.Drawing.Drawing2D.CompositingQuality]::HighQuality; ' + '$graphics.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic; ' + '$graphics.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::HighQuality; ' + '$graphics.DrawImage($clipboard, 0, 0, $newWidth, $newHeight); ' + '$resized.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png); ' + '$graphics.Dispose(); ' + '$resized.Dispose(); ' + '} else { ' + '$clipboard.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png); ' + '}; ' + '$bytes = $ms.ToArray(); ' + '$ms.Close(); ' + '[Convert]::ToBase64String($bytes); ' + '}'; let base64Raw: string; if (isWslEnv) { // WSL: bash expands $var inside double-quotes, mangling the script. // Use -EncodedCommand (base64 UTF-16LE) to bypass all shell interpretation. const encoded = Buffer.from(psScript, 'utf16le').toString('base64'); base64Raw = execSync( `${psCmd} -NoProfile -EncodedCommand ${encoded}`, { encoding: 'utf-8', timeout: 10000, maxBuffer: 50 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'], }, ); } else { base64Raw = execSync( `${psCmd} -NoProfile -Command "${psScript}"`, { encoding: 'utf-8', timeout: 10000, maxBuffer: 50 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'], }, ); } // 高效清理：一次性移除所有空白字符 const base64 = base64Raw.replace(/\s/g, ''); if (base64 && base64.length > 100) { // 直接传入 base64 数据，不需要 data URL 前缀 buffer.insertImage(base64, 'image/png'); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, cursorPos); triggerUpdate(); return; } } catch (imgError) { // No image in clipboard or error, fall through to text logger.error( 'Failed to read image from Windows clipboard:', imgError, ); } } else if (process.platform === 'darwin') { // macOS: Use osascript to read image from clipboard try { // First check if there's an image in clipboard const checkScript = `osascript -e 'try set imgData to the clipboard as «class PNGf» return "hasImage" on error return "noImage" end try'`; const hasImage = execSync(checkScript, { encoding: 'utf-8', timeout: 2000, }).trim(); if (hasImage === 'hasImage') { // Save clipboard image to temporary file and read it const tmpFile = `/tmp/snow_clipboard_${Date.now()}.png`; const saveScript = `osascript -e 'set imgData to the clipboard as «class PNGf»' -e 'set fileRef to open for access POSIX file "${tmpFile}" with write permission' -e 'write imgData to fileRef' -e 'close access fileRef'`; execSync(saveScript, { encoding: 'utf-8', timeout: 3000, }); // Use sips to resize if needed, then convert to base64 // First check image size const sizeCheck = execSync( `sips -g pixelWidth -g pixelHeight "${tmpFile}" | grep -E "pixelWidth|pixelHeight" | awk '{print $2}'`, { encoding: 'utf-8', timeout: 2000, }, ); const [widthStr, heightStr] = sizeCheck.trim().split('\n'); const width = parseInt(widthStr || '0', 10); const height = parseInt(heightStr || '0', 10); const maxSize = 2048; // Resize if too large if (width > maxSize || height > maxSize) { const ratio = Math.min(maxSize / width, maxSize / height); const newWidth = Math.floor(width * ratio); const newHeight = Math.floor(height * ratio); execSync( `sips -z ${newHeight} ${newWidth} "${tmpFile}" --out "${tmpFile}"`, { encoding: 'utf-8', timeout: 5000, }, ); } // Read the file as base64 with optimized buffer const base64Raw = execSync(`base64 -i "${tmpFile}"`, { encoding: 'utf-8', timeout: 5000, maxBuffer: 50 * 1024 * 1024, // 50MB buffer }); // 高效清理：一次性移除所有空白字符 const base64 = base64Raw.replace(/\s/g, ''); // Clean up temp file try { execSync(`rm "${tmpFile}"`, {timeout: 1000}); } catch (e) { // Ignore cleanup errors } if (base64 && base64.length > 100) { // 直接传入 base64 数据，不需要 data URL 前缀 buffer.insertImage(base64, 'image/png'); const text = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(text); updateFilePickerState(text, cursorPos); triggerUpdate(); return; } } } catch (imgError) { logger.error('Failed to read image from macOS clipboard:', imgError); } } // If no image, try to read text from clipboard try { let clipboardText = ''; if (process.platform === 'win32' || isWslEnv) { clipboardText = execSync( `${psCmd} -NoProfile -Command "Get-Clipboard"`, { encoding: 'utf-8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'], }, ).trim(); } else if (process.platform === 'darwin') { clipboardText = execSync('pbpaste', { encoding: 'utf-8', timeout: 2000, }).trim(); } else { clipboardText = execSync('xclip -selection clipboard -o', { encoding: 'utf-8', timeout: 2000, }).trim(); } if (clipboardText) { buffer.insert(clipboardText); const fullText = buffer.getFullText(); const cursorPos = buffer.getCursorPosition(); updateCommandPanelState(fullText); updateFilePickerState(fullText, cursorPos); triggerUpdate(); } } catch (textError) { logger.error('Failed to read text from clipboard:', textError); } } catch (error) { logger.error('Failed to read from clipboard:', error); } }, [buffer, updateCommandPanelState, updateFilePickerState, triggerUpdate]); return {pasteFromClipboard}; } ================================================ FILE: source/hooks/input/useHistoryNavigation.ts ================================================ import {useState, useCallback, useRef, useEffect} from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import {cleanIDEContext} from '../../utils/core/fileUtils.js'; import { historyManager, type HistoryEntry, } from '../../utils/session/historyManager.js'; type ChatMessage = { role: string; content: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; /** Present when a user message was directed to specific running sub-agents */ subAgentDirected?: unknown; }; export function useHistoryNavigation( buffer: TextBuffer, triggerUpdate: () => void, chatHistory: ChatMessage[], onHistorySelect?: ( selectedIndex: number, message: string, images?: Array<{type: 'image'; data: string; mimeType: string}>, ) => void, ) { const [showHistoryMenu, setShowHistoryMenu] = useState(false); const [historySelectedIndex, setHistorySelectedIndex] = useState(0); const [escapeKeyCount, setEscapeKeyCount] = useState(0); const escapeKeyTimer = useRef(null); // Terminal-style history navigation state const [currentHistoryIndex, setCurrentHistoryIndex] = useState(-1); // -1 means not in history mode const savedInput = useRef(''); // Save current input when entering history mode const [persistentHistory, setPersistentHistory] = useState( [], ); const persistentHistoryRef = useRef([]); // Keep ref in sync with state useEffect(() => { persistentHistoryRef.current = persistentHistory; }, [persistentHistory]); // Load persistent history on mount useEffect(() => { historyManager.getEntries().then(entries => { setPersistentHistory(entries); }); }, []); // Cleanup timer on unmount useEffect(() => { return () => { if (escapeKeyTimer.current) { clearTimeout(escapeKeyTimer.current); } }; }, []); // Get user messages from chat history for navigation (rollback panel). // Exclude messages directed to sub-agents — those belong to the sub-agent // flow, not the main conversation, and should not appear as rollback targets. const getUserMessages = useCallback(() => { const userMessages = chatHistory .map((msg, index) => ({...msg, originalIndex: index})) .filter( msg => msg.role === 'user' && msg.content.trim() && !msg.subAgentDirected, ); // Keep original order (oldest first, newest last) and map with display numbers return userMessages.map((msg, index) => { // Clean IDE context info first, then clean for display const cleanedContent = cleanIDEContext(msg.content); // Remove all newlines, control characters and extra whitespace to ensure single line display const cleanContent = cleanedContent .replace(/[\r\n\t\v\f\u0000-\u001F\u007F-\u009F]+/g, ' ') .replace(/\s+/g, ' ') .trim(); return { label: `${index + 1}. ${cleanContent.slice(0, 50)}${ cleanContent.length > 50 ? '...' : '' }`, value: msg.originalIndex.toString(), infoText: cleanedContent, // Use cleaned content for infoText as well }; }); }, [chatHistory]); const handleHistorySelect = useCallback( (value: string) => { const selectedIndex = parseInt(value, 10); const selectedMessage = chatHistory[selectedIndex]; if (selectedMessage && onHistorySelect) { // Don't modify buffer here - let ChatInput handle everything via initialContent // This prevents duplicate image placeholders setShowHistoryMenu(false); onHistorySelect( selectedIndex, cleanIDEContext(selectedMessage.content), // Clean IDE context before passing selectedMessage.images, ); } }, [chatHistory, onHistorySelect], ); // Terminal-style history navigation: navigate up (older) const navigateHistoryUp = useCallback(() => { const history = persistentHistoryRef.current; if (history.length === 0) return false; // Save current input when first entering history mode if (currentHistoryIndex === -1) { savedInput.current = buffer.getFullText(); } // Navigate to older message (persistentHistory is already newest first) const newIndex = currentHistoryIndex === -1 ? 0 : Math.min(history.length - 1, currentHistoryIndex + 1); setCurrentHistoryIndex(newIndex); const entry = history[newIndex]; if (entry) { buffer.setText(entry.content); // Move cursor to end so subsequent Down at end-of-text can keep navigating. buffer.setCursorPosition(buffer.getFullText().length); triggerUpdate(); } return true; }, [currentHistoryIndex]); // 移除 buffer 避免循环依赖 // Terminal-style history navigation: navigate down (newer) const navigateHistoryDown = useCallback(() => { if (currentHistoryIndex === -1) return false; const newIndex = currentHistoryIndex - 1; const history = persistentHistoryRef.current; if (newIndex < 0) { // Restore original input buffer.setText(savedInput.current); buffer.setCursorPosition(buffer.getFullText().length); setCurrentHistoryIndex(-1); savedInput.current = ''; } else { setCurrentHistoryIndex(newIndex); const entry = history[newIndex]; if (entry) { buffer.setText(entry.content); buffer.setCursorPosition(buffer.getFullText().length); } } triggerUpdate(); return true; }, [currentHistoryIndex]); // 移除 buffer 避免循环依赖 // Reset history navigation state const resetHistoryNavigation = useCallback(() => { setCurrentHistoryIndex(-1); savedInput.current = ''; }, []); // Save message to persistent history const saveToHistory = useCallback(async (content: string) => { await historyManager.addEntry(content); // Reload history to update the list const entries = await historyManager.getEntries(); setPersistentHistory(entries); }, []); return { showHistoryMenu, setShowHistoryMenu, historySelectedIndex, setHistorySelectedIndex, escapeKeyCount, setEscapeKeyCount, escapeKeyTimer, getUserMessages, handleHistorySelect, // Terminal-style history navigation currentHistoryIndex, navigateHistoryUp, navigateHistoryDown, resetHistoryNavigation, saveToHistory, }; } ================================================ FILE: source/hooks/input/useInputBuffer.ts ================================================ import {useReducer, useCallback, useEffect, useRef} from 'react'; import {TextBuffer, Viewport} from '../../utils/ui/textBuffer.js'; export function useInputBuffer(viewport: Viewport) { // Use useReducer for faster synchronous updates const [, forceRender] = useReducer((x: number) => x + 1, 0); const lastUpdateTime = useRef(0); const bufferRef = useRef(null); // Stable forceUpdate function using useRef const forceUpdateRef = useRef(() => { forceRender(); }); // Stable triggerUpdate function using useRef const triggerUpdateRef = useRef(() => { const now = Date.now(); lastUpdateTime.current = now; forceUpdateRef.current(); }); // Initialize buffer once if (!bufferRef.current) { bufferRef.current = new TextBuffer(viewport, triggerUpdateRef.current); } const buffer = bufferRef.current; // Expose stable callback functions const forceUpdate = useCallback(() => { forceUpdateRef.current(); }, []); const triggerUpdate = useCallback(() => { triggerUpdateRef.current(); }, []); // Update buffer viewport when viewport changes useEffect(() => { buffer.updateViewport(viewport); forceUpdateRef.current(); }, [viewport.width, viewport.height, buffer]); // Cleanup buffer on unmount useEffect(() => { return () => { buffer.destroy(); }; }, [buffer]); return { buffer, triggerUpdate, forceUpdate, }; } ================================================ FILE: source/hooks/input/useKeyboardInput.ts ================================================ import {useRef, useEffect} from 'react'; import {useInput, useStdin} from 'ink'; import type {HandlerContext, HandlerRefs, KeyboardInputOptions} from './keyboard/types.js'; import {createHelpers} from './keyboard/context.js'; import {focusFilterHandler} from './keyboard/handlers/focusFilter.js'; import {modeToggleHandler} from './keyboard/handlers/modeToggle.js'; import {profileShortcutHandler} from './keyboard/handlers/profileShortcut.js'; import {newlineHandler} from './keyboard/handlers/newline.js'; import {escapeHandler} from './keyboard/handlers/escape.js'; import {argsPickerHandler} from './keyboard/handlers/pickers/argsPicker.js'; import {skillsPickerHandler} from './keyboard/handlers/pickers/skillsPicker.js'; import {gitLinePickerHandler} from './keyboard/handlers/pickers/gitLinePicker.js'; import {profilePickerHandler} from './keyboard/handlers/pickers/profilePicker.js'; import {runningAgentsPickerHandler} from './keyboard/handlers/pickers/runningAgentsPicker.js'; import {todoPickerHandler} from './keyboard/handlers/pickers/todoPicker.js'; import {agentPickerHandler} from './keyboard/handlers/pickers/agentPicker.js'; import {historyMenuHandler} from './keyboard/handlers/pickers/historyMenu.js'; import {editingHandler} from './keyboard/handlers/editing.js'; import {clipboardHandler} from './keyboard/handlers/clipboard.js'; import {deleteAndBackspaceHandler} from './keyboard/handlers/deleteAndBackspace.js'; import {filePickerHandler} from './keyboard/handlers/pickers/filePicker.js'; import {commandPanelHandler} from './keyboard/handlers/pickers/commandPanel.js'; import {tabArgsPickerHandler} from './keyboard/handlers/tabArgsPicker.js'; import {submitHandler} from './keyboard/handlers/submit.js'; import {arrowKeysHandler} from './keyboard/handlers/arrowKeys.js'; import {regularInputHandler} from './keyboard/handlers/regularInput.js'; export type {KeyboardInputOptions} from './keyboard/types.js'; export function useKeyboardInput(options: KeyboardInputOptions) { const {disabled} = options; // Track paste detection const inputBuffer = useRef(''); const inputTimer = useRef(null); const isPasting = useRef(false); // Track if we're in pasting mode const inputStartCursorPos = useRef(0); // Track cursor position when input starts accumulating const isProcessingInput = useRef(false); // Track if multi-char input is being processed const inputSessionId = useRef(0); // Invalidates stale buffered input timers const lastPasteShortcutAt = useRef(0); // Track recent paste shortcut usage const componentMountTime = useRef(Date.now()); // Track when component mounted // Cleanup timer on unmount useEffect(() => { return () => { if (inputTimer.current) { clearTimeout(inputTimer.current); } }; }, []); // Track if Delete key was pressed (detected via Ink's internal event emitter) const deleteKeyPressed = useRef(false); // Access Ink's internal event emitter to detect Delete key (escape sequence \x1b[3~) // ink's useInput doesn't distinguish between Backspace and Delete. // We must NOT use process.stdin.on('data', ...) directly, as adding a 'data' listener // switches stdin to flowing mode, conflicting with Ink's readable-event-based handling. const stdinContext = useStdin() as { internal_eventEmitter?: import('events').EventEmitter; }; const {internal_eventEmitter: inkEventEmitter} = stdinContext; useEffect(() => { if (!inkEventEmitter) return; const handleRawInput = (data: string) => { if (data === '\x1b[3~') { deleteKeyPressed.current = true; } }; inkEventEmitter.on('input', handleRawInput); return () => { inkEventEmitter.removeListener('input', handleRawInput); }; }, [inkEventEmitter]); const refs: HandlerRefs = { inputBuffer, inputTimer, isPasting, inputStartCursorPos, isProcessingInput, inputSessionId, lastPasteShortcutAt, componentMountTime, deleteKeyPressed, }; // Handle input using useInput hook useInput((input, key) => { if (disabled) return; const helpers = createHelpers(options.buffer, options, refs); const ctx: HandlerContext = { input, key, buffer: options.buffer, options, refs, helpers, }; // Order matches the original file 100% — do not reorder. if (focusFilterHandler(ctx)) return; if (modeToggleHandler(ctx)) return; if (profileShortcutHandler(ctx)) return; if (newlineHandler(ctx)) return; if (escapeHandler(ctx)) return; if (argsPickerHandler(ctx)) return; if (skillsPickerHandler(ctx)) return; if (gitLinePickerHandler(ctx)) return; if (profilePickerHandler(ctx)) return; if (runningAgentsPickerHandler(ctx)) return; if (todoPickerHandler(ctx)) return; if (agentPickerHandler(ctx)) return; if (historyMenuHandler(ctx)) return; if (editingHandler(ctx)) return; if (clipboardHandler(ctx)) return; if (deleteAndBackspaceHandler(ctx)) return; if (filePickerHandler(ctx)) return; if (commandPanelHandler(ctx)) return; if (tabArgsPickerHandler(ctx)) return; if (submitHandler(ctx)) return; if (arrowKeysHandler(ctx)) return; if (regularInputHandler(ctx)) return; }); } ================================================ FILE: source/hooks/integration/useGlobalExit.ts ================================================ import {useInput} from 'ink'; import {useState} from 'react'; import {useI18n} from '../../i18n/index.js'; import {navigateTo} from './useGlobalNavigation.js'; export interface ExitNotification { show: boolean; message: string; } export function useGlobalExit( onNotification?: (notification: ExitNotification) => void, ) { const {t} = useI18n(); const [lastCtrlCTime, setLastCtrlCTime] = useState(0); const ctrlCTimeout = 1000; // 1 second timeout for double Ctrl+C useInput((input, key) => { if (key.ctrl && input === 'c') { const now = Date.now(); if (now - lastCtrlCTime < ctrlCTimeout) { navigateTo('exit'); } else { // First Ctrl+C - show notification setLastCtrlCTime(now); if (onNotification) { onNotification({ show: true, message: t.hooks.pressCtrlCAgain, }); // Hide notification after timeout setTimeout(() => { onNotification({ show: false, message: '', }); }, ctrlCTimeout); } } } }); } ================================================ FILE: source/hooks/integration/useGlobalNavigation.ts ================================================ import {EventEmitter} from 'events'; // Global navigation event emitter const navigationEmitter = new EventEmitter(); // Increase max listeners to prevent warnings, but not unlimited to catch real leaks navigationEmitter.setMaxListeners(20); export const NAVIGATION_EVENT = 'navigate'; export interface NavigationEvent { destination: | 'welcome' | 'chat' | 'help' | 'settings' | 'systemprompt' | 'customheaders' | 'tasks' | 'pixel' | 'exit'; } // Emit navigation event export function navigateTo(destination: NavigationEvent['destination']) { navigationEmitter.emit(NAVIGATION_EVENT, {destination}); } // Subscribe to navigation events export function onNavigate(handler: (event: NavigationEvent) => void) { navigationEmitter.on(NAVIGATION_EVENT, handler); return () => { navigationEmitter.off(NAVIGATION_EVENT, handler); }; } ================================================ FILE: source/hooks/integration/useVSCodeState.ts ================================================ import {useState, useEffect, useRef} from 'react'; import { vscodeConnection, type EditorContext, } from '../../utils/ui/vscodeConnection.js'; export type VSCodeConnectionStatus = | 'disconnected' | 'connecting' | 'connected' | 'error'; export function useVSCodeState() { const [vscodeConnected, setVscodeConnected] = useState(false); const [vscodeConnectionStatus, setVscodeConnectionStatus] = useState('disconnected'); const [editorContext, setEditorContext] = useState({}); // Use ref to track last status without causing re-renders const lastStatusRef = useRef('disconnected'); // Use ref to track last editor context to avoid unnecessary updates const lastEditorContextRef = useRef({}); // Monitor VSCode connection status and editor context useEffect(() => { const checkConnectionInterval = setInterval(() => { const isConnected = vscodeConnection.isConnected(); setVscodeConnected(isConnected); // Update connection status based on actual connection state // Use ref to avoid reading from state if (isConnected && lastStatusRef.current !== 'connected') { lastStatusRef.current = 'connected'; setVscodeConnectionStatus('connected'); } else if (!isConnected && lastStatusRef.current === 'connected') { lastStatusRef.current = 'disconnected'; setVscodeConnectionStatus('disconnected'); } }, 1000); // Check every second const unsubscribe = vscodeConnection.onContextUpdate(context => { // Only update state if context has actually changed const hasChanged = context.activeFile !== lastEditorContextRef.current.activeFile || context.selectedText !== lastEditorContextRef.current.selectedText || context.cursorPosition?.line !== lastEditorContextRef.current.cursorPosition?.line || context.cursorPosition?.character !== lastEditorContextRef.current.cursorPosition?.character || context.workspaceFolder !== lastEditorContextRef.current.workspaceFolder; if (hasChanged) { lastEditorContextRef.current = context; setEditorContext(context); } // When we receive context, it means connection is successful if (lastStatusRef.current !== 'connected') { lastStatusRef.current = 'connected'; setVscodeConnectionStatus('connected'); } }); return () => { clearInterval(checkConnectionInterval); unsubscribe(); }; }, []); // Remove vscodeConnectionStatus from dependencies // Separate effect for handling connecting timeout useEffect(() => { if (vscodeConnectionStatus !== 'connecting') { return; } // Set timeout for connecting state (15 seconds to allow for port scanning and connection) const connectingTimeout = setTimeout(() => { const isConnected = vscodeConnection.isConnected(); const isClientRunning = vscodeConnection.isClientRunning(); // Only set error if still not connected after timeout if (!isConnected) { if (isClientRunning) { // Client is running but no connection - show error with helpful message setVscodeConnectionStatus('error'); } else { // Client not running - go back to disconnected setVscodeConnectionStatus('disconnected'); } lastStatusRef.current = isClientRunning ? 'error' : 'disconnected'; } }, 15000); // 15 seconds: 10s for connection timeout + 5s buffer return () => { clearTimeout(connectingTimeout); }; }, [vscodeConnectionStatus]); return { vscodeConnected, vscodeConnectionStatus, setVscodeConnectionStatus, editorContext, }; } ================================================ FILE: source/hooks/picker/useAgentPicker.ts ================================================ import {useState, useCallback, useEffect} from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import { getSubAgents, type SubAgent, } from '../../utils/config/subAgentConfig.js'; export function useAgentPicker(buffer: TextBuffer, triggerUpdate: () => void) { const [showAgentPicker, setShowAgentPicker] = useState(false); const [agentSelectedIndex, setAgentSelectedIndex] = useState(0); const [agents, setAgents] = useState([]); const [agentQuery, setAgentQuery] = useState(''); const [hashSymbolPosition, setHashSymbolPosition] = useState(-1); // Load agents when picker is shown useEffect(() => { if (showAgentPicker) { const loadedAgents = getSubAgents(); setAgents(loadedAgents); setAgentSelectedIndex(0); } }, [showAgentPicker]); // Update agent picker state based on # symbol const updateAgentPickerState = useCallback( (_text: string, cursorPos: number) => { // Use display text (with placeholders) instead of full text (expanded) const displayText = buffer.text; // Find the last '#' symbol before the cursor const beforeCursor = displayText.slice(0, cursorPos); let position = -1; let query = ''; // Search backwards from cursor to find # for (let i = beforeCursor.length - 1; i >= 0; i--) { if (beforeCursor[i] === '#') { // Check if # is preceded by @ or @@ (file picker should handle it) if (i > 0 && beforeCursor[i - 1] === '@') { // # is part of @# or @@#, don't activate agent picker position = -1; break; } // Check if # is part of a placeholder like [Paste N lines #M] or [image #M] const textBeforeHash = displayText.slice(0, i); if (/\[(?:Paste \d+ lines |image )$/.test(textBeforeHash)) { position = -1; break; } position = i; const afterHash = beforeCursor.slice(i + 1); // Only activate if no space/newline after # if (!afterHash.includes(' ') && !afterHash.includes('\n')) { query = afterHash; break; } else { // Has space after #, not valid position = -1; break; } } } if (position !== -1) { // Found valid # context if ( !showAgentPicker || agentQuery !== query || hashSymbolPosition !== position ) { setShowAgentPicker(true); setAgentQuery(query); setHashSymbolPosition(position); setAgentSelectedIndex(0); } } else { // Hide agent picker if no valid # context found and it was triggered by # if (showAgentPicker && hashSymbolPosition !== -1) { setShowAgentPicker(false); setHashSymbolPosition(-1); setAgentQuery(''); } } }, [buffer, showAgentPicker, agentQuery, hashSymbolPosition], ); // Get filtered agents based on query const getFilteredAgents = useCallback(() => { if (!agentQuery) { return agents; } const query = agentQuery.toLowerCase(); return agents.filter( agent => agent.id.toLowerCase().includes(query) || agent.name.toLowerCase().includes(query) || agent.description.toLowerCase().includes(query), ); }, [agents, agentQuery]); // Handle agent selection const handleAgentSelect = useCallback( (agent: SubAgent) => { if (hashSymbolPosition !== -1) { // Triggered by # symbol - replace inline const displayText = buffer.text; const cursorPos = buffer.getCursorPosition(); // Replace query with selected agent ID const beforeHash = displayText.slice(0, hashSymbolPosition); const afterCursor = displayText.slice(cursorPos); // Construct the replacement: #agent_id const newText = beforeHash + '#' + agent.id + ' ' + afterCursor; // Set the new text and position cursor after the inserted agent ID + space buffer.setText(newText); // Calculate cursor position after the inserted text // # length (1) + agent ID length + space (1) const insertedLength = 1 + agent.id.length + 1; const targetPos = hashSymbolPosition + insertedLength; // Reset cursor to beginning, then move to correct position for (let i = 0; i < targetPos; i++) { if (i < buffer.text.length) { buffer.moveRight(); } } setHashSymbolPosition(-1); setAgentQuery(''); } else { // Triggered by command - clear buffer and insert buffer.setText(''); buffer.insert(`#${agent.id} `); } setShowAgentPicker(false); setAgentSelectedIndex(0); triggerUpdate(); }, [hashSymbolPosition, buffer, triggerUpdate], ); return { showAgentPicker, setShowAgentPicker, agentSelectedIndex, setAgentSelectedIndex, agents, agentQuery, hashSymbolPosition, updateAgentPickerState, getFilteredAgents, handleAgentSelect, }; } ================================================ FILE: source/hooks/picker/useFilePicker.ts ================================================ import {useReducer, useCallback, useRef} from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import {FileListRef} from '../../ui/components/tools/FileList.js'; type FilePickerState = { showFilePicker: boolean; fileSelectedIndex: number; fileQuery: string; atSymbolPosition: number; filteredFileCount: number; searchMode: 'file' | 'content'; // 'file' for @ search, 'content' for @@ search }; type FilePickerAction = | { type: 'SHOW'; query: string; position: number; searchMode: 'file' | 'content'; } | {type: 'HIDE'} | {type: 'SELECT_FILE'} | {type: 'SET_SELECTED_INDEX'; index: number} | {type: 'SET_FILTERED_COUNT'; count: number}; function filePickerReducer( state: FilePickerState, action: FilePickerAction, ): FilePickerState { switch (action.type) { case 'SHOW': return { ...state, showFilePicker: true, fileSelectedIndex: 0, fileQuery: action.query, atSymbolPosition: action.position, searchMode: action.searchMode, }; case 'HIDE': return { ...state, showFilePicker: false, fileSelectedIndex: 0, fileQuery: '', atSymbolPosition: -1, }; case 'SELECT_FILE': return { ...state, showFilePicker: false, fileSelectedIndex: 0, fileQuery: '', atSymbolPosition: -1, }; case 'SET_SELECTED_INDEX': return { ...state, fileSelectedIndex: action.index, }; case 'SET_FILTERED_COUNT': return { ...state, filteredFileCount: action.count, }; default: return state; } } export function useFilePicker(buffer: TextBuffer, triggerUpdate: () => void) { const [state, dispatch] = useReducer(filePickerReducer, { showFilePicker: false, fileSelectedIndex: 0, fileQuery: '', atSymbolPosition: -1, filteredFileCount: 0, searchMode: 'file', }); const fileListRef = useRef(null); // Update file picker state const updateFilePickerState = useCallback( (_text: string, cursorPos: number) => { // Use display text (with placeholders) instead of full text (expanded) // to ensure cursor position matches text content // Note: _text parameter is ignored, we use buffer.text instead const displayText = buffer.text; if (!displayText.includes('@')) { if (state.showFilePicker) { dispatch({type: 'HIDE'}); } return; } // Find the last '@' or '@@' symbol before the cursor const beforeCursor = displayText.slice(0, cursorPos); // Look for @@ first (content search), then @ (file search) let searchMode: 'file' | 'content' = 'file'; let position = -1; let query = ''; // Search backwards from cursor to find @@ or @ for (let i = beforeCursor.length - 1; i >= 0; i--) { if (beforeCursor[i] === '@') { // Check if @ is preceded by # (agent picker should handle it) if (i > 0 && beforeCursor[i - 1] === '#') { // @ is part of #@, don't activate file picker position = -1; break; } // Check if this is part of @@ if (i > 0 && beforeCursor[i - 1] === '@') { // Found @@, use content search searchMode = 'content'; position = i - 1; // Position of first @ const afterDoubleAt = beforeCursor.slice(i + 1); // Only activate if no space/newline after @@ if (!afterDoubleAt.includes(' ') && !afterDoubleAt.includes('\n')) { query = afterDoubleAt; break; } else { // Has space after @@, not valid position = -1; break; } } else { // Found single @, check if next char is also @ if (i < beforeCursor.length - 1 && beforeCursor[i + 1] === '@') { // This @ is part of @@, continue searching continue; } // Single @, use file search searchMode = 'file'; position = i; const afterAt = beforeCursor.slice(i + 1); // Only activate if no space/newline after @ if (!afterAt.includes(' ') && !afterAt.includes('\n')) { query = afterAt; break; } else { // Has space after @, not valid position = -1; break; } } } } if (position !== -1) { // For both @ and @@, position points to where we should start replacement // For @@, position is the first @ // For @, position is the single @ if ( !state.showFilePicker || state.fileQuery !== query || state.atSymbolPosition !== position || state.searchMode !== searchMode ) { dispatch({ type: 'SHOW', query, position, searchMode, }); } } else { // Hide file picker if no valid @ context found if (state.showFilePicker) { dispatch({type: 'HIDE'}); } } }, [ buffer, state.showFilePicker, state.fileQuery, state.atSymbolPosition, state.searchMode, ], ); // Handle file selection const handleFileSelect = useCallback( async (filePath: string) => { if (state.atSymbolPosition !== -1) { // Use display text (with placeholders) for position calculations const displayText = buffer.text; const cursorPos = buffer.getCursorPosition(); // Replace query with selected file path // For content search (@@), the filePath already includes line number // For file search (@), directories can keep the picker open for deeper filtering const beforeAt = displayText.slice(0, state.atSymbolPosition); const afterCursor = displayText.slice(cursorPos); const prefix = state.searchMode === 'content' ? '@@' : '@'; const isDirectoryContinuation = state.searchMode === 'file' && filePath.endsWith('/'); const suffix = isDirectoryContinuation ? '' : ' '; const newText = beforeAt + prefix + filePath + suffix + afterCursor; // Set the new text and position cursor after the inserted file path buffer.setText(newText); // Calculate cursor position after the inserted text const insertedLength = prefix.length + filePath.length + suffix.length; const targetPos = state.atSymbolPosition + insertedLength; // Reset cursor to beginning, then move to correct position for (let i = 0; i < targetPos; i++) { if (i < buffer.text.length) { buffer.moveRight(); } } if (isDirectoryContinuation) { dispatch({ type: 'SHOW', query: filePath, position: state.atSymbolPosition, searchMode: state.searchMode, }); } else { dispatch({type: 'SELECT_FILE'}); } triggerUpdate(); } }, [state.atSymbolPosition, state.searchMode, buffer, triggerUpdate], ); // Handle filtered file count change const handleFilteredCountChange = useCallback((count: number) => { dispatch({type: 'SET_FILTERED_COUNT', count}); }, []); // Wrapper setters for backwards compatibility const setShowFilePicker = useCallback((show: boolean) => { if (show) { dispatch({ type: 'SHOW', query: '', position: -1, searchMode: 'file', }); } else { dispatch({type: 'HIDE'}); } }, []); const setFileSelectedIndex = useCallback( (index: number | ((prev: number) => number)) => { if (typeof index === 'function') { // For functional updates, we need to get current state first // This is a simplified version - in production you might want to use a ref dispatch({ type: 'SET_SELECTED_INDEX', index: index(state.fileSelectedIndex), }); } else { dispatch({type: 'SET_SELECTED_INDEX', index}); } }, [state.fileSelectedIndex], ); return { showFilePicker: state.showFilePicker, setShowFilePicker, fileSelectedIndex: state.fileSelectedIndex, setFileSelectedIndex, fileQuery: state.fileQuery, setFileQuery: (_query: string) => { // Not used, but kept for compatibility }, atSymbolPosition: state.atSymbolPosition, setAtSymbolPosition: (_pos: number) => { // Not used, but kept for compatibility }, filteredFileCount: state.filteredFileCount, searchMode: state.searchMode, updateFilePickerState, handleFileSelect, handleFilteredCountChange, fileListRef, }; } ================================================ FILE: source/hooks/picker/useGitLinePicker.ts ================================================ import {useCallback, useEffect, useMemo, useState} from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import {reviewAgent} from '../../agents/reviewAgent.js'; export type GitLineCommit = { sha: string; subject: string; authorName: string; dateIso: string; kind: 'commit' | 'staged'; fileCount?: number; }; const PAGE_SIZE = 30; const STAGED_ENTRY_SHA = 'staged'; function createStagedEntry(fileCount: number): GitLineCommit { return { sha: STAGED_ENTRY_SHA, subject: 'Staged changes', authorName: '', dateIso: '', kind: 'staged', fileCount, }; } function buildInjectedGitLineText( commit: GitLineCommit, gitRoot: string, ): string { const patch = commit.kind === 'staged' ? reviewAgent.getStagedDiff(gitRoot).trim() : reviewAgent.getCommitPatch(gitRoot, commit.sha).trim(); if (commit.kind === 'staged') { return [ '# GitLine: staged', 'Type: staged', commit.fileCount !== undefined ? `Files: ${commit.fileCount}` : undefined, '', '```git', patch, '```', '# GitLine End', '', ] .filter((line): line is string => line !== undefined) .join('\n'); } return [ `# GitLine: ${commit.sha}`, `Commit: ${commit.sha}`, `Author: ${commit.authorName}`, `Date: ${commit.dateIso}`, `Subject: ${commit.subject}`, '', '```git', patch, '```', '# GitLine End', '', ].join('\n'); } export function useGitLinePicker( buffer: TextBuffer, triggerUpdate: () => void, ) { const [showGitLinePicker, setShowGitLinePicker] = useState(false); const [gitLineSelectedIndex, setGitLineSelectedIndex] = useState(0); const [commits, setCommits] = useState([]); const [stagedEntry, setStagedEntry] = useState(null); const [selectedCommits, setSelectedCommits] = useState>( new Set(), ); const [isLoading, setIsLoading] = useState(false); const [isLoadingMore, setIsLoadingMore] = useState(false); const [hasMore, setHasMore] = useState(true); const [skip, setSkip] = useState(0); const [searchQuery, setSearchQuery] = useState(''); const [error, setError] = useState(null); const [gitRoot, setGitRoot] = useState(null); const allCommits = useMemo(() => { return stagedEntry ? [stagedEntry, ...commits] : commits; }, [commits, stagedEntry]); const filteredCommits = useMemo(() => { const query = searchQuery.trim().toLowerCase(); if (!query) { return allCommits; } return allCommits.filter(commit => { const searchableFields = [ commit.sha, commit.subject, commit.authorName, commit.dateIso, ]; if (commit.kind === 'staged') { searchableFields.push('staged', 'staged changes'); } return searchableFields.some(field => field.toLowerCase().includes(query), ); }); }, [allCommits, searchQuery]); const loadFirstPage = useCallback(async () => { setIsLoading(true); setIsLoadingMore(false); setError(null); try { const gitCheck = reviewAgent.checkGitRepository(); if (!gitCheck.isGitRepo || !gitCheck.gitRoot) { setGitRoot(null); setCommits([]); setStagedEntry(null); setHasMore(false); setSkip(0); setError(gitCheck.error || 'Not a git repository'); return; } const status = reviewAgent.getWorkingTreeStatus(gitCheck.gitRoot); const result = reviewAgent.listCommitsPaginated( gitCheck.gitRoot, 0, PAGE_SIZE, ); setGitRoot(gitCheck.gitRoot); setStagedEntry( status.hasStaged ? createStagedEntry(status.stagedFileCount) : null, ); setCommits( result.commits.map(commit => ({ ...commit, kind: 'commit', })), ); setHasMore(result.hasMore); setSkip(result.nextSkip); setError(null); } catch (loadError) { setGitRoot(null); setCommits([]); setStagedEntry(null); setHasMore(false); setSkip(0); setError( loadError instanceof Error ? loadError.message : 'Failed to load git commits', ); } finally { setIsLoading(false); } }, []); const loadMoreGitLineCommits = useCallback(async () => { if (!gitRoot || isLoading || isLoadingMore || !hasMore) { return; } setIsLoadingMore(true); try { const result = reviewAgent.listCommitsPaginated(gitRoot, skip, PAGE_SIZE); setCommits(prev => [ ...prev, ...result.commits.map(commit => ({ ...commit, kind: 'commit' as const, })), ]); setHasMore(result.hasMore); setSkip(result.nextSkip); setError(null); } catch (loadError) { setError( loadError instanceof Error ? loadError.message : 'Failed to load more git commits', ); } finally { setIsLoadingMore(false); } }, [gitRoot, hasMore, isLoading, isLoadingMore, skip]); useEffect(() => { if (!showGitLinePicker) { return; } setSearchQuery(''); setGitLineSelectedIndex(0); setSelectedCommits(new Set()); void loadFirstPage(); }, [showGitLinePicker, loadFirstPage]); useEffect(() => { if (!showGitLinePicker || isLoading || isLoadingMore || !hasMore) { return; } if (filteredCommits.length === 0) { return; } if (gitLineSelectedIndex < filteredCommits.length - 4) { return; } void loadMoreGitLineCommits(); }, [ filteredCommits.length, gitLineSelectedIndex, hasMore, isLoading, isLoadingMore, loadMoreGitLineCommits, showGitLinePicker, ]); const closeGitLinePicker = useCallback(() => { setShowGitLinePicker(false); setGitLineSelectedIndex(0); setSelectedCommits(new Set()); setSearchQuery(''); setError(null); setHasMore(true); setSkip(0); setIsLoadingMore(false); setStagedEntry(null); triggerUpdate(); }, [triggerUpdate]); const toggleCommitSelection = useCallback(() => { const current = filteredCommits[gitLineSelectedIndex]; if (!current) { return; } setSelectedCommits(prev => { const next = new Set(prev); if (next.has(current.sha)) { next.delete(current.sha); } else { next.add(current.sha); } return next; }); triggerUpdate(); }, [filteredCommits, gitLineSelectedIndex, triggerUpdate]); const confirmGitLineSelection = useCallback(() => { if (!gitRoot) { closeGitLinePicker(); return; } let effectiveSelection = selectedCommits; if (effectiveSelection.size === 0 && filteredCommits.length > 0) { const highlighted = filteredCommits[gitLineSelectedIndex]; if (highlighted) { effectiveSelection = new Set([highlighted.sha]); } } const commitsToInsert = allCommits.filter(commit => effectiveSelection.has(commit.sha), ); if (commitsToInsert.length === 0) { closeGitLinePicker(); return; } buffer.setText(''); for (const commit of commitsToInsert) { buffer.insertTextPlaceholder( buildInjectedGitLineText(commit, gitRoot), `[GitLine:${commit.sha.slice(0, 8)}] `, ); } setShowGitLinePicker(false); setGitLineSelectedIndex(0); setSelectedCommits(new Set()); setSearchQuery(''); setError(null); setHasMore(true); setSkip(0); setIsLoadingMore(false); setStagedEntry(null); triggerUpdate(); }, [ allCommits, buffer, closeGitLinePicker, filteredCommits, gitLineSelectedIndex, gitRoot, selectedCommits, triggerUpdate, ]); return { showGitLinePicker, setShowGitLinePicker, gitLineSelectedIndex, setGitLineSelectedIndex, gitLineCommits: filteredCommits, selectedGitLineCommits: selectedCommits, gitLineHasMore: hasMore, gitLineIsLoading: isLoading, gitLineIsLoadingMore: isLoadingMore, gitLineSearchQuery: searchQuery, setGitLineSearchQuery: setSearchQuery, gitLineError: error, toggleGitLineCommitSelection: toggleCommitSelection, confirmGitLineSelection, closeGitLinePicker, loadMoreGitLineCommits, }; } ================================================ FILE: source/hooks/picker/useProfilePicker.ts ================================================ import {useState, useCallback} from 'react'; import {getAllProfiles} from '../../utils/config/configManager.js'; import type {ConfigProfile} from '../../utils/config/configManager.js'; export function useProfilePicker() { const [selectedIndex, setSelectedIndex] = useState(0); // Get all available profiles const getProfiles = useCallback((): ConfigProfile[] => { return getAllProfiles(); }, []); // Get filtered profiles (for future search functionality) const getFilteredProfiles = useCallback((): ConfigProfile[] => { return getProfiles(); }, [getProfiles]); return { selectedIndex, setSelectedIndex, getProfiles, getFilteredProfiles, }; } ================================================ FILE: source/hooks/picker/useRunningAgentsPicker.ts ================================================ import {useState, useCallback, useEffect, useSyncExternalStore, useMemo} from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import {runningSubAgentTracker} from '../../utils/execution/runningSubAgentTracker.js'; import {teamTracker} from '../../utils/execution/teamTracker.js'; // Stable function references for useSyncExternalStore (must not change between renders) const subscribeToTracker = (onStoreChange: () => void) => runningSubAgentTracker.subscribe(onStoreChange); const getTrackerSnapshot = () => runningSubAgentTracker.getRunningAgents(); const subscribeToTeamTracker = (onStoreChange: () => void) => teamTracker.subscribe(onStoreChange); const getTeamTrackerSnapshot = () => teamTracker.getRunningTeammates(); /** * Unified entry in the running-agents picker. * Can represent either a sub-agent or a team teammate. */ export interface PickerAgent { instanceId: string; agentId: string; agentName: string; prompt: string; startedAt: Date; /** 'subagent' for normal sub-agents, 'teammate' for team mode teammates */ sourceType: 'subagent' | 'teammate'; } /** * Build a short visual tag for a selected running agent. * Uses "»" (U+00BB) instead of ">>" to avoid re-triggering the picker. * Includes a truncated prompt snippet to distinguish parallel agents of the same type. * * Example: [»Explore Agent: 调查项目架构和结构...] */ function buildVisualTag(agent: PickerAgent): string { const shortId = agent.instanceId.slice(-4); const promptSnippet = agent.prompt .replace(/[\r\n]+/g, ' ') .replace(/\s+/g, ' ') .trim(); const prefix = agent.sourceType === 'teammate' ? '»☆' : '»'; if (promptSnippet) { const maxPromptLen = 20; const truncated = promptSnippet.length > maxPromptLen ? promptSnippet.slice(0, maxPromptLen) + '…' : promptSnippet; return `[${prefix}${agent.agentName}#${shortId}: ${truncated}] `; } return `[${prefix}${agent.agentName}#${shortId}] `; } /** * Find a ">>" trigger that starts at the very beginning of the input (ignoring leading whitespace). * Only triggers when ">>" is at the start — typing ">>" in the middle of text does nothing. * Also skips ">>" inside [...] brackets (placeholder tags). * Returns the position of the first ">" in the ">>" pair, or -1 if not found. */ function findDoubleGreaterTrigger(beforeCursor: string): number { // >> must be at the very start of the display text (optionally preceded by whitespace only) // This prevents accidental triggers when typing >> in the middle of a sentence. const trimmedStart = beforeCursor.search(/\S/); if (trimmedStart === -1) { // All whitespace or empty — no trigger return -1; } // Check if the first non-whitespace characters are ">>" if ( beforeCursor[trimmedStart] === '>' && trimmedStart + 1 < beforeCursor.length && beforeCursor[trimmedStart + 1] === '>' ) { // Verify it's not inside brackets (e.g. from a placeholder tag) let bracketDepth = 0; for (let i = 0; i <= trimmedStart; i++) { if (beforeCursor[i] === '[') { bracketDepth++; } else if (beforeCursor[i] === ']') { bracketDepth = Math.max(0, bracketDepth - 1); } } if (bracketDepth === 0) { return trimmedStart; } } return -1; } /** * Hook to manage the running agents picker panel. * Triggered by ">>" in input, shows currently running sub-agents and team teammates * with multi-select support for directing messages to specific agents. */ export function useRunningAgentsPicker( buffer: TextBuffer, triggerUpdate: () => void, ) { const [showRunningAgentsPicker, setShowRunningAgentsPicker] = useState(false); const [runningAgentsSelectedIndex, setRunningAgentsSelectedIndex] = useState(0); const [selectedRunningAgents, setSelectedRunningAgents] = useState< Set >(new Set()); const [doubleGreaterPosition, setDoubleGreaterPosition] = useState(-1); const subAgents = useSyncExternalStore( subscribeToTracker, getTrackerSnapshot, ); const teammates = useSyncExternalStore( subscribeToTeamTracker, getTeamTrackerSnapshot, ); const runningAgents: PickerAgent[] = useMemo(() => { const agents: PickerAgent[] = subAgents.map(a => ({ ...a, sourceType: 'subagent' as const, })); for (const t of teammates) { agents.push({ instanceId: t.instanceId, agentId: `teammate-${t.memberId}`, agentName: t.memberName, prompt: t.prompt, startedAt: t.startedAt, sourceType: 'teammate' as const, }); } return agents; }, [subAgents, teammates]); // Reset selected index when agents list changes useEffect(() => { if (showRunningAgentsPicker) { // Clamp selected index to valid range if (runningAgentsSelectedIndex >= runningAgents.length) { setRunningAgentsSelectedIndex(Math.max(0, runningAgents.length - 1)); } // Reset selection if the selected agents are no longer running setSelectedRunningAgents(prev => { const runningIds = new Set(runningAgents.map(a => a.instanceId)); const filtered = new Set( Array.from(prev).filter(id => runningIds.has(id)), ); if (filtered.size !== prev.size) { return filtered; } return prev; }); } }, [runningAgents, showRunningAgentsPicker, runningAgentsSelectedIndex]); // Update running agents picker state based on >> pattern. // >> must appear at the very start of the input (leading whitespace OK) to trigger the panel. // When the user deletes >> (e.g. via backspace), the panel auto-closes. const updateRunningAgentsPickerState = useCallback( (_text: string, _cursorPos: number) => { const displayText = buffer.text; // Check the full display text for >> at the beginning const position = findDoubleGreaterTrigger(displayText); if (position !== -1) { // Found valid >> at start of input if ( !showRunningAgentsPicker || doubleGreaterPosition !== position ) { setShowRunningAgentsPicker(true); setDoubleGreaterPosition(position); setRunningAgentsSelectedIndex(0); setSelectedRunningAgents(new Set()); } } else { // No >> at start — hide picker if (showRunningAgentsPicker) { setShowRunningAgentsPicker(false); setDoubleGreaterPosition(-1); setSelectedRunningAgents(new Set()); } } }, [buffer, showRunningAgentsPicker, doubleGreaterPosition], ); // Toggle selection of current agent const toggleRunningAgentSelection = useCallback(() => { if ( runningAgents.length > 0 && runningAgentsSelectedIndex < runningAgents.length ) { const agent = runningAgents[runningAgentsSelectedIndex]; if (agent) { setSelectedRunningAgents(prev => { const newSet = new Set(prev); if (newSet.has(agent.instanceId)) { newSet.delete(agent.instanceId); } else { newSet.add(agent.instanceId); } return newSet; }); triggerUpdate(); } } }, [runningAgents, runningAgentsSelectedIndex, triggerUpdate]); // Confirm selection - remove >> from buffer, insert visual tags, return selected agents. // Each selected agent is inserted as a TextPlaceholder: // Visual: [»AgentName: promptSnippet] (shown in input box, no ">>" to avoid re-trigger) // Content: # SubAgentTarget:instanceId:agentName\n or # TeamTarget:instanceId:agentName\n // The pending message system can later parse these markers to route messages. // // If no agents have been explicitly toggled via Space, the currently highlighted // agent is auto-selected so the user can pick with a single Enter press. const confirmRunningAgentsSelection = useCallback((): PickerAgent[] => { let effectiveSelection = selectedRunningAgents; // Auto-select the highlighted item when nothing was explicitly toggled if ( effectiveSelection.size === 0 && runningAgents.length > 0 && runningAgentsSelectedIndex < runningAgents.length ) { const highlighted = runningAgents[runningAgentsSelectedIndex]; if (highlighted) { effectiveSelection = new Set([highlighted.instanceId]); } } const selected = runningAgents.filter(agent => effectiveSelection.has(agent.instanceId), ); if (doubleGreaterPosition !== -1) { const displayText = buffer.text; const beforeGt = displayText.slice(0, doubleGreaterPosition); const afterGt = displayText .slice(doubleGreaterPosition + 2) .trimStart(); buffer.setText(beforeGt + afterGt); if (selected.length > 0) { buffer.setCursorPosition(beforeGt.length); for (const agent of selected) { const markerPrefix = agent.sourceType === 'teammate' ? 'TeamTarget' : 'SubAgentTarget'; const markerContent = `# ${markerPrefix}:${agent.instanceId}:${agent.agentName}\n`; const visualTag = buildVisualTag(agent); buffer.insertTextPlaceholder(markerContent, visualTag); } } } // Reset state setShowRunningAgentsPicker(false); setRunningAgentsSelectedIndex(0); setSelectedRunningAgents(new Set()); setDoubleGreaterPosition(-1); triggerUpdate(); return selected; }, [ buffer, runningAgents, runningAgentsSelectedIndex, selectedRunningAgents, doubleGreaterPosition, triggerUpdate, ]); // Close the picker without confirming const closeRunningAgentsPicker = useCallback(() => { setShowRunningAgentsPicker(false); setRunningAgentsSelectedIndex(0); setSelectedRunningAgents(new Set()); setDoubleGreaterPosition(-1); }, []); return { showRunningAgentsPicker, setShowRunningAgentsPicker, runningAgentsSelectedIndex, setRunningAgentsSelectedIndex, runningAgents, selectedRunningAgents, toggleRunningAgentSelection, confirmRunningAgentsSelection, closeRunningAgentsPicker, updateRunningAgentsPickerState, }; } ================================================ FILE: source/hooks/picker/useSkillsPicker.ts ================================================ import {useCallback, useEffect, useMemo, useState} from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import type {Skill} from '../../mcp/skills.js'; export type SkillsPickerFocus = 'search' | 'append'; function buildInjectedSkillText(skill: Skill, appendText: string): string { const append = appendText.trim(); const skillBody = skill.content.trim(); // If the skill markdown provides an $ARGUMENTS placeholder, fill it in. // Otherwise keep the legacy behavior (append a separate [User Append] block). if (skillBody.includes('$ARGUMENTS')) { const replaced = skillBody.split('$ARGUMENTS').join(append); return `# Skill: ${skill.id}\n\n${replaced}`.trim(); } const appendBlock = append ? `\n\n[User Append]\n${append}\n` : ''; // Keep it plain text; the actual skill prompt is markdown. return `# Skill: ${skill.id}\n\n${skillBody}${appendBlock}`.trim(); } export function useSkillsPicker(buffer: TextBuffer, triggerUpdate: () => void) { const [showSkillsPicker, setShowSkillsPicker] = useState(false); const [skillsSelectedIndex, setSkillsSelectedIndex] = useState(0); const [allSkills, setAllSkills] = useState([]); const [isLoading, setIsLoading] = useState(false); const [searchQuery, setSearchQuery] = useState(''); const [appendText, setAppendText] = useState(''); const [focus, setFocus] = useState('search'); const [originalTextBeforeOpen, setOriginalTextBeforeOpen] = useState(''); const filteredSkills = useMemo(() => { const q = searchQuery.trim().toLowerCase(); if (!q) return allSkills; return allSkills.filter(skill => { return ( skill.id.toLowerCase().includes(q) || skill.name.toLowerCase().includes(q) || skill.description.toLowerCase().includes(q) ); }); }, [allSkills, searchQuery]); // Load skills when picker is shown. useEffect(() => { if (!showSkillsPicker) return; setIsLoading(true); setSearchQuery(''); setAppendText(''); setFocus('search'); setSkillsSelectedIndex(0); setOriginalTextBeforeOpen(buffer.getFullText()); // Let UI render loading state first. setTimeout(() => { import('../../mcp/skills.js') .then(async m => m.listAvailableSkills(process.cwd())) .then(list => { setAllSkills(list); setIsLoading(false); }) .catch(error => { console.error('Failed to load skills:', error); setAllSkills([]); setIsLoading(false); }); }, 0); }, [showSkillsPicker, buffer]); const closeSkillsPicker = useCallback(() => { setShowSkillsPicker(false); setSkillsSelectedIndex(0); setSearchQuery(''); setAppendText(''); setFocus('search'); triggerUpdate(); }, [triggerUpdate]); const toggleFocus = useCallback(() => { setFocus(prev => (prev === 'search' ? 'append' : 'search')); triggerUpdate(); }, [triggerUpdate]); const appendChar = useCallback( (ch: string) => { if (!ch) return; if (focus === 'search') { setSearchQuery(prev => prev + ch); setSkillsSelectedIndex(0); } else { setAppendText(prev => prev + ch); } triggerUpdate(); }, [focus, triggerUpdate], ); const backspace = useCallback(() => { if (focus === 'search') { setSearchQuery(prev => (prev.length > 0 ? prev.slice(0, -1) : prev)); setSkillsSelectedIndex(0); } else { setAppendText(prev => (prev.length > 0 ? prev.slice(0, -1) : prev)); } triggerUpdate(); }, [focus, triggerUpdate]); const confirmSelection = useCallback(async () => { if (isLoading) return; if (filteredSkills.length === 0) { closeSkillsPicker(); return; } const selected = filteredSkills[skillsSelectedIndex]; if (!selected) { closeSkillsPicker(); return; } const injected = buildInjectedSkillText(selected, appendText); // 结束标记：用于让 display-only mask 只折叠注入块本身。 // 注意：必须以换行结尾，否则用户在占位符后继续输入时会与 "# Skill End" 黏连， // 导致 mask 无法识别 end marker，从而把用户输入也一并折叠掉。 const injectedWithEndMarker = `${injected}\n# Skill End\n`; const original = originalTextBeforeOpen.trim(); buffer.setText(''); if (original) { buffer.insert(original); buffer.insert('\n\n'); } // 视觉层只显示占位符，但发送时通过 buffer.getFullText() 仍会还原完整注入块。 // 注意：末尾空格用于让用户继续输入时视觉上分隔开。 buffer.insertTextPlaceholder( injectedWithEndMarker, `[Skill:${selected.id}] `, ); setShowSkillsPicker(false); setSkillsSelectedIndex(0); setSearchQuery(''); setAppendText(''); setFocus('search'); triggerUpdate(); }, [ appendText, buffer, closeSkillsPicker, filteredSkills, isLoading, originalTextBeforeOpen, skillsSelectedIndex, triggerUpdate, ]); return { showSkillsPicker, setShowSkillsPicker, skillsSelectedIndex, setSkillsSelectedIndex, skills: filteredSkills, isLoading, searchQuery, appendText, focus, toggleFocus, appendChar, backspace, confirmSelection, closeSkillsPicker, }; } ================================================ FILE: source/hooks/picker/useTodoPicker.ts ================================================ import {useState, useCallback, useEffect, useMemo} from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import {scanProjectTodos, type TodoItem} from '../../utils/core/todoScanner.js'; export function useTodoPicker( buffer: TextBuffer, triggerUpdate: () => void, projectRoot: string, ) { const [showTodoPicker, setShowTodoPicker] = useState(false); const [todoSelectedIndex, setTodoSelectedIndex] = useState(0); const [allTodos, setAllTodos] = useState([]); const [selectedTodos, setSelectedTodos] = useState>(new Set()); const [isLoading, setIsLoading] = useState(false); const [searchQuery, setSearchQuery] = useState(''); // Filter todos based on search query const filteredTodos = useMemo(() => { if (!searchQuery.trim()) { return allTodos; } const query = searchQuery.toLowerCase(); return allTodos.filter( todo => todo.content.toLowerCase().includes(query) || todo.file.toLowerCase().includes(query), ); }, [allTodos, searchQuery]); // Load todos when picker is shown useEffect(() => { if (showTodoPicker) { setIsLoading(true); setSearchQuery(''); setTodoSelectedIndex(0); setSelectedTodos(new Set()); // Use setTimeout to allow UI to update with loading state setTimeout(() => { const foundTodos = scanProjectTodos(projectRoot); setAllTodos(foundTodos); setIsLoading(false); }, 0); } }, [showTodoPicker, projectRoot]); // Toggle selection of current todo const toggleTodoSelection = useCallback(() => { if (filteredTodos.length > 0 && todoSelectedIndex < filteredTodos.length) { const todo = filteredTodos[todoSelectedIndex]; if (todo) { setSelectedTodos(prev => { const newSet = new Set(prev); if (newSet.has(todo.id)) { newSet.delete(todo.id); } else { newSet.add(todo.id); } return newSet; }); triggerUpdate(); } } }, [filteredTodos, todoSelectedIndex, triggerUpdate]); // Confirm selection and insert into buffer const confirmTodoSelection = useCallback(() => { if (selectedTodos.size === 0) { // If no todos selected, just close the picker setShowTodoPicker(false); setTodoSelectedIndex(0); triggerUpdate(); return; } // Build the text to insert const selectedTodoItems = allTodos.filter(todo => selectedTodos.has(todo.id), ); const todoTexts = selectedTodoItems.map( todo => `<${todo.file}:${todo.line}> ${todo.content}`, ); // Clear buffer and insert selected todos const currentText = buffer.getFullText().trim(); buffer.setText(''); if (currentText) { buffer.insert(currentText + '\n' + todoTexts.join('\n')); } else { buffer.insert(todoTexts.join('\n')); } // Reset state setShowTodoPicker(false); setTodoSelectedIndex(0); setSelectedTodos(new Set()); triggerUpdate(); }, [buffer, allTodos, selectedTodos, triggerUpdate]); return { showTodoPicker, setShowTodoPicker, todoSelectedIndex, setTodoSelectedIndex, todos: filteredTodos, selectedTodos, toggleTodoSelection, confirmTodoSelection, isLoading, searchQuery, setSearchQuery, totalTodoCount: allTodos.length, }; } ================================================ FILE: source/hooks/session/useSessionManagement.ts ================================================ import {useState} from 'react'; import {sessionManager} from '../../utils/session/sessionManager.js'; import type {Message} from '../../ui/components/chat/MessageList.js'; import {convertSessionMessagesToUI} from '../../utils/session/sessionConverter.js'; /** * Hook for managing session list and session selection */ export function useSessionManagement( setMessages: React.Dispatch>, setPendingMessages: React.Dispatch>, setIsStreaming: React.Dispatch>, setRemountKey: React.Dispatch>, initializeFromSession: (messages: any[]) => void, ) { const [showSessionList, setShowSessionList] = useState(false); /** * Handle session selection from the session list */ const handleSessionSelect = async (sessionId: string) => { try { const session = await sessionManager.loadSession(sessionId); if (session) { // Convert API format messages to UI format const uiMessages = convertSessionMessagesToUI(session.messages); setMessages(uiMessages); setPendingMessages([]); setIsStreaming(false); setShowSessionList(false); setRemountKey(prev => prev + 1); // Initialize session save hook with loaded API messages initializeFromSession(session.messages); } } catch (error) { console.error('Failed to load session:', error); } }; /** * Handle back action from session list */ const handleBackFromSessionList = () => { setShowSessionList(false); }; return { showSessionList, setShowSessionList, handleSessionSelect, handleBackFromSessionList, }; } ================================================ FILE: source/hooks/session/useSessionSave.ts ================================================ import {useCallback, useRef} from 'react'; import { sessionManager, type ChatMessage as SessionChatMessage, } from '../../utils/session/sessionManager.js'; import type {ChatMessage as APIChatMessage} from '../../api/chat.js'; export function useSessionSave() { const savedMessagesRef = useRef>(new Set()); // Generate a unique ID for a message (based on role + content + timestamp window + tool identifiers) const generateMessageId = useCallback( (message: APIChatMessage, timestamp: number): string => { let id = `${message.role}-${message.content.length}-${Math.floor( timestamp / 5000, )}`; if ( message.role === 'assistant' && message.tool_calls && message.tool_calls.length > 0 ) { const toolCallIds = message.tool_calls .map(tc => tc.id) .sort() .join(','); id += `-tools:${toolCallIds}`; } if (message.role === 'assistant' && message.subAgentContent) { id += `-subagent-content:${message.subAgent?.agentId || 'unknown'}`; const thinking = message.thinking?.thinking; if (thinking) { id += `-thinking:${thinking.length}`; } } if (message.role === 'tool' && message.tool_call_id) { id += `-toolcall:${message.tool_call_id}`; } return id; }, [], ); // Save API message directly - 直接保存 API 格式的消息 const saveMessage = useCallback( async (message: APIChatMessage) => { const timestamp = Date.now(); const messageId = generateMessageId(message, timestamp); if (savedMessagesRef.current.has(messageId)) { return; // Already saved } const sessionMessage: SessionChatMessage = { ...message, // 直接展开 API 消息，包含所有字段 timestamp, }; try { await sessionManager.addMessage(sessionMessage); savedMessagesRef.current.add(messageId); } catch (error) { console.error('Failed to save message:', error); } }, [generateMessageId], ); // Save multiple API messages at once const saveMessages = useCallback( async (messages: APIChatMessage[]) => { for (const message of messages) { await saveMessage(message); } }, [saveMessage], ); // Clear saved messages tracking (for new sessions) const clearSavedMessages = useCallback(() => { savedMessagesRef.current.clear(); }, []); // Initialize from existing session - 从已有会话初始化 const initializeFromSession = useCallback( (messages: SessionChatMessage[]) => { savedMessagesRef.current.clear(); messages.forEach(message => { const messageId = generateMessageId(message, message.timestamp); savedMessagesRef.current.add(messageId); }); }, [generateMessageId], ); return { saveMessage, saveMessages, clearSavedMessages, initializeFromSession, }; } ================================================ FILE: source/hooks/session/useSnapshotState.ts ================================================ import {useState, useEffect} from 'react'; import {sessionManager} from '../../utils/session/sessionManager.js'; import {hashBasedSnapshotManager} from '../../utils/codebase/hashBasedSnapshot.js'; export function useSnapshotState(messagesLength: number) { const currentSessionId = sessionManager.getCurrentSession()?.id ?? null; const [snapshotFileCount, setSnapshotFileCount] = useState< Map >(new Map()); const [pendingRollback, setPendingRollback] = useState<{ messageIndex: number; fileCount: number; filePaths?: string[]; notebookCount?: number; teamCount?: number; message?: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; crossSessionRollback?: boolean; originalSessionId?: string; } | null>(null); // Reload when message count or current session changes, and ignore stale async results. useEffect(() => { let disposed = false; const loadSnapshotFileCounts = async () => { if (!currentSessionId) { if (!disposed) { setSnapshotFileCount(new Map()); } return; } const snapshots = await hashBasedSnapshotManager.listSnapshots( currentSessionId, ); if ( disposed || sessionManager.getCurrentSession()?.id !== currentSessionId ) { return; } const counts = new Map(); for (const snapshot of snapshots) { counts.set(snapshot.messageIndex, snapshot.fileCount); } setSnapshotFileCount(counts); }; void loadSnapshotFileCounts(); return () => { disposed = true; }; }, [messagesLength, currentSessionId]); return { snapshotFileCount, setSnapshotFileCount, pendingRollback, setPendingRollback, }; } ================================================ FILE: source/hooks/ui/useCommandPanel.ts ================================================ import { useState, useCallback, useMemo, useEffect, useSyncExternalStore, } from 'react'; import {TextBuffer} from '../../utils/ui/textBuffer.js'; import {useI18n} from '../../i18n/index.js'; import {getCustomCommands} from '../../utils/commands/custom.js'; import {commandUsageManager} from '../../utils/session/commandUsageManager.js'; import {runningSubAgentTracker} from '../../utils/execution/runningSubAgentTracker.js'; import {teamTracker} from '../../utils/execution/teamTracker.js'; const subscribeToSubAgentTracker = (cb: () => void) => runningSubAgentTracker.subscribe(cb); const getSubAgentSnapshot = () => runningSubAgentTracker.getRunningAgents(); const subscribeToTeamTracker = (cb: () => void) => teamTracker.subscribe(cb); const getTeamSnapshot = () => teamTracker.getRunningTeammates(); export type CommandPanelCommand = { name: string; description: string; type: 'builtin' | 'execute' | 'prompt'; mainFlowOnly?: boolean; }; // 指令参数提示：当用户输入 /cmd 后（尚未补充参数），在输入框末尾以暗色显示可用参数组合 // key 为指令名（不含斜杠），value 为提示文本（不含前导空格） export const COMMAND_ARGS_HINTS: Record = { branch: '[name]', fork: '[name]', resume: '[sessionId]', reindex: '[-force]', codebase: '[on|off|status]', 'auto-format': '[on|off|status]', simple: '[on|off|status]', 'add-dir': '[path]', loop: ' | list | tasks | cancel ', role: '[-l|--list | -d|--delete]', skills: '[-l|--list]', 'role-subagent': '[-l|--list | -d|--delete]', 'subagent-depth': '[|status]', btw: '', deepresearch: '', connect: '[apiUrl]', }; // 指令参数可选值列表：用于 Tab 弹出参数选择面板 // key 为指令名（不含斜杠），value 为可选参数值数组 export const COMMAND_ARGS_OPTIONS: Record = { codebase: ['on', 'off', 'status'], 'auto-format': ['on', 'off', 'status'], simple: ['on', 'off', 'status'], reindex: ['-force'], role: ['-l', '-d'], skills: ['-l'], 'role-subagent': ['-l', '-d'], 'subagent-depth': ['status'], loop: ['list', 'tasks', 'cancel'], }; export function useCommandPanel(buffer: TextBuffer, isProcessing = false) { const {t} = useI18n(); const subAgents = useSyncExternalStore( subscribeToSubAgentTracker, getSubAgentSnapshot, ); const teammates = useSyncExternalStore( subscribeToTeamTracker, getTeamSnapshot, ); const hasRunningAgentsOrTeam = subAgents.length > 0 || teammates.length > 0; // Built-in commands - only depends on translation const builtInCommands = useMemo( () => [ { name: 'branch', description: t.commandPanel.commands.branch || 'Fork current conversation into a new branch', }, {name: 'help', description: t.commandPanel.commands.help}, {name: 'clear', description: t.commandPanel.commands.clear}, { name: 'copy-last', description: t.commandPanel.commands.copyLast || 'Copy last AI message to clipboard', }, {name: 'resume', description: t.commandPanel.commands.resume}, {name: 'mcp', description: t.commandPanel.commands.mcp}, {name: 'yolo', description: t.commandPanel.commands.yolo}, { name: 'plan', description: t.commandPanel.commands.plan, }, { name: 'init', description: t.commandPanel.commands.init, }, {name: 'ide', description: t.commandPanel.commands.ide}, { name: 'compact', description: t.commandPanel.commands.compact, }, {name: 'home', description: t.commandPanel.commands.home}, { name: 'review', description: t.commandPanel.commands.review, }, { name: 'gitline', description: t.commandPanel.commands.gitline || 'Select git commits and insert them into the chat input', }, { name: 'role', description: t.commandPanel.commands.role, }, { name: 'role-subagent', description: t.commandPanel.commands.roleSubagent || 'Customize sub-agent prompts with ROLE-{name}.md files. Use -l to list, -d to delete', }, { name: 'usage', description: t.commandPanel.commands.usage, }, { name: 'backend', description: t.commandPanel.commands.backend || 'Show background processes', }, { name: 'profiles', description: t.commandPanel.commands.profiles, }, { name: 'models', description: t.commandPanel.commands.models || 'Open the model switching panel', }, { name: 'loop', description: t.commandPanel.commands.loop || 'Schedule a session-scoped recurring task. Usage: /loop 5m ', }, { name: 'subagent-depth', description: t.commandPanel.commands.subAgentDepth || 'Set the maximum nested spawn depth for sub-agents', }, { name: 'export', description: t.commandPanel.commands.export, }, { name: 'custom', description: t.commandPanel.commands.custom || 'Add custom command', }, { name: 'skills', description: t.commandPanel.commands.skills || 'Create skill template', }, { name: 'agent-', description: t.commandPanel.commands.agent, }, { name: 'todo-', description: t.commandPanel.commands.todo, }, { name: 'todolist', description: t.commandPanel.commands.todolist || 'Show current session TODO tree and manage items', }, { name: 'skills-', description: t.commandPanel.commands.skillsPicker || 'Select a skill and inject its content into the input', }, { name: 'add-dir', description: t.commandPanel.commands.addDir || 'Add working directory', }, { name: 'reindex', description: t.commandPanel.commands.reindex, }, { name: 'codebase', description: t.commandPanel.commands.codebase || 'Toggle codebase indexing for current project', }, { name: 'permissions', description: t.commandPanel.commands.permissions || 'Manage tool permissions', }, { name: 'vulnerability-hunting', description: t.commandPanel.commands.vulnerabilityHunting || 'Toggle vulnerability hunting mode', }, { name: 'auto-format', description: t.commandPanel.commands.autoFormat || 'Toggle MCP file auto-formatting. Usage: /auto-format [on|off|status]', }, { name: 'simple', description: t.commandPanel.commands.simple || 'Toggle theme simple mode. Usage: /simple [on|off|status]', }, { name: 'tool-search', description: t.commandPanel.commands.toolSearch || 'Toggle Tool Search (progressive tool loading)', }, { name: 'worktree', description: t.commandPanel.commands.worktree || 'Open Git branch management panel', }, { name: 'hybrid-compress', description: t.commandPanel.commands.hybridCompress || 'Toggle Hybrid Compress mode (AI summary + smart truncation)', }, { name: 'diff', description: t.commandPanel.commands.diff || 'Review file changes from a conversation in IDE diff view', }, { name: 'connect', description: t.commandPanel.commands.connect || 'Connect to a Snow Instance for AI processing', }, { name: 'disconnect', description: t.commandPanel.commands.disconnect || 'Disconnect from the current Snow Instance', }, { name: 'connection-status', description: t.commandPanel.commands.connectionStatus || 'Show current connection status', }, { name: 'new-prompt', description: t.commandPanel.commands.newPrompt || 'Generate a refined prompt from your requirement using AI', }, { name: 'team', description: t.commandPanel.commands.team || 'Toggle Agent Team mode - orchestrate multiple agents working together', }, { name: 'pixel', description: t.commandPanel.commands.pixel || 'Open the terminal pixel editor', mainFlowOnly: true, }, { name: 'quit', description: t.commandPanel.commands.quit, }, { name: 'btw', description: t.commandPanel.commands.btw || 'Ask a side-question while AI is working (temporary, no context saved)', allowDuringProcessing: true, mainFlowOnly: true, }, { name: 'deepresearch', description: t.commandPanel.commands.deepresearch || 'Run an autonomous web research workflow and save a cited markdown report to .snow/deepresearch/', }, ], [t], ); const normalizedBuiltInCommands = useMemo( () => builtInCommands.map(command => ({ name: command.name, description: command.description, type: (command as any).allowDuringProcessing ? 'prompt' : 'builtin', mainFlowOnly: (command as any).mainFlowOnly || false, })), [builtInCommands], ); // Get all commands (built-in + custom) - dynamically fetch custom commands const getAllCommands = useCallback((): CommandPanelCommand[] => { const customCommands = getCustomCommands().map(cmd => ({ name: cmd.name, description: cmd.description || cmd.command, type: cmd.type, })); return [...normalizedBuiltInCommands, ...customCommands]; }, [normalizedBuiltInCommands]); const [showCommands, setShowCommands] = useState(false); const [commandSelectedIndex, setCommandSelectedIndex] = useState(0); const [usageLoaded, setUsageLoaded] = useState(false); // Load command usage data on mount // Use isMounted flag to prevent state update on unmounted component useEffect(() => { let isMounted = true; commandUsageManager.ensureLoaded().then(() => { if (isMounted) { setUsageLoaded(true); } }); return () => { isMounted = false; }; }, []); // Get filtered commands based on current input // Sorting strategy: // - Empty query: Sort by usage frequency (most used first) // - With query: Sort by match priority, then by usage frequency within same priority const getFilteredCommands = useCallback((): CommandPanelCommand[] => { const text = buffer.getFullText(); if (!text.startsWith('/')) return []; const query = text.slice(1).toLowerCase(); // Get all commands (including latest custom commands) const allCommands = getAllCommands(); const availableCommands = isProcessing ? allCommands.filter( command => command.type === 'prompt' && !(command.mainFlowOnly && hasRunningAgentsOrTeam), ) : allCommands; // Filter and sort commands by priority and usage frequency // Priority order: // 1. Command starts with query (highest) // 2. Command contains query // 3. Description starts with query // 4. Description contains query (lowest) const filtered = availableCommands .filter( command => command.name.toLowerCase().includes(query) || command.description.toLowerCase().includes(query), ) .map(command => { const nameLower = command.name.toLowerCase(); const descLower = command.description.toLowerCase(); const usageCount = commandUsageManager.getUsageCountSync(command.name); let priority = 4; // Default: description contains query if (nameLower.startsWith(query)) { priority = 1; // Command starts with query } else if (nameLower.includes(query)) { priority = 2; // Command contains query } else if (descLower.startsWith(query)) { priority = 3; // Description starts with query } return {command, priority, usageCount}; }) .sort((a, b) => { // When query is empty, sort primarily by usage frequency if (query === '') { // Sort by usage count (descending), then alphabetically if (a.usageCount !== b.usageCount) { return b.usageCount - a.usageCount; } return a.command.name.localeCompare(b.command.name); } // With query: sort by priority first, then by usage frequency if (a.priority !== b.priority) { return a.priority - b.priority; } // Same priority: sort by usage count (descending) if (a.usageCount !== b.usageCount) { return b.usageCount - a.usageCount; } // Same usage count: sort alphabetically return a.command.name.localeCompare(b.command.name); }) .map(item => item.command); return filtered; }, [ buffer, getAllCommands, isProcessing, hasRunningAgentsOrTeam, usageLoaded, ]); // Update command panel state const updateCommandPanelState = useCallback((text: string) => { // Check if / is at the start (not preceded by @ or #) if (text.startsWith('/') && text.length > 0) { setShowCommands(true); setCommandSelectedIndex(0); } else { setShowCommands(false); setCommandSelectedIndex(0); } }, []); return { showCommands, setShowCommands, commandSelectedIndex, setCommandSelectedIndex, getFilteredCommands, updateCommandPanelState, getAllCommands, }; } ================================================ FILE: source/hooks/ui/useCursorHide.ts ================================================ import { useEffect } from 'react'; import { useStdout } from 'ink'; import ansiEscapes from 'ansi-escapes'; /** * Hide terminal cursor on component mount. * * This hook is used to prevent cursor flickering during page transitions. * Cursor visibility is restored by cli.tsx cleanup functions on application exit. * * @example * ```tsx * function MyScreen() { * useCursorHide(); * return ...; * } * ``` */ export function useCursorHide(): void { const { stdout } = useStdout(); useEffect(() => { stdout.write(ansiEscapes.cursorHide); }, [stdout]); } ================================================ FILE: source/hooks/ui/usePanelState.ts ================================================ import {useState, type Dispatch, type SetStateAction} from 'react'; import {reloadConfig} from '../../utils/config/apiConfig.js'; import { getAllProfiles, getActiveProfileName, switchProfile, } from '../../utils/config/configManager.js'; export type PanelState = { showSessionPanel: boolean; showMcpPanel: boolean; showUsagePanel: boolean; showHelpPanel: boolean; showCustomCommandConfig: boolean; showSkillsCreation: boolean; showSkillsListPanel: boolean; showRoleCreation: boolean; showRoleDeletion: boolean; showRoleList: boolean; showRoleSubagentCreation: boolean; showRoleSubagentDeletion: boolean; showRoleSubagentList: boolean; showWorkingDirPanel: boolean; showReviewCommitPanel: boolean; showBranchPanel: boolean; showProfilePanel: boolean; // 配置编辑面板：从 ProfilePanel 按右方向键进入，编辑指定 profile（不切换 active） showProfileEditPanel: boolean; editingProfileName: string | null; showModelsPanel: boolean; showDiffReviewPanel: boolean; showConnectionPanel: boolean; showNewPromptPanel: boolean; showTodoListPanel: boolean; showPixelEditor: boolean; showIdeSelectPanel: boolean; connectionPanelApiUrl?: string; profileSelectedIndex: number; profileSearchQuery: string; currentProfileName: string; }; export type PanelActions = { setShowSessionPanel: Dispatch>; setShowMcpPanel: Dispatch>; setShowUsagePanel: Dispatch>; setShowHelpPanel: Dispatch>; setShowConnectionPanel: Dispatch>; setShowNewPromptPanel: Dispatch>; setConnectionPanelApiUrl: Dispatch>; setShowCustomCommandConfig: Dispatch>; setShowSkillsCreation: Dispatch>; setShowSkillsListPanel: Dispatch>; setShowRoleCreation: Dispatch>; setShowRoleDeletion: Dispatch>; setShowRoleList: Dispatch>; setShowRoleSubagentCreation: Dispatch>; setShowRoleSubagentDeletion: Dispatch>; setShowRoleSubagentList: Dispatch>; setShowWorkingDirPanel: Dispatch>; setShowReviewCommitPanel: Dispatch>; setShowBranchPanel: Dispatch>; setShowProfilePanel: Dispatch>; setShowProfileEditPanel: Dispatch>; setEditingProfileName: Dispatch>; setShowModelsPanel: Dispatch>; /** * 打开 ProfileEditPanel 编辑指定 profile： * 同时关闭 ProfilePanel（picker），切换为编辑视图。 */ openProfileEdit: (profileName: string) => void; /** * 关闭 ProfileEditPanel 并回到 ProfilePanel（picker）。 */ closeProfileEditAndReturnToPicker: () => void; setShowDiffReviewPanel: Dispatch>; setShowTodoListPanel: Dispatch>; setShowPixelEditor: Dispatch>; setShowIdeSelectPanel: Dispatch>; setProfileSelectedIndex: Dispatch>; setProfileSearchQuery: Dispatch>; handleSwitchProfile: (options: { isStreaming: boolean; hasPendingRollback: boolean; hasPendingToolConfirmation: boolean; hasPendingUserQuestion: boolean; }) => void; handleProfileSelect: (profileName: string) => void; handleEscapeKey: () => boolean; // Returns true if ESC was handled isAnyPanelOpen: () => boolean; }; export function usePanelState(): PanelState & PanelActions { const [showSessionPanel, setShowSessionPanel] = useState(false); const [showMcpPanel, setShowMcpPanel] = useState(false); const [showUsagePanel, setShowUsagePanel] = useState(false); const [showHelpPanel, setShowHelpPanel] = useState(false); const [showCustomCommandConfig, setShowCustomCommandConfig] = useState(false); const [showSkillsCreation, setShowSkillsCreation] = useState(false); const [showSkillsListPanel, setShowSkillsListPanel] = useState(false); const [showRoleCreation, setShowRoleCreation] = useState(false); const [showRoleDeletion, setShowRoleDeletion] = useState(false); const [showRoleList, setShowRoleList] = useState(false); const [showRoleSubagentCreation, setShowRoleSubagentCreation] = useState(false); const [showRoleSubagentDeletion, setShowRoleSubagentDeletion] = useState(false); const [showRoleSubagentList, setShowRoleSubagentList] = useState(false); const [showWorkingDirPanel, setShowWorkingDirPanel] = useState(false); const [showReviewCommitPanel, setShowReviewCommitPanel] = useState(false); const [showBranchPanel, setShowBranchPanel] = useState(false); const [showProfilePanel, setShowProfilePanel] = useState(false); const [showProfileEditPanel, setShowProfileEditPanel] = useState(false); const [editingProfileName, setEditingProfileName] = useState( null, ); const [showModelsPanel, setShowModelsPanel] = useState(false); const [showDiffReviewPanel, setShowDiffReviewPanel] = useState(false); const [showConnectionPanel, setShowConnectionPanel] = useState(false); const [showNewPromptPanel, setShowNewPromptPanel] = useState(false); const [showTodoListPanel, setShowTodoListPanel] = useState(false); const [showPixelEditor, setShowPixelEditor] = useState(false); const [showIdeSelectPanel, setShowIdeSelectPanel] = useState(false); const [connectionPanelApiUrl, setConnectionPanelApiUrl] = useState< string | undefined >(undefined); const [profileSelectedIndex, setProfileSelectedIndex] = useState(0); const [profileSearchQuery, setProfileSearchQuery] = useState(''); const [currentProfileName, setCurrentProfileName] = useState(() => { const profiles = getAllProfiles(); const activeName = getActiveProfileName(); const profile = profiles.find(p => p.name === activeName); return profile?.displayName || activeName; }); const handleSwitchProfile = (options: { isStreaming: boolean; hasPendingRollback: boolean; hasPendingToolConfirmation: boolean; hasPendingUserQuestion: boolean; }) => { // Don't switch if any panel is open or streaming if ( showSessionPanel || showMcpPanel || showUsagePanel || showCustomCommandConfig || showSkillsCreation || showSkillsListPanel || showRoleCreation || showRoleDeletion || showRoleList || showRoleSubagentCreation || showRoleSubagentDeletion || showRoleSubagentList || showReviewCommitPanel || showBranchPanel || showProfilePanel || showModelsPanel || showDiffReviewPanel || showConnectionPanel || showNewPromptPanel || showTodoListPanel || showPixelEditor || showIdeSelectPanel || options.hasPendingRollback || options.hasPendingToolConfirmation || options.hasPendingUserQuestion || options.isStreaming ) { return; } // Show profile selection panel instead of cycling setShowProfilePanel(true); setProfileSearchQuery(''); const profiles = getAllProfiles(); // 使用内存中的 currentProfileName（displayName）定位光标， // 避免其他终端切换 profile 写文件后，本终端读到的 active 与内存不一致 const activeIndex = profiles.findIndex( p => p.displayName === currentProfileName, ); setProfileSelectedIndex(activeIndex >= 0 ? activeIndex : 0); }; // 从 ProfilePanel 进入 ProfileEditPanel：编辑光标焦点的 profile // 注意：保留 profileSelectedIndex 与 profileSearchQuery， // 这样 ESC 返回 picker 时光标停留在原来的 profile 上。 const openProfileEdit = (profileName: string) => { setEditingProfileName(profileName); setShowProfileEditPanel(true); // 关闭 picker 让 footer 不再渲染 ProfilePanel； // ProfileEditPanel 会在 PanelsManager 里独立渲染。 setShowProfilePanel(false); }; // 关闭 ProfileEditPanel 后回到 ProfilePanel（picker） // 同样保留 profileSelectedIndex，让光标回到进入编辑面板时的位置。 const closeProfileEditAndReturnToPicker = () => { setShowProfileEditPanel(false); setEditingProfileName(null); setShowProfilePanel(true); }; const handleProfileSelect = (profileName: string) => { // Switch to selected profile switchProfile(profileName); // Reload config to pick up new profile's configuration reloadConfig(); // Update display name const profiles = getAllProfiles(); const profile = profiles.find(p => p.name === profileName); setCurrentProfileName(profile?.displayName || profileName); // Close panel and reset search setShowProfilePanel(false); setProfileSelectedIndex(0); setProfileSearchQuery(''); }; const handleEscapeKey = (): boolean => { // Check each panel in priority order and close if open if (showSessionPanel) { setShowSessionPanel(false); return true; } if (showMcpPanel) { // Let MCPInfoPanel handle ESC internally (tool list page vs main page) return false; } if (showUsagePanel) { setShowUsagePanel(false); return true; } if (showHelpPanel) { setShowHelpPanel(false); return true; } // CustomCommandConfigPanel handles its own ESC key logic internally // Don't close it here - let the panel decide when to close if (showCustomCommandConfig) { return false; // Let CustomCommandConfigPanel handle ESC } // SkillsCreationPanel handles its own ESC key logic internally // Don't close it here - let the panel decide when to close if (showSkillsCreation) { return false; // Let SkillsCreationPanel handle ESC } if (showSkillsListPanel) { setShowSkillsListPanel(false); return true; } // RoleCreationPanel handles its own ESC key logic internally // Don't close it here - let the panel decide when to close if (showRoleCreation) { return false; // Let RoleCreationPanel handle ESC } if (showRoleDeletion) { setShowRoleDeletion(false); return true; } if (showRoleList) { setShowRoleList(false); return true; } if (showRoleSubagentCreation) { return false; // Let the panel handle ESC } if (showRoleSubagentDeletion) { return false; // Let the panel handle ESC } if (showRoleSubagentList) { setShowRoleSubagentList(false); return true; } // WorkingDirectoryPanel handles its own ESC key logic internally // Don't close it here - let the panel decide when to close if (showWorkingDirPanel) { return false; // Let WorkingDirectoryPanel handle ESC } if (showReviewCommitPanel) { setShowReviewCommitPanel(false); return true; } // BranchPanel handles its own ESC key logic internally // Don't close it here - let the panel decide when to close if (showBranchPanel) { return false; // Let BranchPanel handle ESC } if (showDiffReviewPanel) { setShowDiffReviewPanel(false); return true; } // ConnectionPanel handles its own ESC key logic internally if (showConnectionPanel) { return false; // Let ConnectionPanel handle ESC } // ProfileEditPanel 完全交由 ConfigScreen 内部处理 ESC： // 内部 useConfigInput 会按层级处理（先关闭 select 子项 / 退出编辑模式， // 再按 ESC 才会保存并通过 onBack 触发 closeProfileEditAndReturnToPicker）。 // 外层若也处理，会一次 ESC 直接弹出整个面板，破坏多级返回体验。 if (showProfileEditPanel) { return false; } if (showProfilePanel) { setShowProfilePanel(false); return true; } // ModelsPanel handles its own ESC key logic internally // Don't close it here - let the panel decide when to close if (showModelsPanel) { return false; // Let ModelsPanel handle ESC } // NewPromptPanel handles its own ESC key logic internally if (showNewPromptPanel) { return false; // Let NewPromptPanel handle ESC } if (showTodoListPanel) { setShowTodoListPanel(false); return true; } if (showPixelEditor) { return false; // Let PixelEditorScreen handle ESC } if (showIdeSelectPanel) { setShowIdeSelectPanel(false); return true; } return false; // ESC not handled }; const isAnyPanelOpen = (): boolean => { return ( showSessionPanel || showMcpPanel || showUsagePanel || showCustomCommandConfig || showSkillsCreation || showSkillsListPanel || showRoleCreation || showRoleDeletion || showRoleList || showRoleSubagentCreation || showRoleSubagentDeletion || showRoleSubagentList || showWorkingDirPanel || showReviewCommitPanel || showBranchPanel || showProfilePanel || showProfileEditPanel || showModelsPanel || showDiffReviewPanel || showConnectionPanel || showNewPromptPanel || showTodoListPanel || showPixelEditor || showIdeSelectPanel ); }; return { // State showSessionPanel, showMcpPanel, showUsagePanel, showHelpPanel, showCustomCommandConfig, showSkillsCreation, showSkillsListPanel, showRoleCreation, showRoleDeletion, showRoleList, showRoleSubagentCreation, showRoleSubagentDeletion, showRoleSubagentList, showWorkingDirPanel, showReviewCommitPanel, showBranchPanel, showProfilePanel, showProfileEditPanel, editingProfileName, showModelsPanel, showDiffReviewPanel, showConnectionPanel, showNewPromptPanel, showTodoListPanel, showPixelEditor, showIdeSelectPanel, connectionPanelApiUrl, profileSelectedIndex, profileSearchQuery, currentProfileName, // Actions setShowSessionPanel, setShowMcpPanel, setShowUsagePanel, setShowHelpPanel, setShowCustomCommandConfig, setShowSkillsCreation, setShowSkillsListPanel, setShowRoleCreation, setShowRoleDeletion, setShowRoleList, setShowRoleSubagentCreation, setShowRoleSubagentDeletion, setShowRoleSubagentList, setShowWorkingDirPanel, setShowReviewCommitPanel, setShowBranchPanel, setShowProfilePanel, setShowProfileEditPanel, setEditingProfileName, setShowModelsPanel, openProfileEdit, closeProfileEditAndReturnToPicker, setShowDiffReviewPanel, setShowConnectionPanel, setShowNewPromptPanel, setShowTodoListPanel, setShowPixelEditor, setShowIdeSelectPanel, setConnectionPanelApiUrl, setProfileSelectedIndex, setProfileSearchQuery, handleSwitchProfile, handleProfileSelect, handleEscapeKey, isAnyPanelOpen, }; } ================================================ FILE: source/hooks/ui/useTerminalFocus.ts ================================================ import {useState, useEffect, useCallback, useRef} from 'react'; import {useInput} from 'ink'; /** * Hook to detect terminal window focus state. * Returns true when terminal has focus, false otherwise. * * Uses ANSI escape sequences to detect focus events: * - ESC[I (\x1b[I) - Focus gained * - ESC[O (\x1b[O) - Focus lost * * Cross-platform support: * - ✅ Windows Terminal * - ✅ macOS Terminal.app, iTerm2 * - ✅ Linux: GNOME Terminal, Konsole, Alacritty, kitty, etc. * * Note: Older or minimal terminals that don't support focus reporting * will simply ignore the escape sequences and cursor will remain visible. * * Also provides a function to check if input contains focus events * so they can be filtered from normal input processing. * * Auto-focus recovery: If user input is detected while in unfocused state, * automatically restore focus state to ensure cursor visibility during * operations like Shift+drag file drop where focus events may be delayed. * * IMPORTANT: Uses Ink's useInput instead of direct process.stdin listeners * to avoid switching stdin between flowing/paused modes, which causes * stream conflicts with Ink's internal readable-event-based input handling. */ export function useTerminalFocus(): { hasFocus: boolean; isFocusEvent: (input: string) => boolean; ensureFocus: () => void; } { const [hasFocus, setHasFocus] = useState(true); // Default to focused const hasFocusRef = useRef(true); const handleInput = useCallback((input: string) => { // Ink strips the ESC prefix, so ESC[I arrives as '[I' and ESC[O as '[O' if (input === '[I' || input === '\x1b[I') { hasFocusRef.current = true; setHasFocus(true); return; } if (input === '[O' || input === '\x1b[O') { hasFocusRef.current = false; setHasFocus(false); return; } // Auto-recovery: If we receive printable input while in unfocused state, // treat it as an implicit focus gain. // This handles cases where focus events are delayed (e.g., Shift+drag operations) if (!hasFocusRef.current) { const isPrintableInput = input.length > 0 && !input.startsWith('\x1b') && !input.startsWith('[') && !/^[\x00-\x1f\x7f]+$/.test(input); if (isPrintableInput) { hasFocusRef.current = true; setHasFocus(true); } } }, []); useInput(handleInput); // Enable/disable focus reporting useEffect(() => { let syncTimer: NodeJS.Timeout | null = null; const enableTimer = setTimeout(() => { // ESC[?1004h - Enable focus events process.stdout.write('\x1b[?1004h'); // After enabling focus reporting, assume terminal has focus // This ensures cursor is visible after component remount (e.g., after /clear) // The terminal will send ESC[O if it doesn't have focus syncTimer = setTimeout(() => { hasFocusRef.current = true; setHasFocus(true); }, 100); }, 50); return () => { clearTimeout(enableTimer); if (syncTimer) { clearTimeout(syncTimer); } // Disable focus reporting on cleanup // ESC[?1004l - Disable focus events process.stdout.write('\x1b[?1004l'); }; }, []); // Helper function to check if input is a focus event const isFocusEvent = (input: string): boolean => { return input === '\x1b[I' || input === '\x1b[O'; }; // Manual focus restoration function (can be called externally if needed) const ensureFocus = () => { hasFocusRef.current = true; setHasFocus(true); }; return {hasFocus, isFocusEvent, ensureFocus}; } ================================================ FILE: source/hooks/ui/useTerminalSize.ts ================================================ import {useEffect, useState} from 'react'; // Singleton pattern to avoid MaxListenersExceededWarning // All components share a single resize listener instead of each adding their own type SizeListener = (size: {columns: number; rows: number}) => void; const listeners = new Set(); let isListening = false; let currentSize = { columns: process.stdout.columns || 80, rows: process.stdout.rows || 20, }; function handleResize() { currentSize = { columns: process.stdout.columns || 80, rows: process.stdout.rows || 20, }; listeners.forEach(listener => listener(currentSize)); } function subscribe(listener: SizeListener): () => void { listeners.add(listener); // Start listening only when first subscriber joins if (!isListening) { isListening = true; process.stdout.on('resize', handleResize); } // Return unsubscribe function return () => { listeners.delete(listener); // Stop listening when last subscriber leaves if (listeners.size === 0 && isListening) { isListening = false; process.stdout.off('resize', handleResize); } }; } export function useTerminalSize(): {columns: number; rows: number} { const [size, setSize] = useState(currentSize); useEffect(() => { // Sync with current size in case it changed before mount setSize(currentSize); // Subscribe to size changes const unsubscribe = subscribe(setSize); return unsubscribe; }, []); return size; } ================================================ FILE: source/hooks/ui/useTerminalTitle.ts ================================================ import {useEffect} from 'react'; import {useStdout} from 'ink'; /** * 设置终端窗口/标签标题，组件卸载时自动清空。 * * 跨平台兼容策略： * 1. process.title：Windows 控制台直接生效，类 Unix 上仅修改进程名 * 2. OSC 转义序列 ESC]0;BEL：所有支持 ANSI 的现代终端 * （macOS Terminal/iTerm2、Windows Terminal、Linux 终端、mintty 等） * * 注意： * - 非 TTY 环境（管道、重定向、CI 日志）会跳过，避免污染输出 * - 退出页面会写入空标题，多数终端会回退到默认值（如 cwd 或 shell 名） * - tmux/screen 用户需启用 set-titles on 才能透传到外层终端 * * @param title 要显示的标题；传入空字符串会清空标题 * @example * ```tsx * function MyScreen() { * useTerminalTitle('Snow CLI - 设置'); * return <Box>...</Box>; * } * ``` */ export function useTerminalTitle(title: string): void { const {stdout} = useStdout(); useEffect(() => { if (!stdout?.isTTY) return; // 保存原 process.title 以便卸载时恢复 let previousProcessTitle: string | undefined; try { previousProcessTitle = process.title; } catch { // 某些受限环境读取 process.title 可能抛错，忽略即可 } // 1. process.title：Windows 控制台直接生效，类 Unix 仅修改进程名 if (title) { try { process.title = title; } catch { // 某些平台（如部分容器/沙箱）写入 process.title 会失败，忽略 } } // 2. OSC 序列：所有支持 ANSI 的终端 try { stdout.write(`\x1b]0;${title}\x07`); } catch { // stdout 已关闭或不可写时忽略，避免应用崩溃 } return () => { if (!stdout?.isTTY) return; if (previousProcessTitle !== undefined) { try { process.title = previousProcessTitle; } catch { // 同上，忽略恢复失败 } } try { stdout.write('\x1b]0;\x07'); } catch { // 卸载阶段 stdout 可能已关闭，忽略 } }; }, [stdout, title]); } ================================================ FILE: source/i18n/I18nContext.tsx ================================================ import React, {createContext, useState, useCallback, ReactNode} from 'react'; import type {Language, TranslationKeys} from './types.js'; import {translations} from './translations.js'; import { getCurrentLanguage, setCurrentLanguage, } from '../utils/config/languageConfig.js'; type I18nContextType = { language: Language; setLanguage: (lang: Language) => void; t: TranslationKeys; }; const I18nContext = createContext<I18nContextType | undefined>(undefined); type Props = { children: ReactNode; defaultLanguage?: Language; }; export function I18nProvider({children, defaultLanguage}: Props) { // Load saved language on mount or use default const [language, setLanguageState] = useState<Language>(() => { return defaultLanguage || getCurrentLanguage(); }); const setLanguage = useCallback((lang: Language) => { setLanguageState(lang); setCurrentLanguage(lang); // Persist to file system }, []); // Get translations for current language const t = translations[language]; return ( <I18nContext.Provider value={{language, setLanguage, t}}> {children} </I18nContext.Provider> ); } export function useI18n(): I18nContextType { const context = React.useContext(I18nContext); if (!context) { throw new Error('useI18n must be used within I18nProvider'); } return context; } ================================================ FILE: source/i18n/index.ts ================================================ export {I18nProvider, useI18n} from './I18nContext.js'; export type {Language, TranslationKeys, Translations} from './types.js'; export {translations} from './translations.js'; ================================================ FILE: source/i18n/lang/en.ts ================================================ import type {TranslationKeys} from '../types.js'; export const en: TranslationKeys = { welcome: { title: '❆ SNOW AI CLI', subtitle: 'Agentic coding in your terminal', startChat: 'Start', startChatInfo: 'Start a new chat conversation', resumeLastChat: 'Resume Last Chat', resumeLastChatInfo: 'Resume the most recent conversation', apiSettings: 'API & Model Settings', apiSettingsInfo: 'Configure API settings, AI models, and manage profiles', proxySettings: 'Proxy & Browser Settings', proxySettingsInfo: 'Configure system proxy and browser for web search and fetch', codebaseSettings: 'CodeBase Settings', codebaseSettingsInfo: 'Configure codebase indexing with embedding models', systemPromptSettings: 'System Prompt Settings', systemPromptSettingsInfo: 'Configure custom system prompt (overrides default)', customHeadersSettings: 'Custom Headers Settings', customHeadersSettingsInfo: 'Configure custom HTTP headers for API requests', mcpSettings: 'MCP Settings', mcpSettingsInfo: 'Configure Model Context Protocol servers', subAgentSettings: 'Sub-Agent Settings', subAgentSettingsInfo: 'Configure sub-agents with custom tool permissions', sensitiveCommands: 'Sensitive Commands', sensitiveCommandsInfo: 'Configure commands that require confirmation even in YOLO mode', languageSettings: 'Language Settings', languageSettingsInfo: 'Switch application language', themeSettings: 'Theme Settings', themeSettingsInfo: 'Configure theme and preview DiffViewer', hooksSettings: 'Hooks Settings', hooksSettingsInfo: 'Configure hooks for customizing AI workflow', updateNoticeTitle: 'Update available', updateNoticeCurrent: 'Current', updateNoticeLatest: 'Latest', updateNoticeRun: 'Run', updateNoticeGithub: 'GitHub', updateNow: 'Update Now', updateNowInfo: 'Exit the CLI and run "npm i -g snow-ai" to upgrade to the latest version', exit: 'Exit', exitInfo: 'Exit the application', }, menu: { navigate: 'Use ↑↓ keys to navigate, press Enter to select:', }, proxyConfig: { title: 'Proxy Configuration', subtitle: 'Configure system proxy for web search and fetch', enableProxy: 'Enable Proxy:', enabled: '[✓] Enabled', disabled: '[ ] Disabled', toggleHint: '(Press Enter to toggle)', proxyPort: 'Proxy Port:', notSet: 'Not set', browserPath: 'Browser Path (Optional):', autoDetect: 'Auto-detect', searchEngine: 'Search Engine:', errors: 'Errors:', editingHint: 'Editing mode: Press Enter to save and exit editing (Make your changes and press Enter when done)', navigationHint: 'Use ↑↓ to navigate between fields, press Enter to edit/toggle, and press Ctrl+S or Esc to save and return', browserExamplesTitle: 'Browser Path Examples:', browserExamplesFooter: 'Leave empty to auto-detect system browser (Edge/Chrome)', portValidationError: 'Port must be a number between 1 and 65535', portPlaceholder: '7890', browserPathPlaceholder: 'Leave empty for auto-detect', windowsExample: '• Windows: C:\\Program Files(x86)\\Microsoft\\Edge\\Application\\msedge.exe', macosExample: '• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome', linuxExample: '• Linux: /usr/bin/chromium-browser', }, codebaseConfig: { title: 'CodeBase Configuration', subtitle: 'Configure codebase indexing and search settings', settingsPosition: 'Settings', scrollHint: '· ↑↓ to scroll', codebaseEnabled: 'CodeBase Enabled:', agentReview: 'Agent Review:', enabled: '[✓] Enabled', disabled: '[ ] Disabled', toggleHint: '(Press Enter to toggle)', embeddingType: 'Request Type:', embeddingModelName: 'Embedding Model Name:', embeddingBaseUrl: 'Embedding Base URL:', embeddingApiKey: 'Embedding API Key:', embeddingApiKeyOptional: 'Embedding API Key (Optional for local):', embeddingDimensions: 'Embedding Dimensions:', embeddingSettingsGroup: 'Embedding Model Config', embeddingSettingsExpandHint: '(Press Enter to expand/collapse)', batchSettingsGroup: 'Batch Settings', batchSettingsExpandHint: '(Press Enter to expand/collapse)', batchMaxLines: 'Batch Max Lines:', batchConcurrency: 'Batch Concurrency:', notSet: 'Not set', masked: '••••••••', errors: 'Errors:', editingHint: 'Editing mode: Type to edit, Enter to save, Esc to cancel', navigationHint: 'Use ↑↓ to navigate, Enter to edit/toggle, Ctrl+S or Esc to save', validationModelNameRequired: 'Embedding model name is required when enabled', validationBaseUrlRequired: 'Embedding base URL is required when enabled', validationDimensionsPositive: 'Embedding dimensions must be greater than 0', validationMaxLinesPositive: 'Batch max lines must be greater than 0', validationConcurrencyPositive: 'Batch concurrency must be greater than 0', validationMaxLinesPerChunkPositive: 'Max lines per chunk must be greater than 0', validationMinLinesPerChunkPositive: 'Min lines per chunk must be greater than 0', validationMinCharsPerChunkPositive: 'Min characters per chunk must be greater than 0', validationOverlapLinesNonNegative: 'Overlap lines must be non-negative', validationOverlapLessThanMaxLines: 'Overlap lines must be less than max lines per chunk', chunkingMaxLinesPerChunk: 'Max Lines Per Chunk:', chunkingMinLinesPerChunk: 'Min Lines Per Chunk:', chunkingMinCharsPerChunk: 'Min Characters Per Chunk:', chunkingOverlapLines: 'Overlap Lines:', rerankingToggle: 'Result Reranking:', rerankingSettingsGroup: 'Reranking Model Config', rerankingSettingsExpandHint: '(Press Enter to expand/collapse)', rerankingModelName: 'Model Name:', rerankingBaseUrl: 'Base URL:', rerankingApiKey: 'API Key:', rerankingContextLength: 'Model Context Length:', rerankingTopN: 'Top N:', rerankingNotConfigured: 'Please configure Model Name and Base URL in "Reranking Model Config" first', validationRerankingModelNameRequired: 'Reranking model name is required when enabled', validationRerankingBaseUrlRequired: 'Reranking base URL is required when enabled', validationRerankingContextLengthPositive: 'Model context length must be greater than 0', validationRerankingTopNPositive: 'Top N must be greater than 0', saveError: 'Failed to save configuration', gitignoreNotFound: 'Cannot create index: .gitignore file not found. Please add a .gitignore file to your project to prevent indexing unnecessary files.', enterValue: 'Enter value:', }, systemPromptConfig: { title: 'System Prompt Management', subtitle: 'Manage multiple system prompts (multi-select supported)', activePrompt: 'Active Prompts:', none: 'None', noPromptsConfigured: 'No system prompts configured. Press Enter to add one.', availablePrompts: 'Available Prompts:', actions: 'Actions:', activate: 'Toggle', deactivate: 'Deactivate All', edit: 'Edit', delete: 'Delete', addNew: 'Add New', escBack: '[ESC] Back', navigationHint: '↑↓ Select prompt | Space Toggle | ←→ Select action | Enter Confirm', addNewTitle: 'Add New System Prompt', editTitle: 'Edit System Prompt', nameLabel: 'Name:', contentLabel: 'Content:', enterPromptName: 'Enter prompt name', enterPromptContent: 'Enter prompt content', notSet: 'Not set', editingHint: '↑↓: Navigate fields | Enter: Edit | Ctrl+S: Save | ESC: Cancel', externalEditorHint: 'Press E to use external editor', editorNotFound: 'No text editor found. Please set EDITOR or VISUAL environment variable', editorOpenFailed: 'Failed to open editor', editorEditFailed: 'Edit failed', editorSaved: 'Content saved successfully', confirmDelete: 'Confirm Delete', deleteConfirmMessage: 'Are you sure you want to delete', confirmHint: 'Press Y to confirm, N or ESC to cancel', saveError: 'Failed to save', activeCount: '{count} active', }, configScreen: { title: 'API & Model Configuration', subtitle: 'Configure your API settings and AI models', activeProfile: 'Active Profile:', settingsPosition: 'Settings', scrollHint: '· ↑↓ to scroll', moreAbove: '{count} more above', moreBelow: '{count} more below', profile: 'Profile:', baseUrl: 'Base URL:', apiKey: 'API Key:', requestMethod: 'Request Method:', requestUrlLabel: 'Request URL: ', anthropicBeta: 'Anthropic Beta:', anthropicCacheTTL: 'Anthropic Cache TTL:', anthropicCacheTTL5m: '5 minutes (default)', anthropicCacheTTL1h: '1 hour', anthropicSpeed: 'Anthropic Speed:', anthropicSpeedNotUsed: 'Not Used (default)', anthropicSpeedFast: 'fast', anthropicSpeedStandard: 'standard', enablePromptOptimization: 'Enable Prompt Optimization:', enableAutoCompress: 'Enable Auto Compression:', autoCompressThreshold: 'Auto Compress Threshold (%):', autoCompressThresholdHint: 'Algorithm: maxContextTokens × {percentage}% = {actualThreshold} tokens', autoCompressThresholdDesc: 'Triggers compression when context exceeds this threshold (recommended 60-80%, too low impacts performance, too high defeats purpose)', showThinking: 'Show Thinking Process:', streamingDisplay: 'Streaming Line Display:', thinkingEnabled: 'Thinking Enabled:', thinkingMode: 'Thinking Mode:', thinkingModeTokens: 'Input Tokens', thinkingModeAdaptive: 'Adaptive', thinkingBudgetTokens: 'Thinking Budget Tokens:', thinkingEffort: 'Thinking Effort:', geminiThinkingEnabled: 'Gemini Thinking Enabled:', geminiThinkingLevel: 'Gemini Thinking Level:', responsesReasoningEnabled: 'Responses Reasoning Enabled:', responsesReasoningEffort: 'Responses Reasoning Effort:', responsesVerbosity: 'Responses Verbosity:', responsesFastMode: 'Responses Fast Mode (priority):', chatThinkingEnabled: 'Chat Thinking (DeepSeek):', chatReasoningEffort: 'Chat Reasoning Effort:', advancedModel: 'Advanced Model(Type to search):', basicModel: 'Basic Model(Type to search):', maxContextTokens: 'Max Context Tokens:', maxTokens: 'Max Tokens:', streamIdleTimeoutSec: 'Stream Idle Timeout(sec):', toolResultTokenLimit: 'Tool Result Limit (%):', toolResultTokenLimitHint: 'Algorithm: maxContextTokens × {percentage}% = {actualLimit} tokens', toolResultTokenLimitDesc: 'Limits tool result as % of context window (recommended 20-40%, too low truncates, too high fills context)', notSet: 'Not set', enabled: '[✓] Enabled', disabled: '[ ] Disabled', toggleHint: '(Press Enter to toggle)', enterValue: 'Enter value:', createNewProfile: 'Create New Profile', renameProfile: 'Rename Profile', enterProfileName: 'Enter a name for the new configuration profile', enterRenameProfileName: 'Enter a new name for this profile', profileNameLabel: 'Profile Name:', profileNamePlaceholder: 'e.g., work, personal, test', renameProfilePlaceholder: 'Enter the new profile name', createHint: 'Press Enter to create, Esc to cancel', renameHint: 'Press Enter to rename, Esc to cancel', deleteProfile: 'Delete Profile', confirmDelete: 'Confirm profile deletion', deleteWarning: 'This action cannot be undone. You will be switched to the default profile.', confirmHint: 'Press Y to confirm, N or Esc to cancel', loadingModels: 'API & Model Configuration', loadingMessage: 'Loading available models...', loadingCancelHint: 'Press Esc to cancel and return to configuration', manualInputTitle: 'Manual Input Model', manualInputSubtitle: 'Enter model name manually', manualInputHint: 'Press Enter to confirm, Esc to cancel', loadingError: '⚠ Failed to load models from API', requestMethodChat: 'Chat Completions - Modern chat API (DeepSeek)', requestMethodResponses: 'Responses - New responses API (2025, with built-in tools)', requestMethodGemini: 'Gemini - Google Gemini API', requestMethodAnthropic: 'Anthropic - Claude API', manualInputOption: 'Manual Input (Enter model name)', errors: 'Errors:', cannotDeleteDefault: 'Cannot delete the default profile', profileNameEmpty: 'Profile name cannot be empty', navigationHint: 'Use ↑↓ to navigate, Enter to edit, R to rename, M for manual input, Ctrl+S or Esc to save', editingHintNumeric: 'Type to edit, Enter to save', editingHintGeneral: 'Press Enter to save and exit editing', modelFilterHint: 'Type to filter, ↑↓ to select, Enter to confirm, Esc to cancel', effortSelectHint: '↑↓ to select, Enter to confirm, Esc to cancel', profileSelectHint: '↑↓ to select profile, N to create new, R to rename, D to delete, Enter to confirm, Esc to cancel', requestMethodSelectHint: '↑↓ to select, Enter to confirm, Esc to cancel', newProfile: '+ New', renameProfileShort: '[R] Rename', deleteProfileShort: '🆇 Delete', mark: '✓ Mark', cannotRenameDefault: 'Cannot rename the default profile', noProfilesMarked: 'Please mark profiles to delete with Space first', confirmDeleteProfiles: 'Are you sure you want to delete the following {count} profiles?', fetchingModels: 'Fetching models from API...', fetchingHint: 'This may take a few seconds depending on your network connection', systemPrompt: 'System Prompt (Optional)', customHeadersField: 'Custom Headers (Optional)', followGlobalNone: 'Follow Global: None', followGlobal: 'Follow Global: {name}', followGlobalWithParentheses: 'Follow Global ({name})', followGlobalNoneWithParentheses: 'Follow Global (None)', notUse: 'Not Use', systemPromptMultiSelectHint: 'Space: toggle | Enter: confirm | Esc: cancel', modelSelectFilterLabel: 'Filter:', modelSelectModelCount: '{count} models', modelSelectScrollHint: '↑↓ scroll for more', }, customHeaders: { title: 'Custom Headers Management', subtitle: 'Manage multiple header schemes and switch between them', activeScheme: 'Active Scheme:', none: 'None', noSchemesConfigured: 'No header schemes configured. Press Enter to add one.', availableSchemes: 'Available Schemes:', actions: 'Actions:', activate: 'Activate', deactivate: 'Deactivate', edit: 'Edit', delete: 'Delete', addNew: 'Add New', escBack: '[ESC] Back', navigationHint: 'Use ↑↓ to select scheme, ←→ to select action, Enter to confirm', addNewTitle: 'Add New Header Scheme', editTitle: 'Edit Header Scheme', nameLabel: 'Name:', headersLabel: 'Headers', headersConfigured: 'configured', enterSchemeName: 'Enter scheme name', notSet: 'Not set', pressEnterToEdit: 'Press Enter to edit headers →', editingHint: '↑↓: Navigate fields | Enter: Edit | Ctrl+S: Save | ESC: Cancel', confirmDelete: 'Confirm Delete', deleteConfirmMessage: 'Are you sure you want to delete', confirmHint: 'Press Y to confirm, N or ESC to cancel', saveError: 'Failed to save', editHeadersTitle: 'Edit Headers', headerList: 'Header List:', noHeadersConfigured: 'No headers configured. Press Enter to add one.', addNewHeader: '[+] Add new header', headerNavigationHint: '↑↓: Navigate | Enter: Edit/Add | D: Delete | ESC: Finish', keyLabel: 'Key:', valueLabel: 'Value:', headerKeyPlaceholder: 'Header key (e.g., X-API-Key)', headerValuePlaceholder: 'Header value', headerEditingHint: '↑↓: Navigate fields | Enter: Edit | Ctrl+S: Save | ESC: Cancel', }, subAgentConfig: { title: 'Sub-Agent Configuration', titleEdit: 'Edit', titleNew: 'New', subtitle: 'Configure sub-agents with custom tool permissions', agentName: 'Agent Name:', description: 'Description:', role: 'Role:', roleOptional: 'Role (Optional):', toolSelection: 'Tool Selection:', agentNamePlaceholder: 'Enter agent name...', descriptionPlaceholder: 'Enter agent description...', rolePlaceholder: 'Specify agent role to guide output and focus...', selectedTools: 'Selected:', toolsCount: 'tools', loadingMCP: 'Loading MCP services...', mcpLoadError: '⚠', categoryCount: '({selected}/{total})', categoryMCP: '(MCP)', navigationHint: '↑↓: Navigate | ←→: Switch category | Space: Toggle | A: Toggle all | Enter: Save | Esc: Back', saveSuccess: 'Sub-agent saved successfully!', saveSuccessEdit: 'updated', saveSuccessCreate: 'created', saveError: 'Failed to save sub-agent', validationFailed: 'Validation failed', filesystemTools: 'Filesystem Tools', aceTools: 'ACE Code Search Tools', codebaseTools: 'Codebase Search Tools', terminalTools: 'Terminal Tools', todoTools: 'TODO Management Tools', webSearchTools: 'Web Search Tools', ideTools: 'IDE Diagnostics Tools', userInteractionTools: 'User Interaction Tools', skillTools: 'Skill Tools', configProfile: 'Config Profile (Optional):', followGlobal: 'Follow Global ({name})', customSystemPrompt: 'Custom System Prompt (Optional):', customHeaders: 'Custom Headers (Optional):', noItems: 'No items available', moreAbove: '{count} more above', moreBelow: '{count} more below', scrollToggleHint: '↑/↓ scroll, ←/→ switch config area, Space toggle', spaceToggleHint: 'Space to toggle', moreTools: '{count} more tools', scrollToolsHint: '↑/↓ scroll, Space toggle, A toggle all', builtinReadonly: ' (built-in, read-only)', roleExpandHint: '({status} - Space to toggle)', roleExpanded: 'Expanded', roleCollapsed: 'Collapsed', roleViewFull: '(Space to view full)', }, subAgentList: { title: 'Sub-Agent Management', noAgents: 'No sub-agents configured yet.', noAgentsHint: 'Press "A" to add a new sub-agent.', agentsCount: 'Sub-Agents ({count}):', description: 'Description:', noDescription: 'No description', toolsCount: 'Tools: {count} selected', updated: 'Updated:', deleteConfirm: 'Delete "{name}"? (Y/N)', deleteSuccess: 'Sub-agent deleted successfully!', deleteFailed: 'Cannot delete built-in sub-agents', navigationHint: '↑↓: Navigate | Enter: Edit | A: Add New | D: Delete | Esc: Back', }, sensitiveCommandConfig: { title: 'Sensitive Command Protection', subtitle: 'Configure commands that require confirmation even in YOLO/Always-Approved mode', noCommands: 'No commands configured', custom: 'custom', enabled: 'Enabled', disabled: 'Disabled', customLabel: 'Custom', // Scope scopeProject: 'Project', scopeGlobal: 'Global', scopeSelectTitle: 'Select scope for new command', scopeSelectHint: '↑↓: Navigate • Enter: Select • Esc: Cancel', duplicatePattern: 'Pattern "{pattern}" already exists in {scope} scope', resetScopeSelectTitle: 'Select scope to reset', resetGlobalDesc: 'Restore to default preset commands', resetProjectDesc: 'Clear all project custom commands', confirmResetScopeMessage: '⚠️ Press Enter again to confirm {scope} reset', // Add view addTitle: 'Add Custom Sensitive Command ({scope})', patternLabel: 'Pattern (supports wildcards, e.g., "rm*"):', patternPlaceholder: 'e.g., rm -rf, sudo, etc.', descriptionLabel: 'Description:', addEditingHint: 'Tab: Switch • Enter: Submit • Esc: Cancel', // List view actions addedMessage: 'Added: {pattern}', enabledMessage: 'Enabled: {pattern}', disabledMessage: 'Disabled: {pattern}', deletedMessage: 'Deleted: {pattern}', resetMessage: 'Reset to default commands', // Confirmation messages confirmDeleteMessage: '⚠️ Press D again to confirm deletion of "{pattern}"', confirmResetMessage: '⚠️ Press R again to confirm reset to default commands', confirmHint: 'Press the same key again to confirm • Esc: Cancel', // Navigation hints listNavigationHint: '↑↓: Navigate • Space: Toggle • A: Add • D: Delete • R: Reset • Esc: Back', }, themeSettings: { title: 'Theme Settings', current: 'Current:', preview: 'Preview:', userMessagePreview: 'User message preview:', userMessageSample: 'Check if user message background looks right.', back: '← Back', backInfo: 'Return to main menu', simpleMode: 'Simple Mode:', simpleModeInfo: 'Enable simple mode to simplify the interface', diffOpacity: 'Diff Highlight Strength:', diffOpacityInfo: 'Adjust diff highlight strength, default 100%, minimum 30%, press Enter to cycle by 10%', enabled: '[✓] Enabled', disabled: '[ ] Disabled', darkTheme: 'Dark Theme', darkThemeInfo: 'Classic dark color scheme', lightTheme: 'Light Theme', lightThemeInfo: 'Classic light color scheme', githubDark: 'GitHub Dark', githubDarkInfo: 'GitHub inspired dark theme', rainbow: 'Rainbow', rainbowInfo: 'Vibrant rainbow colors for a fun experience', solarizedDark: 'Solarized Dark', solarizedDarkInfo: 'Solarized dark theme with precision colors', nord: 'Nord', nordInfo: 'Arctic, north-bluish color palette', tiffany: 'Tiffany Blue', tiffanyInfo: 'Fresh and elegant Tiffany blue palette', macaronPink: 'Macaron Pink', macaronPinkInfo: 'Sweet pastel macaron pink palette', custom: 'Custom', customInfo: 'Use your own custom colors', editCustom: 'Edit Custom Theme...', editCustomInfo: 'Customize theme colors', }, customTheme: { title: 'Custom Theme Editor', save: 'Save', saveInfo: 'Save custom theme colors', reset: 'Reset to Default', resetInfo: 'Reset all colors to default', back: '← Back', backInfo: 'Return to theme settings', editColor: 'Edit Color', currentValue: 'Current', newValue: 'New value', colorFormat: 'Format: #RRGGBB or color name (red, blue, etc.)', cancel: 'Cancel', confirm: 'Confirm', preview: 'Preview', userMessagePreview: 'User message preview', userMessageSample: 'Check if userMessageBackground looks right.', colorHint: 'Press Enter to edit this color', }, helpPanel: { title: '🔰 Keyboard Shortcuts & Help', textEditingTitle: '📝 Text Editing:', deleteToStart: 'Ctrl+L - Delete from cursor to start (legacy)', deleteToEnd: 'Ctrl+R - Delete from cursor to end (legacy)', copyInput: 'Ctrl+O - Copy input content to system clipboard', pasteImages: '{pasteKey} - Paste images from clipboard', toggleExpandedView: 'Ctrl+T - Toggle expanded/collapsed view for pasted text', readlineTitle: '🚀 Readline Shortcuts:', moveToLineStart: 'Ctrl+A - Move to beginning of line', moveToLineEnd: 'Ctrl+E - Move to end of line', forwardWord: 'Alt+F - Move forward one word', backwardWord: 'Alt+B - Move backward one word', deleteToLineEnd: 'Ctrl+K - Delete from cursor to end of line', deleteToLineStart: 'Ctrl+U - Delete from cursor to beginning of line', deleteWord: 'Ctrl+W - Delete word before cursor', deleteChar: 'Ctrl+D - Delete character at cursor', quickAccessTitle: '🔍 Quick Access:', insertFiles: '@ - Insert files from project', searchContent: '@@ - Search file content', selectAgent: '# - Select sub-agent for task execution', showCommands: '/ - Show available commands', bashModeTitle: '🔲 Bash Mode:', bashModeTrigger: '!`Command`<Optional timeout duration in ms>', bashModeDesc: 'Example: !`ls -l`<5000>', navigationTitle: '📋 Navigation:', navigateHistory: '↑/↓ - Navigate command/message history', selectItem: 'Tab/Enter - Select item in pickers', cancelClose: 'ESC - Cancel/close pickers or interrupt AI response', toggleYolo: 'Shift+Tab/Ctrl+Y - Toggle modes (cycle: Off → YOLO → YOLO+Plan → Plan → YOLO+Team → Team → Off)', tipsTitle: '💡 Tips:', tipUseHelp: 'Use /help anytime to see this information', tipShowCommands: 'Type / to see all available commands', tipInterrupt: 'Press ESC during AI response to interrupt', closeHint: 'Press ESC to close this help panel', }, connectionPanel: { errorPrefix: 'Error: ', loggingIn: 'Logging in...', connectingToHub: 'Connecting to hub...', connectedSuccessfully: 'Connected successfully', title: 'Instance Connection', statusLabel: 'Status:', statusConnected: 'Connected', statusConnecting: 'Connecting', statusDisconnected: 'Disconnected', savedConfigFound: '✓ Found saved connection config', apiUrlLabel: 'API URL:', usernameLabel: 'Username:', instanceLabel: 'Instance:', savedConfigHint: 'Press Enter to continue with saved config, Esc to cancel', confirmDeletePrefix: 'Press', confirmDeleteSuffix: 'again to confirm delete', clearSavedPrefix: 'Press', clearSavedSuffix: 'to clear saved config', apiBaseUrlLabel: 'API Base URL:', apiBaseUrlPlaceholder: 'Enter API URL...', enterContinueEscCancel: 'Press Enter to continue, Esc to cancel', authenticationTitle: 'Authentication', usernameFieldLabel: 'Username: ', usernamePlaceholder: 'Enter username...', passwordFieldLabel: 'Password: ', passwordPlaceholder: 'Enter password...', enterContinueEscBack: '↑↓ switch fields, Enter to continue, Esc to go back', instanceConfigTitle: 'Instance Configuration', loggedInAs: '✓ Logged in as:', instanceIdLabel: 'Instance ID: ', instanceIdPlaceholder: 'Enter instance ID...', instanceNameLabel: 'Instance Name: ', instanceNamePlaceholder: 'Enter display name...', enterConnectEscBack: '↑↓ switch fields, Enter to connect, Esc to go back', pleaseWait: 'Please wait...', connectedSuccessfullyWithIcon: '✓ Connected successfully!', pressEscToClose: 'Press Esc to close', useCommandPrefix: 'Use', useCommandSuffix: 'command to disconnect', }, commandPanel: { title: 'Command Panel', availableCommands: 'Available Commands', processingMessage: 'Please wait for the conversation to complete before using commands', scrollHint: '↑↓ to scroll', moreHidden: '{count} more hidden', moreAbove: '{count} more above', moreBelow: '{count} more below', interactionHint: 'Tab: Autocomplete • Enter: Execute', commands: { help: 'Show keyboard shortcuts and help information', clear: 'Clear chat context and conversation history', copyLast: 'Copy last AI message to clipboard', resume: 'Resume a conversation', mcp: 'Show Model Context Protocol services and tools', yolo: 'Toggle unattended mode (auto-approve all tools)', plan: 'Toggle Plan mode (specialized planning assistant)', init: 'Analyze project and generate/update AGENTS.md documentation', ide: 'Connect to VSCode editor and sync context', compact: 'Compress conversation history using compact model', home: 'Return to welcome screen to modify settings', review: 'Review changes in the working tree and selected commits. Opens a picker panel where you can select items and add notes.', gitline: 'Select git commits and insert their content into the current chat input', role: 'Open or create ROLE.md file to customize AI assistant role. Use -l or --list to list all roles', roleSubagent: 'Customize sub-agent prompts with ROLE-{name}.md files. Use -l to list, -d to delete', usage: 'View token usage statistics with interactive charts', export: 'Export chat conversation to text file with save dialog', custom: 'Add custom command and save to ~/.snow/commands', skills: 'Create skill template with documentation and examples', skillsPicker: 'Pick a skill and inject its SKILL.md content into the input', agent: 'Select and use a sub-agent to handle specific tasks', todo: 'Search and select TODO comments from project files', todolist: 'Show the current session TODO tree and manage items', addDir: 'Add working directory for multi-project context. Usage: /add-dir or /add-dir path', reindex: 'Rebuild codebase index. Use -force to delete existing database and rebuild from scratch', codebase: 'Toggle codebase indexing for current project. Usage: /codebase [on|off|status]', permissions: 'Manage always-approved tools permissions', backend: 'Show background processes panel', loop: 'Schedule a session-scoped recurring task. Usage: /loop 5m <prompt>', profiles: 'Switch configuration profiles', models: 'Open the model switching panel', subAgentDepth: 'Set the maximum nested spawn depth for sub-agents', vulnerabilityHunting: 'Toggle vulnerability hunting mode for security-focused code analysis', autoFormat: 'Auto-formatting switch after file editing. Usage: /auto-format [on|off|status]', simple: 'Toggle theme simple mode. Usage: /simple [on|off|status]', toolSearch: 'Toggle Tool Search (progressive tool loading). Enabled by default to save context', hybridCompress: 'Toggle Hybrid Compress mode (AI summary + smart truncation for /compact and auto-compress)', team: 'Toggle Agent Team mode - orchestrate multiple agents working together in independent Git worktrees', branch: 'Fork current conversation into a new branch', worktree: 'Open Git branch management panel for switching, creating and deleting branches', diff: 'Review file changes from a conversation in IDE diff view', connect: 'Connect to a Snow Instance for AI processing', disconnect: 'Disconnect from the current Snow Instance', connectionStatus: 'Show current Snow Instance connection status', newPrompt: 'Generate a refined prompt from your requirement using AI', pixel: 'Open the terminal pixel editor', btw: 'Ask a side-question while AI is working (temporary, no context saved)', deepresearch: 'Run an autonomous multi-step web research workflow and save a cited markdown report to .snow/deepresearch/', quit: 'Exit the application', }, copyLastFeedback: { noAssistantMessage: 'No AI assistant message found to copy.', emptyAssistantMessage: 'The last AI assistant message has no content to copy.', copySuccess: '✓ Last AI message copied to clipboard', copyFailedPrefix: '✗ Failed to copy to clipboard', unknownError: 'Unknown error', }, // Command output messages (for command execution results) commandOutput: { // Auto-format command messages autoFormat: { enabled: 'Auto-format: Enabled for this project', disabled: 'Auto-format: Disabled for this project', statusEnabled: 'Auto-format: Enabled for this project', statusDisabled: 'Auto-format: Disabled for this project', }, // Simple mode command messages simpleMode: { enabled: 'Simple mode: Enabled', disabled: 'Simple mode: Disabled', statusEnabled: 'Simple mode: Enabled', statusDisabled: 'Simple mode: Disabled', }, // Export command messages export: { exporting: 'Exporting conversation...', openingDialog: 'Opening file save dialog...', cancelledByUser: 'Export cancelled by user.', }, // IDE command messages ide: { disconnected: 'Disconnected from IDE.', noAvailableIDEs: 'No available IDEs detected. Make sure your IDE has the Snow CLI extension or plugin installed and is running.', unmatchedIDEs: 'Found {count} other running IDE(s). However, their workspace/project directories do not match the current cwd.', connectedTo: 'Connected to {label}', connectFailed: 'Failed to connect to IDE: {error}', }, branchFork: { noActiveSession: 'No active session to fork.', success: 'Conversation forked into branch {name}. To return to the original session:\n/resume {originalId}', failed: 'Failed to fork session', }, // Deep Research command messages deepResearch: { usage: 'Usage: /deepresearch <prompt>\nExample: /deepresearch Compare the architectures of OpenAI Deep Research and Gemini Deep Research', }, // Loop command messages loop: { usage: 'Usage: /loop 5m <prompt> | /loop 8h30m <prompt> | /loop <prompt> every 2 hours | /loop list | /loop cancel <id> | /loop tasks', openingTaskManager: 'Opening task manager...', relatedLoopTasks: 'Related loop tasks:', noActiveLoops: 'No active loops. Create one with /loop 5m <prompt> or /loop <prompt> every 2 hours.', loopNotFound: 'Loop not found: {id}', cancelled: 'Cancelled loop {id} (every {interval})', created: 'Loop created: {id}', scheduleEvery: 'Schedule: every {interval}', promptLabel: 'Prompt: {prompt}', nextRun: 'Next run: {time}', sessionScopedNote: 'Session-scoped only: loop jobs stop when Snow CLI exits.', usageHint: 'Use /loop list to inspect jobs or /loop cancel <id> to stop one.', }, }, }, fileList: { loadingFiles: 'Loading files...', noFilesFound: 'No files found', searchingDeeper: 'Searching deeper (depth {depth})...', scanning: 'Scanning... ({count} indexed)', scanningDeeper: 'Searching deeper (depth {depth}, {count} indexed)...', deeperSearchHint: 'More directories not scanned · press ↓ on the last item to search deeper', contentSearchHeader: '≡ Content Search', filesHeader: '≡ Files [{mode} • Ctrl+T]', treeMode: 'Tree', listMode: 'List', }, ideSelectPanel: { title: 'Select IDE', subtitle: 'Connect to an IDE for integrated development features.', noneOption: 'None', connectedMark: ' ✔', hint: '↑↓ navigate • Enter select • ESC close', connecting: 'Connecting...', connectSuccess: 'Connected to {label}', connectError: 'Failed to connect: {error}', unmatchedIDEs: 'The above {count} IDE(s) have workspaces that do not match the current directory. Selecting one will switch the working directory.', unmatchedHeader: '— Switch working directory —', switchWorkdirMark: ' (switch cwd)', switchWorkdirError: 'Failed to switch working directory: {error}', }, permissionsPanel: { title: 'Permissions', clearAll: 'Clear All', noTools: 'No tools are always approved', hint: '↑↓ navigate • Enter remove • ESC close', confirmDelete: 'Delete allowed tool?', confirmClearAll: 'Clear all permissions?', yes: 'Yes', no: 'No', }, subAgentDepthPanel: { title: 'Sub-Agent Depth', description: 'Set the maximum depth allowed when sub-agents spawn other sub-agents.', currentValueLabel: 'Current value:', inputLabel: 'Input depth:', invalidInput: 'Enter a non-negative integer', saveSuccess: 'Saved successfully', hint: 'Enter save • Esc close • digits only', fileHint: 'This setting is persisted to .snow/settings.json in the project root', }, modelsPanel: { title: 'Model Switching', subtitle: 'Tab to switch tabs | Enter to select', tabAdvanced: 'Advanced Model', tabBasic: 'Basic Model', tabThinking: 'Thinking', currentModel: 'Current Model:', notSet: 'Not Set', loadingModels: 'Loading models...', hint: 'Enter to select model | m for manual input | Esc to close', manualInputTitle: 'Manual Input', manualInputHint: 'Enter to save, Esc to close', filterLabel: 'Filter:', manualInputOption: 'Manual Input', requestMethod: 'Request Method:', showThinkingProcess: 'Show Thinking Process:', enableThinking: 'Enable Thinking:', thinkingMode: 'Thinking Mode:', thinkingStrength: 'Thinking Strength:', inputNumberHint: 'Enter number, press Enter to save', escCancel: 'Esc to cancel', navigationHint: '↑↓ to select | Enter to toggle | Esc to close', notSupported: 'Not Supported', advancedModelLabel: 'Advanced Model', basicModelLabel: 'Basic Model', thinkingLabel: 'Thinking', requestMethodNotSupportedForThinking: 'Current request method ({requestMethod}) does not support thinking', requestMethodNotSupportedForThinkingStrength: 'Current request method ({requestMethod}) does not support thinking strength settings', anthropicSpeed: 'Speed:', saveFailed: 'Save failed', modelSaveFailed: 'Model save failed', tipLabel: 'Tip:', modelCount: '{count} models', scrollHint: '↑↓ scroll for more', }, profilePanel: { title: 'Select Profile', scrollHint: '↑↓ to scroll', moreHidden: '{count} more hidden', moreAbove: '{count} more above', moreBelow: '{count} more below', escHint: 'Press ESC to close', editHint: 'Press Tab to edit', activeLabel: '(active)', searchLabel: 'Search:', noResults: 'No matching profiles found', }, skillsPickerPanel: { title: 'Select Skill', keyboardHint: '(ESC: cancel · Tab: switch · Enter: confirm)', loading: 'Loading skills...', searchLabel: 'Search:', appendLabel: 'Append:', empty: '(empty)', noSkillsFound: 'No skills found', noDescription: 'No description', scrollHint: '↑↓ to scroll', moreAbove: '{count} above', moreBelow: '{count} below', }, todoListPanel: { title: 'Current Session TODOs', loading: 'Loading TODO list...', deleting: 'Deleting selected TODO items...', empty: 'This session has no TODO items yet', noActiveSession: 'No active session', hint: '↑↓ navigate • Space select • D delete • Esc close', confirmModeHint: 'Confirm delete mode • Enter/Y/D confirm • N/Esc cancel', confirmDelete: 'Delete the {count} selected item(s)?', confirmDeleteHint: 'Press Enter, Y or D to confirm, N or Esc to cancel', selectedCount: '{count} selected', moreAbove: '{count} more above', moreBelow: '{count} more below', }, reviewCommitPanel: { title: 'Review: Select Changes', loadingCommits: 'Loading commits...', stagedLabel: 'Staged changes', unstagedLabel: 'Unstaged changes', filesLabel: 'files', hintEscClose: 'Press ESC to close', hintNavigation: '↑/↓ navigate · Space toggle · Enter confirm · Type to add notes', loadingMoreSuffix: '(loading more...)', notesLabel: 'Notes', notesOptional: '(optional)', selectedLabel: 'Selected', errorSelectAtLeastOne: 'Please select at least one item to review.', }, gitLinePickerPanel: { title: 'GitLine: Select Commits', loadingCommits: 'Loading commits...', loadingMoreSuffix: '(loading more...)', noCommits: 'No commits available', searchLabel: 'Search:', emptySearch: '(empty)', hintNavigation: '↑/↓ navigate · Space toggle · Enter confirm · Type to filter', selectedLabel: 'Selected', scrollToLoadMore: '(scroll to load more)', }, hooks: { pressCtrlCAgain: 'Press Ctrl+C again to exit', exitingApplication: 'Exiting safely...', }, hooksConfig: { title: 'Hooks Configuration', scopeSelect: { globalHooks: 'Global Hooks', globalInfo: 'Saved in user directory ~/.snow/hooks', projectHooks: 'Project Hooks', projectInfo: 'Saved in project directory .snow/hooks', back: 'Back', backInfo: 'Return', }, hookTypes: { onUserMessage: 'Triggered when user sends a message', beforeToolCall: 'Run before tool call', afterToolCall: 'Run after tool call completes', toolConfirmation: 'Triggered during the second confirmation of the tool (including sensitive word check)', onSubAgentComplete: 'Run when sub-agent task completes', beforeCompress: 'Run before compression operation', onSessionStart: 'Run when starting new session or resuming existing session', onStop: 'Run before Stop AI process ends', }, hookList: { title: 'Hooks Configuration', global: 'Global', project: 'Project', configured: 'configured', rules: 'rules', back: 'Back', backInfo: 'Back to scope selection', }, hookDetail: { rule: 'Rule', actions: 'actions', matcher: 'Matcher', addNewRule: 'Add New Rule', addNewRuleInfo: 'Add a new Hook rule', deleteHook: 'Delete Hook', deleteHookInfo: 'Delete entire Hook configuration file', back: 'Back', backInfo: 'Back to Hook list', }, ruleEdit: { title: 'Edit Rule', editDescription: 'Edit description', editMatcher: 'Edit matcher', editDescriptionLabel: 'Description', editMatcherLabel: 'Matcher', matcherHint: 'Comma-separated tool names (e.g., filesystem-edit,filesystem-read), generally used for beforeToolCall/afterToolCall, other Hooks do not need to fill in', clickToEdit: 'Click to edit rule description', clickToEditMatcher: 'Click to edit matcher (optional, multiple separated by comma)', enabled: 'Enabled', disabled: 'Disabled', addAction: 'Add Action', addActionInfo: 'Add a new execution action', deleteRule: 'Delete Rule', deleteRuleInfo: 'Delete current rule', saveRule: 'Save Rule', saveRuleInfo: 'Save current rule to configuration file', cancel: 'Cancel', cancelInfo: 'Back to Hook detail', hint: 'Use ↑↓ to select, Enter to edit/toggle, D to delete this rule', enterToSave: 'Press Enter to save, Esc to cancel', }, actionEdit: { title: 'Edit Action', enabled: 'Enabled', enabledInfo: 'Click to toggle enable/disable', type: 'Type', typeInfo: 'Click to toggle type (command/prompt)', command: 'Command', commandInfo: 'Click to edit command', commandNotSet: 'Not set', prompt: 'Prompt', promptInfo: 'Click to edit prompt content', promptNotSet: 'Not set', timeout: 'Timeout', timeoutInfo: 'Click to edit timeout (milliseconds), leave empty for no timeout', deleteAction: 'Delete Action', deleteActionInfo: 'Delete current Action', saveAction: 'Save Action', saveActionInfo: 'Save Action and return', cancel: 'Cancel', cancelInfo: 'Cancel and return', hint: 'Use ↑↓ to select, Enter to edit/toggle, D to delete this action', enterToSave: 'Press Enter to save, Esc to cancel', }, }, customCommand: { title: 'Add Custom Command', nameLabel: 'Command name:', namePlaceholder: 'e.g., open', commandLabel: 'Enter the command to execute:', commandPlaceholder: 'npm run build && npm run deploy...', descriptionLabel: 'Description (optional):', descriptionPlaceholder: 'A brief description...', descriptionHint: 'Optional, keep it short (press Enter to skip)', descriptionNotSet: 'Not set', typeLabel: 'Select command type:', typeExecute: 'Execute (run in terminal)', typePrompt: 'Prompt (send to AI)', locationLabel: 'Select save location:', locationGlobal: 'Global', locationProject: 'Project', locationGlobalInfo: 'Available in all projects (~/.snow/commands/)', locationProjectInfo: 'Only available in this project (.snow/commands/)', confirmSave: 'Save this custom command? (y/n)', confirmYes: 'Yes', confirmNo: 'Cancel', escCancel: 'Press ESC to cancel', resultTypeExecute: 'Execute in terminal', resultTypePrompt: 'Send to AI', resultLocationGlobal: 'Global (~/.snow/commands/)', resultLocationProject: 'Project (.snow/commands/)', saveSuccessMessage: "Custom command '{name}' saved successfully!\nType: {type}\nLocation: {location}\nYou can now use /{name}", }, chatScreen: { // Header headerTitle: 'Programming efficiency x10!', headerSubtitle: '❆ SNOW AI CLI', headerExplanations: 'Ask for code explanations and debugging help', headerInterrupt: 'Press ESC during response to interrupt', headerYolo: 'Press Shift+Tab/Ctrl+Y: toggle modes (cycle: Off → YOLO → YOLO+Plan → Plan → YOLO+Team → Team → Off)', headerShortcuts: "Shortcuts: Ctrl+L (delete to start) • Ctrl+R (delete to end) • Ctrl+O (copy input) • {pasteKey} (paste images) • '@' (files) • '@@' (search content) • '#' (sub-agents) • '/' (commands)", headerExpandedView: 'Press Ctrl+T: toggle expanded/collapsed view for pasted text', headerWorkingDirectory: 'Working directory: {directory}', // Status messages statusThinking: 'Thinking...', statusDeepThinking: 'Deep thinking...', statusWriting: 'Writing...', statusStreaming: 'Streaming', statusWorking: 'Working', statusIndexing: 'Indexing codebase...', statusWatcherActive: 'File watcher active - monitoring code changes', statusWatcherActiveShort: 'Watcher', statusFileUpdated: 'Updated: {file}', statusFileUpdatedShort: 'Updated', statusCreating: 'Creating...', statusSaving: 'Saving...', statusCompressing: 'Compressing...', statusConnecting: 'Connecting to IDE...', statusConnected: 'IDE Connected', statusConnectionFailed: 'Connection Failed (this will not affect any usage) - Make sure Snow CLI plugin is installed and active in your IDE', statusStopping: 'Stopping...', inputCopySuccess: 'Input content copied to clipboard', inputCopyFailedPrefix: 'Failed to copy input content', // Profile switch profileCurrent: 'Profile', profileSwitchHint: 'switch', gitBranch: 'Git Branch', memoryUsageLabel: 'Memory Usage:', // Tool execution toolCall: 'Tool call', toolThinking: 'Thinking', toolReading: 'Reading', toolWriting: 'Writing', toolSearching: 'Searching', toolExecuting: 'Executing', toolSuccess: '✓ Success', toolRejected: '✗ Rejected', // Parallel execution parallelStart: '┌─ Parallel execution', parallelEnd: '└─ Execution completed', // Messages userMessage: 'You', assistantMessage: 'Assistant', commandMessage: 'Command', discontinuedMessage: '└─ user discontinue', aiCompletionTimeMessage: '└─ AI finished at {time}', // File operations fileCreated: 'Created', fileModified: 'Modified', fileRead: 'Read', fileDeleted: 'Deleted', fileCount: '{count} files', fileNotFound: 'file not found', fileLine: 'line', fileLines: 'lines', // Images imageAttached: '[image #{index}]', // Token usage tokenTotal: 'Total tokens', tokenInput: 'Input tokens', tokenOutput: 'Output tokens', tokenCached: 'Cached tokens', tokenCacheCreation: 'Cache creation', tokenCacheRead: 'Cache read', // Time timeElapsed: 'Elapsed', timeSeconds: '{count}s', timeMinutes: '{count}m', timeHours: '{count}h', // Errors errorGeneric: 'Error: {message}', errorApi: 'API Error: {message}', errorNetwork: 'Network Error: {message}', errorConfig: 'Configuration Error: {message}', errorCompression: 'Compression Error: {message}', errorCompressionFailed: 'Auto-compression Failed', errorLoadSession: 'Failed to load session', errorRollback: 'Failed to rollback', // Warnings terminalTooSmall: '⚠ Terminal Too Small', terminalResizePrompt: 'Your terminal height is {current} lines, but at least {required} lines are required.', terminalMinHeight: 'Please resize your terminal window to continue.', // Compression compressionAuto: '✵ Auto-compressing context due to token limit...', compressionInProgress: 'Compressing conversation history...', compressionSuccess: 'Compression complete', compressionFailed: '✗ Compression failed: {error}', compressionBlockToast: '✵ Compressing context, cannot interrupt, please wait...', // Review reviewStartTitle: 'Preparing to start code review', reviewSelectedSummary: 'Selected: {workingTreePrefix}{commitCount} commit(s)', reviewSelectedWorkingTreePrefix: 'Working Tree + ', reviewCommitsLine: 'Commits: {commitList}{moreSuffix}', reviewCommitsMoreSuffix: ' and {commitCount} total', reviewNotesLine: 'Notes: {notes}', reviewGenerating: 'Generating diff/patch and requesting model review...', reviewInterruptHint: 'Tip: press ESC to interrupt', // Retry retryAttempt: 'Retry {current}/{max}', retryIn: 'in {seconds}s...', retryResending: '⟳ Resending... (Attempt {current}/{max})', retryError: '✗ Error: {message}', // Codebase codebaseIndexing: 'Indexing codebase... {processed}/{total} files', codebaseIndexingShort: 'Indexing', codebaseProgress: '{chunks} chunks', codebaseChunks: 'chunks', codebaseSearching: '◉ Codebase Search (Attempt {current}/{max})', codebaseSearchAttempt: 'Attempt {current}/{max}', codebaseSearchComplete: 'Codebase search complete', codebaseIndexingEnabled: 'Codebase indexing enabled for this project', codebaseIndexingDisabled: 'Codebase indexing disabled for this project', // IDE ideConnecting: 'Connecting to IDE...', ideConnected: 'IDE Connected', ideDisconnected: 'IDE Disconnected', ideError: 'Connection Failed (this will not affect any usage) - Make sure Snow CLI plugin is installed and active in your IDE', ideActiveFile: '| {file}', ideSelectedText: '| {count} chars selected', // Input inputPlaceholder: 'Ask me anything about coding...', inputProcessing: 'Processing...', inputDisabled: 'Input disabled', // Shortcuts shortcutPasteImage: 'Paste images', shortcutFileReference: 'Reference files', shortcutSearchContent: 'Search content', shortcutCommands: 'Commands', shortcutDeleteToStart: 'Delete to start', shortcutDeleteToEnd: 'Delete to end', shortcutCancel: 'Cancel (ESC)', shortcutRegenerate: 'Regenerate (Ctrl+R)', shortcutToggleYolo: 'Toggle modes (Shift+Tab/Ctrl+Y)', // Rollback rollbackConfirm: 'Confirm rollback', rollbackFiles: 'Rollback files', rollbackConversation: 'Rollback conversation only', rollbackWarning: '{count} files will be affected', // Session chatInitializing: 'Initializing...', sessionCreating: 'Create the first dialogue record file...', sessionLoading: 'Loading session...', sessionSaving: 'Saving session...', sessionDeleting: 'Deleting session...', // Rejection rejectionReason: 'Rejection reason:', rejectionNoReason: 'No reason provided', // Batch operations batchFile: 'File {index}: {path}', batchEditResults: 'Batch edit results', // Pending pendingMessageWaiting: 'Pending message waiting...', pendingToolConfirmation: 'Tool confirmation required', pendingMessagesTitle: 'Pending Messages', pendingMessagesFooter: 'Will be sent after tool execution completes', pendingMessagesEscHint: 'Press ESC to restore to input (does not interrupt the current process)', pendingMessagesImagesAttached: '{count} images attached', // Press keys hints pressEscToClose: 'Press ESC to close', pressEnterToToggle: 'Press Enter to toggle', pressCtrlC: 'Ctrl+C to cancel', pressCtrlR: 'Ctrl+R to regenerate', pressCtrlS: 'Ctrl+S to save', // Context contextUsage: 'Context usage: {percentage}%', contextPercentage: '{percentage}%', contextLimit: 'Token limit reached', // ChatInput waitingForResponse: 'Waiting for response...', moreAbove: '↑ {count} more above...', moreBelow: '↓ {count} more below...', historyNavigateHint: '↑↓ navigate · Enter select · ESC close', typeToFilterCommands: 'Type to filter commands', contentSearchHint: 'Content search • Tab/Enter to select • ESC to cancel', fileSearchHint: 'Type to filter files • Tab/Enter to select • Ctrl+T to toggle view • ESC to cancel', expandedViewHint: 'Expanded view • Ctrl+T to toggle', yoloModeActive: '⧴ YOLO MODE ACTIVE - All tools will be auto-approved without confirmation', planModeActive: '⚐ Plan mode active - Specialized planning and coordination agent', vulnerabilityHuntingModeActive: '⍨ Vulnerability Hunting Mode Active - Focused on vulnerability discovery and security analysis', toolSearchEnabled: '♾︎ Tool Search ON - Tools loaded on demand', hybridCompressEnabled: '⇌ Hybrid Compress ON - AI summary + smart truncation', teamModeActive: '⚑ Agent Team Mode Active - Orchestrating multiple agents with independent worktrees', tokens: ' tokens', cached: 'cached', newCache: 'new cache', }, taskManager: { title: 'Task Manager', loadingTasks: 'Loading tasks...', noTasksFound: 'No tasks found', noTasksHint: 'Create with: snow --task "prompt"', escToClose: 'ESC to close', tasksCount: 'Tasks ({current}/{total})', messagesCount: '{count} msgs', markedCount: '{count} marked', navigationHint: '↑↓ navigate • Space mark • D delete • R refresh • Enter view • ESC close', moreAbove: '↑ {count} more above', moreBelow: '↓ {count} more below', deleteConfirm: 'Press D again to delete task', deleteMultipleConfirm: 'Press D again to delete {count} marked tasks', taskDetailsTitle: 'Task Details', continueHint: 'C continue', backToList: 'ESC back to list', titleLabel: 'Title:', statusLabel: 'Status:', createdLabel: 'Created:', updatedLabel: 'Updated:', messagesLabel: 'Messages: {count}', untitled: 'Untitled', statusPending: 'pending', statusRunning: 'running', statusCompleted: 'completed', statusFailed: 'failed', taskNotCompleted: 'Task not completed yet. Please wait for the task to finish.', confirmConvertToSession: 'Press C again to convert to session (task will be deleted)', sensitiveCommandDetected: 'Sensitive Command Detected', commandLabel: 'Command: ', approveRejectHint: 'Press A to approve or R to reject', enterRejectionReason: 'Enter rejection reason:', submitCancelHint: 'Enter Submit • ESC Cancel', }, skillsCreation: { title: 'Create New Skill', modeLabel: 'Creation Mode:', modeAi: 'AI Generate (describe requirement)', modeManual: 'Manual (create templates)', requirementLabel: 'Requirement:', requirementHint: 'Describe what you want this Skill to do (content will follow this language)', requirementPlaceholder: 'e.g., Generate a Skill for releasing npm packages...', generatingLabel: 'AI Generating...', generatingMessage: 'Generating skill files, please wait', filesLabel: 'Files to be created:', editName: 'Edit Name', editNameLabel: 'Current Skill Name:', editNameHint: 'Enter a new skill name (lowercase letters/numbers/hyphens, max 64 chars)', editNamePlaceholder: 'new-skill-name', regenerate: 'Regenerate', cancel: 'Cancel', nameLabel: 'Skill Name:', nameHint: 'Use lowercase letters, numbers, and hyphens. Use "/" to namespace (max 64 chars per segment)', namePlaceholder: 'team/my-skill-name', descriptionLabel: 'Description:', descriptionHint: 'Brief description of what this Skill does and when to use it', descriptionPlaceholder: 'A brief description...', locationLabel: 'Select Location:', locationGlobal: 'Global (~/.snow/skills/)', locationGlobalInfo: 'Available across all projects', locationProject: 'Project (.snow/skills/ in project root)', locationProjectInfo: 'Only available in this project', confirmQuestion: 'Create this Skill?', confirmYes: 'Yes, Create', confirmNo: 'No, Cancel', escCancel: 'Press ESC to cancel', // Error messages errorInvalidName: 'Invalid skill name', errorExistsBoth: 'Skill "{name}" already exists in both global and project locations', errorExistsGlobal: 'Skill "{name}" already exists in global location (~/.snow/skills/)', errorExistsProject: 'Skill "{name}" already exists in project location (.snow/skills/)', errorExistsAny: 'Skill "{name}" already exists, please choose another name', errorGeneration: 'AI generation failed', errorNoGeneratedContent: 'No generated content, please retry', resultModeAi: 'AI Generated', resultModeManual: 'Manual Template', createSuccessMessage: 'Skill "{name}" created successfully!\nMode: {mode}\nLocation: {location}\nPath: {path}\n\nThe following files have been created:\n- SKILL.md (main skill documentation)\n- reference.md (detailed reference)\n- examples.md (usage examples)\n- templates/template.txt (template file)\n- scripts/helper.py (helper script)\n\nYou can now edit these files to customize your skill.', createErrorMessage: 'Failed to create skill: {error}', errorUnknown: 'Unknown error', }, roleCreation: { title: 'Create ROLE.md', locationLabel: 'Select Location:', locationGlobal: 'Global (~/.snow/ROLE.md)', locationGlobalInfo: 'Available across all projects', locationProject: 'Project (./ROLE.md in project root)', locationProjectInfo: 'Only available in this project', confirmQuestion: 'Create ROLE.md?', confirmYes: 'Yes, Create', confirmNo: 'No, Cancel', escCancel: 'Press ESC to cancel', warningExistsGlobal: 'Warning: Global ROLE.md already exists (~/.snow/ROLE.md)', warningExistsProject: 'Warning: Project ROLE.md already exists (./ROLE.md)', createSuccessMessage: 'Created ROLE.md successfully! ｜ Location: {location} ｜ Path: {path}', createErrorMessage: 'Failed to create ROLE.md: {error}', errorUnknown: 'Unknown error', }, roleDeletion: { title: 'Delete ROLE.md', locationLabel: 'Select Location:', locationGlobal: 'Global (~/.snow/ROLE.md)', locationGlobalInfo: 'ROLE.md for all projects', locationProject: 'Project (./ROLE.md in project root)', locationProjectInfo: 'ROLE.md for current project only', confirmQuestion: 'Confirm deletion of ROLE.md?', confirmYes: 'Yes, Delete', confirmNo: 'No, Cancel', escCancel: 'Press ESC to cancel', warningNotExistsGlobal: 'Warning: Global ROLE.md does not exist (~/.snow/ROLE.md)', warningNotExistsProject: 'Warning: Project ROLE.md does not exist (./ROLE.md)', deleteSuccessMessage: 'Deleted ROLE.md successfully! | Location: {location} | Path: {path}', deleteErrorMessage: 'Failed to delete ROLE.md: {error}', errorNotFound: 'ROLE.md file does not exist', errorUnknown: 'Unknown error', }, roleList: { title: 'ROLE Management', tabGlobal: 'Global', tabProject: 'Project', noRoles: 'No roles found. Press N to create one.', active: 'Active', switchSuccess: 'Role switched successfully', createSuccess: 'Role created successfully', deleteSuccess: 'Role deleted successfully', loading: 'Processing...', hints: 'Tab: Switch scope | Enter: Activate | N: New | D: Delete | R: Override prompt | ESC: Close', cannotDeleteActive: 'Cannot delete active role', confirmDelete: 'Confirm delete this role?', confirmDeleteHint: 'Press Y to confirm, N to cancel', overrideTag: 'Override', overrideEnabled: 'Enabled: this role overrides the system prompt', overrideDisabled: 'Disabled: default system prompt restored', cannotOverrideInactive: 'Only the active role can be marked as override', }, roleSubagentCreation: { title: 'Create Sub-Agent Role', locationLabel: 'Select Location:', locationGlobal: 'Global (~/.snow/)', locationGlobalInfo: 'Available across all projects', locationProject: 'Project (project root)', locationProjectInfo: 'Only available in this project', selectAgentLabel: 'Select Sub-Agent:', selectAgentHint: '↑↓: Navigate | Enter: Select | ESC: Back', noAvailableAgents: 'All sub-agents already have role files at this location.', agentLabel: 'Sub-Agent:', fileLabel: 'File:', confirmQuestion: 'Create this role file?', confirmYes: 'Yes, Create', confirmNo: 'No, Cancel', escCancel: 'Press ESC to cancel', createSuccessMessage: 'Created sub-agent role successfully! | Agent: {agent} | Location: {location} | Path: {path}', createErrorMessage: 'Failed to create sub-agent role: {error}', errorUnknown: 'Unknown error', }, roleSubagentDeletion: { title: 'Delete Sub-Agent Role', locationLabel: 'Select Location:', locationGlobal: 'Global (~/.snow/)', locationGlobalInfo: 'Sub-agent role files for all projects', locationProject: 'Project (project root)', locationProjectInfo: 'Sub-agent role files for current project only', selectRoleLabel: 'Select role file to delete:', selectRoleHint: '↑↓: Navigate | Enter: Select | ESC: Back', noRoleFiles: 'No sub-agent role files found at this location.', fileLabel: 'File:', confirmQuestion: 'Confirm deletion?', confirmYes: 'Yes, Delete', confirmNo: 'No, Cancel', escCancel: 'Press ESC to cancel', deleteSuccessMessage: 'Deleted sub-agent role successfully! | Agent: {agent} | Location: {location} | Path: {path}', deleteErrorMessage: 'Failed to delete sub-agent role: {error}', errorNotFound: 'Sub-agent role file does not exist', errorUnknown: 'Unknown error', }, roleSubagentList: { title: 'Sub-Agent Role Management', tabGlobal: 'Global', tabProject: 'Project', noRoles: 'No sub-agent role files found. Use /role-subagent to create one.', deleteSuccess: 'Role file deleted successfully', loading: 'Processing...', hints: 'Tab: Switch scope | D: Delete | ESC: Close', confirmDelete: 'Confirm delete role for "{name}"?', confirmDeleteHint: 'Press Y to confirm, N to cancel', }, branchPanel: { title: 'Git Branch Management', notGitRepo: 'Current directory is not a Git repository. Cannot manage branches.', noBranches: 'No branches found. Press N to create one.', current: 'current', newBranchLabel: 'New branch name:', newBranchPlaceholder: 'feature/my-new-branch', createHint: 'Enter to confirm, ESC to cancel', confirmDelete: 'Delete branch "{branch}"?', confirmDeleteHint: 'Press Y to confirm, N to cancel', cannotDeleteCurrent: 'Cannot delete the currently checked-out branch', stashConfirm: 'Local changes detected. Stash changes and switch to "{branch}"?', stashConfirmHint: 'Press Y to stash & switch, N to cancel', loading: 'Processing...', hints: '↑↓: Navigate | Enter: Switch | N: New branch | D: Delete | ESC: Close', pressEscToClose: 'Press ESC to close', }, askUser: { header: '[User Input Required]', customInputOption: 'Custom input...', customInputLabel: 'Custom input', cancelOption: 'Cancel', selectPrompt: 'Select an option:', enterResponse: 'Enter your response:', keyboardHints: "Tip: Press 'Enter' to select | Press 'e' to edit selected option", multiSelectHint: 'Multi-select mode', multiSelectKeyboardHints: '↑↓ Move | Tab Toggle (Custom/Cancel) | Space Toggle | 1-9 Quick toggle | Enter Confirm | e Edit', optionListScrollHint: '↑↓ to scroll', optionListMoreAbove: '{count} more above', optionListMoreBelow: '{count} more below', }, toolConfirmation: { header: '[Tool Confirmation]', tool: 'Tool:', tools: 'Tools:', toolsInParallel: '{count} tools in parallel', sensitiveCommandDetected: 'SENSITIVE COMMAND DETECTED', pattern: 'Pattern:', reason: 'Reason:', requiresConfirmation: 'This command requires confirmation even in YOLO/Always-Approved mode', arguments: 'Arguments:', commandPagerTitle: 'Command (paged):', commandPagerStatus: '{page}/{total}', commandPagerHint: 'Tab: Next page (wraps)', multiToolPagerHint: 'Tab: View next tool group ({page}/{total})', selectAction: 'Select action:', enterRejectionReason: 'Enter rejection reason:', pressEnterToSubmit: 'Press Enter to submit', confirmed: 'Confirmed', approveOnce: 'Approve (once)', alwaysApprove: 'Approve (this project will no longer ask about this tool)', rejectWithReply: 'Reject with reply', rejectEndSession: 'Reject (end session)', }, bash: { sensitiveCommandDetected: 'SENSITIVE COMMAND DETECTED', sensitivePattern: 'Pattern:', sensitiveReason: 'Reason:', executeConfirm: 'This command requires confirmation. Proceed?', confirmHint: 'Press y to execute, n to cancel, or ESC to go back', executingCommand: 'Executing command...', timeout: 'Timeout:', customTimeout: '(custom)', backgroundHint: 'Ctrl+B to move to background', inputRequired: 'INPUT REQUIRED', inputPlaceholder: 'Type your input and press Enter', inputHint: 'Press Enter to submit input', }, scheduler: { title: 'Scheduled Task', hint: 'AI workflow is paused, waiting for countdown to finish...', }, backgroundProcesses: { title: 'Background Processes', status: 'Status', statusRunning: 'Running', statusCompleted: 'Completed', statusFailed: 'Failed', duration: 'Duration', navigateHint: '↑↓ Navigate | Enter Kill selected | ESC Close', emptyHint: 'No background processes', }, fileRollback: { title: 'File Rollback Confirmation', description: 'This checkpoint has', filesCount: '{count} file(s) will be rolled back', filesCountWithSelection: '{count} file(s) will be rolled back ({selected}/{total} selected)', notebookCount: '{count} notebook(s) will also be rolled back', teamCount: '{count} team member(s) will be terminated and worktrees cleaned up', question: 'Choose rollback mode:', conversationOnly: 'Rollback conversation only', conversationAndFiles: 'Rollback conversation + files', filesOnly: 'Rollback files only', moreAbove: 'more above...', moreBelow: 'more below...', andMoreFiles: 'and', viewAllHint: 'Tab view all', selectHint: '↑↓ select', confirmHint: 'Enter confirm', cancelHint: 'ESC cancel', scrollHint: '↑↓ scroll', navigateHint: '↑↓ navigate', toggleHint: 'Space toggle', backHint: 'Tab back', closeHint: 'ESC close', emptyHint: 'No files to rollback', noFilesConfirm: 'No file changes detected. Rollback conversation only?', noFilesConfirmHint: 'Enter confirm · ESC cancel', }, usagePanel: { title: 'Token Usage Statistics', granularity: { last24h: 'Last 24h', last7d: 'Last 7d', last30d: 'Last 30d', last12m: 'Last 12m', }, chart: { noData: 'No data available', usage: 'Usage', cacheHit: 'Cache Hit', cacheCreate: 'Cache Create', moreAbove: '↑ {count} more above (use ↑ arrow)', in: 'In:', out: 'Out:', hit: 'Hit:', create: 'Create:', total: 'TOTAL:', moreBelow: '↓ {count} more below (use ↓ arrow)', }, loading: 'Loading usage statistics...', error: 'Error: {error}', tabToSwitch: '- Tab to switch', noDataForPeriod: 'No usage data for this period', }, workingDirectoryPanel: { title: 'Working Directories', loading: 'Loading...', noDirectories: 'No directories found', defaultLabel: '[DEFAULT]', remoteLabel: '[SSH]', markedCount: '{count} director{plural} marked for deletion', markedCountSingular: 'y', markedCountPlural: 'ies', // Navigation hints navigationHint: '↑↓ Navigate | Space Mark/Unmark | A Add Local | S Add SSH | D Delete Marked | ESC Close', // Add mode addTitle: 'Add Working Directory', addPathLabel: 'Path: ', addPathPrompt: 'Enter directory path:', addErrorEmpty: 'Path cannot be empty', addErrorFailed: 'Failed to add directory (already exists or invalid path)', addHint: 'Enter to add, ESC to cancel', // SSH mode sshTitle: 'Add SSH Remote Directory', sshHostLabel: 'Host: ', sshHostPlaceholder: 'example.com', sshPortLabel: 'Port: ', sshUsernameLabel: 'Username: ', sshUsernamePlaceholder: 'root', sshAuthMethodLabel: 'Auth Method: ', sshAuthPassword: 'Password', sshAuthPrivateKey: 'Private Key', sshAuthAgent: 'SSH Agent', sshPasswordLabel: 'Password: ', sshPrivateKeyLabel: 'Key Path: ', sshPrivateKeyPlaceholder: '~/.ssh/id_rsa', sshRemotePathLabel: 'Remote Path: ', sshRemotePathPlaceholder: '/home/user/project', sshConnecting: 'Connecting...', sshTestSuccess: 'Connection successful!', sshTestFailed: 'Connection failed: {error}', sshAddSuccess: 'SSH directory added successfully', sshAddFailed: 'Failed to add SSH directory', sshHint: '↑↓ Switch fields | Enter Connect | ESC Cancel', // Delete confirmation confirmDeleteTitle: 'Confirm Delete', confirmDeleteMessage: 'Are you sure you want to delete {count} directory?', confirmDeleteMessagePlural: 'Are you sure you want to delete {count} directories?', confirmHint: 'Y to confirm, N to cancel', // Alert messages alertDefaultCannotDelete: 'Default directory cannot be deleted', }, diffReviewPanel: { title: 'Diff Review', noSnapshots: 'No file changes found in this session', navigationHint: '↑↓ navigate • Tab view files • Enter open all • ESC close', filesSuffix: '{count} files', filesViewNavigationHint: '↑↓ navigate • Tab back • Enter open all • ESC close', moreAbove: '↑ {count} more above', moreBelow: '↓ {count} more below', }, sessionListPanel: { title: 'Resume', loading: 'Loading sessions...', noResults: 'No results for "{query}"', noConversations: 'No conversations found', marked: '{count} marked', loadingMore: 'Loading...', messages: '{count} msgs', searchLabel: 'Search:', searchPlaceholder: 'Type to search', searching: 'searching...', navigationHint: 'Type to search • ↑↓ navigate • Space mark • D delete • R rename • Enter select • ESC close', moreAbove: '↑ {count} more above', moreBelow: '↓ {count} more below', scrollToLoadMore: '(scroll to load more)', untitled: 'Untitled', now: 'now', renamePrompt: 'Rename Session', renaming: 'Renaming...', renamePlaceholder: 'Enter new title', confirmDelete: 'Press D again within 1s to confirm delete ({count})', }, mcpInfoPanel: { title: 'MCP Services', loading: 'Loading MCP services...', refreshing: 'Refreshing services...', toggling: 'Toggling {service}...', refreshAll: 'Refresh all services', noServices: 'No available MCP services detected', error: 'Error: {message}', statusSystem: '(System)', statusExternal: '(External)', statusDisabled: '(Disabled)', statusFailed: 'Failed', navigationHint: '↑↓ Navigate • Enter Reconnect • Tab Toggle Service • V View Tools', pleaseWait: 'Please wait...', skillsTitle: 'Skills', noSkills: 'No skills available', skillLocationProject: '(Project)', skillLocationGlobal: '(Global)', scrollHint: '↑↓ to scroll', moreAbove: '{count} more above', moreBelow: '{count} more below', toolsListTitle: '{service} - Tool List', toolsNavigationHint: '↑↓ Navigate • Tab Toggle Tool (Global/Project) • ESC Back', toolTogglingHint: 'Toggling tool {tool}...', toolDisabled: '(Disabled)', toolScopeGlobal: '[Global]', toolScopeProject: '[Project]', mcpSourceProject: ' [Project]', mcpSourceGlobal: ' [Global]', }, skillsListPanel: { title: 'Skills', loading: 'Loading skills...', error: 'Error: {message}', noSkills: 'No skills available', locationProject: '(Project)', locationGlobal: '(Global)', statusDisabled: '(Disabled)', navigationHint: '↑↓ Navigate • Tab/Space/Enter Toggle • ESC Close', moreAbove: '↑ {count} more above', moreBelow: '↓ {count} more below', }, mcpConfigScreen: { title: 'MCP Config - Select scope to edit', scopeProject: 'Project Config', scopeGlobal: 'Global Config', navigationHint: '↑↓ Navigate • Enter Edit • ESC Back', savedSuccess: '{scope} MCP configuration saved successfully! Please use `snow` restart!', configErrors: 'Configuration errors: {errors}', reverted: 'Changes have been reverted to the previous valid configuration.', invalidJson: 'Invalid JSON format. Changes have been reverted to the previous valid configuration.', }, commandArgsPanel: { navigationHint: '\u2191\u2193 navigate Enter select Tab/ESC close', }, runningAgentsPanel: { title: 'Running Agents', noAgentsRunning: 'No agents or teammates are currently running', keyboardHint: '(Space: toggle · Enter: confirm · Esc: cancel)', selected: 'Selected: {count}', scrollHint: '↑↓ to scroll', moreAbove: '{count} more above', moreBelow: '{count} more below', subAgentLabel: '[Agent]', teammateLabel: '[Team]', }, sseServer: { started: '✓ SSE Server Started', port: 'Port', workingDir: 'Working Directory', running: 'Running', endpoints: 'Endpoints', logs: 'Logs', stopHint: 'Press Ctrl+C to stop server', }, sseDaemon: { portOccupied: 'Port {port} is already occupied by daemon (PID: {pid})', stopExistingByPort: 'Use "snow --sse-stop --sse-port {port}" to stop existing service', stopExistingByPid: 'Or use "snow --sse-stop {pid}" to stop by PID', startingDaemon: 'Starting SSE daemon (port: {port})...', daemonStarted: '✓ SSE Daemon Started', pid: 'PID', port: 'Port', workDir: 'Working Directory', timeout: 'Timeout', logFile: 'Log File', stopService: 'Stop Service', stopByPort: 'By Port', stopByPid: 'By PID', checkStatus: 'Check Status', savePidFailed: 'Failed to save PID file', daemonStartFailed: '✗ Daemon failed to start, check log file', noRunningDaemon: 'No running daemon on port {port}', readPidFailed: 'Failed to read PID file', tryRemoveInvalidPid: 'Trying to remove invalid PID file...', noDaemonForPid: 'No daemon found for PID {pid}', stoppingDaemon: 'Stopping SSE daemon (PID: {pid})...', stopProcessFailed: 'Failed to stop process', daemonStopped: '✓ SSE Daemon Stopped', processNotExists: 'Process no longer exists, cleaning up PID file', stopProcessError: 'Error stopping process', noRunningDaemons: 'No running SSE daemons', foundInvalidPids: 'Found {count} invalid PID files', cleanupHint: 'Use "snow --sse-stop --sse-port <port>" to cleanup', runningDaemons: 'Running SSE Daemons ({count})', startTime: 'Start Time', endpoint: 'Endpoint', stopCommand: 'Stop', invalidPidsStopped: 'Found {count} invalid PID files (processes stopped)', autoCleanupHint: 'These files will be automatically cleaned on next stop operation', }, newPrompt: { title: '✦ Prompt Generator', inputHint: 'Describe your requirement, AI will generate a refined prompt:', placeholder: 'Enter your requirement...', escHint: 'ESC to cancel', generating: 'Generating prompt...', previewTitle: '✓ Prompt generated:', moreLines: '({count} more lines)', actionAccept: 'Write to input', actionReject: 'Discard', actionRegenerate: 'Regenerate', actionRetry: 'Retry', actionCancel: 'Cancel', errorPrefix: 'Error: ', scrollHint: '↑↓ Scroll', }, btw: { title: '✦ BTW', thinking: 'Thinking...', escHint: 'ESC to cancel', actionClose: 'Close', errorPrefix: 'Error: ', scrollHint: '↑↓ Scroll', }, pixelEditor: { title: 'Pixel Editor', palette: 'Palette', eraser: 'Eraser', colorNumber: 'Color {n}', canvasCleared: 'Canvas cleared', clearCancelled: 'Clear cancelled', saveCancelled: 'Save cancelled', nameCannotBeEmpty: 'Name cannot be empty', savedAs: 'Saved as {name}', controlsHint: 'Arrows: move • Space: draw/erase • Enter: draw • 1-9: color • 0: erase • C: clear', controlsHintPosBrush: 'ESC/Q: back • Ctrl+S: save • Pos: ({x}, {y}) • Brush: ', saveDrawingLabel: 'Save drawing: ', namePlaceholder: 'Enter name...', escCancelHint: ' ESC cancel', confirmClearCanvas: 'Clear canvas? Press Y to confirm, any other key to cancel.', }, pixelEditorScreen: { screenTitle: 'Pixel Editor', newCanvas: 'New Canvas', manageDrawings: 'Manage Drawings', menuNavigateHint: '↑↓ navigate • Enter select • Esc back', manageTitle: 'Manage Drawings', noDrawings: 'No drawings found.', managerHint: '↑↓ navigate • Space select • D delete • S toggle exit image • Enter edit • Esc back', confirmDeleteMany: 'Confirm delete {count} item(s)? Enter/Y/D confirm, N/Esc cancel', moreAbove: '↑ {count} more above', moreBelow: '↓ {count} more below', selectedCount: 'Selected {count} item(s)', exitImageDisabled: 'Exit image disabled', failedDisableExitImage: 'Failed to disable exit image', setAsExitImage: 'Set "{name}" as exit image', }, agentPickerPanel: { title: 'Sub-Agent Selection', noAgentsWarning: 'No sub-agents configured. Please configure sub-agents first.', selectAgent: 'Select Sub-Agent', escHint: '(Press ESC to close)', noDescription: 'No description', scrollHint: '· ↑↓ to scroll', moreAbove: '{count} more above', moreBelow: '{count} more below', }, todoPickerPanel: { title: 'TODO Selection', scanning: 'Scanning project for TODO comments...', noTodosFound: 'No TODO comments found in the project', noMatchSearch: 'No TODOs match "{searchQuery}" (Total: {totalCount})', typeToClearSearch: 'Type to filter · Backspace to clear search', selectTodos: 'Select TODOs', filteringLabel: 'Filtering: "{searchQuery}"', typeToFilterHint: 'Type to filter · Backspace to clear · Space: toggle · Enter: confirm', typeToSearchHint: 'Type to search · Space: toggle · Enter: confirm · Esc: cancel', selectedCount: '{count} TODO(s) selected', noDescription: 'No description', }, exitScreen: { title: 'Goodbye', goodbye: 'Thanks for using Snow CLI', thankYou: 'See you next time', resumeSession: 'Resume Session', version: 'v{version}', }, }; ================================================ FILE: source/i18n/lang/zh-TW.ts ================================================ import type {TranslationKeys} from '../types.js'; export const zhTW: TranslationKeys = { welcome: { title: '❆ SNOW AI CLI', subtitle: '終端程式設計智能體', startChat: '開始對話', startChatInfo: '開始新的對話', resumeLastChat: '繼續上次對話', resumeLastChatInfo: '恢復最近的對話記錄', apiSettings: 'API 和模型設定', apiSettingsInfo: '配置 API 設定、AI 模型和管理配置檔案', proxySettings: '代理和瀏覽器設定', proxySettingsInfo: '配置系統代理和瀏覽器以進行網路搜尋和抓取', codebaseSettings: '代碼庫設定', codebaseSettingsInfo: '使用嵌入模型配置代碼庫索引', systemPromptSettings: '系統提示詞設定', systemPromptSettingsInfo: '配置自訂系統提示詞（覆蓋預設值）', customHeadersSettings: '自訂請求頭設定', customHeadersSettingsInfo: '為 API 請求配置自訂 HTTP 請求頭', mcpSettings: 'MCP 設定', mcpSettingsInfo: '配置模型上下文協定伺服器', subAgentSettings: '子代理設定', subAgentSettingsInfo: '配置具有自訂工具權限的子代理', sensitiveCommands: '敏感命令', sensitiveCommandsInfo: '配置即使在 YOLO 模式下也需要確認的命令', languageSettings: '語言設定', languageSettingsInfo: '切換應用語言', themeSettings: '主題設定', themeSettingsInfo: '設定主題並預覽差異檢視器', hooksSettings: 'Hooks 設定', hooksSettingsInfo: '設定 Hooks 以自訂 AI 工作流程', updateNoticeTitle: '有新版本可用', updateNoticeCurrent: '目前版本', updateNoticeLatest: '最新版本', updateNoticeRun: '更新指令', updateNoticeGithub: '專案網址', updateNow: '立即更新', updateNowInfo: '退出 CLI 並執行 "npm i -g snow-ai" 升級到最新版本', exit: '退出', exitInfo: '退出應用程式', }, menu: { navigate: '使用 ↑↓ 鍵導航,按 Enter 選擇:', }, proxyConfig: { title: '代理配置', subtitle: '配置系統代理以進行網路搜尋和抓取', enableProxy: '啟用代理:', enabled: '[✓] 已啟用', disabled: '[ ] 已停用', toggleHint: '(按 Enter 切換)', proxyPort: '代理埠:', notSet: '未設定', browserPath: '瀏覽器路徑(可選):', autoDetect: '自動偵測', searchEngine: '搜尋引擎:', errors: '錯誤:', editingHint: '編輯模式: 按 Enter 儲存並退出編輯(完成更改後按 Enter)', navigationHint: '使用 ↑↓ 在欄位間導航,按 Enter 編輯/切換,按 Ctrl+S 或 Esc 儲存並返回', browserExamplesTitle: '瀏覽器路徑範例:', browserExamplesFooter: '留空以自動偵測系統瀏覽器 (Edge/Chrome)', portValidationError: '埠必須是 1 到 65535 之間的數字', portPlaceholder: '7890', browserPathPlaceholder: '留空以自動偵測', windowsExample: '• Windows: C:\\Program Files(x86)\\Microsoft\\Edge\\Application\\msedge.exe', macosExample: '• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome', linuxExample: '• Linux: /usr/bin/chromium-browser', }, codebaseConfig: { title: '代碼庫配置', subtitle: '配置代碼庫索引和搜尋設定', settingsPosition: '設定', scrollHint: '· ↑↓ 捲動', codebaseEnabled: '啟用代碼庫:', agentReview: 'Agent 審查:', enabled: '[✓] 已啟用', disabled: '[ ] 已停用', toggleHint: '(按 Enter 切換)', embeddingType: '請求類型:', embeddingModelName: '嵌入模型名稱:', embeddingBaseUrl: '嵌入 Base URL:', embeddingApiKey: '嵌入 API 金鑰:', embeddingApiKeyOptional: '嵌入 API 金鑰(本地部署可選):', embeddingDimensions: '嵌入維度:', embeddingSettingsGroup: '嵌入模型設定', embeddingSettingsExpandHint: '(按 Enter 展開/收起)', batchSettingsGroup: '批次處理設定', batchSettingsExpandHint: '(按 Enter 展開/收起)', batchMaxLines: '批次處理最大行數:', batchConcurrency: '批次處理並行數:', notSet: '未設定', masked: '••••••••', errors: '錯誤:', editingHint: '編輯模式: 輸入編輯,Enter 儲存,Esc 取消', navigationHint: '使用 ↑↓ 導航,Enter 編輯/切換,Ctrl+S 或 Esc 儲存', validationModelNameRequired: '啟用時需要嵌入模型名稱', validationBaseUrlRequired: '啟用時需要嵌入 Base URL', validationDimensionsPositive: '嵌入維度必須大於 0', validationMaxLinesPositive: '批次處理最大行數必須大於 0', validationConcurrencyPositive: '批次處理並行數必須大於 0', validationMaxLinesPerChunkPositive: '每塊最大行數必須大於 0', validationMinLinesPerChunkPositive: '每塊最小行數必須大於 0', validationMinCharsPerChunkPositive: '每塊最小字元數必須大於 0', validationOverlapLinesNonNegative: '重疊行數必須為非負數', validationOverlapLessThanMaxLines: '重疊行數必須小於每塊最大行數', chunkingMaxLinesPerChunk: '每塊最大行數:', chunkingMinLinesPerChunk: '每塊最小行數:', chunkingMinCharsPerChunk: '每塊最小字元數:', chunkingOverlapLines: '重疊行數:', rerankingToggle: '結果重排序:', rerankingSettingsGroup: '重排序模型設定', rerankingSettingsExpandHint: '(按 Enter 展開/收起)', rerankingModelName: '模型名:', rerankingBaseUrl: 'Base URL:', rerankingApiKey: 'API 金鑰:', rerankingContextLength: '模型上下文長度:', rerankingTopN: 'Top N:', rerankingNotConfigured: '請先在「重排序模型設定」中設定模型名和 Base URL', validationRerankingModelNameRequired: '啟用重排序時需要模型名', validationRerankingBaseUrlRequired: '啟用重排序時需要 Base URL', validationRerankingContextLengthPositive: '模型上下文長度必須大於 0', validationRerankingTopNPositive: 'Top N 必須大於 0', saveError: '儲存配置失敗', gitignoreNotFound: '無法建立索引：未找到 .gitignore 檔案。請在專案中新增 .gitignore 檔案以防止索引不必要的檔案。', enterValue: '輸入值:', }, systemPromptConfig: { title: '系統提示詞管理', subtitle: '管理多個系統提示詞（支援多選啟用）', activePrompt: '已啟用提示詞:', none: '無', noPromptsConfigured: '未配置系統提示詞。按 Enter 新增一個。', availablePrompts: '可用提示詞:', actions: '操作:', activate: '切換啟用', deactivate: '全部停用', edit: '編輯', delete: '刪除', addNew: '新增新提示詞', escBack: '[ESC] 返回', navigationHint: '\u2191\u2193 \u9078\u64c7\u63d0\u793a\u8a5e | \u7a7a\u683c \u5207\u63db\u555f\u7528 | \u2190\u2192 \u9078\u64c7\u64cd\u4f5c | Enter \u78ba\u8a8d', addNewTitle: '新增新系統提示詞', editTitle: '編輯系統提示詞', nameLabel: '名稱:', contentLabel: '內容:', enterPromptName: '輸入提示詞名稱', enterPromptContent: '輸入提示詞內容', notSet: '未設定', editingHint: '↑↓: 導航欄位 | Enter: 編輯 | Ctrl+S: 儲存 | ESC: 取消', externalEditorHint: '按 E 鍵使用外部編輯器', editorNotFound: '未找到文字編輯器，請設定 EDITOR 或 VISUAL 環境變數', editorOpenFailed: '無法開啟編輯器', editorEditFailed: '編輯失敗', editorSaved: '已儲存編輯內容', confirmDelete: '確認刪除', deleteConfirmMessage: '確定要刪除', confirmHint: '按 Y 確認,N 或 ESC 取消', saveError: '儲存失敗', activeCount: '已啟用 {count} 個', }, configScreen: { title: 'API 和模型配置', subtitle: '配置 API 設定和 AI 模型', activeProfile: '當前配置:', settingsPosition: '設定', scrollHint: '· ↑↓ 捲動', moreAbove: '上方還有 {count} 項', moreBelow: '下方還有 {count} 項', profile: '配置檔案:', baseUrl: 'Base URL:', apiKey: 'API 金鑰:', requestMethod: '請求方式:', requestUrlLabel: '請求 URL: ', anthropicBeta: 'Anthropic Beta:', anthropicCacheTTL: 'Anthropic 快取時效:', anthropicCacheTTL5m: '5分鐘（預設）', anthropicCacheTTL1h: '1小時', anthropicSpeed: 'Anthropic Speed:', anthropicSpeedNotUsed: '不使用（預設）', anthropicSpeedFast: 'fast', anthropicSpeedStandard: 'standard', enablePromptOptimization: '啟用提示詞優化:', enableAutoCompress: '啟用自動壓縮:', autoCompressThreshold: '自動壓縮閾值 (%):', autoCompressThresholdHint: '算法: maxContextTokens × {percentage}% = {actualThreshold} tokens', autoCompressThresholdDesc: '當上下文超過此閾值時自動觸發壓縮 (推薦 60-80%, 過低頻繁壓縮影響性能, 過高則失去壓縮意義)', showThinking: '顯示思考過程:', streamingDisplay: '流式逐行顯示:', thinkingEnabled: '啟用思考模式:', thinkingMode: '思考模式:', thinkingModeTokens: '輸入令牌數', thinkingModeAdaptive: '自適應', thinkingBudgetTokens: '思考預算令牌數:', thinkingEffort: '思考強度:', geminiThinkingEnabled: '啟用 Gemini 思考:', geminiThinkingLevel: 'Gemini 思考級別:', responsesReasoningEnabled: '啟用 Responses 推理:', responsesReasoningEffort: 'Responses 推理強度:', responsesVerbosity: 'Responses 輸出詳細度:', responsesFastMode: 'Responses Fast (priority):', chatThinkingEnabled: '啟用 Chat 思考 (DeepSeek):', chatReasoningEffort: 'Chat 思考強度:', advancedModel: '進階模型(輸入後可以搜尋):', basicModel: '基礎模型(輸入後可以搜尋):', maxContextTokens: '最大上下文令牌:', maxTokens: '最大回复令牌數:', streamIdleTimeoutSec: '流式閒置超時(秒):', toolResultTokenLimit: '工具返回結果限制(%):', toolResultTokenLimitHint: '算法: maxContextTokens × {percentage}% = {actualLimit} tokens', toolResultTokenLimitDesc: '限制單個工具返回結果佔上下文窗口的比例 (推薦 20-40%, 過低會截斷, 過高會佔滿上下文)', notSet: '未設定', enabled: '[✓] 已啟用', disabled: '[ ] 已停用', toggleHint: '(按 Enter 切換)', enterValue: '輸入值:', createNewProfile: '建立新配置', renameProfile: '重新命名配置', enterProfileName: '輸入新配置的名稱', enterRenameProfileName: '輸入配置的新名稱', profileNameLabel: '配置名稱:', profileNamePlaceholder: '例如: work, personal, test', renameProfilePlaceholder: '輸入新的配置名稱', createHint: '按 Enter 建立,Esc 取消', renameHint: '按 Enter 重新命名,Esc 取消', deleteProfile: '刪除配置', confirmDelete: '確認刪除配置', deleteWarning: '此操作無法撤銷。你將被切換到預設配置。', confirmHint: '按 Y 確認,按 N 或 Esc 取消', loadingModels: 'API 和模型配置', loadingMessage: '正在載入可用模型...', loadingCancelHint: '按 Esc 取消並返回配置', manualInputTitle: '手動輸入模型', manualInputSubtitle: '手動輸入模型名稱', manualInputHint: '按 Enter 確認,Esc 取消', loadingError: '⚠ 無法從 API 載入模型', requestMethodChat: 'Chat Completions - 現代聊天 API (DeepSeek)', requestMethodResponses: 'Responses - 新 Responses API (2025, 內建工具)', requestMethodGemini: 'Gemini - Google Gemini API', requestMethodAnthropic: 'Anthropic - Claude API', manualInputOption: '手動輸入(輸入模型名稱)', errors: '錯誤:', cannotDeleteDefault: '無法刪除預設配置', profileNameEmpty: '配置名稱不能為空', navigationHint: '使用 ↑↓ 導航,Enter 編輯,R 重新命名,M 手動輸入,Ctrl+S 或 Esc 儲存', editingHintNumeric: '輸入數字編輯,Enter 儲存', editingHintGeneral: '按 Enter 儲存並退出編輯', modelFilterHint: '輸入過濾,↑↓ 選擇,Enter 確認,Esc 取消', effortSelectHint: '↑↓ 選擇,Enter 確認,Esc 取消', profileSelectHint: '↑↓ 選擇配置,N 建立新配置,R 重新命名,D 刪除,Enter 確認,Esc 取消', requestMethodSelectHint: '↑↓ 選擇,Enter 確認,Esc 取消', newProfile: '+ 新建', renameProfileShort: '[R] 重新命名', deleteProfileShort: '🆇 刪除', mark: '✓ 標記', cannotRenameDefault: '無法重新命名預設配置', noProfilesMarked: '請先使用空格鍵選中要刪除的配置', confirmDeleteProfiles: '確定要刪除以下 {count} 個配置嗎？', fetchingModels: '從 API 獲取模型...', fetchingHint: '根據網絡連接情況,這可能需要幾秒鐘', systemPrompt: '系統提示詞（選填）', customHeadersField: '自定義請求頭（選填）', followGlobalNone: '跟隨全域：無', followGlobal: '跟隨全域：{name}', followGlobalWithParentheses: '跟隨全域（{name}）', followGlobalNoneWithParentheses: '跟隨全域（無）', notUse: '不使用', systemPromptMultiSelectHint: '空格: 切換選中 | Enter: 確認 | Esc: 取消', modelSelectFilterLabel: '篩選:', modelSelectModelCount: '共 {count} 個模型', modelSelectScrollHint: '↑↓ 捲動瀏覽更多模型', }, customHeaders: { title: '自訂請求頭管理', subtitle: '管理多個請求頭方案並在它們之間切換', activeScheme: '活動方案:', none: '無', noSchemesConfigured: '未配置請求頭方案。按 Enter 新增一個。', availableSchemes: '可用方案:', actions: '操作:', activate: '啟用', deactivate: '停用', edit: '編輯', delete: '刪除', addNew: '新增新方案', escBack: '[ESC] 返回', navigationHint: '使用 ↑↓ 選擇方案,←→ 選擇操作,Enter 確認', addNewTitle: '新增新請求頭方案', editTitle: '編輯請求頭方案', nameLabel: '名稱:', headersLabel: '請求頭', headersConfigured: '已配置', enterSchemeName: '輸入方案名稱', notSet: '未設定', pressEnterToEdit: '按 Enter 編輯請求頭 →', editingHint: '↑↓: 導航欄位 | Enter: 編輯 | Ctrl+S: 儲存 | ESC: 取消', confirmDelete: '確認刪除', deleteConfirmMessage: '確定要刪除', confirmHint: '按 Y 確認,N 或 ESC 取消', saveError: '儲存失敗', editHeadersTitle: '編輯請求頭', headerList: '請求頭列表:', noHeadersConfigured: '未配置請求頭。按 Enter 新增一個。', addNewHeader: '[+] 新增新請求頭', headerNavigationHint: '↑↓: 導航 | Enter: 編輯/新增 | D: 刪除 | ESC: 完成', keyLabel: '鍵:', valueLabel: '值:', headerKeyPlaceholder: '請求頭鍵 (例如, X-API-Key)', headerValuePlaceholder: '請求頭值', headerEditingHint: '↑↓: 導航欄位 | Enter: 編輯 | Ctrl+S: 儲存 | ESC: 取消', }, subAgentConfig: { title: '子代理配置', titleEdit: '編輯', titleNew: '新建', subtitle: '配置具有自訂工具權限的子代理', agentName: '代理名稱:', description: '描述:', role: '角色:', roleOptional: '角色(可選):', toolSelection: '工具選擇:', agentNamePlaceholder: '輸入代理名稱...', descriptionPlaceholder: '輸入代理描述...', rolePlaceholder: '指定代理角色以指導輸出和焦點...', selectedTools: '已選擇:', toolsCount: '個工具', loadingMCP: '正在載入 MCP 服務...', mcpLoadError: '⚠', categoryCount: '({selected}/{total})', categoryMCP: '(MCP)', navigationHint: '↑↓: 導航 | ←→: 切換分類 | 空格: 切換 | A: 全選/取消全選 | Enter: 儲存 | Esc: 返回', saveSuccess: '子代理儲存成功!', saveSuccessEdit: '已更新', saveSuccessCreate: '已建立', saveError: '儲存子代理失敗', validationFailed: '驗證失敗', filesystemTools: '檔案系統工具', aceTools: 'ACE 程式碼搜尋工具', codebaseTools: '代碼庫搜尋工具', terminalTools: '終端工具', todoTools: 'TODO 管理工具', webSearchTools: '網路搜尋工具', ideTools: 'IDE 診斷工具', userInteractionTools: '用戶交互工具', skillTools: '技能工具', configProfile: '配置文件(可選):', followGlobal: '跟隨全域 ({name})', customSystemPrompt: '自定義系統提示詞(可選):', customHeaders: '自定義請求頭(可選):', noItems: '暫無可用項', moreAbove: '還有 {count} 項在上方', moreBelow: '還有 {count} 項在下方', scrollToggleHint: '↑/↓ 捲動, ←/→ 切換配置區域, 空格 切換', spaceToggleHint: '空格 切換選擇', moreTools: '還有 {count} 個工具', scrollToolsHint: '↑/↓ 捲動, 空格 切換, A 全選/全不選', builtinReadonly: ' (內建,不可編輯)', roleExpandHint: '({status} - 空格切換)', roleExpanded: '已展開', roleCollapsed: '已省略', roleViewFull: '(空格查看完整)', }, subAgentList: { title: '子代理管理', noAgents: '尚未配置子代理。', noAgentsHint: '按 "A" 新增新的子代理。', agentsCount: '子代理 ({count}):', description: '描述:', noDescription: '無描述', toolsCount: '工具: {count} 個已選擇', updated: '更新時間:', deleteConfirm: '刪除 "{name}"? (Y/N)', deleteSuccess: '子代理刪除成功!', deleteFailed: '無法刪除系統內建子代理', navigationHint: '↑↓: 導航 | Enter: 編輯 | A: 新增新代理 | D: 刪除 | Esc: 返回', }, sensitiveCommandConfig: { title: '敏感命令保護', subtitle: '配置即使在 YOLO/自動批准模式下也需要確認的命令', noCommands: '未配置命令', custom: '自訂', enabled: '已啟用', disabled: '已停用', customLabel: '自訂', // Scope scopeProject: '專案', scopeGlobal: '全域', scopeSelectTitle: '選擇新命令的作用域', scopeSelectHint: '↑↓: 導航 • Enter: 選擇 • Esc: 取消', duplicatePattern: '模式 "{pattern}" 已存在於{scope}作用域', resetScopeSelectTitle: '選擇要重設的作用域', resetGlobalDesc: '還原為預設命令', resetProjectDesc: '清空所有專案自訂命令', confirmResetScopeMessage: '⚠️ 再次按 Enter 確認重設{scope}', // Add view addTitle: '新增自訂敏感命令 ({scope})', patternLabel: '命令模式(支援萬用字元,例如 "rm*"):', patternPlaceholder: '例如: rm -rf, sudo 等', descriptionLabel: '描述:', addEditingHint: 'Tab: 切換 • Enter: 提交 • Esc: 取消', // List view actions addedMessage: '已新增: {pattern}', enabledMessage: '已啟用: {pattern}', disabledMessage: '已停用: {pattern}', deletedMessage: '已刪除: {pattern}', resetMessage: '已重設為預設命令', // Confirmation messages confirmDeleteMessage: '⚠️ 再次按 D 確認刪除 "{pattern}"', confirmResetMessage: '⚠️ 再次按 R 確認重設為預設命令', confirmHint: '再次按相同鍵確認 • Esc: 取消', // Navigation hints listNavigationHint: '↑↓: 導航 • 空格: 切換 • A: 新增 • D: 刪除 • R: 重設 • Esc: 返回', }, themeSettings: { title: '主題設定', current: '目前:', preview: '預覽:', userMessagePreview: '使用者訊息預覽:', userMessageSample: '用於檢查使用者訊息背景色是否合適。', back: '← 返回', backInfo: '返回主選單', simpleMode: '簡易模式:', simpleModeInfo: '啟用簡易模式以簡化介面', diffOpacity: 'Diff 高亮強度:', diffOpacityInfo: '調整差異高亮顯示強度，預設 100%，最低 30%，按 Enter 以 10% 循環切換', enabled: '[✓] 已啟用', disabled: '[ ] 已停用', darkTheme: '深色主題', darkThemeInfo: '經典深色配色方案', lightTheme: '淺色主題', lightThemeInfo: '經典淺色配色方案', githubDark: 'GitHub 深色', githubDarkInfo: '受 GitHub 啟發的深色主題', rainbow: '彩虹', rainbowInfo: '生動的彩虹色彩，帶來有趣的體驗', solarizedDark: 'Solarized 深色', solarizedDarkInfo: '具有精確色彩的 Solarized 深色主題', nord: 'Nord', nordInfo: '北極、北方藍調色板', tiffany: '蒂芙尼藍', tiffanyInfo: '清新優雅的蒂芙尼藍色調', macaronPink: '馬卡龍粉', macaronPinkInfo: '甜美柔和的馬卡龍粉色調', custom: '自訂', customInfo: '使用你自己的自訂顏色', editCustom: '編輯自訂主題...', editCustomInfo: '自訂主題顏色', }, customTheme: { title: '自訂主題編輯器', save: '儲存', saveInfo: '儲存自訂主題顏色', reset: '重設為預設值', resetInfo: '將所有顏色重設為預設值', back: '← 返回', backInfo: '返回主題設定', editColor: '編輯顏色', currentValue: '目前', newValue: '新值', colorFormat: '格式: #RRGGBB 或顏色名稱 (red, blue 等)', cancel: '取消', confirm: '確認', preview: '預覽', userMessagePreview: '使用者訊息預覽', userMessageSample: '用於檢查 userMessageBackground 是否合適。', colorHint: '按 Enter 編輯此顏色', }, helpPanel: { title: '🔰 鍵盤快捷鍵和說明', textEditingTitle: '📝 文字編輯:', deleteToStart: 'Ctrl+L - 從游標刪除到開頭(舊版)', deleteToEnd: 'Ctrl+R - 從游標刪除到末尾(舊版)', copyInput: 'Ctrl+O - 複製輸入框內容到系統剪貼簿', pasteImages: '{pasteKey} - 從剪貼簿貼上圖片', toggleExpandedView: 'Ctrl+T - 切換貼上文字的展開/摺疊顯示', readlineTitle: '🚀 Readline 快捷鍵:', moveToLineStart: 'Ctrl+A - 移動到行首', moveToLineEnd: 'Ctrl+E - 移動到行尾', forwardWord: 'Alt+F - 向前移動一個詞', backwardWord: 'Alt+B - 向後移動一個詞', deleteToLineEnd: 'Ctrl+K - 從游標刪除到行尾', deleteToLineStart: 'Ctrl+U - 從游標刪除到行首', deleteWord: 'Ctrl+W - 刪除游標前的詞', deleteChar: 'Ctrl+D - 刪除游標處的字元', quickAccessTitle: '🔍 快速存取:', insertFiles: '@ - 從專案插入檔案', searchContent: '@@ - 搜尋檔案內容', selectAgent: '# - 選擇子代理執行任務', showCommands: '/ - 顯示可用命令', bashModeTitle: '🔲 Bash 模式:', bashModeTrigger: '!`命令`<可選超時時長ms>', bashModeDesc: '示例: !`ls -l`<5000>', navigationTitle: '📋 導航:', navigateHistory: '↑/↓ - 導航命令/訊息歷史', selectItem: 'Tab/Enter - 在選擇器中選擇項目', cancelClose: 'ESC - 取消/關閉選擇器或中斷 AI 回應', toggleYolo: 'Shift+Tab/Ctrl+Y - 切換模式(循環: 關閉 → YOLO → YOLO+Plan → Plan → YOLO+Team → Team → 關閉)', tipsTitle: '💡 提示:', tipUseHelp: '隨時使用 /help 查看此資訊', tipShowCommands: '輸入 / 查看所有可用命令', tipInterrupt: '在 AI 回應期間按 ESC 中斷', closeHint: '按 ESC 關閉此說明面板', }, connectionPanel: { errorPrefix: '錯誤: ', loggingIn: '正在登入...', connectingToHub: '正在連線到 Hub...', connectedSuccessfully: '連線成功', title: '實例連線', statusLabel: '狀態:', statusConnected: '已連線', statusConnecting: '連線中', statusDisconnected: '未連線', savedConfigFound: '✓ 找到已儲存的連線設定', apiUrlLabel: 'API URL:', usernameLabel: '使用者名稱:', instanceLabel: '實例:', savedConfigHint: '按 Enter 使用已儲存設定繼續，按 Esc 取消', confirmDeletePrefix: '再按一次', confirmDeleteSuffix: '確認刪除', clearSavedPrefix: '按', clearSavedSuffix: '清除已儲存設定', apiBaseUrlLabel: 'API 基礎位址:', apiBaseUrlPlaceholder: '請輸入 API URL...', enterContinueEscCancel: '按 Enter 繼續，按 Esc 取消', authenticationTitle: '身分驗證', usernameFieldLabel: '使用者名稱: ', usernamePlaceholder: '請輸入使用者名稱...', passwordFieldLabel: '密碼: ', passwordPlaceholder: '請輸入密碼...', enterContinueEscBack: '↑↓ 切換輸入框, Enter 繼續, Esc 返回', instanceConfigTitle: '實例設定', loggedInAs: '✓ 已登入帳號:', instanceIdLabel: '實例 ID: ', instanceIdPlaceholder: '請輸入實例 ID...', instanceNameLabel: '實例名稱: ', instanceNamePlaceholder: '請輸入顯示名稱...', enterConnectEscBack: '↑↓ 切換輸入框, Enter 連線, Esc 返回', pleaseWait: '請稍候...', connectedSuccessfullyWithIcon: '✓ 連線成功!', pressEscToClose: '按 Esc 關閉', useCommandPrefix: '使用', useCommandSuffix: '命令中斷連線', }, commandPanel: { title: '命令面板', availableCommands: '可用命令', processingMessage: '請等待對話完成後再使用命令', scrollHint: '↑↓ 捲動', moreHidden: '隱藏 {count} 個', moreAbove: '上方還有 {count} 項', moreBelow: '下方還有 {count} 項', interactionHint: 'Tab: 補全 • Enter: 執行', commands: { help: '顯示快捷鍵和說明資訊', clear: '清空聊天上下文和對話歷史', copyLast: '複製最後一條AI回覆到剪貼簿', resume: '恢復對話', mcp: '顯示模型上下文協定服務和工具', yolo: '切換無人值守模式(自動批准所有工具)', plan: '切換計劃模式(專業規劃助手)', init: '分析專案並產生/更新 AGENTS.md 文件', ide: '連線到 VSCode 編輯器並同步上下文', compact: '使用壓縮模型壓縮對話歷史', home: '返回歡迎畫面修改設定', review: '審查工作區變更與選定提交。會開啟選擇面板，可多選並輸入備註。', gitline: '選擇 Git 提交記錄並將提交內容插入到目前輸入框', role: '開啟或建立 ROLE.md 檔案以自訂 AI 助手角色。使用 -l 或 --list 參數列出所有角色', roleSubagent: '為子代理自訂前置提示詞 (ROLE-名字.md)。使用 -l 列出，-d 刪除', usage: '查看帶有互動式圖表的令牌使用統計', export: '將聊天對話匯出到帶儲存對話方塊的文字檔案', custom: '新增自訂命令並儲存到 ~/.snow/commands', skills: '建立包含文件和範例的技能模板', skillsPicker: '選擇 Skill 並將其 SKILL.md 內容注入到輸入框', agent: '選擇並使用子代理處理特定任務', todo: '從專案檔案搜尋並選擇 TODO 註釋', todolist: '顯示目前會話的 TODO 樹並支援批次刪除', addDir: '新增工作目錄以支援多專案上下文。用法: /add-dir 或 /add-dir 路徑', reindex: '重建代碼庫索引。使用 -force 刪除現有資料庫並完全重建', codebase: '切換當前專案的代碼庫索引功能。用法: /codebase [on|off|status]', permissions: '管理永遠允許的工具權限', backend: '顯示背景處理程序面板', loop: '建立會話級循環任務。用法: /loop 5m <提示詞>', profiles: '開啟設定檔切換面板', models: '開啟模型切換面板', subAgentDepth: '設定子代理巢狀建立深度上限', vulnerabilityHunting: '切換漏洞檢查模式，進行安全性代碼分析', autoFormat: '文件編輯後自動格式化開關。用法: /auto-format [on|off|status]', simple: '切換主題簡易模式。用法: /simple [on|off|status]', toolSearch: '切換工具搜尋（漸進式工具載入）。預設啟用以節省上下文', hybridCompress: '切換混合壓縮模式（AI 摘要 + 智慧截斷，用於 /compact 和自動壓縮）', team: '切換 Agent Team 模式 - 協調多個代理在獨立 Git Worktree 中並行工作', branch: '將目前對話分叉為新分支，可用 /resume 返回原會話', worktree: '開啟 Git 分支管理面板，支援切換、新建和刪除分支', diff: '在 IDE 中查看對話的檔案修改 Diff', connect: '連接到 Snow Instance 進行 AI 處理', disconnect: '斷開目前 Snow Instance 連接', connectionStatus: '顯示目前 Snow Instance 連接狀態', newPrompt: '根據需求使用 AI 生成精煉的提示詞', pixel: '開啟終端像素編輯器', btw: '在 AI 運行時快速提問（臨時對話，不儲存上下文）', deepresearch: '執行自主多步聯網深度研究，並將帶引用的 Markdown 報告儲存到 .snow/deepresearch/', quit: '退出應用程式', }, copyLastFeedback: { noAssistantMessage: '未找到可複製的 AI 助手消息。', emptyAssistantMessage: '最後一條 AI 助手消息沒有可複製的內容。', copySuccess: '✓ 已複製最後一條 AI 消息到剪貼簿', copyFailedPrefix: '✗ 複製到剪貼簿失敗', unknownError: '未知錯誤', }, // 命令輸出消息（用於命令執行結果） commandOutput: { // 自動格式化命令消息 autoFormat: { enabled: '自動格式化: 已啟用', disabled: '自動格式化: 已停用', statusEnabled: '自動格式化: 已啟用', statusDisabled: '自動格式化: 已停用', }, // 簡易模式命令訊息 simpleMode: { enabled: '簡易模式: 已啟用', disabled: '簡易模式: 已停用', statusEnabled: '簡易模式: 已啟用', statusDisabled: '簡易模式: 已停用', }, // 導出命令消息 export: { exporting: '正在導出對話...', openingDialog: '正在開啟檔案儲存對話方塊...', cancelledByUser: '導出已被使用者取消。', }, // IDE 命令訊息 ide: { disconnected: '已中斷 IDE 連線。', noAvailableIDEs: '未偵測到可用的 IDE。請確認 IDE 已安裝 Snow CLI 擴充套件/外掛程式且正在執行。', unmatchedIDEs: '發現 {count} 個其他執行中的 IDE，但其工作區/專案目錄與目前工作目錄不相符。', connectedTo: '已連線至 {label}', connectFailed: '連線 IDE 失敗：{error}', }, branchFork: { noActiveSession: '沒有可分叉的活躍會話。', success: '對話已分叉為分支 {name}。返回原會話請執行:\n/resume {originalId}', failed: '會話分叉失敗', }, // Deep Research 命令訊息 deepResearch: { usage: '用法: /deepresearch <提示詞>\n範例: /deepresearch 對比 OpenAI Deep Research 與 Gemini Deep Research 的架構差異', }, // Loop 命令訊息 loop: { usage: '用法: /loop 5m <提示詞> | /loop 8h30m <提示詞> | /loop <提示詞> every 2 hours | /loop list | /loop cancel <id> | /loop tasks', openingTaskManager: '正在開啟任務管理員...', relatedLoopTasks: '相關迴圈任務:', noActiveLoops: '目前沒有活躍的迴圈任務。可使用 /loop 5m <提示詞> 或 /loop <提示詞> every 2 hours 建立。', loopNotFound: '找不到迴圈任務: {id}', cancelled: '已取消迴圈任務 {id}（每 {interval}）', created: '迴圈任務已建立: {id}', scheduleEvery: '排程: 每 {interval}', promptLabel: '提示詞: {prompt}', nextRun: '下次執行: {time}', sessionScopedNote: '僅限會話作用域: Snow CLI 結束後迴圈任務將停止。', usageHint: '使用 /loop list 檢視任務，或使用 /loop cancel <id> 停止某個任務。', }, }, }, fileList: { loadingFiles: '正在載入檔案...', noFilesFound: '未找到檔案', searchingDeeper: '正在搜尋更深目錄（深度 {depth}）...', scanning: '正在掃描...（已索引 {count}）', scanningDeeper: '正在搜尋更深目錄（深度 {depth}，已索引 {count}）...', deeperSearchHint: '尚有更深目錄未掃描 · 在末項按 ↓ 繼續深入搜尋', contentSearchHeader: '≡ 內容搜尋', filesHeader: '≡ 檔案 [{mode} • Ctrl+T]', treeMode: '樹狀', listMode: '清單', }, ideSelectPanel: { title: '選擇 IDE', subtitle: '連線至 IDE 以使用整合開發功能。', noneOption: '無', connectedMark: ' ✔', hint: '↑↓ 導覽 • Enter 選擇 • ESC 關閉', connecting: '正在連線...', connectSuccess: '已連線至 {label}', connectError: '連線失敗：{error}', unmatchedIDEs: '上述 {count} 個 IDE 的工作區與目前目錄不相符，選擇後將自動切換工作目錄。', unmatchedHeader: '— 切換工作目錄 —', switchWorkdirMark: ' (切換工作目錄)', switchWorkdirError: '切換工作目錄失敗：{error}', }, permissionsPanel: { title: '權限', clearAll: '全部清除', noTools: '目前沒有工具被永遠允許', hint: '↑↓ 導航 • Enter 移除 • ESC 關閉', confirmDelete: '刪除已批准的工具？', confirmClearAll: '清除全部權限？', yes: '是', no: '否', }, subAgentDepthPanel: { title: '子代理深度設定', description: '設定子代理繼續建立子代理時允許的最大深度。', currentValueLabel: '目前值:', inputLabel: '輸入深度:', invalidInput: '請輸入大於等於 0 的整數', saveSuccess: '儲存成功', hint: 'Enter 儲存 • Esc 關閉 • 僅支援數字輸入', fileHint: '此設定會持久化到專案根目錄的 .snow/settings.json', }, modelsPanel: { title: '模型切換', subtitle: 'Tab 切換標籤 | Enter 選擇', tabAdvanced: '進階模型', tabBasic: '基礎模型', tabThinking: '思考', currentModel: '目前模型:', notSet: '未設定', loadingModels: '正在載入模型...', hint: 'Enter 選擇模型 | m 手動輸入 | Esc 關閉', manualInputTitle: '手動輸入', manualInputHint: 'Enter 儲存 | Esc 關閉', filterLabel: '篩選:', manualInputOption: '手動輸入', requestMethod: '請求方式:', showThinkingProcess: '顯示思考過程:', enableThinking: '啟用思考:', thinkingMode: '思考模式:', thinkingStrength: '思考強度:', inputNumberHint: '輸入數字，Enter 儲存', escCancel: 'Esc 取消', navigationHint: '↑↓ 選擇 | Enter 切換 | Esc 關閉', notSupported: '不支援', advancedModelLabel: '進階模型', basicModelLabel: '基礎模型', thinkingLabel: '思考', requestMethodNotSupportedForThinking: '目前請求方式({requestMethod})不支援思考', requestMethodNotSupportedForThinkingStrength: '目前請求方式({requestMethod})不支援思考強度設定', anthropicSpeed: 'Speed:', saveFailed: '儲存失敗', modelSaveFailed: '模型儲存失敗', tipLabel: '提示:', modelCount: '共 {count} 個模型', scrollHint: '↑↓ 捲動瀏覽更多模型', }, profilePanel: { title: '選擇設定檔', scrollHint: '↑↓ 捲動', moreHidden: '隱藏 {count} 個', moreAbove: '上方還有 {count} 項', moreBelow: '下方還有 {count} 項', escHint: '按 ESC 關閉', editHint: '按 Tab 編輯', activeLabel: '(目前)', searchLabel: '搜尋:', noResults: '未找到符合的設定檔', }, skillsPickerPanel: { title: '選擇技能', keyboardHint: '(ESC: 取消 · Tab: 切換 · Enter: 確認)', loading: '正在載入技能...', searchLabel: '搜尋:', appendLabel: '追加:', empty: '(空)', noSkillsFound: '未找到技能', noDescription: '無描述', scrollHint: '↑↓ 捲動', moreAbove: '上方 {count} 項', moreBelow: '下方 {count} 項', }, todoListPanel: { title: '目前會話 TODO', loading: '正在載入 TODO 清單...', deleting: '正在刪除選取的 TODO...', empty: '目前會話還沒有 TODO', noActiveSession: '目前沒有活動會話', hint: '↑↓ 導航 • 空白選取 • D 刪除 • Esc 關閉', confirmModeHint: '確認刪除模式 • Enter/Y/D 確認 • N/Esc 取消', confirmDelete: '確定刪除已選取的 {count} 項嗎？', confirmDeleteHint: '按 Enter、Y 或 D 確認，按 N 或 Esc 取消', selectedCount: '已選 {count} 項', moreAbove: '上方還有 {count} 項', moreBelow: '下方還有 {count} 項', }, reviewCommitPanel: { title: '程式碼審查：選擇變更', loadingCommits: '正在載入提交記錄...', stagedLabel: '已暫存的變更', unstagedLabel: '未暫存的變更', filesLabel: '個檔案', hintEscClose: '按 ESC 關閉', hintNavigation: '↑/↓ 導航 · 空格 勾選/取消 · Enter 確認 · 直接輸入備註', loadingMoreSuffix: '（載入更多中...）', notesLabel: '備註', notesOptional: '（可選）', selectedLabel: '已選擇', errorSelectAtLeastOne: '請至少選擇一項進行審查。', }, gitLinePickerPanel: { title: 'GitLine：選擇提交記錄', loadingCommits: '正在載入提交記錄...', loadingMoreSuffix: '（載入更多中...）', noCommits: '找不到可用的提交記錄', searchLabel: '搜尋:', emptySearch: '(空)', hintNavigation: '↑/↓ 導航 · 空格 勾選 · Enter 確認 · 直接輸入篩選', selectedLabel: '已選擇', scrollToLoadMore: '(滾動載入更多)', }, hooks: { pressCtrlCAgain: '再次按 Ctrl+C 退出', exitingApplication: '正在安全退出...', }, hooksConfig: { title: 'Hooks 配置', scopeSelect: { globalHooks: '全域 Hooks', globalInfo: '儲存在使用者目錄 ~/.snow/hooks', projectHooks: '專案 Hooks', projectInfo: '儲存在專案目錄 .snow/hooks', back: '返回', backInfo: '返回', }, hookTypes: { onUserMessage: '使用者發送訊息時觸發', beforeToolCall: '在工具呼叫之前執行', afterToolCall: '在工具呼叫完成後執行', toolConfirmation: '工具的第二確認中引起的（包括敏感词汇的確認）', onSubAgentComplete: '當子代理任務完成時執行', beforeCompress: '在即將執行壓縮操作之前執行', onSessionStart: '當啟動新會話或恢復現有會話時執行', onStop: 'Stop AI流程結束前執行', }, hookList: { title: 'Hooks 配置', global: '全域', project: '專案', configured: '已配置', rules: '條規則', back: '返回', backInfo: '返回作用域選擇', }, hookDetail: { rule: '規則', actions: '個動作', matcher: '匹配器', addNewRule: '新增規則', addNewRuleInfo: '新增一條新的 Hook 規則', deleteHook: '刪除 Hook', deleteHookInfo: '刪除整個 Hook 配置檔案', back: '返回', backInfo: '返回 Hook 列表', }, ruleEdit: { title: '編輯規則', editDescription: '編輯描述', editMatcher: '編輯匹配器', editDescriptionLabel: '描述', editMatcherLabel: '匹配器', matcherHint: '逗號分隔的工具名（如 filesystem-edit,filesystem-read），一般用於 beforeToolCall/afterToolCall，其他 Hook 無需填寫', clickToEdit: '點擊編輯規則描述', clickToEditMatcher: '點擊編輯匹配器（可選，多個用逗號分隔）', enabled: '已啟用', disabled: '已停用', addAction: '新增動作', addActionInfo: '新增一個新的執行動作', deleteRule: '刪除規則', deleteRuleInfo: '刪除目前規則', saveRule: '儲存規則', saveRuleInfo: '儲存目前規則到配置檔案', cancel: '取消', cancelInfo: '返回 Hook 詳情', hint: '使用上下鍵選擇，Enter 編輯/切換，D 鍵刪除此規則', enterToSave: '按 Enter 儲存，Esc 取消', }, actionEdit: { title: '編輯 Action', enabled: '已啟用', enabledInfo: '點擊切換啟用/停用', type: '類型', typeInfo: '點擊切換類型 (command/prompt)', command: '命令', commandInfo: '點擊編輯命令', commandNotSet: '未設定', prompt: '提示', promptInfo: '點擊編輯提示內容', promptNotSet: '未設定', timeout: '超時時間', timeoutInfo: '點擊編輯超時時間（毫秒），留空表示無超時', deleteAction: '刪除動作', deleteActionInfo: '刪除目前 Action', saveAction: '儲存動作', saveActionInfo: '儲存 Action 並返回', cancel: '取消', cancelInfo: '取消並返回', hint: '使用上下鍵選擇，Enter 編輯/切換，D 鍵刪除此動作', enterToSave: '按 Enter 儲存，Esc 取消', }, }, customCommand: { title: 'Add Custom Command', nameLabel: 'Command name:', namePlaceholder: 'e.g., open', commandLabel: 'Enter the command to execute:', commandPlaceholder: 'npm run build && npm run deploy...', descriptionLabel: '描述(可選):', descriptionPlaceholder: '簡短描述...', descriptionHint: '可選，建議簡短（直接 Enter 跳過）', descriptionNotSet: '未設定', typeLabel: 'Select command type:', typeExecute: 'Execute (run in terminal)', typePrompt: 'Prompt (send to AI)', locationLabel: '選擇儲存位置:', locationGlobal: '全域', locationProject: '專案', locationGlobalInfo: '在所有專案中可用 (~/.snow/commands/)', locationProjectInfo: '僅在當前專案中可用 (.snow/commands/)', confirmSave: 'Save this custom command? (y/n)', confirmYes: 'Yes', confirmNo: 'Cancel', escCancel: 'Press ESC to cancel', resultTypeExecute: '在終端執行', resultTypePrompt: '傳送給 AI', resultLocationGlobal: '全域 (~/.snow/commands/)', resultLocationProject: '專案 (.snow/commands/)', saveSuccessMessage: "自訂命令 '{name}' 儲存成功！\n類型: {type}\n位置: {location}\n你現在可以使用 /{name}", }, chatScreen: { // Header headerTitle: '程式設計效率 x10!', headerSubtitle: '❆ SNOW AI CLI', headerExplanations: '詢問程式碼說明和偵錯協助', headerInterrupt: '在回應期間按 ESC 中斷', headerYolo: '按 Shift+Tab/Ctrl+Y: 切換模式(循環: 關閉 → YOLO → YOLO+Plan → Plan → YOLO+Team → Team → 關閉)', headerShortcuts: "快捷鍵: Ctrl+L (刪除至開頭) • Ctrl+R (刪除至末尾) • Ctrl+O (複製輸入) • {pasteKey} (貼上圖片) • '@' (檔案) • '@@' (搜尋內容) • '#' (子代理) • '/' (命令)", headerExpandedView: '按 Ctrl+T: 切換貼上文字的展開/摺疊顯示', headerWorkingDirectory: '工作目錄: {directory}', // Status messages statusThinking: '思考中...', statusDeepThinking: '深度思考中...', statusWriting: '輸出中...', statusStreaming: '串流傳輸中', statusWorking: '工作中', statusIndexing: '索引代碼庫...', statusWatcherActive: '檔案監視器已啟用 - 監控代碼變更', statusWatcherActiveShort: '檔案監視', statusFileUpdated: '已更新: {file}', statusFileUpdatedShort: '已更新', statusCreating: '建立中...', statusSaving: '儲存中...', statusCompressing: '壓縮中...', statusConnecting: '連線到 IDE...', statusConnected: 'IDE 已連線', statusConnectionFailed: '連線失敗（這不會影響任何使用） - 請確保在你的 IDE 中安裝並啟用了 Snow CLI 外掛', statusStopping: '停止中...', inputCopySuccess: '已複製輸入框內容到剪貼簿', inputCopyFailedPrefix: '複製輸入框內容失敗', // Profile switch profileCurrent: '目前設定檔', profileSwitchHint: '切換', gitBranch: 'Git分支', memoryUsageLabel: '記憶體佔用:', // Tool execution toolCall: '工具呼叫', toolThinking: '思考', toolReading: '讀取', toolWriting: '寫入', toolSearching: '搜尋', toolExecuting: '執行', toolSuccess: '✓ 成功', toolRejected: '✗ 已拒絕', // Parallel execution parallelStart: '┌─ 並行執行', parallelEnd: '└─ 執行完成', // Messages userMessage: '你', assistantMessage: '助手', commandMessage: '命令', discontinuedMessage: '└─ 使用者中斷', aiCompletionTimeMessage: '└─ AI 結束時間：{time}', // File operations fileCreated: '已建立', fileModified: '已修改', fileRead: '已讀取', fileDeleted: '已刪除', fileCount: '{count} 個檔案', fileNotFound: '檔案未找到', fileLine: '行', fileLines: '行', // Images imageAttached: '[圖片 #{index}]', // Token usage tokenTotal: '總令牌數', tokenInput: '輸入令牌', tokenOutput: '輸出令牌', tokenCached: '快取令牌', tokenCacheCreation: '快取建立', tokenCacheRead: '快取讀取', // Time timeElapsed: '已用時', timeSeconds: '{count}秒', timeMinutes: '{count}分', timeHours: '{count}時', // Errors errorGeneric: '錯誤: {message}', errorApi: 'API 錯誤: {message}', errorNetwork: '網路錯誤: {message}', errorConfig: '配置錯誤: {message}', errorCompression: '壓縮錯誤: {message}', errorCompressionFailed: '自動壓縮失敗', errorLoadSession: '載入會話失敗', errorRollback: '回復失敗', // Warnings terminalTooSmall: '⚠ 終端太小', terminalResizePrompt: '你的終端高度為 {current} 行,但至少需要 {required} 行。', terminalMinHeight: '請調整終端視窗大小以繼續。', // Compression compressionAuto: '已自動壓縮對話歷史', compressionInProgress: '正在壓縮對話歷史...', compressionSuccess: '對話歷史壓縮成功', compressionFailed: '對話歷史壓縮失敗: {error}', compressionBlockToast: '✵ 正在壓縮上下文，無法中斷，請等待完成...', reviewStartTitle: '準備開始程式碼 Review', reviewSelectedSummary: '已選：{workingTreePrefix}{commitCount} 個提交', reviewSelectedWorkingTreePrefix: 'Working Tree + ', reviewCommitsLine: '提交：{commitList}{moreSuffix}', reviewCommitsMoreSuffix: ' 等 {commitCount} 個', reviewNotesLine: '附加說明：{notes}', reviewGenerating: '正在生成 diff/patch 並請求模型審查...', reviewInterruptHint: '提示：可按 ESC 中止', // Retry retryAttempt: '重試 {current}/{max}', retryIn: '{seconds}秒後...', retryResending: '⟳ 重新發送... (嘗試 {current}/{max})', retryError: '✗ 錯誤: {message}', // Codebase codebaseIndexing: '索引代碼庫... {processed}/{total} 個檔案', codebaseIndexingShort: '索引', codebaseProgress: '{chunks} 個區塊', codebaseChunks: '個塊', codebaseSearching: '◉ 代碼庫搜尋 (嘗試 {current}/{max})', codebaseSearchAttempt: '嘗試 {current}/{max}', codebaseSearchComplete: '代碼庫搜尋完成', codebaseIndexingEnabled: '已為此專案啟用代碼庫索引', codebaseIndexingDisabled: '已為此專案禁用代碼庫索引', // IDE ideConnecting: '連線到 IDE...', ideConnected: 'IDE 已連線', ideDisconnected: 'IDE 已斷開', ideError: '連線失敗（這不會影響任何使用） - 請確保在你的 IDE 中安裝並啟用了 Snow CLI 外掛', ideActiveFile: '| {file}', ideSelectedText: '| 已選擇 {count} 個字元', // Input inputPlaceholder: '詢問我有關程式設計的任何問題...', inputProcessing: '處理中...', inputDisabled: '輸入已停用', // Shortcuts shortcutPasteImage: '貼上圖片', shortcutFileReference: '引用檔案', shortcutSearchContent: '搜尋內容', shortcutCommands: '命令', shortcutDeleteToStart: '刪除至開頭', shortcutDeleteToEnd: '刪除至末尾', shortcutCancel: '取消 (ESC)', shortcutRegenerate: '重新產生 (Ctrl+R)', shortcutToggleYolo: '切換模式 (Shift+Tab/Ctrl+Y)', // Rollback rollbackConfirm: '確認回復', rollbackFiles: '回復檔案', rollbackConversation: '僅回復對話', rollbackWarning: '將影響 {count} 個檔案', // Session chatInitializing: '初始化中...', sessionCreating: '建立第一個對話記錄檔案...', sessionLoading: '載入會話...', sessionSaving: '儲存會話...', sessionDeleting: '刪除會話...', // Rejection rejectionReason: '拒絕原因:', rejectionNoReason: '未提供原因', // Batch operations batchFile: '檔案 {index}: {path}', batchEditResults: '批次編輯結果', // Pending pendingMessageWaiting: '待處理訊息等待中...', pendingToolConfirmation: '需要工具確認', pendingMessagesTitle: '待處理訊息', pendingMessagesFooter: '工具執行完成後將自動傳送', pendingMessagesEscHint: '按 ESC 可撤回到輸入框，不會中斷目前流程', pendingMessagesImagesAttached: '已附帶 {count} 張圖片', // Press keys hints pressEscToClose: '按 ESC 關閉', pressEnterToToggle: '按 Enter 切換', pressCtrlC: 'Ctrl+C 取消', pressCtrlR: 'Ctrl+R 重新產生', pressCtrlS: 'Ctrl+S 儲存', // Context contextUsage: '上下文使用: {percentage}%', contextPercentage: '{percentage}%', contextLimit: '已達令牌限制', // ChatInput waitingForResponse: '等待回應...', moreAbove: '↑ 上方還有 {count} 條...', moreBelow: '↓ 下方還有 {count} 條...', historyNavigateHint: '↑↓ 導航 · Enter 選擇 · ESC 關閉', typeToFilterCommands: '輸入以過濾命令', contentSearchHint: '內容搜尋 • Tab/Enter 選擇 • ESC 取消', fileSearchHint: '輸入以過濾檔案 • Tab/Enter 選擇 • Ctrl+T 切換檢視 • ESC 取消', expandedViewHint: '展開檢視 • Ctrl+T 切換', yoloModeActive: '⧴ YOLO 模式已啟用 - 所有工具將自動批准無需確認', planModeActive: '⚐ Plan 模式已啟用 - 專業規劃與協調助手', vulnerabilityHuntingModeActive: '⍨ Vulnerability Hunting 模式已啟用 - 專注漏洞挖掘與安全分析', toolSearchEnabled: '♾︎ 工具搜尋已開啟 - 按需搜尋載入工具', hybridCompressEnabled: '⇌ 混合壓縮已開啟 - AI 摘要 + 智慧截斷', teamModeActive: '⚑ Agent Team 模式已啟用 - 多代理獨立 Worktree 協同工作', tokens: ' 個詞元', cached: '已快取', newCache: '新快取', }, taskManager: { title: '任務管理器', loadingTasks: '正在載入任務...', noTasksFound: '未找到任務', noTasksHint: '使用以下命令建立: snow --task "提示詞"', escToClose: 'ESC 關閉', tasksCount: '任務 ({current}/{total})', messagesCount: '{count} 則訊息', markedCount: '{count} 個已標記', navigationHint: '↑↓ 導航 • 空格 標記 • D 刪除 • R 重新整理 • Enter 檢視 • ESC 關閉', moreAbove: '↑ 上方還有 {count} 個', moreBelow: '↓ 下方還有 {count} 個', deleteConfirm: '再次按 D 確認刪除任務', deleteMultipleConfirm: '再次按 D 確認刪除 {count} 個已標記任務', taskDetailsTitle: '任務詳情', continueHint: 'C 繼續', backToList: 'ESC 返回清單', titleLabel: '標題:', statusLabel: '狀態:', createdLabel: '建立時間:', updatedLabel: '更新時間:', messagesLabel: '訊息: {count}', untitled: '無標題', statusPending: '待處理', statusRunning: '執行中', statusCompleted: '已完成', statusFailed: '失敗', taskNotCompleted: '任務尚未完成。請等待任務完成。', confirmConvertToSession: '再次按 C 確認轉換為會話(任務將被刪除)', sensitiveCommandDetected: '檢測到敏感命令', commandLabel: '命令:', approveRejectHint: '按 A 同意或按 R 拒絕', enterRejectionReason: '請輸入拒絕原因:', submitCancelHint: 'Enter 提交 • ESC 取消', }, skillsCreation: { title: '創建新技能', modeLabel: '選擇創建方式:', modeAi: 'AI 生成（輸入需求即可）', modeManual: '手動創建（生成模板）', requirementLabel: '技能需求:', requirementHint: '簡要描述你希望該技能完成什麼（生成內容將跟隨此語言）', requirementPlaceholder: '例如：生成一個用於發佈 npm 套件的技能…', generatingLabel: 'AI 生成中...', generatingMessage: '正在生成技能檔案，請稍等', filesLabel: '將創建檔案:', editName: '編輯名稱', editNameLabel: '目前技能名稱:', editNameHint: '輸入新的技能名稱（小寫字母/數字/連字符，最多 64 個字符）', editNamePlaceholder: 'new-skill-name', regenerate: '重新生成', cancel: '取消', nameLabel: '技能名稱:', nameHint: '僅使用小寫字母、數字和連字符（最多 64 個字符）', namePlaceholder: 'my-skill-name', descriptionLabel: '描述:', descriptionHint: '簡要描述此技能的用途和使用場景', descriptionPlaceholder: '簡要描述...', locationLabel: '選擇位置:', locationGlobal: '全局 (~/.snow/skills/)', locationGlobalInfo: '所有項目均可使用', locationProject: '項目 (.snow/skills/ 在項目根目錄)', locationProjectInfo: '僅在此項目中可用', confirmQuestion: '創建此技能？', confirmYes: '是，創建', confirmNo: '否，取消', escCancel: '按 ESC 取消', errorInvalidName: '無效的技能名稱', errorExistsBoth: '技能 "{name}" 在全局和項目位置都已存在', errorExistsGlobal: '技能 "{name}" 已存在於全局位置 (~/.snow/skills/)', errorExistsProject: '技能 "{name}" 已存在於項目位置 (.snow/skills/)', errorExistsAny: '技能 "{name}" 已存在，請換一個名稱', errorGeneration: 'AI 生成失敗', errorNoGeneratedContent: '缺少生成內容，請重試', resultModeAi: 'AI 生成', resultModeManual: '手動模板', createSuccessMessage: '技能 "{name}" 創建成功！\n模式: {mode}\n位置: {location}\n路徑: {path}\n\n已創建以下檔案：\n- SKILL.md（主技能文件）\n- reference.md（詳細參考）\n- examples.md（使用範例）\n- templates/template.txt（模板檔案）\n- scripts/helper.py（輔助腳本）\n\n你現在可以編輯這些檔案來自訂技能。', createErrorMessage: '創建技能失敗：{error}', errorUnknown: '未知錯誤', }, roleCreation: { title: '創建 ROLE.md', locationLabel: '選擇位置:', locationGlobal: '全局 (~/.snow/ROLE.md)', locationGlobalInfo: '所有項目均可使用', locationProject: '項目 (./ROLE.md 在項目根目錄)', locationProjectInfo: '僅在此項目中可用', confirmQuestion: '創建 ROLE.md？', confirmYes: '是，創建', confirmNo: '否，取消', escCancel: '按 ESC 取消', warningExistsGlobal: '警告：全局 ROLE.md 已存在 (~/.snow/ROLE.md)', warningExistsProject: '警告：項目 ROLE.md 已存在 (./ROLE.md)', createSuccessMessage: '創建 ROLE.md 成功\n位置: {location}\n路徑: {path}', createErrorMessage: '創建 ROLE.md 失敗：{error}', errorUnknown: '未知錯誤', }, roleDeletion: { title: '刪除 ROLE.md', locationLabel: '選擇位置:', locationGlobal: '全局 (~/.snow/ROLE.md)', locationGlobalInfo: '所有項目的 ROLE.md', locationProject: '項目 (./ROLE.md 在項目根目錄)', locationProjectInfo: '僅當前項目的 ROLE.md', confirmQuestion: '確認刪除 ROLE.md？', confirmYes: '是，刪除', confirmNo: '否，取消', escCancel: '按 ESC 取消', warningNotExistsGlobal: '警告：全局 ROLE.md 不存在 (~/.snow/ROLE.md)', warningNotExistsProject: '警告：項目 ROLE.md 不存在 (./ROLE.md)', deleteSuccessMessage: '刪除 ROLE.md 成功！\n位置: {location}\n路徑: {path}', deleteErrorMessage: '刪除 ROLE.md 失敗：{error}', errorNotFound: 'ROLE.md 檔案不存在', errorUnknown: '未知錯誤', }, roleList: { title: 'ROLE 管理', tabGlobal: '全局', tabProject: '項目', noRoles: '沒有找到角色。按 N 創建一個。', active: '啟用', switchSuccess: '角色切換成功', createSuccess: '角色創建成功', deleteSuccess: '角色刪除成功', loading: '處理中...', hints: 'Tab: 切換作用域 | Enter: 啟用 | N: 新建 | D: 刪除 | R: 覆蓋系統提示詞 | ESC: 關閉', cannotDeleteActive: '無法刪除啟用的角色', confirmDelete: '確認刪除該角色？', confirmDeleteHint: '按 Y 確認，按 N 取消', overrideTag: '覆蓋', overrideEnabled: '已啟用：使用該角色覆蓋系統提示詞', overrideDisabled: '已關閉：恢復使用預設系統提示詞', cannotOverrideInactive: '只有啟用的角色才能標記為覆蓋', }, roleSubagentCreation: { title: '建立子代理角色', locationLabel: '選擇位置:', locationGlobal: '全局 (~/.snow/)', locationGlobalInfo: '所有專案均可使用', locationProject: '專案 (專案根目錄)', locationProjectInfo: '僅在此專案中可用', selectAgentLabel: '選擇子代理:', selectAgentHint: '↑↓: 導航 | Enter: 選擇 | ESC: 返回', noAvailableAgents: '所有子代理在該位置已有角色檔案。', agentLabel: '子代理:', fileLabel: '檔案:', confirmQuestion: '建立該角色檔案？', confirmYes: '是，建立', confirmNo: '否，取消', escCancel: '按 ESC 取消', createSuccessMessage: '建立子代理角色成功！\n子代理: {agent}\n位置: {location}\n路徑: {path}', createErrorMessage: '建立子代理角色失敗：{error}', errorUnknown: '未知錯誤', }, roleSubagentDeletion: { title: '刪除子代理角色', locationLabel: '選擇位置:', locationGlobal: '全局 (~/.snow/)', locationGlobalInfo: '所有專案的子代理角色檔案', locationProject: '專案 (專案根目錄)', locationProjectInfo: '僅當前專案的子代理角色檔案', selectRoleLabel: '選擇要刪除的角色檔案:', selectRoleHint: '↑↓: 導航 | Enter: 選擇 | ESC: 返回', noRoleFiles: '該位置沒有子代理角色檔案。', fileLabel: '檔案:', confirmQuestion: '確認刪除？', confirmYes: '是，刪除', confirmNo: '否，取消', escCancel: '按 ESC 取消', deleteSuccessMessage: '刪除子代理角色成功！\n子代理: {agent}\n位置: {location}\n路徑: {path}', deleteErrorMessage: '刪除子代理角色失敗：{error}', errorNotFound: '子代理角色檔案不存在', errorUnknown: '未知錯誤', }, roleSubagentList: { title: '子代理角色管理', tabGlobal: '全局', tabProject: '專案', noRoles: '沒有找到子代理角色檔案。使用 /role-subagent 建立。', deleteSuccess: '角色檔案刪除成功', loading: '處理中...', hints: 'Tab: 切換作用域 | D: 刪除 | ESC: 關閉', confirmDelete: '確認刪除 "{name}" 的角色？', confirmDeleteHint: '按 Y 確認，按 N 取消', }, branchPanel: { title: 'Git 分支管理', notGitRepo: '目前目錄不是 Git 倉庫，無法管理分支。', noBranches: '沒有找到分支。按 N 建立一個新分支。', current: '目前', newBranchLabel: '新分支名稱:', newBranchPlaceholder: 'feature/my-new-branch', createHint: 'Enter 確認，ESC 取消', confirmDelete: '確定刪除分支 "{branch}" 嗎？', confirmDeleteHint: '按 Y 確認，按 N 取消', cannotDeleteCurrent: '無法刪除目前正在使用的分支', stashConfirm: '偵測到本地未提交的改動，是否暫存(stash)後切換到 "{branch}"？', stashConfirmHint: '按 Y 暫存並切換，按 N 取消', loading: '處理中...', hints: '↑↓: 導航 | Enter: 切換 | N: 新建分支 | D: 刪除 | ESC: 關閉', pressEscToClose: '按 ESC 關閉', }, askUser: { header: '[需要使用者輸入]', customInputOption: '自訂輸入...', customInputLabel: '自訂輸入', cancelOption: '取消', selectPrompt: '選擇一個選項:', enterResponse: '請輸入您的回答:', keyboardHints: "提示: 按 'Enter' 選擇 | 按 'e' 編輯當前選項", multiSelectHint: '多選模式', multiSelectKeyboardHints: '↑↓ 移動 | Tab 切換(自訂/取消) | 空格 切換 | 1-9 快速切換 | 回車 確認 | e 編輯', optionListScrollHint: '↑↓ 捲動', optionListMoreAbove: '上方還有 {count} 項', optionListMoreBelow: '下方還有 {count} 項', }, toolConfirmation: { header: '[工具確認]', tool: '工具:', tools: '工具:', toolsInParallel: '{count} 個工具並行執行', sensitiveCommandDetected: '檢測到敏感命令', pattern: '模式:', reason: '原因:', requiresConfirmation: '此命令即使在 YOLO/自動批准模式下也需要確認', arguments: '參數:', commandPagerTitle: '命令(翻頁):', commandPagerStatus: '{page}/{total}', commandPagerHint: 'Tab 下一頁(循環)', multiToolPagerHint: 'Tab 查看下一組工具 ({page}/{total})', selectAction: '選擇操作:', enterRejectionReason: '輸入拒絕原因:', pressEnterToSubmit: '按 Enter 提交', confirmed: '已確認', approveOnce: '批准(一次)', alwaysApprove: '批准（此項目將不再詢問此工具）', rejectWithReply: '拒絕並回覆', rejectEndSession: '拒絕（結束工作階段）', }, bash: { sensitiveCommandDetected: '偵測到敏感命令', sensitivePattern: '匹配模式:', sensitiveReason: '原因:', executeConfirm: '此命令需要確認，是否繼續執行？', confirmHint: '按 y 執行，n 取消，或 ESC 返回', executingCommand: '正在執行命令...', timeout: '逾時時間:', customTimeout: '(自訂)', backgroundHint: 'Ctrl+B 移至背景', inputRequired: '需要輸入', inputPlaceholder: '輸入內容後按 Enter 提交', inputHint: '按 Enter 提交輸入', }, scheduler: { title: '預約任務', hint: 'AI 流程已暫停，等待倒數計時結束...', }, backgroundProcesses: { title: '背景處理程序', status: '狀態', statusRunning: '執行中', statusCompleted: '已完成', statusFailed: '失敗', duration: '持續時間', navigateHint: '↑↓ 導航 | Enter 終止選取項目 | ESC 關閉', emptyHint: '無背景處理程序', }, fileRollback: { title: '檔案回滾確認', description: '此檢查點包含', filesCount: '{count} 個檔案將被回滾', filesCountWithSelection: '{count} 個檔案將被回滾 ({selected}/{total} 已選擇)', notebookCount: '{count} 條備忘錄也將被回滾', teamCount: '{count} 個團隊成員將被終止，工作區將被清理', question: '請選擇回滾方式：', conversationOnly: '僅回滾對話', conversationAndFiles: '回滾對話 + 檔案', filesOnly: '僅回滾檔案', moreAbove: '更多...', moreBelow: '更多...', andMoreFiles: '以及', viewAllHint: 'Tab 查看全部', selectHint: '↑↓ 選擇', confirmHint: 'Enter 確認', cancelHint: 'ESC 取消', scrollHint: '↑↓ 滾動', navigateHint: '↑↓ 導航', toggleHint: '空白鍵 切換', backHint: 'Tab 返回', closeHint: 'ESC 關閉', emptyHint: '無檔案可回滾', noFilesConfirm: '未偵測到檔案變更。僅回滾對話？', noFilesConfirmHint: 'Enter 確認 · ESC 取消', }, usagePanel: { title: 'Token 使用統計', granularity: { last24h: '最近24小時', last7d: '最近7天', last30d: '最近30天', last12m: '最近12個月', }, chart: { noData: '無可用資料', usage: '使用量', cacheHit: '快取命中', cacheCreate: '快取建立', moreAbove: '↑ 上方還有 {count} 個 (使用 ↑ 方向鍵)', in: '輸入:', out: '輸出:', hit: '命中:', create: '建立:', total: '總計:', moreBelow: '↓ 下方還有 {count} 個 (使用 ↓ 方向鍵)', }, loading: '載入使用統計中...', error: '錯誤: {error}', tabToSwitch: '- Tab 切換', noDataForPeriod: '此期間無使用資料', }, workingDirectoryPanel: { title: '工作目錄', loading: '載入中...', noDirectories: '未找到目錄', defaultLabel: '[預設]', remoteLabel: '[SSH]', markedCount: '已標記 {count} 個目錄以刪除', markedCountSingular: '個目錄', markedCountPlural: '個目錄', navigationHint: '↑↓ 導航 | 空格 標記/取消 | A 新增本地 | S 新增SSH | D 刪除已標記 | ESC 關閉', addTitle: '新增工作目錄', addPathLabel: '路徑: ', addPathPrompt: '輸入目錄路徑:', addErrorEmpty: '路徑不能為空', addErrorFailed: '新增目錄失敗（已存在或路徑無效）', addHint: 'Enter 新增, ESC 取消', // SSH mode sshTitle: '新增SSH遠端目錄', sshHostLabel: '主機: ', sshHostPlaceholder: 'example.com', sshPortLabel: '連接埠: ', sshUsernameLabel: '使用者名稱: ', sshUsernamePlaceholder: 'root', sshAuthMethodLabel: '認證方式: ', sshAuthPassword: '密碼', sshAuthPrivateKey: '私鑰', sshAuthAgent: 'SSH Agent', sshPasswordLabel: '密碼: ', sshPrivateKeyLabel: '金鑰路徑: ', sshPrivateKeyPlaceholder: '~/.ssh/id_rsa', sshRemotePathLabel: '遠端路徑: ', sshRemotePathPlaceholder: '/home/user/project', sshConnecting: '連線中...', sshTestSuccess: '連線成功!', sshTestFailed: '連線失敗: {error}', sshAddSuccess: 'SSH目錄新增成功', sshAddFailed: '新增SSH目錄失敗', sshHint: '↑↓ 切换欄位 | Enter 連線 | ESC 取消', confirmDeleteTitle: '確認刪除', confirmDeleteMessage: '確定要刪除 {count} 個目錄嗎？', confirmDeleteMessagePlural: '確定要刪除 {count} 個目錄嗎？', confirmHint: 'Y 確認, N 取消', alertDefaultCannotDelete: '預設目錄不能被刪除', }, diffReviewPanel: { title: 'Diff 審查', noSnapshots: '該會話沒有找到檔案變更記錄', navigationHint: '↑↓ 導航 • Tab 查看檔案 • Enter 開啟全部 • ESC 關閉', filesSuffix: '{count} 個檔案', filesViewNavigationHint: '↑↓ 導航 • Tab 返回 • Enter 開啟全部 • ESC 關閉', moreAbove: '↑ 上方還有 {count} 個', moreBelow: '↓ 下方還有 {count} 個', }, sessionListPanel: { title: '恢復會話', loading: '載入會話中...', noResults: '未找到 "{query}" 的結果', noConversations: '未找到對話', marked: '{count} 個已標記', loadingMore: '載入中...', messages: '{count} 條訊息', searchLabel: '搜尋:', searchPlaceholder: '輸入以搜尋', searching: '搜尋中...', navigationHint: '輸入以搜尋 • ↑↓ 導航 • 空格 標記 • D 刪除 • R 重新命名 • Enter 選擇 • ESC 關閉', moreAbove: '↑ 上方還有 {count} 個', moreBelow: '↓ 下方還有 {count} 個', scrollToLoadMore: '(滾動載入更多)', untitled: '無標題', now: '現在', renamePrompt: '重新命名會話', renaming: '重新命名中...', renamePlaceholder: '輸入新的標題', confirmDelete: '1 秒內再按一次 D 確認刪除（共 {count} 個）', }, mcpInfoPanel: { title: 'MCP 服務', loading: '載入 MCP 服務中...', refreshing: '重新整理服務中...', toggling: '切換 {service} 中...', refreshAll: '重新整理全部服務', noServices: '未偵測到可用的 MCP 服務', error: '錯誤: {message}', statusSystem: '(系統)', statusExternal: '(外部)', statusDisabled: '(已停用)', statusFailed: '失敗', navigationHint: '↑↓ 導航 • Enter 重新連線 • Tab 啟停服務 • V 檢視工具', pleaseWait: '請稍候...', skillsTitle: '技能', noSkills: '沒有可用的技能', skillLocationProject: '(專案)', skillLocationGlobal: '(全域)', scrollHint: '↑↓ 捲動', moreAbove: '上方還有 {count} 項', moreBelow: '下方還有 {count} 項', toolsListTitle: '{service} - 工具列表', toolsNavigationHint: '↑↓ 導航 • Tab 啟停工具 (全域/專案) • ESC 返回', toolTogglingHint: '切換工具 {tool} 中...', toolDisabled: '(已停用)', toolScopeGlobal: '[全域]', toolScopeProject: '[專案]', mcpSourceProject: ' [專案]', mcpSourceGlobal: ' [全域]', }, skillsListPanel: { title: '技能列表', loading: '載入技能中...', error: '錯誤: {message}', noSkills: '沒有可用的技能', locationProject: '(專案)', locationGlobal: '(全域)', statusDisabled: '(已停用)', navigationHint: '↑↓ 導航 • Tab/空格/Enter 啟停 • ESC 關閉', moreAbove: '↑ 上方還有 {count} 項', moreBelow: '↓ 下方還有 {count} 項', }, mcpConfigScreen: { title: 'MCP 設定 - 選擇編輯範圍', scopeProject: '專案級設定', scopeGlobal: '全域設定', navigationHint: '↑↓ 導航 • Enter 編輯 • ESC 返回', savedSuccess: '{scope} MCP 設定儲存成功！請用 `snow` 重新啟動！', configErrors: '設定錯誤: {errors}', reverted: '修改已還原至上一個有效設定。', invalidJson: 'JSON 格式無效，修改已還原至上一個有效設定。', }, commandArgsPanel: { navigationHint: '\u2191\u2193 \u5c0e\u822a Enter \u9078\u64c7 Tab/ESC \u95dc\u9589', }, runningAgentsPanel: { title: '\u57f7\u884c\u4e2d\u7684\u4ee3\u7406', noAgentsRunning: '目前沒有執行中的代理或隊友', keyboardHint: '(空白鍵: 切換 · Enter: 確認 · Esc: 取消)', selected: '已選擇: {count}', scrollHint: '↑↓ 捲動', moreAbove: '上方還有 {count} 個', moreBelow: '下方還有 {count} 個', subAgentLabel: '[代理]', teammateLabel: '[隊友]', }, sseServer: { started: '✓ SSE 伺服器已啟動', port: '連接埠', workingDir: '工作目錄', running: '執行中', endpoints: '可用端點', logs: '執行日誌', stopHint: '按 Ctrl+C 停止伺服器', }, sseDaemon: { portOccupied: '連接埠 {port} 已被守護行程占用 (PID: {pid})', stopExistingByPort: '使用 "snow --sse-stop --sse-port {port}" 停止現有服務', stopExistingByPid: '或使用 "snow --sse-stop {pid}" 通過PID停止', startingDaemon: '正在啟動 SSE 守護行程 (連接埠: {port})...', daemonStarted: '✓ SSE 守護行程已啟動', pid: 'PID', port: '連接埠', workDir: '工作目錄', timeout: '逾時時長', logFile: '日誌檔案', stopService: '停止服務', stopByPort: '通過連接埠', stopByPid: '通過PID', checkStatus: '查看狀態', savePidFailed: '儲存 PID 檔案失敗', daemonStartFailed: '✗ 守護行程啟動失敗，請檢查日誌檔案', noRunningDaemon: '連接埠 {port} 上沒有執行中的守護行程', readPidFailed: '讀取 PID 檔案失敗', tryRemoveInvalidPid: '嘗試刪除無效的 PID 檔案...', noDaemonForPid: 'PID {pid} 對應的守護行程不存在', stoppingDaemon: '正在停止 SSE 守護行程 (PID: {pid})...', stopProcessFailed: '停止行程失敗', daemonStopped: '✓ SSE 守護行程已停止', processNotExists: '行程已不存在，清理 PID 檔案', stopProcessError: '停止行程時出錯', noRunningDaemons: '沒有執行中的 SSE 守護行程', foundInvalidPids: '發現 {count} 個無效的PID檔案', cleanupHint: '使用 "snow --sse-stop --sse-port <port>" 清理', runningDaemons: '執行中的 SSE 守護行程 ({count})', startTime: '啟動時間', endpoint: '端點', stopCommand: '停止', invalidPidsStopped: '發現 {count} 個無效的PID檔案（行程已停止）', autoCleanupHint: '這些檔案會在下次停止操作時自動清理', }, newPrompt: { title: '✦ 提示詞產生器', inputHint: '描述你的需求，AI 將產生精煉的提示詞：', placeholder: '輸入你的需求...', escHint: 'ESC 取消', generating: '正在產生提示詞...', previewTitle: '✓ 提示詞已產生：', moreLines: '(還有 {count} 行)', actionAccept: '寫入輸入框', actionReject: '放棄', actionRegenerate: '重新產生', actionRetry: '重試', actionCancel: '取消', errorPrefix: '錯誤：', scrollHint: '↑↓ 捲動瀏覽', }, btw: { title: '✦ 順便問一下', thinking: '思考中...', escHint: 'ESC 取消', actionClose: '關閉', errorPrefix: '錯誤：', scrollHint: '↑↓ 捲動瀏覽', }, pixelEditor: { title: '像素編輯器', palette: '調色盤', eraser: '橡皮擦', colorNumber: '顏色 {n}', canvasCleared: '畫布已清空', clearCancelled: '已取消清空', saveCancelled: '已取消儲存', nameCannotBeEmpty: '名稱不能為空', savedAs: '已儲存為 {name}', controlsHint: '方向鍵：移動 • 空白鍵：繪製/擦除 • Enter：繪製 • 1-9：選色 • 0：擦除 • C：清空畫布', controlsHintPosBrush: 'ESC/Q：返回 • Ctrl+S：儲存 • 座標：({x}, {y}) • 筆刷： ', saveDrawingLabel: '儲存作品：', namePlaceholder: '輸入名稱...', escCancelHint: ' ESC 取消', confirmClearCanvas: '清空畫布？按 Y 確認，按其他鍵取消。', }, pixelEditorScreen: { screenTitle: '像素編輯器', newCanvas: '新建畫布', manageDrawings: '管理作品', menuNavigateHint: '↑↓ 選擇 • Enter 確認 • Esc 返回', manageTitle: '管理作品', noDrawings: '尚無作品。', managerHint: '↑↓ 移動 • 空白鍵 多選 • D 刪除 • S 切換結束畫面 • Enter 編輯 • Esc 返回', confirmDeleteMany: '確認刪除 {count} 項？Enter/Y/D 確認，N/Esc 取消', moreAbove: '↑ 上方還有 {count} 項', moreBelow: '↓ 下方還有 {count} 項', selectedCount: '已選擇 {count} 項', exitImageDisabled: '已關閉結束畫面', failedDisableExitImage: '關閉結束畫面失敗', setAsExitImage: '已將「{name}」設為結束畫面', }, agentPickerPanel: { title: '子代理選擇', noAgentsWarning: '尚未配置子代理。請先配置子代理。', selectAgent: '選擇子代理', escHint: '（按 ESC 關閉）', noDescription: '無描述', scrollHint: '· ↑↓ 捲動', moreAbove: '上方還有 {count} 項', moreBelow: '下方還有 {count} 項', }, todoPickerPanel: { title: 'TODO 選擇', scanning: '正在掃描專案中的 TODO 註釋...', noTodosFound: '專案中未找到 TODO 註釋', noMatchSearch: '沒有符合 "{searchQuery}" 的 TODO（總數：{totalCount}）', typeToClearSearch: '輸入以篩選 · 退格鍵清除搜尋', selectTodos: '選擇 TODO', filteringLabel: '篩選: "{searchQuery}"', typeToFilterHint: '輸入篩選 · 退格清除 · 空白鍵: 切換 · Enter: 確認', typeToSearchHint: '輸入搜尋 · 空白鍵: 切換 · Enter: 確認 · Esc: 取消', selectedCount: '已選擇 {count} 個 TODO', noDescription: '無描述', }, exitScreen: { title: '再見', goodbye: '感謝使用 Snow CLI', thankYou: '期待下次相見', resumeSession: '恢復會話', version: 'v{version}', }, }; ================================================ FILE: source/i18n/lang/zh.ts ================================================ import type {TranslationKeys} from '../types.js'; export const zh: TranslationKeys = { welcome: { title: '❆ SNOW AI CLI', subtitle: '终端编程智能体', startChat: '开始对话', startChatInfo: '开始新的对话', resumeLastChat: '继续上次对话', resumeLastChatInfo: '恢复最近的对话记录', apiSettings: 'API 和模型设置', apiSettingsInfo: '配置 API 设置、AI 模型和管理配置文件', proxySettings: '代理和浏览器设置', proxySettingsInfo: '配置系统代理和浏览器以进行网络搜索和抓取', codebaseSettings: '代码库设置', codebaseSettingsInfo: '使用嵌入模型配置代码库索引', systemPromptSettings: '系统提示词设置', systemPromptSettingsInfo: '配置自定义系统提示词（覆盖默认值）', customHeadersSettings: '自定义请求头设置', customHeadersSettingsInfo: '为 API 请求配置自定义 HTTP 请求头', mcpSettings: 'MCP 设置', mcpSettingsInfo: '配置模型上下文协议服务器', subAgentSettings: '子代理设置', subAgentSettingsInfo: '配置具有自定义工具权限的子代理', sensitiveCommands: '敏感命令', sensitiveCommandsInfo: '配置即使在 YOLO 模式下也需要确认的命令', languageSettings: '语言设置', languageSettingsInfo: '切换应用语言', themeSettings: '主题设置', themeSettingsInfo: '配置主题并预览差异查看器', hooksSettings: 'Hooks 设置', hooksSettingsInfo: '配置 Hooks 以自定义 AI 工作流', updateNoticeTitle: '发现新版本', updateNoticeCurrent: '当前版本', updateNoticeLatest: '最新版本', updateNoticeRun: '更新命令', updateNoticeGithub: '项目地址', updateNow: '立即更新', updateNowInfo: '退出 CLI 并执行 "npm i -g snow-ai" 升级到最新版本', exit: '退出', exitInfo: '退出应用程序', }, menu: { navigate: '使用 ↑↓ 键导航,按 Enter 选择:', }, proxyConfig: { title: '代理配置', subtitle: '配置系统代理以进行网络搜索和抓取', enableProxy: '启用代理:', enabled: '[✓] 已启用', disabled: '[ ] 已禁用', toggleHint: '(按 Enter 切换)', proxyPort: '代理端口:', notSet: '未设置', browserPath: '浏览器路径(可选):', autoDetect: '自动检测', searchEngine: '搜索引擎:', errors: '错误:', editingHint: '编辑模式: 按 Enter 保存并退出编辑(完成更改后按 Enter)', navigationHint: '使用 ↑↓ 在字段间导航,按 Enter 编辑/切换,按 Ctrl+S 或 Esc 保存并返回', browserExamplesTitle: '浏览器路径示例:', browserExamplesFooter: '留空以自动检测系统浏览器 (Edge/Chrome)', portValidationError: '端口必须是 1 到 65535 之间的数字', portPlaceholder: '7890', browserPathPlaceholder: '留空以自动检测', windowsExample: '• Windows: C:\\Program Files(x86)\\Microsoft\\Edge\\Application\\msedge.exe', macosExample: '• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome', linuxExample: '• Linux: /usr/bin/chromium-browser', }, codebaseConfig: { title: '代码库配置', subtitle: '配置代码库索引和搜索设置', settingsPosition: '设置', scrollHint: '· ↑↓ 滚动', codebaseEnabled: '启用代码库:', agentReview: 'Agent 审查:', enabled: '[✓] 已启用', disabled: '[ ] 已禁用', toggleHint: '(按 Enter 切换)', embeddingType: '请求类型:', embeddingModelName: '嵌入模型名称:', embeddingBaseUrl: '嵌入 Base URL:', embeddingApiKey: '嵌入 API 密钥:', embeddingApiKeyOptional: '嵌入 API 密钥(本地部署可选):', embeddingDimensions: '嵌入维度:', embeddingSettingsGroup: '嵌入模型配置', embeddingSettingsExpandHint: '(按 Enter 展开/收起)', batchSettingsGroup: '批处理设置', batchSettingsExpandHint: '(按 Enter 展开/收起)', batchMaxLines: '批处理最大行数:', batchConcurrency: '批处理并发数:', notSet: '未设置', masked: '••••••••', errors: '错误:', editingHint: '编辑模式: 输入编辑,Enter 保存,Esc 取消', navigationHint: '使用 ↑↓ 导航,Enter 编辑/切换,Ctrl+S 或 Esc 保存', validationModelNameRequired: '启用时需要嵌入模型名称', validationBaseUrlRequired: '启用时需要嵌入 Base URL', validationDimensionsPositive: '嵌入维度必须大于 0', validationMaxLinesPositive: '批处理最大行数必须大于 0', validationConcurrencyPositive: '批处理并发数必须大于 0', validationMaxLinesPerChunkPositive: '每块最大行数必须大于 0', validationMinLinesPerChunkPositive: '每块最小行数必须大于 0', validationMinCharsPerChunkPositive: '每块最小字符数必须大于 0', validationOverlapLinesNonNegative: '重叠行数必须为非负数', validationOverlapLessThanMaxLines: '重叠行数必须小于每块最大行数', chunkingMaxLinesPerChunk: '每块最大行数:', chunkingMinLinesPerChunk: '每块最小行数:', chunkingMinCharsPerChunk: '每块最小字符数:', chunkingOverlapLines: '重叠行数:', rerankingToggle: '结果重排序:', rerankingSettingsGroup: '重排序模型配置', rerankingSettingsExpandHint: '(按 Enter 展开/收起)', rerankingModelName: '模型名:', rerankingBaseUrl: 'Base URL:', rerankingApiKey: 'API 密钥:', rerankingContextLength: '模型上下文长度:', rerankingTopN: 'Top N:', rerankingNotConfigured: '请先在「重排序模型配置」中设置模型名和 Base URL', validationRerankingModelNameRequired: '启用重排序时需要模型名', validationRerankingBaseUrlRequired: '启用重排序时需要 Base URL', validationRerankingContextLengthPositive: '模型上下文长度必须大于 0', validationRerankingTopNPositive: 'Top N 必须大于 0', saveError: '保存配置失败', gitignoreNotFound: '无法创建索引：未找到 .gitignore 文件。请在项目中添加 .gitignore 文件以防止索引不必要的文件。', enterValue: '输入值:', }, systemPromptConfig: { title: '系统提示词管理', subtitle: '管理多个系统提示词（支持多选激活）', activePrompt: '已激活提示词:', none: '无', noPromptsConfigured: '未配置系统提示词。按 Enter 添加一个。', availablePrompts: '可用提示词:', actions: '操作:', activate: '切换激活', deactivate: '全部停用', edit: '编辑', delete: '删除', addNew: '添加新提示词', escBack: '[ESC] 返回', navigationHint: '↑↓ 选择提示词 | 空格 切换激活 | ←→ 选择操作 | Enter 确认', addNewTitle: '添加新系统提示词', editTitle: '编辑系统提示词', nameLabel: '名称:', contentLabel: '内容:', enterPromptName: '输入提示词名称', enterPromptContent: '输入提示词内容', notSet: '未设置', editingHint: '↑↓: 导航字段 | Enter: 编辑 | Ctrl+S: 保存 | ESC: 取消', externalEditorHint: '按 E 键使用外部编辑器', editorNotFound: '未找到文本编辑器，请设置 EDITOR 或 VISUAL 环境变量', editorOpenFailed: '无法打开编辑器', editorEditFailed: '编辑失败', editorSaved: '已保存编辑内容', confirmDelete: '确认删除', deleteConfirmMessage: '确定要删除', confirmHint: '按 Y 确认,N 或 ESC 取消', saveError: '保存失败', activeCount: '已激活 {count} 个', }, configScreen: { title: 'API 和模型配置', subtitle: '配置 API 设置和 AI 模型', activeProfile: '当前配置:', settingsPosition: '设置', scrollHint: '· ↑↓ 滚动', moreAbove: '上方还有 {count} 项', moreBelow: '下方还有 {count} 项', profile: '配置文件:', baseUrl: 'Base URL:', apiKey: 'API 密钥:', requestMethod: '请求方式:', requestUrlLabel: '请求 URL: ', anthropicBeta: 'Anthropic Beta:', anthropicCacheTTL: 'Anthropic 缓存时效:', anthropicCacheTTL5m: '5分钟（默认）', anthropicCacheTTL1h: '1小时', anthropicSpeed: 'Anthropic Speed:', anthropicSpeedNotUsed: '不使用（默认）', anthropicSpeedFast: 'fast', anthropicSpeedStandard: 'standard', enablePromptOptimization: '启用提示词优化:', enableAutoCompress: '启用自动压缩:', autoCompressThreshold: '自动压缩阈值 (%):', autoCompressThresholdHint: '算法: maxContextTokens × {percentage}% = {actualThreshold} tokens', autoCompressThresholdDesc: '当上下文超过此阈值时自动触发压缩 (推荐 60-80%, 过低频繁压缩影响性能, 过高则失去压缩意义)', showThinking: '显示思考过程:', streamingDisplay: '流式逐行显示:', thinkingEnabled: '启用思考模式:', thinkingMode: '思考模式:', thinkingModeTokens: '输入令牌数', thinkingModeAdaptive: '自适应', thinkingBudgetTokens: '思考预算令牌数:', thinkingEffort: '思考强度:', geminiThinkingEnabled: '启用 Gemini 思考:', geminiThinkingLevel: 'Gemini 思考级别:', responsesReasoningEnabled: '启用 Responses 推理:', responsesReasoningEffort: 'Responses 推理强度:', responsesVerbosity: 'Responses 输出详细度:', responsesFastMode: 'Responses Fast (priority):', chatThinkingEnabled: '启用 Chat 思考 (DeepSeek):', chatReasoningEffort: 'Chat 思考强度:', advancedModel: '高级模型(键入可搜索):', basicModel: '基础模型(键入可搜索):', maxContextTokens: '最大上下文令牌:', maxTokens: '最大回复令牌数:', streamIdleTimeoutSec: '流式空闲超时(秒):', toolResultTokenLimit: '工具返回结果限制(%):', toolResultTokenLimitHint: '算法: maxContextTokens × {percentage}% = {actualLimit} tokens', toolResultTokenLimitDesc: '限制单个工具返回结果占上下文窗口的比例 (推荐 20-40%, 过低会截断, 过高会占满上下文)', notSet: '未设置', enabled: '[✓] 已启用', disabled: '[ ] 已禁用', toggleHint: '(按 Enter 切换)', enterValue: '输入值:', createNewProfile: '创建新配置', renameProfile: '重命名配置', enterProfileName: '输入新配置的名称', enterRenameProfileName: '输入配置的新名称', profileNameLabel: '配置名称:', profileNamePlaceholder: '例如: work, personal, test', renameProfilePlaceholder: '输入新的配置名称', createHint: '按 Enter 创建,Esc 取消', renameHint: '按 Enter 重命名,Esc 取消', deleteProfile: '删除配置', confirmDelete: '确认删除配置', deleteWarning: '此操作无法撤销。你将被切换到默认配置。', confirmHint: '按 Y 确认,按 N 或 Esc 取消', loadingModels: 'API 和模型配置', loadingMessage: '正在加载可用模型...', loadingCancelHint: '按 Esc 取消并返回配置', manualInputTitle: '手动输入模型', manualInputSubtitle: '手动输入模型名称', manualInputHint: '按 Enter 确认,Esc 取消', loadingError: '⚠ 无法从 API 加载模型', requestMethodChat: 'Chat Completions - 现代聊天 API (DeepSeek)', requestMethodResponses: 'Responses - 新 Responses API (2025, 内置工具)', requestMethodGemini: 'Gemini - Google Gemini API', requestMethodAnthropic: 'Anthropic - Claude API', manualInputOption: '手动输入(输入模型名称)', errors: '错误:', cannotDeleteDefault: '无法删除默认配置', profileNameEmpty: '配置名称不能为空', navigationHint: '使用 ↑↓ 导航,Enter 编辑,R 重命名,M 手动输入,Ctrl+S 或 Esc 保存', editingHintNumeric: '输入数字编辑,Enter 保存', editingHintGeneral: '按 Enter 保存并退出编辑', modelFilterHint: '输入过滤,↑↓ 选择,Enter 确认,Esc 取消', effortSelectHint: '↑↓ 选择,Enter 确认,Esc 取消', profileSelectHint: '↑↓ 选择配置,N 创建新配置,R 重命名,D 删除,Enter 确认,Esc 取消', requestMethodSelectHint: '↑↓ 选择,Enter 确认,Esc 取消', newProfile: '+ 新建', renameProfileShort: '[R] 重命名', deleteProfileShort: '🆇 删除', mark: '✓ 标记', cannotRenameDefault: '无法重命名默认配置', noProfilesMarked: '请先使用空格键选中要删除的配置', confirmDeleteProfiles: '确定要删除以下 {count} 个配置吗？', fetchingModels: '从 API 获取模型...', fetchingHint: '根据网络连接情况,这可能需要几秒钟', systemPrompt: '系统提示词（选填）', customHeadersField: '自定义请求头（选填）', followGlobalNone: '跟随全局：无', followGlobal: '跟随全局：{name}', followGlobalWithParentheses: '跟随全局（{name}）', followGlobalNoneWithParentheses: '跟随全局（无）', notUse: '不使用', systemPromptMultiSelectHint: '空格: 切换选中 | Enter: 确认 | Esc: 取消', modelSelectFilterLabel: '筛选:', modelSelectModelCount: '共 {count} 个模型', modelSelectScrollHint: '↑↓ 滚动浏览更多模型', }, customHeaders: { title: '自定义请求头管理', subtitle: '管理多个请求头方案并在它们之间切换', activeScheme: '活动方案:', none: '无', noSchemesConfigured: '未配置请求头方案。按 Enter 添加一个。', availableSchemes: '可用方案:', actions: '操作:', activate: '激活', deactivate: '停用', edit: '编辑', delete: '删除', addNew: '添加新方案', escBack: '[ESC] 返回', navigationHint: '使用 ↑↓ 选择方案,←→ 选择操作,Enter 确认', addNewTitle: '添加新请求头方案', editTitle: '编辑请求头方案', nameLabel: '名称:', headersLabel: '请求头', headersConfigured: '已配置', enterSchemeName: '输入方案名称', notSet: '未设置', pressEnterToEdit: '按 Enter 编辑请求头 →', editingHint: '↑↓: 导航字段 | Enter: 编辑 | Ctrl+S: 保存 | ESC: 取消', confirmDelete: '确认删除', deleteConfirmMessage: '确定要删除', confirmHint: '按 Y 确认,N 或 ESC 取消', saveError: '保存失败', editHeadersTitle: '编辑请求头', headerList: '请求头列表:', noHeadersConfigured: '未配置请求头。按 Enter 添加一个。', addNewHeader: '[+] 添加新请求头', headerNavigationHint: '↑↓: 导航 | Enter: 编辑/添加 | D: 删除 | ESC: 完成', keyLabel: '键:', valueLabel: '值:', headerKeyPlaceholder: '请求头键 (例如, X-API-Key)', headerValuePlaceholder: '请求头值', headerEditingHint: '↑↓: 导航字段 | Enter: 编辑 | Ctrl+S: 保存 | ESC: 取消', }, subAgentConfig: { title: '子代理配置', titleEdit: '编辑', titleNew: '新建', subtitle: '配置具有自定义工具权限的子代理', agentName: '代理名称:', description: '描述:', role: '角色:', roleOptional: '角色(可选):', toolSelection: '工具选择:', agentNamePlaceholder: '输入代理名称...', descriptionPlaceholder: '输入代理描述...', rolePlaceholder: '指定代理角色以指导输出和焦点...', selectedTools: '已选择:', toolsCount: '个工具', loadingMCP: '正在加载 MCP 服务...', mcpLoadError: '⚠', categoryCount: '({selected}/{total})', categoryMCP: '(MCP)', navigationHint: '↑↓: 导航 | ←→: 切换分类 | 空格: 切换 | A: 全选/取消全选 | Enter: 保存 | Esc: 返回', saveSuccess: '子代理保存成功!', saveSuccessEdit: '已更新', saveSuccessCreate: '已创建', saveError: '保存子代理失败', validationFailed: '验证失败', filesystemTools: '文件系统工具', aceTools: 'ACE 代码搜索工具', codebaseTools: '代码库搜索工具', terminalTools: '终端工具', todoTools: 'TODO 管理工具', webSearchTools: '网络搜索工具', ideTools: 'IDE 诊断工具', userInteractionTools: '用户交互工具', skillTools: '技能工具', configProfile: '配置文件(可选):', followGlobal: '跟随全局 ({name})', customSystemPrompt: '自定义系统提示词(可选):', customHeaders: '自定义请求头(可选):', noItems: '暂无可用项', moreAbove: '还有 {count} 项', moreBelow: '还有 {count} 项', scrollToggleHint: '↑/↓ 滚动, ←/→ 切换配置区域, Space 切换', spaceToggleHint: 'Space 切换选择', moreTools: '还有 {count} 个工具', scrollToolsHint: '↑/↓ 滚动, Space 切换, A 全选/全不选', builtinReadonly: ' (内置,不可编辑)', roleExpandHint: '({status} - Space切换)', roleExpanded: '已展开', roleCollapsed: '已省略', roleViewFull: '(Space查看完整)', }, subAgentList: { title: '子代理管理', noAgents: '尚未配置子代理。', noAgentsHint: '按 "A" 添加新的子代理。', agentsCount: '子代理 ({count}):', description: '描述:', noDescription: '无描述', toolsCount: '工具: {count} 个已选择', updated: '更新时间:', deleteConfirm: '删除 "{name}"? (Y/N)', deleteSuccess: '子代理删除成功!', deleteFailed: '无法删除系统内置子代理', navigationHint: '↑↓: 导航 | Enter: 编辑 | A: 添加新代理 | D: 删除 | Esc: 返回', }, sensitiveCommandConfig: { title: '敏感命令保护', subtitle: '配置即使在 YOLO/自动批准模式下也需要确认的命令', noCommands: '未配置命令', custom: '自定义', enabled: '已启用', disabled: '已禁用', customLabel: '自定义', // Scope scopeProject: '项目', scopeGlobal: '全局', scopeSelectTitle: '选择新命令的作用域', scopeSelectHint: '↑↓: 导航 • Enter: 选择 • Esc: 取消', duplicatePattern: '模式 "{pattern}" 已存在于{scope}作用域', resetScopeSelectTitle: '选择要重置的作用域', resetGlobalDesc: '恢复为默认预设命令', resetProjectDesc: '清空所有项目自定义命令', confirmResetScopeMessage: '⚠️ 再次按 Enter 确认重置{scope}', // Add view addTitle: '添加自定义敏感命令 ({scope})', patternLabel: '命令模式(支持通配符,例如 "rm*"):', patternPlaceholder: '例如: rm -rf, sudo 等', descriptionLabel: '描述:', addEditingHint: 'Tab: 切换 • Enter: 提交 • Esc: 取消', // List view actions addedMessage: '已添加: {pattern}', enabledMessage: '已启用: {pattern}', disabledMessage: '已禁用: {pattern}', deletedMessage: '已删除: {pattern}', resetMessage: '已重置为默认命令', // Confirmation messages confirmDeleteMessage: '⚠️ 再次按 D 确认删除 "{pattern}"', confirmResetMessage: '⚠️ 再次按 R 确认重置为默认命令', confirmHint: '再次按相同键确认 • Esc: 取消', // Navigation hints listNavigationHint: '↑↓: 导航 • 空格: 切换 • A: 添加 • D: 删除 • R: 重置 • Esc: 返回', }, themeSettings: { title: '主题设置', current: '当前:', preview: '预览:', userMessagePreview: '用户消息预览:', userMessageSample: '用于检查用户消息背景色是否合适。', back: '← 返回', backInfo: '返回主菜单', simpleMode: '简易模式:', simpleModeInfo: '启用简易模式以简化界面', diffOpacity: 'Diff 高亮强度:', diffOpacityInfo: '调整差异高亮显示强度，默认 100%，最低 30%，回车按 10% 循环切换', enabled: '[✓] 已启用', disabled: '[ ] 已禁用', darkTheme: '深色主题', darkThemeInfo: '经典深色配色方案', lightTheme: '浅色主题', lightThemeInfo: '经典浅色配色方案', githubDark: 'GitHub 深色', githubDarkInfo: '受 GitHub 启发的深色主题', rainbow: '彩虹', rainbowInfo: '生动的彩虹色彩，带来有趣的体验', solarizedDark: 'Solarized 深色', solarizedDarkInfo: '具有精确色彩的 Solarized 深色主题', nord: 'Nord', nordInfo: '北极、北方蓝调色板', tiffany: '蒂芙尼蓝', tiffanyInfo: '清新优雅的蒂芙尼蓝色调', macaronPink: '马卡龙粉', macaronPinkInfo: '甜美柔和的马卡龙粉色调', custom: '自定义', customInfo: '使用您自定义的颜色', editCustom: '编辑自定义主题...', editCustomInfo: '自定义主题颜色', }, customTheme: { title: '自定义主题编辑器', save: '保存', saveInfo: '保存自定义主题颜色', reset: '重置为默认', resetInfo: '重置所有颜色为默认值', back: '← 返回', backInfo: '返回主题设置', editColor: '编辑颜色', currentValue: '当前值', newValue: '新值', colorFormat: '格式: #RRGGBB 或颜色名称 (red, blue 等)', cancel: '取消', confirm: '确认', preview: '预览', userMessagePreview: '用户消息预览', userMessageSample: '用于检查 userMessageBackground 是否合适。', colorHint: '按 Enter 编辑此颜色', }, helpPanel: { title: '🔰 键盘快捷键和帮助', textEditingTitle: '📝 文本编辑:', deleteToStart: 'Ctrl+L - 从光标删除到开头(旧版)', deleteToEnd: 'Ctrl+R - 从光标删除到末尾(旧版)', copyInput: 'Ctrl+O - 复制输入框内容到系统剪贴板', pasteImages: '{pasteKey} - 从剪贴板粘贴图片', toggleExpandedView: 'Ctrl+T - 切换粘贴文本的展开/折叠显示', readlineTitle: '🚀 Readline 快捷键:', moveToLineStart: 'Ctrl+A - 移动到行首', moveToLineEnd: 'Ctrl+E - 移动到行尾', forwardWord: 'Alt+F - 向前移动一个词', backwardWord: 'Alt+B - 向后移动一个词', deleteToLineEnd: 'Ctrl+K - 从光标删除到行尾', deleteToLineStart: 'Ctrl+U - 从光标删除到行首', deleteWord: 'Ctrl+W - 删除光标前的词', deleteChar: 'Ctrl+D - 删除光标处的字符', quickAccessTitle: '🔍 快速访问:', insertFiles: '@ - 从项目插入文件', searchContent: '@@ - 搜索文件内容', selectAgent: '# - 选择子代理执行任务', showCommands: '/ - 显示可用命令', bashModeTitle: '🔲 Bash 模式:', bashModeTrigger: '!`命令`<可选超时时长ms>', bashModeDesc: '示例: !`ls -l`<5000>', navigationTitle: '📋 导航:', navigateHistory: '↑/↓ - 导航命令/消息历史', selectItem: 'Tab/Enter - 在选择器中选择项目', cancelClose: 'ESC - 取消/关闭选择器或中断 AI 响应', toggleYolo: 'Shift+Tab/Ctrl+Y - 切换模式(循环: 关闭 → YOLO → YOLO+Plan → Plan → YOLO+Team → Team → 关闭)', tipsTitle: '💡 提示:', tipUseHelp: '随时使用 /help 查看此信息', tipShowCommands: '输入 / 查看所有可用命令', tipInterrupt: '在 AI 响应期间按 ESC 中断', closeHint: '按 ESC 关闭此帮助面板', }, connectionPanel: { errorPrefix: '错误: ', loggingIn: '正在登录...', connectingToHub: '正在连接到 Hub...', connectedSuccessfully: '连接成功', title: '实例连接', statusLabel: '状态:', statusConnected: '已连接', statusConnecting: '连接中', statusDisconnected: '未连接', savedConfigFound: '✓ 找到已保存的连接配置', apiUrlLabel: 'API URL:', usernameLabel: '用户名:', instanceLabel: '实例:', savedConfigHint: '按 Enter 使用已保存配置继续，按 Esc 取消', confirmDeletePrefix: '再按一次', confirmDeleteSuffix: '确认删除', clearSavedPrefix: '按', clearSavedSuffix: '清除已保存配置', apiBaseUrlLabel: 'API 基础地址:', apiBaseUrlPlaceholder: '请输入 API URL...', enterContinueEscCancel: '按 Enter 继续，按 Esc 取消', authenticationTitle: '身份验证', usernameFieldLabel: '用户名: ', usernamePlaceholder: '请输入用户名...', passwordFieldLabel: '密码: ', passwordPlaceholder: '请输入密码...', enterContinueEscBack: '↑↓ 切换输入框, Enter 继续, Esc 返回', instanceConfigTitle: '实例配置', loggedInAs: '✓ 已登录账号:', instanceIdLabel: '实例 ID: ', instanceIdPlaceholder: '请输入实例 ID...', instanceNameLabel: '实例名称: ', instanceNamePlaceholder: '请输入显示名称...', enterConnectEscBack: '↑↓ 切换输入框, Enter 连接, Esc 返回', pleaseWait: '请稍候...', connectedSuccessfullyWithIcon: '✓ 连接成功!', pressEscToClose: '按 Esc 关闭', useCommandPrefix: '使用', useCommandSuffix: '命令断开连接', }, commandPanel: { title: '命令面板', availableCommands: '可用命令', processingMessage: '请等待对话完成后再使用命令', scrollHint: '↑↓ 滚动', moreHidden: '隐藏 {count} 个', moreAbove: '上方还有 {count} 项', moreBelow: '下方还有 {count} 项', interactionHint: 'Tab: 补全 • Enter: 执行', commands: { help: '显示快捷键和帮助信息', clear: '清空聊天上下文和对话历史', copyLast: '复制最后一条AI回复到剪贴板', resume: '恢复对话', mcp: '显示模型上下文协议服务和工具', yolo: '切换无人值守模式(自动批准所有工具)', plan: '切换计划模式(专业规划助手)', init: '分析项目并生成/更新 AGENTS.md 文档', ide: '连接到 VSCode 编辑器并同步上下文', compact: '使用压缩模型压缩对话历史', home: '返回欢迎屏幕修改设置', review: '审查工作区变更与选定提交。会打开选择面板，可多选并输入备注。', gitline: '选择 Git 提交记录并将提交内容插入到当前输入框', role: '打开或创建 ROLE.md 文件以自定义 AI 助手角色。使用 -l 或 --list 参数列出所有角色', roleSubagent: '为子代理自定义前置提示词 (ROLE-名字.md)。使用 -l 列出，-d 删除', usage: '查看带有交互式图表的令牌使用统计', export: '将聊天对话导出到带保存对话框的文本文件', custom: '添加自定义命令并保存到 ~/.snow/commands', skills: '创建包含文档和示例的技能模板', skillsPicker: '选择 Skill 并将其 SKILL.md 内容注入到输入框', agent: '选择并使用子代理处理特定任务', todo: '从项目文件搜索并选择 TODO 注释', todolist: '显示当前会话的 TODO 树并支持批量删除', addDir: '添加工作目录以支持多项目上下文。用法: /add-dir 或 /add-dir 路径', reindex: '重建代码库索引。使用 -force 删除现有数据库并完全重建', codebase: '切换当前项目的代码库索引功能。用法: /codebase [on|off|status]', permissions: '管理始终批准的工具权限', backend: '显示后台进程面板', loop: '创建会话级循环任务。用法: /loop 5m <提示词>', profiles: '打开配置文件切换面板', models: '打开模型切换面板', subAgentDepth: '设置子代理嵌套创建深度上限', vulnerabilityHunting: '切换漏洞检查模式，进行安全性代码分析', autoFormat: '文件编辑后自动格式化开关。用法: /auto-format [on|off|status]', simple: '切换主题简易模式。用法: /simple [on|off|status]', toolSearch: '切换工具搜索（渐进式工具加载）。默认启用以节省上下文', hybridCompress: '切换混合压缩模式（AI 摘要 + 智能截断，用于 /compact 和自动压缩）', team: '切换 Agent Team 模式 - 协调多个代理在独立 Git Worktree 中并行工作', branch: '将当前对话分叉为新分支，可用 /resume 返回原会话', worktree: '打开 Git 分支管理面板，支持切换、新建和删除分支', diff: '在 IDE 中查看对话的文件修改 Diff', connect: '连接到 Snow Instance 进行 AI 处理', disconnect: '断开当前 Snow Instance 连接', connectionStatus: '显示当前 Snow Instance 连接状态', newPrompt: '根据需求使用 AI 生成精炼的提示词', pixel: '打开终端像素编辑器', btw: '在 AI 运行时快速提问（临时对话，不保存上下文）', deepresearch: '执行自主多步联网深度研究，并将带引用的 Markdown 报告保存到 .snow/deepresearch/', quit: '退出应用程序', }, copyLastFeedback: { noAssistantMessage: '未找到可复制的 AI 助手消息。', emptyAssistantMessage: '最后一条 AI 助手消息没有可复制的内容。', copySuccess: '✓ 已复制最后一条 AI 消息到剪贴板', copyFailedPrefix: '✗ 复制到剪贴板失败', unknownError: '未知错误', }, // 命令输出消息（用于命令执行结果） commandOutput: { // 自动格式化命令消息 autoFormat: { enabled: '自动格式化: 已启用', disabled: '自动格式化: 已禁用', statusEnabled: '自动格式化: 已启用', statusDisabled: '自动格式化: 已禁用', }, // 简易模式命令消息 simpleMode: { enabled: '简易模式: 已启用', disabled: '简易模式: 已禁用', statusEnabled: '简易模式: 已启用', statusDisabled: '简易模式: 已禁用', }, // 导出命令消息 export: { exporting: '正在导出对话...', openingDialog: '正在打开文件保存对话框...', cancelledByUser: '导出已被用户取消。', }, // IDE 命令消息 ide: { disconnected: '已断开 IDE 连接。', noAvailableIDEs: '未检测到可用的 IDE。请确保 IDE 已安装 Snow CLI 扩展/插件并正在运行。', unmatchedIDEs: '发现 {count} 个其他运行中的 IDE，但其工作区/项目目录与当前工作目录不匹配。', connectedTo: '已连接到 {label}', connectFailed: '连接 IDE 失败：{error}', }, branchFork: { noActiveSession: '没有可分叉的活跃会话。', success: '对话已分叉为分支 {name}。返回原会话请执行:\n/resume {originalId}', failed: '会话分叉失败', }, // Deep Research 命令消息 deepResearch: { usage: '用法: /deepresearch <提示词>\n示例: /deepresearch 对比 OpenAI Deep Research 与 Gemini Deep Research 的架构差异', }, // Loop 命令消息 loop: { usage: '用法: /loop 5m <提示词> | /loop 8h30m <提示词> | /loop <提示词> every 2 hours | /loop list | /loop cancel <id> | /loop tasks', openingTaskManager: '正在打开任务管理器...', relatedLoopTasks: '相关循环任务:', noActiveLoops: '暂无活跃的循环任务。可使用 /loop 5m <提示词> 或 /loop <提示词> every 2 hours 创建。', loopNotFound: '未找到循环任务: {id}', cancelled: '已取消循环任务 {id}（每 {interval}）', created: '循环任务已创建: {id}', scheduleEvery: '调度: 每 {interval}', promptLabel: '提示词: {prompt}', nextRun: '下次运行: {time}', sessionScopedNote: '仅限会话作用域: Snow CLI 退出后循环任务将停止。', usageHint: '使用 /loop list 查看任务，或使用 /loop cancel <id> 停止某个任务。', }, }, }, fileList: { loadingFiles: '正在加载文件...', noFilesFound: '未找到文件', searchingDeeper: '正在搜索更深目录（深度 {depth}）...', scanning: '正在扫描...（已索引 {count}）', scanningDeeper: '正在搜索更深目录（深度 {depth}，已索引 {count}）...', deeperSearchHint: '尚有更深目录未扫描 · 在末项按 ↓ 继续深入搜索', contentSearchHeader: '≡ 内容搜索', filesHeader: '≡ 文件 [{mode} • Ctrl+T]', treeMode: '树形', listMode: '列表', }, ideSelectPanel: { title: '选择 IDE', subtitle: '连接到 IDE 以使用集成开发功能。', noneOption: '无', connectedMark: ' ✔', hint: '↑↓ 导航 • Enter 选择 • ESC 关闭', connecting: '正在连接...', connectSuccess: '已连接到 {label}', connectError: '连接失败：{error}', unmatchedIDEs: '上述 {count} 个 IDE 的工作区与当前目录不匹配，选择后将自动切换工作目录。', unmatchedHeader: '— 切换工作目录 —', switchWorkdirMark: ' (切换工作目录)', switchWorkdirError: '切换工作目录失败：{error}', }, permissionsPanel: { title: '权限', clearAll: '全部清除', noTools: '暂无始终批准的工具', hint: '↑↓ 导航 • Enter 移除 • ESC 关闭', confirmDelete: '删除已批准的工具？', confirmClearAll: '清除全部权限？', yes: '是', no: '否', }, subAgentDepthPanel: { title: '子代理深度设置', description: '设置子代理继续创建子代理的最大允许深度。', currentValueLabel: '当前值:', inputLabel: '输入深度:', invalidInput: '请输入大于等于 0 的整数', saveSuccess: '保存成功', hint: 'Enter 保存 • Esc 关闭 • 仅支持数字输入', fileHint: '该设置会持久化到项目根目录的 .snow/settings.json', }, modelsPanel: { title: '模型切换', subtitle: 'Tab 切换标签 | Enter 选择', tabAdvanced: '高级模型', tabBasic: '基础模型', tabThinking: '思考', currentModel: '当前模型:', notSet: '未设置', loadingModels: '正在加载模型...', hint: 'Enter 选择模型 | m 手动输入 | Esc 关闭', manualInputTitle: '手动输入', manualInputHint: 'Enter 保存 | Esc 关闭', filterLabel: '筛选:', manualInputOption: '手动输入', requestMethod: '请求方式:', showThinkingProcess: '显示思考过程:', enableThinking: '启用思考:', thinkingMode: '思考模式:', thinkingStrength: '思考强度:', inputNumberHint: '输入数字，回车保存', escCancel: 'Esc 取消', navigationHint: '↑↓键选择 | Enter 切换 | Esc 关闭', notSupported: '不支持', advancedModelLabel: '高级模型', basicModelLabel: '基础模型', thinkingLabel: '思考', requestMethodNotSupportedForThinking: '当前请求方式({requestMethod})不支持思考', requestMethodNotSupportedForThinkingStrength: '当前请求方式({requestMethod})不支持思考强度设置', anthropicSpeed: 'Speed:', saveFailed: '保存失败', modelSaveFailed: '模型保存失败', tipLabel: '提示:', modelCount: '共 {count} 个模型', scrollHint: '↑↓ 滚动浏览更多模型', }, profilePanel: { title: '选择配置', scrollHint: '↑↓ 滚动', moreHidden: '隐藏 {count} 个', moreAbove: '上方还有 {count} 项', moreBelow: '下方还有 {count} 项', escHint: '按 ESC 关闭', editHint: '按 Tab 编辑', activeLabel: '(当前)', searchLabel: '搜索:', noResults: '未找到匹配的配置', }, skillsPickerPanel: { title: '选择技能', keyboardHint: '(ESC: 取消 · Tab: 切换 · Enter: 确认)', loading: '正在加载技能...', searchLabel: '搜索:', appendLabel: '追加:', empty: '(空)', noSkillsFound: '未找到技能', noDescription: '无描述', scrollHint: '↑↓ 滚动', moreAbove: '上方 {count} 项', moreBelow: '下方 {count} 项', }, todoListPanel: { title: '当前会话 TODO', loading: '正在加载 TODO 列表...', deleting: '正在删除选中的 TODO...', empty: '当前会话还没有 TODO', noActiveSession: '当前没有活动会话', hint: '↑↓ 导航 • 空格选中 • D 删除 • Esc 关闭', confirmModeHint: '确认删除模式 • Enter/Y/D 确认 • N/Esc 取消', confirmDelete: '确定删除已选中的 {count} 项吗？', confirmDeleteHint: '按 Enter、Y 或 D 确认，按 N 或 Esc 取消', selectedCount: '已选 {count} 项', moreAbove: '上方还有 {count} 项', moreBelow: '下方还有 {count} 项', }, reviewCommitPanel: { title: '代码审查：选择变更', loadingCommits: '正在加载提交记录...', stagedLabel: '已暂存的更改', unstagedLabel: '未暂存的更改', filesLabel: '个文件', hintEscClose: '按 ESC 关闭', hintNavigation: '↑/↓ 导航 · 空格 勾选/取消 · 回车 确认 · 直接输入备注', loadingMoreSuffix: '（加载更多中...）', notesLabel: '备注', notesOptional: '（可选）', selectedLabel: '已选择', errorSelectAtLeastOne: '请至少选择一项进行审查。', }, gitLinePickerPanel: { title: 'GitLine：选择提交记录', loadingCommits: '正在加载提交记录...', loadingMoreSuffix: '（加载更多中...）', noCommits: '未找到可用的提交记录', searchLabel: '搜索:', emptySearch: '(空)', hintNavigation: '↑/↓ 导航 · 空格 勾选 · Enter 确认 · 直接输入筛选', selectedLabel: '已选择', scrollToLoadMore: '(滚动加载更多)', }, hooks: { pressCtrlCAgain: '再次按 Ctrl+C 退出', exitingApplication: '正在安全退出...', }, hooksConfig: { title: 'Hooks 配置', scopeSelect: { globalHooks: '全局 Hooks', globalInfo: '保存在用户目录 ~/.snow/hooks', projectHooks: '项目 Hooks', projectInfo: '保存在项目目录 .snow/hooks', back: '返回', backInfo: '返回', }, hookTypes: { onUserMessage: '用户发送消息时触发', beforeToolCall: '在工具调用之前运行', afterToolCall: '在工具调用完成后运行', toolConfirmation: '工具二次确认时触发（包括敏感词检查）', onSubAgentComplete: '当子代理任务完成时运行', beforeCompress: '在即将运行压缩操作之前运行', onSessionStart: '当启动新会话或恢复现有会话时运行', onStop: 'Stop AI流程结束前运行', }, hookList: { title: 'Hooks 配置', global: '全局', project: '项目', configured: '已配置', rules: '条规则', back: '返回', backInfo: '返回作用域选择', }, hookDetail: { rule: '规则', actions: '个动作', matcher: '匹配器', addNewRule: '添加新规则', addNewRuleInfo: '添加一条新的 Hook 规则', deleteHook: '删除 Hook', deleteHookInfo: '删除整个 Hook 配置文件', back: '返回', backInfo: '返回 Hook 列表', }, ruleEdit: { title: '编辑规则', editDescription: '编辑描述', editMatcher: '编辑匹配器', editDescriptionLabel: '描述', editMatcherLabel: '匹配器', matcherHint: '逗号分隔的工具名（如 filesystem-edit,filesystem-read），一般用于 beforeToolCall/afterToolCall，其他 Hook 无需填写', clickToEdit: '点击编辑规则描述', clickToEditMatcher: '点击编辑匹配器（可选，多个用逗号分隔）', enabled: '已启用', disabled: '已禁用', addAction: '添加动作', addActionInfo: '添加一个新的执行动作', deleteRule: '删除规则', deleteRuleInfo: '删除当前规则', saveRule: '保存规则', saveRuleInfo: '保存当前规则到配置文件', cancel: '取消', cancelInfo: '返回 Hook 详情', hint: '使用上下键选择，Enter 编辑/切换，D 键删除此规则', enterToSave: '按 Enter 保存，Esc 取消', }, actionEdit: { title: '编辑 Action', enabled: '已启用', enabledInfo: '点击切换启用/禁用', type: '类型', typeInfo: '点击切换类型 (command/prompt)', command: '命令', commandInfo: '点击编辑命令', commandNotSet: '未设置', prompt: '提示', promptInfo: '点击编辑提示内容', promptNotSet: '未设置', timeout: '超时时间', timeoutInfo: '点击编辑超时时间（毫秒），留空表示无超时', deleteAction: '删除 Action', deleteActionInfo: '删除当前 Action', saveAction: '保存 Action', saveActionInfo: '保存 Action 并返回', cancel: '取消', cancelInfo: '取消并返回', hint: '使用上下键选择，Enter 编辑/切换，D 键删除此动作', enterToSave: '按 Enter 保存，Esc 取消', }, }, customCommand: { title: '添加自定义命令', nameLabel: '命令名称:', namePlaceholder: '例如: open', commandLabel: '命令内容:', commandPlaceholder: 'npm run build && npm run deploy...', descriptionLabel: '描述(可选):', descriptionPlaceholder: '简短描述...', descriptionHint: '可选，建议简短（直接回车跳过）', descriptionNotSet: '未设置', typeLabel: '选择命令类型:', typeExecute: 'Execute (在终端执行)', typePrompt: 'Prompt (发送给 AI)', locationLabel: '选择保存位置:', locationGlobal: '全局', locationProject: '项目', locationGlobalInfo: '在所有项目中可用 (~/.snow/commands/)', locationProjectInfo: '仅在当前项目中可用 (.snow/commands/)', confirmSave: '保存此自定义命令? (y/n)', confirmYes: 'Yes', confirmNo: 'Cancel', escCancel: '按 ESC 取消', resultTypeExecute: '在终端执行', resultTypePrompt: '发送给 AI', resultLocationGlobal: '全局 (~/.snow/commands/)', resultLocationProject: '项目 (.snow/commands/)', saveSuccessMessage: "自定义命令 '{name}' 保存成功！\n类型: {type}\n位置: {location}\n你现在可以使用 /{name}", }, chatScreen: { // Header headerTitle: '编程效率 x10!', headerSubtitle: '❆ SNOW AI CLI', headerExplanations: '询问代码说明和调试帮助', headerInterrupt: '在响应期间按 ESC 中断', headerYolo: '按 Shift+Tab/Ctrl+Y: 切换模式(循环: 关闭 → YOLO → YOLO+Plan → Plan → YOLO+Team → Team → 关闭)', headerShortcuts: "快捷键: Ctrl+L (删除至开头) • Ctrl+R (删除至末尾) • Ctrl+O (复制输入) • {pasteKey} (粘贴图片) • '@' (文件) • '@@' (搜索内容) • '#' (子代理) • '/' (命令)", headerExpandedView: '按 Ctrl+T: 切换粘贴文本的展开/折叠显示', headerWorkingDirectory: '工作目录: {directory}', // Status messages statusThinking: '思考中...', statusDeepThinking: '深度思考中...', statusWriting: '输出中...', statusStreaming: '流式传输中', statusWorking: '工作中', statusIndexing: '索引代码库...', statusWatcherActive: '文件监视器已激活 - 监控代码变化', statusWatcherActiveShort: '文件监视', statusFileUpdated: '已更新: {file}', statusFileUpdatedShort: '已更新', statusCreating: '创建中...', statusSaving: '保存中...', statusCompressing: '压缩中...', statusConnecting: '连接到 IDE...', statusConnected: 'IDE 已连接', statusConnectionFailed: '连接失败(这不会影响任何使用) - 请确保在你的 IDE 中安装并激活了 Snow CLI 插件', statusStopping: '停止中...', inputCopySuccess: '已复制输入框内容到剪贴板', inputCopyFailedPrefix: '复制输入框内容失败', // Profile switch profileCurrent: '当前配置', profileSwitchHint: '切换', gitBranch: 'Git分支', memoryUsageLabel: '内存占用:', // Tool execution toolCall: '工具调用', toolThinking: '思考', toolReading: '读取', toolWriting: '写入', toolSearching: '搜索', toolExecuting: '执行', toolSuccess: '✓ 成功', toolRejected: '✗ 已拒绝', // Parallel execution parallelStart: '┌─ 并行执行', parallelEnd: '└─ 执行完成', // Messages userMessage: '你', assistantMessage: '助手', commandMessage: '命令', discontinuedMessage: '└─ 用户中断', aiCompletionTimeMessage: '└─ AI 结束时间：{time}', // File operations fileCreated: '已创建', fileModified: '已修改', fileRead: '已读取', fileDeleted: '已删除', fileCount: '{count} 个文件', fileNotFound: '文件未找到', fileLine: '行', fileLines: '行', // Images imageAttached: '[图片 #{index}]', // Token usage tokenTotal: '总令牌数', tokenInput: '输入令牌', tokenOutput: '输出令牌', tokenCached: '缓存令牌', tokenCacheCreation: '缓存创建', tokenCacheRead: '缓存读取', // Time timeElapsed: '已用时', timeSeconds: '{count}秒', timeMinutes: '{count}分', timeHours: '{count}时', // Errors errorGeneric: '错误: {message}', errorApi: 'API 错误: {message}', errorNetwork: '网络错误: {message}', errorConfig: '配置错误: {message}', errorCompression: '压缩错误: {message}', errorCompressionFailed: '自动压缩失败', errorLoadSession: '加载会话失败', errorRollback: '回滚失败', // Warnings terminalTooSmall: '⚠ 终端太小', terminalResizePrompt: '你的终端高度为 {current} 行,但至少需要 {required} 行。', terminalMinHeight: '请调整终端窗口大小以继续。', // Compression compressionAuto: '已自动压缩对话历史', compressionInProgress: '正在压缩对话历史...', compressionSuccess: '对话历史压缩成功', compressionFailed: '对话历史压缩失败: {error}', compressionBlockToast: '✵ 正在压缩上下文，无法中断，请等待完成...', reviewStartTitle: '准备开始代码 Review', reviewSelectedSummary: '选中：{workingTreePrefix}{commitCount} 个提交', reviewSelectedWorkingTreePrefix: 'Working Tree + ', reviewCommitsLine: '提交：{commitList}{moreSuffix}', reviewCommitsMoreSuffix: ' 等 {commitCount} 个', reviewNotesLine: '附加说明：{notes}', reviewGenerating: '正在生成 diff/patch 并请求模型评审...', reviewInterruptHint: '提示：可按 ESC 中止', // Retry retryAttempt: '重试 {current}/{max}', retryIn: '{seconds}秒后...', retryResending: '⟳ 重新发送... (尝试 {current}/{max})', retryError: '✗ 错误: {message}', // Codebase codebaseIndexing: '索引代码库... {processed}/{total} 个文件', codebaseIndexingShort: '索引', codebaseProgress: '{chunks} 个块', codebaseChunks: '个块', codebaseSearching: '◉ 代码库搜索 (尝试 {current}/{max})', codebaseSearchAttempt: '尝试 {current}/{max}', codebaseSearchComplete: '代码库搜索完成', codebaseIndexingEnabled: '已为此项目启用代码库索引', codebaseIndexingDisabled: '已为此项目禁用代码库索引', // IDE ideConnecting: '连接到 IDE...', ideConnected: 'IDE 已连接', ideDisconnected: 'IDE 已断开', ideError: '连接失败(这不会影响任何使用) - 请确保在你的 IDE 中安装并激活了 Snow CLI 插件', ideActiveFile: '| {file}', ideSelectedText: '| 已选择 {count} 个字符', // Input inputPlaceholder: '询问我有关编程的任何问题...', inputProcessing: '处理中...', inputDisabled: '输入已禁用', // Shortcuts shortcutPasteImage: '粘贴图片', shortcutFileReference: '引用文件', shortcutSearchContent: '搜索内容', shortcutCommands: '命令', shortcutDeleteToStart: '删除至开头', shortcutDeleteToEnd: '删除至末尾', shortcutCancel: '取消 (ESC)', shortcutRegenerate: '重新生成 (Ctrl+R)', shortcutToggleYolo: '切换模式 (Shift+Tab/Ctrl+Y)', // Rollback rollbackConfirm: '确认回滚', rollbackFiles: '回滚文件', rollbackConversation: '仅回滚对话', rollbackWarning: '将影响 {count} 个文件', // Session chatInitializing: '初始化中...', sessionCreating: '创建第一个对话记录文件...', sessionLoading: '加载会话...', sessionSaving: '保存会话...', sessionDeleting: '删除会话...', // Rejection rejectionReason: '拒绝原因:', rejectionNoReason: '未提供原因', // Batch operations batchFile: '文件 {index}: {path}', batchEditResults: '批量编辑结果', // Pending pendingMessageWaiting: '待处理消息等待中...', pendingToolConfirmation: '需要工具确认', pendingMessagesTitle: '待处理消息', pendingMessagesFooter: '工具执行完成后将自动发送', pendingMessagesEscHint: '按 ESC 可撤回到输入框，不会打断当前流程', pendingMessagesImagesAttached: '已附带 {count} 张图片', // Press keys hints pressEscToClose: '按 ESC 关闭', pressEnterToToggle: '按 Enter 切换', pressCtrlC: 'Ctrl+C 取消', pressCtrlR: 'Ctrl+R 重新生成', pressCtrlS: 'Ctrl+S 保存', // Context contextUsage: '上下文使用: {percentage}%', contextPercentage: '{percentage}%', contextLimit: '已达令牌限制', // ChatInput waitingForResponse: '等待响应...', moreAbove: '↑ 上方还有 {count} 条...', moreBelow: '↓ 下方还有 {count} 条...', historyNavigateHint: '↑↓ 导航 · Enter 选择 · ESC 关闭', typeToFilterCommands: '输入以过滤命令', contentSearchHint: '内容搜索 • Tab/Enter 选择 • ESC 取消', fileSearchHint: '输入以过滤文件 • Tab/Enter 选择 • Ctrl+T 切换视图 • ESC 取消', expandedViewHint: '展开视图 • Ctrl+T 切换', yoloModeActive: '⧴ YOLO 模式已激活 - 所有工具将自动批准无需确认', planModeActive: '⚐ Plan 模式已激活 - 专业规划与协调助手', vulnerabilityHuntingModeActive: '⍨ Vulnerability Hunting 模式已激活 - 专注漏洞挖掘与安全分析', toolSearchEnabled: '♾︎ 工具搜索已开启 - 按需搜索加载工具', hybridCompressEnabled: '⇌ 混合压缩已开启 - AI 摘要 + 智能截断', teamModeActive: '⚑ Agent Team 模式已激活 - 多代理独立 Worktree 协同工作', tokens: ' 个词元', cached: '已缓存', newCache: '新缓存', }, taskManager: { title: '任务管理器', loadingTasks: '正在加载任务...', noTasksFound: '未找到任务', noTasksHint: '使用以下命令创建: snow --task "提示词"', escToClose: 'ESC 关闭', tasksCount: '任务 ({current}/{total})', messagesCount: '{count} 条消息', markedCount: '{count} 个已标记', navigationHint: '↑↓ 导航 • 空格 标记 • D 删除 • R 刷新 • Enter 查看 • ESC 关闭', moreAbove: '↑ 上方还有 {count} 个', moreBelow: '↓ 下方还有 {count} 个', deleteConfirm: '再次按 D 确认删除任务', deleteMultipleConfirm: '再次按 D 确认删除 {count} 个已标记任务', taskDetailsTitle: '任务详情', continueHint: 'C 继续', backToList: 'ESC 返回列表', titleLabel: '标题:', statusLabel: '状态:', createdLabel: '创建时间:', updatedLabel: '更新时间:', messagesLabel: '消息: {count}', untitled: '无标题', statusPending: '待处理', statusRunning: '运行中', statusCompleted: '已完成', statusFailed: '失败', taskNotCompleted: '任务尚未完成。请等待任务完成。', confirmConvertToSession: '再次按 C 确认转换为会话(任务将被删除)', sensitiveCommandDetected: '检测到敏感命令', commandLabel: '命令:', approveRejectHint: '按 A 同意或按 R 拒绝', enterRejectionReason: '请输入拒绝原因:', submitCancelHint: 'Enter 提交 • ESC 取消', }, skillsCreation: { title: '创建新技能', modeLabel: '选择创建方式:', modeAi: 'AI 生成（输入需求即可）', modeManual: '手动创建（生成模板）', requirementLabel: '技能需求:', requirementHint: '简要描述你希望该技能完成什么（生成内容将跟随此语言）', requirementPlaceholder: '例如：生成一个用于发布 npm 包的技能…', generatingLabel: 'AI 生成中...', generatingMessage: '正在生成技能文件，请稍等', filesLabel: '将创建文件:', editName: '编辑名称', editNameLabel: '当前技能名称:', editNameHint: '输入新的技能名称（小写字母/数字/连字符，最多 64 个字符）', editNamePlaceholder: 'new-skill-name', regenerate: '重新生成', cancel: '取消', nameLabel: '技能名称:', nameHint: '仅使用小写字母、数字和连字符，可用 "/" 作为命名空间分隔（每段最多 64 个字符）', namePlaceholder: 'team/my-skill-name', descriptionLabel: '描述:', descriptionHint: '简要描述此技能的用途和使用场景', descriptionPlaceholder: '简要描述...', locationLabel: '选择位置:', locationGlobal: '全局 (~/.snow/skills/)', locationGlobalInfo: '所有项目均可使用', locationProject: '项目 (.snow/skills/ 在项目根目录)', locationProjectInfo: '仅在此项目中可用', confirmQuestion: '创建此技能？', confirmYes: '是，创建', confirmNo: '否，取消', escCancel: '按 ESC 取消', // 错误消息 errorInvalidName: '无效的技能名称', errorExistsBoth: '技能 "{name}" 在全局和项目位置都已存在', errorExistsGlobal: '技能 "{name}" 已存在于全局位置 (~/.snow/skills/)', errorExistsProject: '技能 "{name}" 已存在于项目位置 (.snow/skills/)', errorExistsAny: '技能 "{name}" 已存在，请换一个名称', errorGeneration: 'AI 生成失败', errorNoGeneratedContent: '缺少生成内容，请重试', resultModeAi: 'AI 生成', resultModeManual: '手动模板', createSuccessMessage: '技能 "{name}" 创建成功！\n模式: {mode}\n位置: {location}\n路径: {path}\n\n已创建以下文件：\n- SKILL.md（主技能文档）\n- reference.md（详细参考）\n- examples.md（使用示例）\n- templates/template.txt（模板文件）\n- scripts/helper.py（辅助脚本）\n\n你现在可以编辑这些文件来自定义技能。', createErrorMessage: '创建技能失败：{error}', errorUnknown: '未知错误', }, roleCreation: { title: '创建 ROLE.md', locationLabel: '选择位置:', locationGlobal: '全局 (~/.snow/ROLE.md)', locationGlobalInfo: '所有项目均可使用', locationProject: '项目 (./ROLE.md 在项目根目录)', locationProjectInfo: '仅在此项目中可用', confirmQuestion: '创建 ROLE.md？', confirmYes: '是，创建', confirmNo: '否，取消', escCancel: '按 ESC 取消', warningExistsGlobal: '警告：全局 ROLE.md 已存在 (~/.snow/ROLE.md)', warningExistsProject: '警告：项目 ROLE.md 已存在 (./ROLE.md)', createSuccessMessage: '创建 ROLE.md 成功！\n位置: {location}\n路径: {path}', createErrorMessage: '创建 ROLE.md 失败：{error}', errorUnknown: '未知错误', }, roleDeletion: { title: '删除 ROLE.md', locationLabel: '选择位置:', locationGlobal: '全局 (~/.snow/ROLE.md)', locationGlobalInfo: '所有项目的 ROLE.md', locationProject: '项目 (./ROLE.md 在项目根目录)', locationProjectInfo: '仅当前项目的 ROLE.md', confirmQuestion: '确认删除 ROLE.md？', confirmYes: '是，删除', confirmNo: '否，取消', escCancel: '按 ESC 取消', warningNotExistsGlobal: '警告：全局 ROLE.md 不存在 (~/.snow/ROLE.md)', warningNotExistsProject: '警告：项目 ROLE.md 不存在 (./ROLE.md)', deleteSuccessMessage: '删除 ROLE.md 成功！\n位置: {location}\n路径: {path}', deleteErrorMessage: '删除 ROLE.md 失败：{error}', errorNotFound: 'ROLE.md 文件不存在', errorUnknown: '未知错误', }, roleList: { title: 'ROLE 管理', tabGlobal: '全局', tabProject: '项目', noRoles: '没有找到角色。按 N 创建一个。', active: '激活', switchSuccess: '角色切换成功', createSuccess: '角色创建成功', deleteSuccess: '角色删除成功', loading: '处理中...', hints: 'Tab: 切换作用域 | Enter: 激活 | N: 新建 | D: 删除 | R: 覆盖系统提示词 | ESC: 关闭', cannotDeleteActive: '无法删除激活的角色', confirmDelete: '确认删除该角色？', confirmDeleteHint: '按 Y 确认，按 N 取消', overrideTag: '覆盖', overrideEnabled: '已启用：使用该角色覆盖系统提示词', overrideDisabled: '已关闭：恢复使用默认系统提示词', cannotOverrideInactive: '只有激活的角色才能标记为覆盖', }, roleSubagentCreation: { title: '创建子代理角色', locationLabel: '选择位置:', locationGlobal: '全局 (~/.snow/)', locationGlobalInfo: '所有项目均可使用', locationProject: '项目 (项目根目录)', locationProjectInfo: '仅在此项目中可用', selectAgentLabel: '选择子代理:', selectAgentHint: '↑↓: 导航 | Enter: 选择 | ESC: 返回', noAvailableAgents: '所有子代理在该位置已有角色文件。', agentLabel: '子代理:', fileLabel: '文件:', confirmQuestion: '创建该角色文件？', confirmYes: '是，创建', confirmNo: '否，取消', escCancel: '按 ESC 取消', createSuccessMessage: '创建子代理角色成功！\n子代理: {agent}\n位置: {location}\n路径: {path}', createErrorMessage: '创建子代理角色失败：{error}', errorUnknown: '未知错误', }, roleSubagentDeletion: { title: '删除子代理角色', locationLabel: '选择位置:', locationGlobal: '全局 (~/.snow/)', locationGlobalInfo: '所有项目的子代理角色文件', locationProject: '项目 (项目根目录)', locationProjectInfo: '仅当前项目的子代理角色文件', selectRoleLabel: '选择要删除的角色文件:', selectRoleHint: '↑↓: 导航 | Enter: 选择 | ESC: 返回', noRoleFiles: '该位置没有子代理角色文件。', fileLabel: '文件:', confirmQuestion: '确认删除？', confirmYes: '是，删除', confirmNo: '否，取消', escCancel: '按 ESC 取消', deleteSuccessMessage: '删除子代理角色成功！\n子代理: {agent}\n位置: {location}\n路径: {path}', deleteErrorMessage: '删除子代理角色失败：{error}', errorNotFound: '子代理角色文件不存在', errorUnknown: '未知错误', }, roleSubagentList: { title: '子代理角色管理', tabGlobal: '全局', tabProject: '项目', noRoles: '没有找到子代理角色文件。使用 /role-subagent 创建。', deleteSuccess: '角色文件删除成功', loading: '处理中...', hints: 'Tab: 切换作用域 | D: 删除 | ESC: 关闭', confirmDelete: '确认删除 "{name}" 的角色？', confirmDeleteHint: '按 Y 确认，按 N 取消', }, branchPanel: { title: 'Git 分支管理', notGitRepo: '当前目录不是 Git 仓库，无法管理分支。', noBranches: '没有找到分支。按 N 创建一个新分支。', current: '当前', newBranchLabel: '新分支名称:', newBranchPlaceholder: 'feature/my-new-branch', createHint: 'Enter 确认，ESC 取消', confirmDelete: '确定删除分支 "{branch}" 吗？', confirmDeleteHint: '按 Y 确认，按 N 取消', cannotDeleteCurrent: '无法删除当前正在使用的分支', stashConfirm: '检测到本地未提交的改动，是否暂存(stash)后切换到 "{branch}"？', stashConfirmHint: '按 Y 暂存并切换，按 N 取消', loading: '处理中...', hints: '↑↓: 导航 | Enter: 切换 | N: 新建分支 | D: 删除 | ESC: 关闭', pressEscToClose: '按 ESC 关闭', }, askUser: { header: '[需要用户输入]', customInputOption: '自定义输入...', customInputLabel: '自定义输入', cancelOption: '取消', selectPrompt: '选择一个选项:', enterResponse: '请输入您的回答:', keyboardHints: "提示: 按 'Enter' 选择 | 按 'e' 编辑当前选项", multiSelectHint: '多选模式', multiSelectKeyboardHints: '↑↓ 移动 | Tab 切换(自定义/取消) | 空格 切换 | 1-9 快速切换 | 回车 确认 | e 编辑', optionListScrollHint: '↑↓ 滚动', optionListMoreAbove: '上方还有 {count} 项', optionListMoreBelow: '下方还有 {count} 项', }, toolConfirmation: { header: '[工具确认]', tool: '工具:', tools: '工具:', toolsInParallel: '{count} 个工具并行执行', sensitiveCommandDetected: '检测到敏感命令', pattern: '模式:', reason: '原因:', requiresConfirmation: '此命令即使在 YOLO/自动批准模式下也需要确认', arguments: '参数:', commandPagerTitle: '命令(翻页):', commandPagerStatus: '{page}/{total}', commandPagerHint: 'Tab 下一页(循环)', multiToolPagerHint: 'Tab 查看下一组工具 ({page}/{total})', selectAction: '选择操作:', enterRejectionReason: '输入拒绝原因:', pressEnterToSubmit: '按 Enter 提交', confirmed: '已确认', approveOnce: '批准(一次)', alwaysApprove: '批准(此项目不再询问此工具)', rejectWithReply: '拒绝并回复', rejectEndSession: '拒绝（结束会话）', }, bash: { sensitiveCommandDetected: '检测到敏感命令', sensitivePattern: '匹配模式:', sensitiveReason: '原因:', executeConfirm: '此命令需要确认，是否继续执行？', confirmHint: '按 y 执行，n 取消，或 ESC 返回', executingCommand: '正在执行命令...', timeout: '超时时间:', customTimeout: '(自定义)', backgroundHint: 'Ctrl+B 移至后台', inputRequired: '需要输入', inputPlaceholder: '输入内容后按 Enter 提交', inputHint: '按 Enter 提交输入', }, scheduler: { title: '预约任务', hint: 'AI 流程已暂停，等待倒计时结束...', }, backgroundProcesses: { title: '后台进程', status: '状态', statusRunning: '运行中', statusCompleted: '已完成', statusFailed: '失败', duration: '持续时间', navigateHint: '↑↓ 导航 | Enter 终止选定项 | ESC 关闭', emptyHint: '无后台进程', }, fileRollback: { title: '文件回滚确认', description: '此检查点包含', filesCount: '{count} 个文件将被回滚', filesCountWithSelection: '{count} 个文件将被回滚 ({selected}/{total} 已选择)', notebookCount: '{count} 条备忘录也将被回滚', teamCount: '{count} 个团队成员将被终止，工作区将被清理', question: '请选择回滚方式：', conversationOnly: '仅回滚对话', conversationAndFiles: '回滚对话 + 文件', filesOnly: '仅回滚文件', moreAbove: '更多...', moreBelow: '更多...', andMoreFiles: '以及', viewAllHint: 'Tab 查看全部', selectHint: '↑↓ 选择', confirmHint: 'Enter 确认', cancelHint: 'ESC 取消', scrollHint: '↑↓ 滚动', navigateHint: '↑↓ 导航', toggleHint: '空格 切换', backHint: 'Tab 返回', closeHint: 'ESC 关闭', emptyHint: '无文件可回滚', noFilesConfirm: '未检测到文件变更。仅回滚对话？', noFilesConfirmHint: 'Enter 确认 · ESC 取消', }, usagePanel: { title: 'Token 使用统计', granularity: { last24h: '最近24小时', last7d: '最近7天', last30d: '最近30天', last12m: '最近12个月', }, chart: { noData: '无可用数据', usage: '使用量', cacheHit: '缓存命中', cacheCreate: '缓存创建', moreAbove: '↑ 上方还有 {count} 个 (使用 ↑ 方向键)', in: '输入:', out: '输出:', hit: '命中:', create: '创建:', total: '总计:', moreBelow: '↓ 下方还有 {count} 个 (使用 ↓ 方向键)', }, loading: '加载使用统计中...', error: '错误: {error}', tabToSwitch: '- Tab 切换', noDataForPeriod: '此期间无使用数据', }, workingDirectoryPanel: { title: '工作目录', loading: '加载中...', noDirectories: '未找到目录', defaultLabel: '[默认]', remoteLabel: '[SSH]', markedCount: '已标记 {count} 个目录以删除', markedCountSingular: '个目录', markedCountPlural: '个目录', // Navigation hints navigationHint: '↑↓ 导航 | 空格 标记/取消 | A 添加本地 | S 添加SSH | D 删除已标记 | ESC 关闭', // Add mode addTitle: '添加工作目录', addPathLabel: '路径: ', addPathPrompt: '输入目录路径:', addErrorEmpty: '路径不能为空', addErrorFailed: '添加目录失败(已存在或路径无效)', addHint: 'Enter 添加, ESC 取消', // SSH mode sshTitle: '添加SSH远程目录', sshHostLabel: '主机: ', sshHostPlaceholder: 'example.com', sshPortLabel: '端口: ', sshUsernameLabel: '用户名: ', sshUsernamePlaceholder: 'root', sshAuthMethodLabel: '认证方式: ', sshAuthPassword: '密码', sshAuthPrivateKey: '私钥', sshAuthAgent: 'SSH Agent', sshPasswordLabel: '密码: ', sshPrivateKeyLabel: '密钥路径: ', sshPrivateKeyPlaceholder: '~/.ssh/id_rsa', sshRemotePathLabel: '远程路径: ', sshRemotePathPlaceholder: '/home/user/project', sshConnecting: '连接中...', sshTestSuccess: '连接成功!', sshTestFailed: '连接失败: {error}', sshAddSuccess: 'SSH目录添加成功', sshAddFailed: '添加SSH目录失败', sshHint: '↑↓ 切换字段 | Enter 连接 | ESC 取消', // Delete confirmation confirmDeleteTitle: '确认删除', confirmDeleteMessage: '确定要删除 {count} 个目录吗?', confirmDeleteMessagePlural: '确定要删除 {count} 个目录吗?', confirmHint: 'Y 确认, N 取消', // Alert messages alertDefaultCannotDelete: '默认目录不能被删除', }, diffReviewPanel: { title: 'Diff 审查', noSnapshots: '该会话没有找到文件变更记录', navigationHint: '↑↓ 导航 • Tab 查看文件 • Enter 打开全部 • ESC 关闭', filesSuffix: '{count} 个文件', filesViewNavigationHint: '↑↓ 导航 • Tab 返回 • Enter 打开全部 • ESC 关闭', moreAbove: '↑ 上方还有 {count} 个', moreBelow: '↓ 下方还有 {count} 个', }, sessionListPanel: { title: '恢复会话', loading: '加载会话中...', noResults: '未找到 "{query}" 的结果', noConversations: '未找到对话', marked: '{count} 个已标记', loadingMore: '加载中...', messages: '{count} 条消息', searchLabel: '搜索:', searchPlaceholder: '输入以搜索', searching: '搜索中...', navigationHint: '输入以搜索 • ↑↓ 导航 • 空格 标记 • D 删除 • R 重命名 • Enter 选择 • ESC 关闭', moreAbove: '↑ 上方还有 {count} 个', moreBelow: '↓ 下方还有 {count} 个', scrollToLoadMore: '(滚动加载更多)', untitled: '无标题', now: '现在', renamePrompt: '重命名会话', renaming: '重命名中...', renamePlaceholder: '输入新的标题', confirmDelete: '1 秒内再按一次 D 确认删除（共 {count} 个）', }, mcpInfoPanel: { title: 'MCP 服务', loading: '加载 MCP 服务中...', refreshing: '刷新服务中...', toggling: '切换 {service} 中...', refreshAll: '刷新全部服务', noServices: '未检测到可用的 MCP 服务', error: '错误: {message}', statusSystem: '(系统)', statusExternal: '(外部)', statusDisabled: '(已禁用)', statusFailed: '失败', navigationHint: '↑↓ 导航 • Enter 重连服务 • Tab 启停服务 • V 查看工具', pleaseWait: '请稍候...', skillsTitle: '技能', noSkills: '没有可用的技能', skillLocationProject: '(项目)', skillLocationGlobal: '(全局)', scrollHint: '↑↓ 滚动', moreAbove: '上方还有 {count} 项', moreBelow: '下方还有 {count} 项', toolsListTitle: '{service} - 工具列表', toolsNavigationHint: '↑↓ 导航 • Tab 启停工具 (全局/项目) • ESC 返回', toolTogglingHint: '切换工具 {tool} 中...', toolDisabled: '(已禁用)', toolScopeGlobal: '[全局]', toolScopeProject: '[项目]', mcpSourceProject: ' [项目]', mcpSourceGlobal: ' [全局]', }, skillsListPanel: { title: '技能列表', loading: '加载技能中...', error: '错误: {message}', noSkills: '没有可用的技能', locationProject: '(项目)', locationGlobal: '(全局)', statusDisabled: '(已禁用)', navigationHint: '↑↓ 导航 • Tab/空格/Enter 启停 • ESC 关闭', moreAbove: '↑ 上方还有 {count} 项', moreBelow: '↓ 下方还有 {count} 项', }, mcpConfigScreen: { title: 'MCP 配置 - 选择编辑范围', scopeProject: '项目级配置', scopeGlobal: '全局配置', navigationHint: '↑↓ 导航 • Enter 编辑 • ESC 返回', savedSuccess: '{scope} MCP 配置保存成功！请用 `snow` 重启！', configErrors: '配置错误: {errors}', reverted: '修改已回退至上一个有效配置。', invalidJson: 'JSON 格式无效，修改已回退至上一个有效配置。', }, commandArgsPanel: { navigationHint: '\u2191\u2193 \u5bfc\u822a Enter \u9009\u62e9 Tab/ESC \u5173\u95ed', }, runningAgentsPanel: { title: '\u8fd0\u884c\u4e2d\u7684\u4ee3\u7406', noAgentsRunning: '当前没有运行中的代理或队友', keyboardHint: '(空格: 切换 · 回车: 确认 · Esc: 取消)', selected: '已选择: {count}', scrollHint: '↑↓ 滚动', moreAbove: '上方还有 {count} 个', moreBelow: '下方还有 {count} 个', subAgentLabel: '[代理]', teammateLabel: '[队友]', }, sseServer: { started: '✓ SSE 服务器已启动', port: '端口', workingDir: '工作目录', running: '运行中', endpoints: '可用端点', logs: '运行日志', stopHint: '按 Ctrl+C 停止服务器', }, sseDaemon: { portOccupied: '端口 {port} 已被守护进程占用 (PID: {pid})', stopExistingByPort: '使用 "snow --sse-stop --sse-port {port}" 停止现有服务', stopExistingByPid: '或使用 "snow --sse-stop {pid}" 通过PID停止', startingDaemon: '正在启动 SSE 守护进程 (端口: {port})...', daemonStarted: '✓ SSE 守护进程已启动', pid: 'PID', port: '端口', workDir: '工作目录', timeout: '超时时长', logFile: '日志文件', stopService: '停止服务', stopByPort: '通过端口', stopByPid: '通过PID', checkStatus: '查看状态', savePidFailed: '保存 PID 文件失败', daemonStartFailed: '✗ 守护进程启动失败，请检查日志文件', noRunningDaemon: '端口 {port} 上没有运行中的守护进程', readPidFailed: '读取 PID 文件失败', tryRemoveInvalidPid: '尝试删除无效的 PID 文件...', noDaemonForPid: 'PID {pid} 对应的守护进程不存在', stoppingDaemon: '正在停止 SSE 守护进程 (PID: {pid})...', stopProcessFailed: '停止进程失败', daemonStopped: '✓ SSE 守护进程已停止', processNotExists: '进程已不存在，清理 PID 文件', stopProcessError: '停止进程时出错', noRunningDaemons: '没有运行中的 SSE 守护进程', foundInvalidPids: '发现 {count} 个无效的PID文件', cleanupHint: '使用 "snow --sse-stop --sse-port <port>" 清理', runningDaemons: '运行中的 SSE 守护进程 ({count})', startTime: '启动时间', endpoint: '端点', stopCommand: '停止', invalidPidsStopped: '发现 {count} 个无效的PID文件（进程已停止）', autoCleanupHint: '这些文件会在下次停止操作时自动清理', }, newPrompt: { title: '✦ 提示词生成器', inputHint: '描述你的需求，AI 将生成精炼的提示词：', placeholder: '输入你的需求...', escHint: 'ESC 取消', generating: '正在生成提示词...', previewTitle: '✓ 提示词已生成：', moreLines: '(还有 {count} 行)', actionAccept: '写入输入框', actionReject: '放弃', actionRegenerate: '重新生成', actionRetry: '重试', actionCancel: '取消', errorPrefix: '错误：', scrollHint: '↑↓ 滚动浏览', }, btw: { title: '✦ 顺便问一下', thinking: '思考中...', escHint: 'ESC 取消', actionClose: '关闭', errorPrefix: '错误：', scrollHint: '↑↓ 滚动浏览', }, pixelEditor: { title: '像素编辑器', palette: '调色板', eraser: '橡皮擦', colorNumber: '颜色 {n}', canvasCleared: '画布已清空', clearCancelled: '已取消清空', saveCancelled: '已取消保存', nameCannotBeEmpty: '名称不能为空', savedAs: '已保存为 {name}', controlsHint: '方向键：移动 • 空格：绘制/擦除 • Enter：绘制 • 1-9：选色 • 0：擦除 • C：清空画布', controlsHintPosBrush: 'ESC/Q：返回 • Ctrl+S：保存 • 坐标：({x}, {y}) • 画笔： ', saveDrawingLabel: '保存作品：', namePlaceholder: '输入名称...', escCancelHint: ' ESC 取消', confirmClearCanvas: '清空画布？按 Y 确认，按其他键取消。', }, pixelEditorScreen: { screenTitle: '像素编辑器', newCanvas: '新建画布', manageDrawings: '管理作品', menuNavigateHint: '↑↓ 选择 • Enter 确认 • Esc 返回', manageTitle: '管理作品', noDrawings: '暂无作品。', managerHint: '↑↓ 移动 • 空格 多选 • D 删除 • S 切换退出画面 • Enter 编辑 • Esc 返回', confirmDeleteMany: '确认删除 {count} 项？Enter/Y/D 确认，N/Esc 取消', moreAbove: '↑ 上方还有 {count} 项', moreBelow: '↓ 下方还有 {count} 项', selectedCount: '已选择 {count} 项', exitImageDisabled: '已关闭退出画面', failedDisableExitImage: '关闭退出画面失败', setAsExitImage: '已将「{name}」设为退出画面', }, agentPickerPanel: { title: '子代理选择', noAgentsWarning: '未配置子代理。请先配置子代理。', selectAgent: '选择子代理', escHint: '（按 ESC 关闭）', noDescription: '无描述', scrollHint: '· ↑↓ 滚动', moreAbove: '上方还有 {count} 项', moreBelow: '下方还有 {count} 项', }, todoPickerPanel: { title: 'TODO 选择', scanning: '正在扫描项目中的 TODO 注释...', noTodosFound: '项目中未找到 TODO 注释', noMatchSearch: '没有匹配 "{searchQuery}" 的 TODO（总数：{totalCount}）', typeToClearSearch: '输入以筛选 · 退格键清除搜索', selectTodos: '选择 TODO', filteringLabel: '筛选: "{searchQuery}"', typeToFilterHint: '输入筛选 · 退格清除 · 空格: 切换 · 回车: 确认', typeToSearchHint: '输入搜索 · 空格: 切换 · 回车: 确认 · Esc: 取消', selectedCount: '已选择 {count} 个 TODO', noDescription: '无描述', }, exitScreen: { title: '再见', goodbye: '感谢使用 Snow CLI', thankYou: '期待下次相见', resumeSession: '恢复会话', version: 'v{version}', }, }; ================================================ FILE: source/i18n/translations.ts ================================================ import type {Translations} from './types.js'; import {en} from './lang/en.js'; import {zh} from './lang/zh.js'; import {zhTW} from './lang/zh-TW.js'; export const translations: Translations = { en, zh, 'zh-TW': zhTW, }; ================================================ FILE: source/i18n/types.ts ================================================ export type {Language} from '../utils/config/languageConfig.js'; export type TranslationKeys = { welcome: { title: string; subtitle: string; startChat: string; startChatInfo: string; resumeLastChat: string; resumeLastChatInfo: string; apiSettings: string; apiSettingsInfo: string; proxySettings: string; proxySettingsInfo: string; codebaseSettings: string; codebaseSettingsInfo: string; systemPromptSettings: string; systemPromptSettingsInfo: string; customHeadersSettings: string; customHeadersSettingsInfo: string; mcpSettings: string; mcpSettingsInfo: string; subAgentSettings: string; subAgentSettingsInfo: string; sensitiveCommands: string; sensitiveCommandsInfo: string; languageSettings: string; languageSettingsInfo: string; themeSettings: string; themeSettingsInfo: string; hooksSettings: string; hooksSettingsInfo: string; updateNoticeTitle: string; updateNoticeCurrent: string; updateNoticeLatest: string; updateNoticeRun: string; updateNoticeGithub: string; updateNow: string; updateNowInfo: string; exit: string; exitInfo: string; }; // Menu menu: { navigate: string; }; // Proxy Config Screen proxyConfig: { title: string; subtitle: string; enableProxy: string; enabled: string; disabled: string; toggleHint: string; proxyPort: string; notSet: string; browserPath: string; autoDetect: string; searchEngine: string; errors: string; editingHint: string; navigationHint: string; browserExamplesTitle: string; browserExamplesFooter: string; portValidationError: string; portPlaceholder: string; browserPathPlaceholder: string; windowsExample: string; macosExample: string; linuxExample: string; }; // CodeBase Config Screen codebaseConfig: { title: string; subtitle: string; settingsPosition: string; scrollHint: string; codebaseEnabled: string; agentReview: string; enabled: string; disabled: string; toggleHint: string; embeddingType: string; embeddingModelName: string; embeddingBaseUrl: string; embeddingApiKey: string; embeddingApiKeyOptional: string; embeddingDimensions: string; embeddingSettingsGroup: string; embeddingSettingsExpandHint: string; batchSettingsGroup: string; batchSettingsExpandHint: string; batchMaxLines: string; batchConcurrency: string; notSet: string; masked: string; errors: string; editingHint: string; navigationHint: string; validationModelNameRequired: string; validationBaseUrlRequired: string; validationDimensionsPositive: string; validationMaxLinesPositive: string; validationConcurrencyPositive: string; validationMaxLinesPerChunkPositive: string; validationMinLinesPerChunkPositive: string; validationMinCharsPerChunkPositive: string; validationOverlapLinesNonNegative: string; validationOverlapLessThanMaxLines: string; chunkingMaxLinesPerChunk: string; chunkingMinLinesPerChunk: string; chunkingMinCharsPerChunk: string; chunkingOverlapLines: string; rerankingToggle: string; rerankingSettingsGroup: string; rerankingSettingsExpandHint: string; rerankingModelName: string; rerankingBaseUrl: string; rerankingApiKey: string; rerankingContextLength: string; rerankingTopN: string; rerankingNotConfigured: string; validationRerankingModelNameRequired: string; validationRerankingBaseUrlRequired: string; validationRerankingContextLengthPositive: string; validationRerankingTopNPositive: string; saveError: string; gitignoreNotFound: string; enterValue: string; }; // System Prompt Config Screen systemPromptConfig: { title: string; subtitle: string; activePrompt: string; none: string; noPromptsConfigured: string; availablePrompts: string; actions: string; activate: string; deactivate: string; edit: string; delete: string; addNew: string; escBack: string; navigationHint: string; addNewTitle: string; editTitle: string; nameLabel: string; contentLabel: string; enterPromptName: string; enterPromptContent: string; notSet: string; editingHint: string; externalEditorHint: string; editorNotFound: string; editorOpenFailed: string; editorEditFailed: string; editorSaved: string; confirmDelete: string; deleteConfirmMessage: string; confirmHint: string; saveError: string; activeCount: string; }; // Config Screen configScreen: { title: string; subtitle: string; activeProfile: string; settingsPosition: string; scrollHint: string; moreAbove: string; moreBelow: string; profile: string; baseUrl: string; apiKey: string; requestMethod: string; requestUrlLabel: string; anthropicBeta: string; anthropicCacheTTL: string; anthropicCacheTTL5m: string; anthropicCacheTTL1h: string; anthropicSpeed: string; anthropicSpeedNotUsed: string; anthropicSpeedFast: string; anthropicSpeedStandard: string; enablePromptOptimization: string; enableAutoCompress: string; autoCompressThreshold: string; autoCompressThresholdHint: string; autoCompressThresholdDesc: string; showThinking: string; streamingDisplay: string; thinkingEnabled: string; thinkingMode: string; thinkingModeTokens: string; thinkingModeAdaptive: string; thinkingBudgetTokens: string; thinkingEffort: string; geminiThinkingEnabled: string; geminiThinkingLevel: string; responsesReasoningEnabled: string; responsesReasoningEffort: string; responsesVerbosity: string; responsesFastMode: string; chatThinkingEnabled: string; chatReasoningEffort: string; advancedModel: string; basicModel: string; maxContextTokens: string; maxTokens: string; streamIdleTimeoutSec: string; toolResultTokenLimit: string; toolResultTokenLimitHint: string; toolResultTokenLimitDesc: string; notSet: string; enabled: string; disabled: string; toggleHint: string; enterValue: string; createNewProfile: string; renameProfile: string; enterProfileName: string; enterRenameProfileName: string; profileNameLabel: string; profileNamePlaceholder: string; renameProfilePlaceholder: string; createHint: string; renameHint: string; deleteProfile: string; confirmDelete: string; deleteWarning: string; confirmHint: string; loadingModels: string; loadingMessage: string; loadingCancelHint: string; manualInputTitle: string; manualInputSubtitle: string; manualInputHint: string; loadingError: string; requestMethodChat: string; requestMethodResponses: string; requestMethodGemini: string; requestMethodAnthropic: string; manualInputOption: string; errors: string; cannotDeleteDefault: string; profileNameEmpty: string; navigationHint: string; editingHintNumeric: string; editingHintGeneral: string; modelFilterHint: string; effortSelectHint: string; profileSelectHint: string; requestMethodSelectHint: string; newProfile: string; renameProfileShort: string; deleteProfileShort: string; mark: string; cannotRenameDefault: string; noProfilesMarked: string; confirmDeleteProfiles: string; fetchingModels: string; fetchingHint: string; systemPrompt: string; customHeadersField: string; followGlobalNone: string; followGlobal: string; followGlobalWithParentheses: string; followGlobalNoneWithParentheses: string; notUse: string; systemPromptMultiSelectHint: string; modelSelectFilterLabel: string; modelSelectModelCount: string; modelSelectScrollHint: string; }; // Custom Headers Screen customHeaders: { title: string; subtitle: string; activeScheme: string; none: string; noSchemesConfigured: string; availableSchemes: string; actions: string; activate: string; deactivate: string; edit: string; delete: string; addNew: string; escBack: string; navigationHint: string; addNewTitle: string; editTitle: string; nameLabel: string; headersLabel: string; headersConfigured: string; enterSchemeName: string; notSet: string; pressEnterToEdit: string; editingHint: string; confirmDelete: string; deleteConfirmMessage: string; confirmHint: string; saveError: string; editHeadersTitle: string; headerList: string; noHeadersConfigured: string; addNewHeader: string; headerNavigationHint: string; keyLabel: string; valueLabel: string; headerKeyPlaceholder: string; headerValuePlaceholder: string; headerEditingHint: string; }; subAgentConfig: { title: string; titleEdit: string; titleNew: string; subtitle: string; agentName: string; description: string; role: string; roleOptional: string; toolSelection: string; agentNamePlaceholder: string; descriptionPlaceholder: string; rolePlaceholder: string; selectedTools: string; toolsCount: string; loadingMCP: string; mcpLoadError: string; categoryCount: string; categoryMCP: string; navigationHint: string; saveSuccess: string; saveSuccessEdit: string; saveSuccessCreate: string; saveError: string; validationFailed: string; filesystemTools: string; aceTools: string; codebaseTools: string; terminalTools: string; todoTools: string; webSearchTools: string; ideTools: string; userInteractionTools: string; skillTools: string; configProfile: string; followGlobal: string; customSystemPrompt: string; customHeaders: string; noItems: string; moreAbove: string; moreBelow: string; scrollToggleHint: string; spaceToggleHint: string; moreTools: string; scrollToolsHint: string; builtinReadonly: string; roleExpandHint: string; roleExpanded: string; roleCollapsed: string; roleViewFull: string; }; // Sub-Agent List Screen subAgentList: { title: string; noAgents: string; noAgentsHint: string; agentsCount: string; description: string; noDescription: string; toolsCount: string; updated: string; deleteConfirm: string; deleteSuccess: string; deleteFailed: string; navigationHint: string; }; // Sensitive Command Config Screen sensitiveCommandConfig: { title: string; subtitle: string; noCommands: string; custom: string; enabled: string; disabled: string; customLabel: string; // Scope scopeProject: string; scopeGlobal: string; scopeSelectTitle: string; scopeSelectHint: string; duplicatePattern: string; resetScopeSelectTitle: string; resetGlobalDesc: string; resetProjectDesc: string; confirmResetScopeMessage: string; // Add view addTitle: string; patternLabel: string; patternPlaceholder: string; descriptionLabel: string; addEditingHint: string; // List view actions addedMessage: string; enabledMessage: string; disabledMessage: string; deletedMessage: string; resetMessage: string; // Confirmation messages confirmDeleteMessage: string; confirmResetMessage: string; confirmHint: string; // Navigation hints listNavigationHint: string; }; themeSettings: { title: string; current: string; preview: string; userMessagePreview: string; userMessageSample: string; back: string; backInfo: string; simpleMode: string; simpleModeInfo: string; diffOpacity: string; diffOpacityInfo: string; enabled: string; disabled: string; darkTheme: string; darkThemeInfo: string; lightTheme: string; lightThemeInfo: string; githubDark: string; githubDarkInfo: string; rainbow: string; rainbowInfo: string; solarizedDark: string; solarizedDarkInfo: string; nord: string; nordInfo: string; tiffany: string; tiffanyInfo: string; macaronPink: string; macaronPinkInfo: string; custom: string; customInfo: string; editCustom: string; editCustomInfo: string; }; customTheme: { title: string; save: string; saveInfo: string; reset: string; resetInfo: string; back: string; backInfo: string; editColor: string; currentValue: string; newValue: string; colorFormat: string; cancel: string; confirm: string; preview: string; userMessagePreview: string; userMessageSample: string; colorHint: string; }; helpPanel: { title: string; textEditingTitle: string; deleteToStart: string; deleteToEnd: string; copyInput: string; pasteImages: string; toggleExpandedView: string; readlineTitle: string; moveToLineStart: string; moveToLineEnd: string; forwardWord: string; backwardWord: string; deleteToLineEnd: string; deleteToLineStart: string; deleteWord: string; deleteChar: string; quickAccessTitle: string; insertFiles: string; searchContent: string; selectAgent: string; showCommands: string; bashModeTitle: string; bashModeTrigger: string; bashModeDesc: string; navigationTitle: string; navigateHistory: string; selectItem: string; cancelClose: string; toggleYolo: string; tipsTitle: string; tipUseHelp: string; tipShowCommands: string; tipInterrupt: string; closeHint: string; }; connectionPanel: { errorPrefix: string; loggingIn: string; connectingToHub: string; connectedSuccessfully: string; title: string; statusLabel: string; statusConnected: string; statusConnecting: string; statusDisconnected: string; savedConfigFound: string; apiUrlLabel: string; usernameLabel: string; instanceLabel: string; savedConfigHint: string; confirmDeletePrefix: string; confirmDeleteSuffix: string; clearSavedPrefix: string; clearSavedSuffix: string; apiBaseUrlLabel: string; apiBaseUrlPlaceholder: string; enterContinueEscCancel: string; authenticationTitle: string; usernameFieldLabel: string; usernamePlaceholder: string; passwordFieldLabel: string; passwordPlaceholder: string; enterContinueEscBack: string; instanceConfigTitle: string; loggedInAs: string; instanceIdLabel: string; instanceIdPlaceholder: string; instanceNameLabel: string; instanceNamePlaceholder: string; enterConnectEscBack: string; pleaseWait: string; connectedSuccessfullyWithIcon: string; pressEscToClose: string; useCommandPrefix: string; useCommandSuffix: string; }; // Command Panel commandPanel: { title: string; availableCommands: string; processingMessage: string; scrollHint: string; moreHidden: string; moreAbove: string; moreBelow: string; interactionHint: string; commands: { help: string; clear: string; copyLast: string; resume: string; mcp: string; yolo: string; plan: string; init: string; ide: string; compact: string; home: string; review: string; gitline: string; role: string; roleSubagent: string; usage: string; backend: string; loop: string; profiles: string; models: string; subAgentDepth: string; export: string; custom: string; skills: string; skillsPicker: string; agent: string; todo: string; todolist: string; addDir: string; reindex: string; codebase: string; permissions: string; vulnerabilityHunting: string; autoFormat: string; simple: string; toolSearch: string; hybridCompress: string; team: string; branch: string; // Fork conversation into a new branch worktree: string; // Git branch management panel diff: string; connect: string; disconnect: string; connectionStatus: string; newPrompt: string; pixel: string; btw: string; deepresearch: string; quit: string; }; copyLastFeedback: { noAssistantMessage: string; emptyAssistantMessage: string; copySuccess: string; copyFailedPrefix: string; unknownError: string; }; // Command output messages (for command execution results) commandOutput: { // Auto-format command messages autoFormat: { enabled: string; disabled: string; statusEnabled: string; statusDisabled: string; }; // Simple mode command messages simpleMode: { enabled: string; disabled: string; statusEnabled: string; statusDisabled: string; }; // Export command messages export: { exporting: string; openingDialog: string; cancelledByUser: string; }; // IDE command messages ide: { disconnected: string; noAvailableIDEs: string; unmatchedIDEs: string; connectedTo: string; connectFailed: string; }; branchFork: { noActiveSession: string; success: string; failed: string; }; // Deep Research command messages deepResearch: { usage: string; }; // Loop command messages loop: { usage: string; openingTaskManager: string; relatedLoopTasks: string; noActiveLoops: string; loopNotFound: string; cancelled: string; created: string; scheduleEvery: string; promptLabel: string; nextRun: string; sessionScopedNote: string; usageHint: string; }; }; }; // File search list (`@` panel) fileList: { loadingFiles: string; noFilesFound: string; // Used while a deeper rescan is queued or running searchingDeeper: string; // {depth} // Inline status while streaming results in scanning: string; // {count} scanningDeeper: string; // {depth} {count} // Hint shown at the bottom of the list when more directories are still // available to scan, telling the user how to trigger a deeper search. deeperSearchHint: string; // Header labels contentSearchHeader: string; filesHeader: string; // {mode} treeMode: string; listMode: string; }; // IDE Select Panel ideSelectPanel: { title: string; subtitle: string; noneOption: string; connectedMark: string; hint: string; connecting: string; connectSuccess: string; connectError: string; unmatchedIDEs: string; unmatchedHeader: string; switchWorkdirMark: string; switchWorkdirError: string; }; // Profile Panel profilePanel: { title: string; scrollHint: string; moreHidden: string; moreAbove: string; moreBelow: string; escHint: string; // 提示用户按右方向键打开当前光标聚焦 profile 的编辑面板 editHint: string; activeLabel: string; searchLabel: string; noResults: string; }; // Skills Picker Panel skillsPickerPanel: { title: string; keyboardHint: string; loading: string; searchLabel: string; appendLabel: string; empty: string; noSkillsFound: string; noDescription: string; scrollHint: string; moreAbove: string; moreBelow: string; }; todoListPanel: { title: string; loading: string; deleting: string; empty: string; noActiveSession: string; hint: string; confirmModeHint: string; confirmDelete: string; confirmDeleteHint: string; selectedCount: string; moreAbove: string; moreBelow: string; }; reviewCommitPanel: { title: string; loadingCommits: string; stagedLabel: string; unstagedLabel: string; filesLabel: string; hintEscClose: string; hintNavigation: string; loadingMoreSuffix: string; notesLabel: string; notesOptional: string; selectedLabel: string; errorSelectAtLeastOne: string; }; gitLinePickerPanel: { title: string; loadingCommits: string; loadingMoreSuffix: string; noCommits: string; searchLabel: string; emptySearch: string; hintNavigation: string; selectedLabel: string; scrollToLoadMore: string; }; // Permissions Panel permissionsPanel: { title: string; clearAll: string; noTools: string; hint: string; confirmDelete: string; confirmClearAll: string; yes: string; no: string; }; subAgentDepthPanel: { title: string; description: string; currentValueLabel: string; inputLabel: string; invalidInput: string; saveSuccess: string; hint: string; fileHint: string; }; modelsPanel: { title: string; subtitle: string; tabAdvanced: string; tabBasic: string; tabThinking: string; currentModel: string; notSet: string; loadingModels: string; hint: string; manualInputTitle: string; manualInputHint: string; filterLabel: string; manualInputOption: string; requestMethod: string; showThinkingProcess: string; enableThinking: string; thinkingMode: string; thinkingStrength: string; inputNumberHint: string; escCancel: string; navigationHint: string; notSupported: string; advancedModelLabel: string; basicModelLabel: string; thinkingLabel: string; requestMethodNotSupportedForThinking: string; requestMethodNotSupportedForThinkingStrength: string; anthropicSpeed: string; saveFailed: string; modelSaveFailed: string; tipLabel: string; modelCount: string; scrollHint: string; }; // Hooks hooks: { pressCtrlCAgain: string; exitingApplication: string; }; // Hooks Config hooksConfig: { title: string; scopeSelect: { globalHooks: string; globalInfo: string; projectHooks: string; projectInfo: string; back: string; backInfo: string; }; hookTypes: { onUserMessage: string; beforeToolCall: string; afterToolCall: string; toolConfirmation: string; onSubAgentComplete: string; beforeCompress: string; onSessionStart: string; onStop: string; }; hookList: { title: string; global: string; project: string; configured: string; rules: string; back: string; backInfo: string; }; hookDetail: { rule: string; actions: string; matcher: string; addNewRule: string; addNewRuleInfo: string; deleteHook: string; deleteHookInfo: string; back: string; backInfo: string; }; ruleEdit: { title: string; editDescription: string; editMatcher: string; editDescriptionLabel: string; editMatcherLabel: string; matcherHint: string; clickToEdit: string; clickToEditMatcher: string; enabled: string; disabled: string; addAction: string; addActionInfo: string; deleteRule: string; deleteRuleInfo: string; saveRule: string; saveRuleInfo: string; cancel: string; cancelInfo: string; hint: string; enterToSave: string; }; actionEdit: { title: string; enabled: string; enabledInfo: string; type: string; typeInfo: string; command: string; commandInfo: string; commandNotSet: string; prompt: string; promptInfo: string; promptNotSet: string; timeout: string; timeoutInfo: string; deleteAction: string; deleteActionInfo: string; saveAction: string; saveActionInfo: string; cancel: string; cancelInfo: string; hint: string; enterToSave: string; }; }; customCommand: { title: string; nameLabel: string; namePlaceholder: string; commandLabel: string; commandPlaceholder: string; descriptionLabel: string; descriptionPlaceholder: string; descriptionHint: string; descriptionNotSet: string; typeLabel: string; typeExecute: string; typePrompt: string; locationLabel: string; locationGlobal: string; locationProject: string; locationGlobalInfo: string; locationProjectInfo: string; confirmSave: string; confirmYes: string; confirmNo: string; escCancel: string; resultTypeExecute: string; resultTypePrompt: string; resultLocationGlobal: string; resultLocationProject: string; saveSuccessMessage: string; }; // Chat Screen chatScreen: { // Header headerTitle: string; headerSubtitle: string; headerExplanations: string; headerInterrupt: string; headerYolo: string; headerShortcuts: string; headerExpandedView: string; headerWorkingDirectory: string; // Status messages statusThinking: string; statusDeepThinking: string; statusWriting: string; statusStreaming: string; statusWorking: string; statusIndexing: string; statusWatcherActive: string; statusWatcherActiveShort: string; statusFileUpdated: string; statusFileUpdatedShort: string; statusCreating: string; statusSaving: string; statusCompressing: string; statusConnecting: string; statusConnected: string; statusConnectionFailed: string; statusStopping: string; inputCopySuccess: string; inputCopyFailedPrefix: string; // Profile switch profileCurrent: string; profileSwitchHint: string; gitBranch: string; memoryUsageLabel: string; // Tool execution toolCall: string; toolThinking: string; toolReading: string; toolWriting: string; toolSearching: string; toolExecuting: string; toolSuccess: string; toolRejected: string; // Parallel execution parallelStart: string; parallelEnd: string; // Messages userMessage: string; assistantMessage: string; commandMessage: string; discontinuedMessage: string; aiCompletionTimeMessage: string; // File operations fileCreated: string; fileModified: string; fileRead: string; fileDeleted: string; fileCount: string; fileNotFound: string; fileLine: string; fileLines: string; // Images imageAttached: string; // Token usage tokenTotal: string; tokenInput: string; tokenOutput: string; tokenCached: string; tokenCacheCreation: string; tokenCacheRead: string; // Time timeElapsed: string; timeSeconds: string; timeMinutes: string; timeHours: string; // Errors errorGeneric: string; errorApi: string; errorNetwork: string; errorConfig: string; errorCompression: string; errorCompressionFailed: string; errorLoadSession: string; errorRollback: string; // Warnings terminalTooSmall: string; terminalResizePrompt: string; terminalMinHeight: string; // Compression compressionAuto: string; compressionInProgress: string; compressionSuccess: string; compressionFailed: string; compressionBlockToast: string; // Review reviewStartTitle: string; reviewSelectedSummary: string; reviewSelectedWorkingTreePrefix: string; reviewCommitsLine: string; reviewCommitsMoreSuffix: string; reviewNotesLine: string; reviewGenerating: string; reviewInterruptHint: string; // Retry retryAttempt: string; retryIn: string; retryResending: string; retryError: string; // Codebase codebaseIndexing: string; codebaseIndexingShort: string; codebaseProgress: string; codebaseChunks: string; codebaseSearching: string; codebaseSearchAttempt: string; codebaseSearchComplete: string; codebaseIndexingEnabled: string; codebaseIndexingDisabled: string; // IDE ideConnecting: string; ideConnected: string; ideDisconnected: string; ideError: string; ideActiveFile: string; ideSelectedText: string; // Input inputPlaceholder: string; inputProcessing: string; inputDisabled: string; // Shortcuts shortcutPasteImage: string; shortcutFileReference: string; shortcutSearchContent: string; shortcutCommands: string; shortcutDeleteToStart: string; shortcutDeleteToEnd: string; shortcutCancel: string; shortcutRegenerate: string; shortcutToggleYolo: string; // Rollback rollbackConfirm: string; rollbackFiles: string; rollbackConversation: string; rollbackWarning: string; // Session chatInitializing: string; sessionCreating: string; sessionLoading: string; sessionSaving: string; sessionDeleting: string; // Rejection rejectionReason: string; rejectionNoReason: string; // Batch operations batchFile: string; batchEditResults: string; // Pending pendingMessageWaiting: string; pendingToolConfirmation: string; pendingMessagesTitle: string; pendingMessagesFooter: string; pendingMessagesEscHint: string; pendingMessagesImagesAttached: string; // Press keys hints pressEscToClose: string; pressEnterToToggle: string; pressCtrlC: string; pressCtrlR: string; pressCtrlS: string; // Context contextUsage: string; contextPercentage: string; contextLimit: string; // ChatInput waitingForResponse: string; moreAbove: string; moreBelow: string; historyNavigateHint: string; typeToFilterCommands: string; contentSearchHint: string; fileSearchHint: string; expandedViewHint: string; yoloModeActive: string; planModeActive: string; vulnerabilityHuntingModeActive: string; toolSearchEnabled: string; hybridCompressEnabled: string; teamModeActive: string; tokens: string; cached: string; newCache: string; }; taskManager: { title: string; loadingTasks: string; noTasksFound: string; noTasksHint: string; escToClose: string; tasksCount: string; messagesCount: string; markedCount: string; navigationHint: string; moreAbove: string; moreBelow: string; deleteConfirm: string; deleteMultipleConfirm: string; taskDetailsTitle: string; continueHint: string; backToList: string; titleLabel: string; statusLabel: string; createdLabel: string; updatedLabel: string; messagesLabel: string; untitled: string; statusPending: string; statusRunning: string; statusCompleted: string; statusFailed: string; taskNotCompleted: string; confirmConvertToSession: string; sensitiveCommandDetected: string; commandLabel: string; approveRejectHint: string; enterRejectionReason: string; submitCancelHint: string; }; skillsCreation: { title: string; modeLabel: string; modeAi: string; modeManual: string; requirementLabel: string; requirementHint: string; requirementPlaceholder: string; generatingLabel: string; generatingMessage: string; filesLabel: string; editName: string; editNameLabel: string; editNameHint: string; editNamePlaceholder: string; regenerate: string; cancel: string; nameLabel: string; nameHint: string; namePlaceholder: string; descriptionLabel: string; descriptionHint: string; descriptionPlaceholder: string; locationLabel: string; locationGlobal: string; locationGlobalInfo: string; locationProject: string; locationProjectInfo: string; confirmQuestion: string; confirmYes: string; confirmNo: string; escCancel: string; errorInvalidName: string; errorExistsBoth: string; errorExistsGlobal: string; errorExistsProject: string; errorExistsAny: string; errorGeneration: string; errorNoGeneratedContent: string; resultModeAi: string; resultModeManual: string; createSuccessMessage: string; createErrorMessage: string; errorUnknown: string; }; roleCreation: { title: string; locationLabel: string; locationGlobal: string; locationGlobalInfo: string; locationProject: string; locationProjectInfo: string; confirmQuestion: string; confirmYes: string; confirmNo: string; escCancel: string; warningExistsGlobal: string; warningExistsProject: string; createSuccessMessage: string; createErrorMessage: string; errorUnknown: string; }; roleDeletion: { title: string; locationLabel: string; locationGlobal: string; locationGlobalInfo: string; locationProject: string; locationProjectInfo: string; confirmQuestion: string; confirmYes: string; confirmNo: string; escCancel: string; warningNotExistsGlobal: string; warningNotExistsProject: string; deleteSuccessMessage: string; deleteErrorMessage: string; errorNotFound: string; errorUnknown: string; }; roleList: { title: string; tabGlobal: string; tabProject: string; noRoles: string; active: string; switchSuccess: string; createSuccess: string; deleteSuccess: string; loading: string; hints: string; cannotDeleteActive: string; confirmDelete: string; confirmDeleteHint: string; overrideTag: string; overrideEnabled: string; overrideDisabled: string; cannotOverrideInactive: string; }; roleSubagentCreation: { title: string; locationLabel: string; locationGlobal: string; locationGlobalInfo: string; locationProject: string; locationProjectInfo: string; selectAgentLabel: string; selectAgentHint: string; noAvailableAgents: string; agentLabel: string; fileLabel: string; confirmQuestion: string; confirmYes: string; confirmNo: string; escCancel: string; createSuccessMessage: string; createErrorMessage: string; errorUnknown: string; }; roleSubagentDeletion: { title: string; locationLabel: string; locationGlobal: string; locationGlobalInfo: string; locationProject: string; locationProjectInfo: string; selectRoleLabel: string; selectRoleHint: string; noRoleFiles: string; fileLabel: string; confirmQuestion: string; confirmYes: string; confirmNo: string; escCancel: string; deleteSuccessMessage: string; deleteErrorMessage: string; errorNotFound: string; errorUnknown: string; }; roleSubagentList: { title: string; tabGlobal: string; tabProject: string; noRoles: string; deleteSuccess: string; loading: string; hints: string; confirmDelete: string; confirmDeleteHint: string; }; // Branch Panel branchPanel: { title: string; notGitRepo: string; noBranches: string; current: string; newBranchLabel: string; newBranchPlaceholder: string; createHint: string; confirmDelete: string; confirmDeleteHint: string; cannotDeleteCurrent: string; stashConfirm: string; stashConfirmHint: string; loading: string; hints: string; pressEscToClose: string; }; // AskUserQuestion Component askUser: { header: string; customInputOption: string; customInputLabel: string; cancelOption: string; selectPrompt: string; enterResponse: string; keyboardHints: string; multiSelectHint: string; multiSelectKeyboardHints: string; /** 可滚动选项列表底部汇总（与 mcpInfoPanel.scrollHint / more* 一致） */ optionListScrollHint: string; optionListMoreAbove: string; optionListMoreBelow: string; }; toolConfirmation: { header: string; tool: string; tools: string; toolsInParallel: string; sensitiveCommandDetected: string; pattern: string; reason: string; requiresConfirmation: string; arguments: string; commandPagerTitle: string; commandPagerStatus: string; commandPagerHint: string; multiToolPagerHint: string; selectAction: string; enterRejectionReason: string; pressEnterToSubmit: string; confirmed: string; approveOnce: string; alwaysApprove: string; rejectWithReply: string; rejectEndSession: string; }; bash: { sensitiveCommandDetected: string; sensitivePattern: string; sensitiveReason: string; executeConfirm: string; confirmHint: string; executingCommand: string; timeout: string; customTimeout: string; backgroundHint: string; inputRequired: string; inputPlaceholder: string; inputHint: string; }; scheduler: { title: string; hint: string; }; backgroundProcesses: { title: string; status: string; statusRunning: string; statusCompleted: string; statusFailed: string; duration: string; navigateHint: string; emptyHint: string; }; fileRollback: { title: string; description: string; filesCount: string; filesCountWithSelection: string; notebookCount: string; teamCount: string; question: string; conversationOnly: string; conversationAndFiles: string; filesOnly: string; moreAbove: string; moreBelow: string; andMoreFiles: string; viewAllHint: string; selectHint: string; confirmHint: string; cancelHint: string; scrollHint: string; navigateHint: string; emptyHint: string; toggleHint: string; backHint: string; closeHint: string; noFilesConfirm: string; noFilesConfirmHint: string; }; usagePanel: { title: string; granularity: { last24h: string; last7d: string; last30d: string; last12m: string; }; chart: { noData: string; usage: string; cacheHit: string; cacheCreate: string; moreAbove: string; in: string; out: string; hit: string; create: string; total: string; moreBelow: string; }; loading: string; error: string; tabToSwitch: string; noDataForPeriod: string; }; // Working Directory Panel workingDirectoryPanel: { title: string; loading: string; noDirectories: string; defaultLabel: string; remoteLabel: string; markedCount: string; markedCountSingular: string; markedCountPlural: string; // Navigation hints navigationHint: string; // Add mode addTitle: string; addPathLabel: string; addPathPrompt: string; addErrorEmpty: string; addErrorFailed: string; addHint: string; // SSH mode sshTitle: string; sshHostLabel: string; sshHostPlaceholder: string; sshPortLabel: string; sshUsernameLabel: string; sshUsernamePlaceholder: string; sshAuthMethodLabel: string; sshAuthPassword: string; sshAuthPrivateKey: string; sshAuthAgent: string; sshPasswordLabel: string; sshPrivateKeyLabel: string; sshPrivateKeyPlaceholder: string; sshRemotePathLabel: string; sshRemotePathPlaceholder: string; sshConnecting: string; sshTestSuccess: string; sshTestFailed: string; sshAddSuccess: string; sshAddFailed: string; sshHint: string; // Delete confirmation confirmDeleteTitle: string; confirmDeleteMessage: string; confirmDeleteMessagePlural: string; confirmHint: string; // Alert messages alertDefaultCannotDelete: string; }; diffReviewPanel: { title: string; noSnapshots: string; navigationHint: string; filesSuffix: string; filesViewNavigationHint: string; moreAbove: string; moreBelow: string; }; sessionListPanel: { title: string; loading: string; noResults: string; noConversations: string; marked: string; loadingMore: string; messages: string; searchLabel: string; searchPlaceholder: string; searching: string; navigationHint: string; moreAbove: string; moreBelow: string; scrollToLoadMore: string; untitled: string; now: string; renamePrompt: string; renaming: string; renamePlaceholder: string; confirmDelete: string; }; mcpInfoPanel: { title: string; loading: string; refreshing: string; toggling: string; refreshAll: string; noServices: string; error: string; statusSystem: string; statusExternal: string; statusDisabled: string; statusFailed: string; navigationHint: string; pleaseWait: string; skillsTitle: string; noSkills: string; skillLocationProject: string; skillLocationGlobal: string; scrollHint: string; moreAbove: string; moreBelow: string; toolsListTitle: string; toolsNavigationHint: string; toolTogglingHint: string; toolDisabled: string; toolScopeGlobal: string; toolScopeProject: string; mcpSourceProject: string; mcpSourceGlobal: string; }; skillsListPanel: { title: string; loading: string; error: string; noSkills: string; locationProject: string; locationGlobal: string; statusDisabled: string; navigationHint: string; moreAbove: string; moreBelow: string; }; mcpConfigScreen: { title: string; scopeProject: string; scopeGlobal: string; navigationHint: string; savedSuccess: string; configErrors: string; reverted: string; invalidJson: string; }; // Command Args Panel commandArgsPanel: { navigationHint: string; }; // Running Agents Panel runningAgentsPanel: { title: string; noAgentsRunning: string; keyboardHint: string; selected: string; scrollHint: string; moreAbove: string; moreBelow: string; subAgentLabel: string; teammateLabel: string; }; sseServer: { started: string; port: string; workingDir: string; running: string; endpoints: string; logs: string; stopHint: string; }; sseDaemon: { portOccupied: string; stopExistingByPort: string; stopExistingByPid: string; startingDaemon: string; daemonStarted: string; pid: string; port: string; workDir: string; timeout: string; logFile: string; stopService: string; stopByPort: string; stopByPid: string; checkStatus: string; savePidFailed: string; daemonStartFailed: string; noRunningDaemon: string; readPidFailed: string; tryRemoveInvalidPid: string; noDaemonForPid: string; stoppingDaemon: string; stopProcessFailed: string; daemonStopped: string; processNotExists: string; stopProcessError: string; noRunningDaemons: string; foundInvalidPids: string; cleanupHint: string; runningDaemons: string; startTime: string; endpoint: string; stopCommand: string; invalidPidsStopped: string; autoCleanupHint: string; }; newPrompt: { title: string; inputHint: string; placeholder: string; escHint: string; generating: string; previewTitle: string; moreLines: string; actionAccept: string; actionReject: string; actionRegenerate: string; actionRetry: string; actionCancel: string; errorPrefix: string; scrollHint: string; }; btw: { title: string; thinking: string; escHint: string; actionClose: string; errorPrefix: string; scrollHint: string; }; pixelEditor: { title: string; palette: string; eraser: string; colorNumber: string; canvasCleared: string; clearCancelled: string; saveCancelled: string; nameCannotBeEmpty: string; savedAs: string; controlsHint: string; controlsHintPosBrush: string; saveDrawingLabel: string; namePlaceholder: string; escCancelHint: string; confirmClearCanvas: string; }; pixelEditorScreen: { screenTitle: string; newCanvas: string; manageDrawings: string; menuNavigateHint: string; manageTitle: string; noDrawings: string; managerHint: string; confirmDeleteMany: string; moreAbove: string; moreBelow: string; selectedCount: string; exitImageDisabled: string; failedDisableExitImage: string; setAsExitImage: string; }; agentPickerPanel: { title: string; noAgentsWarning: string; selectAgent: string; escHint: string; noDescription: string; scrollHint: string; moreAbove: string; moreBelow: string; }; todoPickerPanel: { title: string; scanning: string; noTodosFound: string; noMatchSearch: string; typeToClearSearch: string; selectTodos: string; filteringLabel: string; typeToFilterHint: string; typeToSearchHint: string; selectedCount: string; noDescription: string; }; exitScreen: { title: string; goodbye: string; thankYou: string; resumeSession: string; version: string; }; }; import type {Language as Lang} from '../utils/config/languageConfig.js'; export type Translations = { [K in Lang]: TranslationKeys; }; ================================================ FILE: source/mcp/aceCodeSearch.ts ================================================ //Autonomous Coding Engine import {promises as fs, createReadStream} from 'fs'; import * as path from 'path'; import {spawn} from 'child_process'; import {createInterface} from 'readline'; import {type FzfResultItem, Fzf} from 'fzf'; import {processManager} from '../utils/core/processManager.js'; import {logger} from '../utils/core/logger.js'; // SSH support for remote file operations import {SSHClient, parseSSHUrl} from '../utils/ssh/sshClient.js'; import { getWorkingDirectories, type SSHConfig, } from '../utils/config/workingDirConfig.js'; // Type definitions import type { CodeSymbol, CodeReference, SemanticSearchResult, SymbolType, } from './types/aceCodeSearch.types.js'; // Utility functions import {detectLanguage} from './utils/aceCodeSearch/language.utils.js'; import { loadExclusionPatterns, shouldExcludeDirectory, shouldExcludeFile, readFileWithCache, type ContentCacheCallbacks, } from './utils/aceCodeSearch/filesystem.utils.js'; import { parseFileSymbols, getContext, } from './utils/aceCodeSearch/symbol.utils.js'; import { isCommandAvailable, parseGrepOutput, expandGlobBraces, isSafeRegexPattern, processWithConcurrency, } from './utils/aceCodeSearch/search.utils.js'; import { INDEX_CACHE_DURATION, BATCH_SIZE, BINARY_EXTENSIONS, GREP_EXCLUDE_DIRS, MAX_INDEXED_FILES, MAX_SYMBOLS_PER_FILE, MAX_FZF_SYMBOL_NAMES, MAX_FILE_OUTLINE_SYMBOLS, MAX_FILE_OUTLINE_PAYLOAD_CHARS, LARGE_FILE_THRESHOLD, FILE_READ_CHUNK_SIZE, TEXT_SEARCH_TIMEOUT_MS, MAX_CONCURRENT_FILE_READS, MAX_REGEX_COMPLEXITY_SCORE, RECENT_FILE_THRESHOLD, MAX_FILE_STAT_CACHE_SIZE, ACE_IDLE_CLEANUP_MS, MAX_CONTENT_CACHE_BYTES, MEMORY_PRESSURE_THRESHOLD_BYTES, MEMORY_CHECK_INTERVAL_MS, } from './utils/aceCodeSearch/constants.utils.js'; export class ACECodeSearchService { private basePath: string; private indexCache: Map<string, CodeSymbol[]> = new Map(); private lastIndexTime: number = 0; private fzfIndex: Fzf<string[]> | undefined; private allIndexedFiles: Set<string> = new Set(); // 使用 Set 提高查找性能 O(1) private fileModTimes: Map<string, number> = new Map(); // Track file modification times private customExcludes: string[] = []; // Custom exclusion patterns from config files private excludesLoaded: boolean = false; // Track if exclusions have been loaded private isIndexTruncated: boolean = false; // Serialize index rebuilds across concurrent/re-entrant tool calls private indexBuildQueue: Promise<void> = Promise.resolve(); // 文件内容缓存（用于减少重复读取） private fileContentCache: Map<string, {content: string; mtime: number}> = new Map(); // 正则表达式缓存（用于 shouldExcludeDirectory） private regexCache: Map<string, RegExp> = new Map(); // 命令可用性缓存（避免重复 spawn which 进程） private commandAvailabilityCache: Map<string, boolean> = new Map(); // Git 仓库状态缓存 private isGitRepoCache: boolean | null = null; // 文件修改时间缓存（用于 sortResultsByRecency） private fileStatCache: Map<string, {mtimeMs: number; cachedAt: number}> = new Map(); private static readonly STAT_CACHE_TTL = 60 * 1000; // 60秒过期 private idleCleanupTimer: NodeJS.Timeout | undefined; private isDisposed = false; private readonly idleCleanupMs: number; private fileContentCacheBytes: number = 0; private lastMemoryCheckTime: number = 0; private readonly contentCacheCallbacks: ContentCacheCallbacks; constructor( basePath: string = process.cwd(), options?: {idleCleanupMs?: number}, ) { this.basePath = path.resolve(basePath); this.idleCleanupMs = options?.idleCleanupMs ?? ACE_IDLE_CLEANUP_MS; this.contentCacheCallbacks = { onAdd: (_filePath, content) => { this.fileContentCacheBytes += content.length * 2; this.trimContentCacheByBytes(); }, onEvict: filePath => { const entry = this.fileContentCache.get(filePath); if (entry) { this.fileContentCacheBytes -= entry.content.length * 2; } }, }; this.scheduleIdleCleanup(); } private async withIndexBuildLock<T>(fn: () => Promise<T>): Promise<T> { const next = this.indexBuildQueue.then(fn, fn); this.indexBuildQueue = next.then( () => undefined, () => undefined, ); return next; } private markIndexTruncated(message: string): void { if (!this.isIndexTruncated) { logger.warn(message); } this.isIndexTruncated = true; } private ensureNotDisposed(): void { if (this.isDisposed) { throw new Error('ACECodeSearchService has been disposed'); } } private scheduleIdleCleanup(): void { if (this.isDisposed || this.idleCleanupMs <= 0) { return; } if (this.idleCleanupTimer) { clearTimeout(this.idleCleanupTimer); } this.idleCleanupTimer = setTimeout(() => { if (this.isDisposed) { return; } logger.debug( `ACECodeSearchService idle cleanup triggered for ${this.basePath}`, ); this.clearCaches({preserveExclusions: true, preserveCommandCache: true}); }, this.idleCleanupMs); this.idleCleanupTimer.unref?.(); } private markActivity(): void { this.ensureNotDisposed(); this.scheduleIdleCleanup(); this.checkMemoryPressure(); } private removeFromContentCache(filePath: string): void { const existing = this.fileContentCache.get(filePath); if (existing) { this.fileContentCacheBytes -= existing.content.length * 2; this.fileContentCache.delete(filePath); } } private clearContentCache(): void { this.fileContentCache.clear(); this.fileContentCacheBytes = 0; } private trimContentCacheByBytes(): void { if (this.fileContentCacheBytes <= MAX_CONTENT_CACHE_BYTES) { return; } const entries = Array.from(this.fileContentCache.entries()); let i = 0; while ( this.fileContentCacheBytes > MAX_CONTENT_CACHE_BYTES && i < entries.length ) { const entry = entries[i]; if (entry) { this.fileContentCacheBytes -= entry[1].content.length * 2; this.fileContentCache.delete(entry[0]); } i++; } if (this.fileContentCacheBytes < 0) { this.fileContentCacheBytes = 0; } } private checkMemoryPressure(): void { const now = Date.now(); if (now - this.lastMemoryCheckTime < MEMORY_CHECK_INTERVAL_MS) { return; } this.lastMemoryCheckTime = now; const rss = process.memoryUsage.rss(); if (rss > MEMORY_PRESSURE_THRESHOLD_BYTES) { logger.warn( `ACE memory pressure detected (RSS: ${Math.round( rss / 1024 / 1024, )}MB), triggering aggressive cleanup`, ); this.clearContentCache(); this.fileStatCache.clear(); if (rss > MEMORY_PRESSURE_THRESHOLD_BYTES * 1.5) { logger.warn( 'ACE critical memory pressure, clearing all transient caches', ); this.clearCaches({ preserveExclusions: true, preserveCommandCache: true, }); } } } getMemoryStats(): { indexedFiles: number; cachedSymbols: number; contentCacheEntries: number; contentCacheBytes: number; statCacheEntries: number; regexCacheEntries: number; rssBytes: number; } { let cachedSymbols = 0; for (const symbols of this.indexCache.values()) { cachedSymbols += symbols.length; } return { indexedFiles: this.allIndexedFiles.size, cachedSymbols, contentCacheEntries: this.fileContentCache.size, contentCacheBytes: this.fileContentCacheBytes, statCacheEntries: this.fileStatCache.size, regexCacheEntries: this.regexCache.size, rssBytes: process.memoryUsage.rss(), }; } private trimFileStatCache(): void { const overflow = this.fileStatCache.size - MAX_FILE_STAT_CACHE_SIZE; if (overflow <= 0) { return; } const entries = Array.from(this.fileStatCache.entries()).sort( (a, b) => a[1].cachedAt - b[1].cachedAt, ); for (let i = 0; i < overflow; i++) { const filePath = entries[i]?.[0]; if (filePath) { this.fileStatCache.delete(filePath); } } } private clearCaches(options?: { preserveExclusions?: boolean; preserveCommandCache?: boolean; }): void { this.indexCache.clear(); this.fileModTimes.clear(); this.allIndexedFiles.clear(); this.clearContentCache(); this.fileStatCache.clear(); this.fzfIndex = undefined; this.lastIndexTime = 0; this.isIndexTruncated = false; this.indexBuildQueue = Promise.resolve(); if (!options?.preserveExclusions) { this.customExcludes = []; this.excludesLoaded = false; this.regexCache.clear(); } if (!options?.preserveCommandCache) { this.commandAvailabilityCache.clear(); this.isGitRepoCache = null; } } dispose(): void { if (this.idleCleanupTimer) { clearTimeout(this.idleCleanupTimer); this.idleCleanupTimer = undefined; } this.clearCaches(); this.isDisposed = true; } /** * Check if a path is a remote SSH URL * @param filePath - Path to check * @returns True if the path is an SSH URL */ private isSSHPath(filePath: string): boolean { return filePath.startsWith('ssh://'); } /** * Get SSH config for a remote path from working directories * @param sshUrl - SSH URL to find config for * @returns SSH config if found, null otherwise */ private async getSSHConfigForPath(sshUrl: string): Promise<SSHConfig | null> { const workingDirs = await getWorkingDirectories(); for (const dir of workingDirs) { if (dir.isRemote && dir.sshConfig && sshUrl.startsWith(dir.path)) { return dir.sshConfig; } } // Try to match by host/user const parsed = parseSSHUrl(sshUrl); if (parsed) { for (const dir of workingDirs) { if (dir.isRemote && dir.sshConfig) { const dirParsed = parseSSHUrl(dir.path); if ( dirParsed && dirParsed.host === parsed.host && dirParsed.username === parsed.username && dirParsed.port === parsed.port ) { return dir.sshConfig; } } } } return null; } /** * Read file content from remote SSH server * @param sshUrl - SSH URL of the file * @returns File content as string */ private async readRemoteFile(sshUrl: string): Promise<string> { const parsed = parseSSHUrl(sshUrl); if (!parsed) { throw new Error(`Invalid SSH URL: ${sshUrl}`); } const sshConfig = await this.getSSHConfigForPath(sshUrl); if (!sshConfig) { throw new Error(`No SSH configuration found for: ${sshUrl}`); } const client = new SSHClient(); const connectResult = await client.connect(sshConfig); if (!connectResult.success) { throw new Error(`SSH connection failed: ${connectResult.error}`); } try { const content = await client.readFile(parsed.path); return content; } finally { client.disconnect(); } } /** * Load custom exclusion patterns from .gitignore and .snowignore */ private async loadExclusionPatterns(): Promise<void> { if (this.excludesLoaded) return; this.customExcludes = await loadExclusionPatterns(this.basePath); this.excludesLoaded = true; } /** * Check if a command is available (with caching) */ private async isCommandAvailableCached(command: string): Promise<boolean> { const cached = this.commandAvailabilityCache.get(command); if (cached !== undefined) { return cached; } const available = await isCommandAvailable(command); this.commandAvailabilityCache.set(command, available); return available; } /** * Check if a directory is a Git repository (with caching) */ private async isGitRepository( directory: string = this.basePath, ): Promise<boolean> { // Only cache for basePath if (directory === this.basePath && this.isGitRepoCache !== null) { return this.isGitRepoCache; } try { const gitDir = path.join(directory, '.git'); const stats = await fs.stat(gitDir); const isRepo = stats.isDirectory(); if (directory === this.basePath) { this.isGitRepoCache = isRepo; } return isRepo; } catch { if (directory === this.basePath) { this.isGitRepoCache = false; } return false; } } /** * Build or refresh the code symbol index with incremental updates */ private async buildIndex(forceRefresh: boolean = false): Promise<void> { this.markActivity(); return this.withIndexBuildLock(async () => { const now = Date.now(); // Use cache if available and not expired if ( !forceRefresh && this.indexCache.size > 0 && now - this.lastIndexTime < INDEX_CACHE_DURATION ) { return; } // Load exclusion patterns await this.loadExclusionPatterns(); // For force refresh, clear everything if (forceRefresh) { this.clearCaches({ preserveExclusions: true, preserveCommandCache: true, }); } const filesToProcess: string[] = []; const searchInDirectory = async (dirPath: string): Promise<void> => { try { const entries = await fs.readdir(dirPath, {withFileTypes: true}); for (const entry of entries) { const fullPath = path.join(dirPath, entry.name); if (entry.isDirectory()) { if ( shouldExcludeDirectory( entry.name, fullPath, this.basePath, this.customExcludes, this.regexCache, ) ) { continue; } await searchInDirectory(fullPath); continue; } if (!entry.isFile()) { continue; } const language = detectLanguage(fullPath); if (!language) { continue; } const isAlreadyIndexed = this.allIndexedFiles.has(fullPath); if ( !isAlreadyIndexed && this.allIndexedFiles.size >= MAX_INDEXED_FILES ) { this.markIndexTruncated( `ACE symbol index reached the ${MAX_INDEXED_FILES} file safety limit; skipping remaining files to avoid excessive memory usage`, ); continue; } try { const stats = await fs.stat(fullPath); const currentMtime = stats.mtimeMs; const cachedMtime = this.fileModTimes.get(fullPath); if (cachedMtime === undefined || currentMtime > cachedMtime) { filesToProcess.push(fullPath); this.fileModTimes.set(fullPath, currentMtime); } this.allIndexedFiles.add(fullPath); } catch { // If we can't stat the file, skip it } } } catch { // Skip directories that cannot be accessed } }; await searchInDirectory(this.basePath); const batches: string[][] = []; for (let i = 0; i < filesToProcess.length; i += BATCH_SIZE) { batches.push(filesToProcess.slice(i, i + BATCH_SIZE)); } for (const batch of batches) { await Promise.all( batch.map(async fullPath => { try { const content = await readFileWithCache( fullPath, this.fileContentCache, 50, this.contentCacheCallbacks, ); const symbols = await parseFileSymbols( fullPath, content, this.basePath, { includeContext: false, includeSignature: false, maxSymbols: MAX_SYMBOLS_PER_FILE, }, ); if (symbols.length >= MAX_SYMBOLS_PER_FILE) { this.markIndexTruncated( `ACE symbol index capped files at ${MAX_SYMBOLS_PER_FILE} symbols each to avoid excessive memory usage`, ); } if (symbols.length > 0) { this.indexCache.set(fullPath, symbols); } else { this.indexCache.delete(fullPath); } } catch { this.indexCache.delete(fullPath); this.fileModTimes.delete(fullPath); this.removeFromContentCache(fullPath); } }), ); } for (const cachedPath of Array.from(this.indexCache.keys())) { try { await fs.access(cachedPath); } catch { this.indexCache.delete(cachedPath); this.fileModTimes.delete(cachedPath); this.allIndexedFiles.delete(cachedPath); this.removeFromContentCache(cachedPath); } } this.lastIndexTime = now; if (filesToProcess.length > 0 || forceRefresh) { this.buildFzfIndex(); } // Symbols are extracted — file contents are no longer needed this.clearContentCache(); }); } /** * Build fzf index for fast fuzzy symbol name matching */ private buildFzfIndex(): void { const uniqueNames = new Set<string>(); for (const fileSymbols of this.indexCache.values()) { for (const symbol of fileSymbols) { uniqueNames.add(symbol.name); if (uniqueNames.size > MAX_FZF_SYMBOL_NAMES) { this.fzfIndex = undefined; this.markIndexTruncated( `ACE fuzzy index exceeded ${MAX_FZF_SYMBOL_NAMES} unique symbol names; falling back to manual scoring to keep memory bounded`, ); return; } } } const symbolNames = Array.from(uniqueNames); const fuzzyAlgorithm = symbolNames.length > 20000 ? 'v1' : 'v2'; // Use sync Fzf to avoid AsyncFzf cancellation/race issues under concurrent tool calls this.fzfIndex = new Fzf(symbolNames, { fuzzy: fuzzyAlgorithm, }); } /** * Search for symbols by name with fuzzy matching using fzf */ async searchSymbols( query: string, symbolType?: CodeSymbol['type'], language?: string, maxResults: number = 100, ): Promise<SemanticSearchResult> { this.markActivity(); const startTime = Date.now(); await this.buildIndex(); await this.indexBuildQueue; const symbols: CodeSymbol[] = []; // Use fzf for fuzzy matching if available if (this.fzfIndex) { try { // Get fuzzy matches from fzf const fzfResults = this.fzfIndex.find(query); // Build a set of matched symbol names for quick lookup const matchedNames = new Set( fzfResults.map((r: FzfResultItem<string>) => r.item), ); // Collect matching symbols with filters for (const fileSymbols of this.indexCache.values()) { for (const symbol of fileSymbols) { // Apply filters if (symbolType && symbol.type !== symbolType) continue; if (language && symbol.language !== language) continue; // Check if symbol name is in fzf matches if (matchedNames.has(symbol.name)) { symbols.push({...symbol}); } if (symbols.length >= maxResults) break; } if (symbols.length >= maxResults) break; } // Sort by fzf score (already sorted by relevance from fzf.find) // Maintain the fzf order by using the original fzfResults order const nameOrder = new Map( fzfResults.map((r: FzfResultItem<string>, i: number) => [r.item, i]), ); symbols.sort((a, b) => { const aOrder = nameOrder.get(a.name); const bOrder = nameOrder.get(b.name); // Handle undefined cases if (aOrder === undefined && bOrder === undefined) return 0; if (aOrder === undefined) return 1; if (bOrder === undefined) return -1; // Both are numbers (TypeScript needs explicit assertion) return (aOrder as number) - (bOrder as number); }); } catch (error) { // Fall back to manual scoring if fzf fails logger.info( `fzf search failed, falling back to manual scoring: ${ error instanceof Error ? error.message : String(error) }`, ); return this.searchSymbolsManual( query, symbolType, language, maxResults, startTime, ); } } else { // Fallback to manual scoring if fzf is not available return this.searchSymbolsManual( query, symbolType, language, maxResults, startTime, ); } const searchTime = Date.now() - startTime; return { query, symbols, references: [], // References would be populated by findReferences totalResults: symbols.length, searchTime, }; } /** * Fallback symbol search using manual fuzzy matching */ private async searchSymbolsManual( query: string, symbolType?: CodeSymbol['type'], language?: string, maxResults: number = 100, startTime: number = Date.now(), ): Promise<SemanticSearchResult> { const queryLower = query.toLowerCase(); // Fuzzy match scoring const calculateScore = (symbolName: string): number => { const nameLower = symbolName.toLowerCase(); // Exact match if (nameLower === queryLower) return 100; // Starts with if (nameLower.startsWith(queryLower)) return 80; // Contains if (nameLower.includes(queryLower)) return 60; // Camel case match (e.g., "gfc" matches "getFileContent") const camelCaseMatch = symbolName .split(/(?=[A-Z])/) .map(s => s[0]?.toLowerCase() || '') .join(''); if (camelCaseMatch.includes(queryLower)) return 40; // Fuzzy match let score = 0; let queryIndex = 0; for ( let i = 0; i < nameLower.length && queryIndex < queryLower.length; i++ ) { if (nameLower[i] === queryLower[queryIndex]) { score += 20; queryIndex++; } } if (queryIndex === queryLower.length) return score; return 0; }; // Search through all indexed symbols with score caching const symbolsWithScores: Array<{symbol: CodeSymbol; score: number}> = []; for (const fileSymbols of this.indexCache.values()) { for (const symbol of fileSymbols) { // Apply filters if (symbolType && symbol.type !== symbolType) continue; if (language && symbol.language !== language) continue; const score = calculateScore(symbol.name); if (score > 0) { symbolsWithScores.push({symbol: {...symbol}, score}); } if (symbolsWithScores.length >= maxResults * 2) break; // 获取更多候选以便排序 } if (symbolsWithScores.length >= maxResults * 2) break; } // Sort by score (避免重复计算) symbolsWithScores.sort((a, b) => b.score - a.score); // Extract top results const symbols = symbolsWithScores .slice(0, maxResults) .map(item => item.symbol); const searchTime = Date.now() - startTime; return { query, symbols, references: [], // References would be populated by findReferences totalResults: symbols.length, searchTime, }; } /** * Find all references to a symbol */ async findReferences( symbolName: string, maxResults: number = 100, ): Promise<CodeReference[]> { this.markActivity(); const references: CodeReference[] = []; // Load exclusion patterns await this.loadExclusionPatterns(); // Escape special regex characters to prevent ReDoS const escapedSymbol = symbolName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // 使用标记来控制递归提前终止 let shouldStop = false; const searchInDirectory = async (dirPath: string): Promise<void> => { // 提前终止检查 if (shouldStop || references.length >= maxResults) { shouldStop = true; return; } try { const entries = await fs.readdir(dirPath, {withFileTypes: true}); for (const entry of entries) { // 每次循环都检查是否应该停止 if (shouldStop || references.length >= maxResults) { shouldStop = true; return; } const fullPath = path.join(dirPath, entry.name); if (entry.isDirectory()) { // Use configurable exclusion check if ( shouldExcludeDirectory( entry.name, fullPath, this.basePath, this.customExcludes, this.regexCache, ) ) { continue; } await searchInDirectory(fullPath); } else if (entry.isFile()) { // 使用配置化的文件排除检查（支持 .gitignore/.snowignore） if ( shouldExcludeFile( entry.name, fullPath, this.basePath, this.customExcludes, this.regexCache, ) ) { continue; } const language = detectLanguage(fullPath); if (language) { try { const content = await readFileWithCache( fullPath, this.fileContentCache, 50, this.contentCacheCallbacks, ); const lines = content.split('\n'); // Search for symbol usage with escaped symbol name const regex = new RegExp(`\\b${escapedSymbol}\\b`, 'g'); for (let i = 0; i < lines.length; i++) { // 内层循环也检查限制 if (references.length >= maxResults) { shouldStop = true; return; } const line = lines[i]; if (!line) continue; // Reset regex for each line regex.lastIndex = 0; let match; while ((match = regex.exec(line)) !== null) { // 每找到一个匹配都检查 if (references.length >= maxResults) { shouldStop = true; return; } // Determine reference type let referenceType: CodeReference['referenceType'] = 'usage'; if (line.includes('import') && line.includes(symbolName)) { referenceType = 'import'; } else if ( new RegExp( `(?:function|class|const|let|var)\\s+${escapedSymbol}`, ).test(line) ) { referenceType = 'definition'; } else if ( line.includes(':') && line.includes(symbolName) ) { referenceType = 'type'; } references.push({ symbol: symbolName, filePath: path.relative(this.basePath, fullPath), line: i + 1, column: match.index + 1, context: getContext(lines, i, 1), referenceType, }); } } } catch (error) { // Skip files that cannot be read } } } } } catch (error) { // Skip directories that cannot be accessed } }; await searchInDirectory(this.basePath); this.trimContentCacheByBytes(); return references; } /** * Find symbol definition (go to definition) */ async findDefinition( symbolName: string, contextFile?: string, ): Promise<CodeSymbol | null> { this.markActivity(); await this.buildIndex(); await this.indexBuildQueue; // Search in the same file first if context is provided if (contextFile) { const fullPath = path.resolve(this.basePath, contextFile); const fileSymbols = this.indexCache.get(fullPath); if (fileSymbols) { const symbol = fileSymbols.find( s => s.name === symbolName && (s.type === 'function' || s.type === 'class' || s.type === 'variable'), ); if (symbol) return symbol; } } // Search in all files for (const fileSymbols of this.indexCache.values()) { const symbol = fileSymbols.find( s => s.name === symbolName && (s.type === 'function' || s.type === 'class' || s.type === 'variable'), ); if (symbol) return symbol; } return null; } /** * Strategy 1: Use git grep for fast searching in Git repositories * Enhanced with timeout protection to prevent hanging */ private async gitGrepSearch( pattern: string, fileGlob?: string, maxResults: number = 100, isRegex: boolean = true, ): Promise< Array<{filePath: string; line: number; column: number; content: string}> > { this.markActivity(); const timeoutMs = 15000; return new Promise((resolve, reject) => { const args = ['grep', '--untracked', '-n', '--ignore-case']; if (isRegex) { args.push('-E'); } else { args.push('--fixed-strings'); } args.push(pattern); if (fileGlob) { let gitGlob = fileGlob.replace(/\\/g, '/'); gitGlob = gitGlob.replace(/\*\*/g, '*'); const expandedGlobs = expandGlobBraces(gitGlob); args.push('--', ...expandedGlobs); } const child = spawn('git', args, { cwd: this.basePath, windowsHide: true, }); processManager.register(child); const stdoutChunks: Buffer[] = []; const stderrChunks: Buffer[] = []; let isCompleted = false; const finalize = ( handler: () => void, killProcess: boolean = false, ): void => { if (isCompleted) { return; } isCompleted = true; clearTimeout(timeoutId); child.stdout.removeAllListeners(); child.stderr.removeAllListeners(); child.removeAllListeners('error'); child.removeAllListeners('close'); if (killProcess && !child.killed) { child.kill('SIGTERM'); } handler(); stdoutChunks.length = 0; stderrChunks.length = 0; }; const timeoutId = setTimeout(() => { finalize(() => { logger.warn( `git grep timed out after ${timeoutMs}ms, killing process`, ); reject(new Error(`git grep timed out after ${timeoutMs}ms`)); }, true); }, timeoutMs); timeoutId.unref?.(); child.stdout.on('data', chunk => stdoutChunks.push(chunk)); child.stderr.on('data', chunk => stderrChunks.push(chunk)); child.once('error', err => { finalize(() => { reject(new Error(`Failed to start git grep: ${err.message}`)); }); }); child.once('close', code => { const stdoutData = Buffer.concat(stdoutChunks).toString('utf8'); const stderrData = Buffer.concat(stderrChunks).toString('utf8').trim(); finalize(() => { if (code === 0) { const results = parseGrepOutput(stdoutData, this.basePath); resolve(results.slice(0, maxResults)); } else if (code === 1) { resolve([]); } else { reject( new Error(`git grep exited with code ${code}: ${stderrData}`), ); } }); }); }); } /** * Strategy 2: Use system grep (or ripgrep if available) for fast searching * Enhanced with timeout protection to prevent hanging on Windows */ private async systemGrepSearch( pattern: string, fileGlob?: string, maxResults: number = 100, grepCommand: 'rg' | 'grep' = 'grep', ): Promise< Array<{filePath: string; line: number; column: number; content: string}> > { this.markActivity(); const isRipgrep = grepCommand === 'rg'; const timeoutMs = 15000; return new Promise((resolve, reject) => { const args = isRipgrep ? ['-n', '-i', '--no-heading'] : ['-r', '-n', '-H', '-E', '-i']; if (isRipgrep) { GREP_EXCLUDE_DIRS.forEach(dir => args.push('--glob', `!${dir}/`)); if (fileGlob) { const normalizedGlob = fileGlob.replace(/\\/g, '/'); const expandedGlobs = expandGlobBraces(normalizedGlob); expandedGlobs.forEach(glob => args.push('--glob', glob)); } } else { GREP_EXCLUDE_DIRS.forEach(dir => args.push(`--exclude-dir=${dir}`)); if (fileGlob) { const normalizedGlob = fileGlob.replace(/\\/g, '/'); const expandedGlobs = expandGlobBraces(normalizedGlob); expandedGlobs.forEach(glob => args.push(`--include=${glob}`)); } } args.push(pattern, '.'); const child = spawn(grepCommand, args, { cwd: this.basePath, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], }); processManager.register(child); const stdoutChunks: Buffer[] = []; const stderrChunks: Buffer[] = []; let isCompleted = false; const finalize = ( handler: () => void, killProcess: boolean = false, ): void => { if (isCompleted) { return; } isCompleted = true; clearTimeout(timeoutId); child.stdout.removeAllListeners(); child.stderr.removeAllListeners(); child.removeAllListeners('error'); child.removeAllListeners('close'); if (killProcess && !child.killed) { child.kill('SIGTERM'); } handler(); stdoutChunks.length = 0; stderrChunks.length = 0; }; const timeoutId = setTimeout(() => { finalize(() => { logger.warn( `${grepCommand} timed out after ${timeoutMs}ms, killing process`, ); reject(new Error(`${grepCommand} timed out after ${timeoutMs}ms`)); }, true); }, timeoutMs); timeoutId.unref?.(); child.stdout.on('data', chunk => stdoutChunks.push(chunk)); child.stderr.on('data', chunk => { const stderrStr = chunk.toString(); if ( !stderrStr.includes('Permission denied') && !/grep:.*: Is a directory/i.test(stderrStr) ) { stderrChunks.push(chunk); } }); child.once('error', err => { finalize(() => { reject(new Error(`Failed to start ${grepCommand}: ${err.message}`)); }); }); child.once('close', code => { const stdoutData = Buffer.concat(stdoutChunks).toString('utf8'); const stderrData = Buffer.concat(stderrChunks).toString('utf8').trim(); finalize(() => { if (code === 0) { const results = parseGrepOutput(stdoutData, this.basePath); resolve(results.slice(0, maxResults)); } else if (code === 1) { resolve([]); } else if (stderrData) { reject( new Error( `${grepCommand} exited with code ${code}: ${stderrData}`, ), ); } else { resolve([]); } }); }); }); } /** * Convert a glob pattern to a RegExp that matches full paths * Supports: *, **, ?, {a,b}, [abc] */ private globPatternToRegex(globPattern: string): RegExp { // Normalize path separators const normalizedGlob = globPattern.replace(/\\/g, '/'); // First, temporarily replace glob special patterns with placeholders // to prevent them from being escaped let regexStr = normalizedGlob .replace(/\*\*/g, '\x00DOUBLESTAR\x00') // ** -> placeholder .replace(/\*/g, '\x00STAR\x00') // * -> placeholder .replace(/\?/g, '\x00QUESTION\x00'); // ? -> placeholder // Now escape all special regex characters regexStr = regexStr.replace(/[.+^${}()|[\]\\]/g, '\\$&'); // Replace placeholders with actual regex patterns regexStr = regexStr .replace(/\x00DOUBLESTAR\x00/g, '.*') // ** -> .* (match any path segments) .replace(/\x00STAR\x00/g, '[^/]*') // * -> [^/]* (match within single segment) .replace(/\x00QUESTION\x00/g, '.'); // ? -> . (match single character) return new RegExp(regexStr, 'i'); } /** * Strategy 3: Pure JavaScript fallback search * Enhanced with performance protections: * - File size limits (skip files > 5MB) * - Timeout protection (30s max) * - ReDoS protection (regex complexity check) * - Concurrent read limiting */ private async jsTextSearch( pattern: string, fileGlob?: string, isRegex: boolean = true, maxResults: number = 100, ): Promise< Array<{filePath: string; line: number; column: number; content: string}> > { this.markActivity(); const results: Array<{ filePath: string; line: number; column: number; content: string; }> = []; // Track if search should be aborted let isAborted = false; const startTime = Date.now(); // Check timeout periodically const checkTimeout = (): void => { if (Date.now() - startTime > TEXT_SEARCH_TIMEOUT_MS) { isAborted = true; logger.warn(`Text search timeout after ${TEXT_SEARCH_TIMEOUT_MS}ms`); } }; // Load exclusion patterns await this.loadExclusionPatterns(); // Compile search pattern with ReDoS protection let searchRegex: RegExp; try { if (isRegex) { // Check for ReDoS vulnerabilities const safety = isSafeRegexPattern(pattern, MAX_REGEX_COMPLEXITY_SCORE); if (!safety.isSafe) { throw new Error(`Potentially unsafe regex pattern: ${safety.reason}`); } searchRegex = new RegExp(pattern, 'gi'); } else { // Escape special regex characters for literal search const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); searchRegex = new RegExp(escaped, 'gi'); } } catch (error) { if (error instanceof Error) { throw error; } throw new Error(`Invalid regex pattern: ${pattern}`); } // Parse glob pattern if provided using improved glob parser const globRegex = fileGlob ? this.globPatternToRegex(fileGlob) : null; // Collect all files to search first interface FileToSearch { fullPath: string; relativePath: string; } const filesToSearch: FileToSearch[] = []; // Search recursively to collect files const collectFiles = async (dirPath: string): Promise<void> => { if (isAborted || filesToSearch.length >= maxResults * 10) return; checkTimeout(); try { const entries = await fs.readdir(dirPath, {withFileTypes: true}); for (const entry of entries) { if (isAborted || filesToSearch.length >= maxResults * 10) break; const fullPath = path.join(dirPath, entry.name); if (entry.isDirectory()) { // Use configurable exclusion check if ( shouldExcludeDirectory( entry.name, fullPath, this.basePath, this.customExcludes, this.regexCache, ) ) { continue; } await collectFiles(fullPath); } else if (entry.isFile()) { // Filter by glob if specified const relativePath = path .relative(this.basePath, fullPath) .replace(/\\/g, '/'); if (globRegex && !globRegex.test(relativePath)) { continue; } // Skip binary files (using Set for fast lookup) const ext = path.extname(entry.name).toLowerCase(); if (BINARY_EXTENSIONS.has(ext)) { continue; } filesToSearch.push({fullPath, relativePath}); } } } catch (error) { // Skip directories that cannot be accessed } }; await collectFiles(this.basePath); // Process files with limited concurrency const processFile = async (fileInfo: FileToSearch): Promise<void> => { if (isAborted || results.length >= maxResults) return; checkTimeout(); try { // Check file size to decide reading strategy const stats = await fs.stat(fileInfo.fullPath); if (stats.size <= LARGE_FILE_THRESHOLD) { // Small file: read entirely for better performance const content = await fs.readFile(fileInfo.fullPath, 'utf-8'); const lines = content.split('\n'); for (let i = 0; i < lines.length; i++) { if (isAborted || results.length >= maxResults) break; const line = lines[i]; if (!line) continue; // Reset regex for each line searchRegex.lastIndex = 0; const match = searchRegex.exec(line); if (match) { results.push({ filePath: fileInfo.relativePath, line: i + 1, column: match.index + 1, content: line.trim(), }); } } } else { // Large file: use streaming to control memory logger.info( `Streaming large file (${stats.size} bytes): ${fileInfo.relativePath}`, ); await this.searchInLargeFile( fileInfo, searchRegex, results, maxResults, () => isAborted, ); } } catch (error) { // Skip files that cannot be read (binary, permissions, etc.) } }; // Process files with concurrency limit await processWithConcurrency( filesToSearch, processFile, MAX_CONCURRENT_FILE_READS, ); if (isAborted) { logger.warn( `Text search aborted after ${Date.now() - startTime}ms, returning ${ results.length } partial results`, ); } return results; } /** * Search within a large file using streaming to control memory usage. * Processes the file line by line without loading entire content into memory. */ private async searchInLargeFile( fileInfo: {fullPath: string; relativePath: string}, searchRegex: RegExp, results: Array<{ filePath: string; line: number; column: number; content: string; }>, maxResults: number, isAborted: () => boolean, ): Promise<void> { this.markActivity(); return new Promise(resolve => { const stream = createReadStream(fileInfo.fullPath, { highWaterMark: FILE_READ_CHUNK_SIZE, encoding: 'utf-8', }); const rl = createInterface({ input: stream, crlfDelay: Infinity, }); let lineNumber = 0; let isResolved = false; const finalize = (): void => { if (isResolved) { return; } isResolved = true; rl.removeAllListeners(); stream.removeAllListeners(); stream.destroy(); resolve(); }; rl.on('line', (line: string) => { if (isAborted() || results.length >= maxResults) { rl.close(); return; } lineNumber++; if (!line) return; searchRegex.lastIndex = 0; const match = searchRegex.exec(line); if (match) { results.push({ filePath: fileInfo.relativePath, line: lineNumber, column: match.index + 1, content: line.trim(), }); } }); rl.once('close', finalize); rl.once('error', (err: Error) => { logger.info( `Error reading large file ${fileInfo.relativePath}: ${err.message}`, ); finalize(); }); stream.once('error', (err: Error) => { logger.info( `Stream error for ${fileInfo.relativePath}: ${err.message}`, ); finalize(); }); }); } /** * Fast text search with multi-layer strategy * Strategy 1: git grep (fastest, uses git index) * Strategy 2: system grep/ripgrep (fast, system-optimized) * Strategy 3: JavaScript fallback (slower, but always works) * Searches for text patterns across files with glob filtering * * Enhanced with global timeout protection to prevent runaway searches */ async textSearch( pattern: string, fileGlob?: string, isRegex: boolean = true, maxResults: number = 100, ): Promise< Array<{filePath: string; line: number; column: number; content: string}> > { this.markActivity(); const timeoutMs = TEXT_SEARCH_TIMEOUT_MS; return new Promise((resolve, reject) => { const timeoutId = setTimeout(() => { reject( new Error( `Text search exceeded ${timeoutMs}ms timeout. Try using a more specific pattern or fileGlob filter.`, ), ); }, timeoutMs); timeoutId.unref?.(); this.executeTextSearch(pattern, fileGlob, isRegex, maxResults) .then(result => { clearTimeout(timeoutId); resolve(result); }) .catch(error => { clearTimeout(timeoutId); reject(error); }); }); } /** * Internal text search implementation (separated for timeout wrapping) * * Strategy priority: * 1. git grep (fastest, works in git repos) * 2. system grep (reliable on all platforms, especially Windows) * 3. ripgrep (fast but can hang on Windows) * 4. JavaScript fallback (always works) */ private async executeTextSearch( pattern: string, fileGlob?: string, isRegex: boolean = true, maxResults: number = 100, ): Promise< Array<{filePath: string; line: number; column: number; content: string}> > { this.markActivity(); // Check command availability once (cached) const [isGitRepo, gitAvailable, rgAvailable, grepAvailable] = await Promise.all([ this.isGitRepository(), this.isCommandAvailableCached('git'), this.isCommandAvailableCached('rg'), this.isCommandAvailableCached('grep'), ]); // Strategy 1: Try git grep first (fastest in git repos) if (isGitRepo && gitAvailable) { try { const results = await this.gitGrepSearch( pattern, fileGlob, maxResults, isRegex, ); if (results.length > 0) { return await this.sortResultsByRecency(results); } } catch (error) { // Fall through to next strategy } } // Strategy 2: Try ripgrep (fast and reliable, with timeout protection) if (rgAvailable) { try { const results = await this.systemGrepSearch( pattern, fileGlob, maxResults, 'rg', ); return await this.sortResultsByRecency(results); } catch (error) { logger.info('Ripgrep failed, trying next strategy'); // Fall through to system grep or JavaScript fallback } } // Strategy 3: Try system grep as fallback if (grepAvailable) { try { const results = await this.systemGrepSearch( pattern, fileGlob, maxResults, 'grep', ); return await this.sortResultsByRecency(results); } catch (error) { logger.info('System grep failed, falling back to JavaScript search'); // Fall through to JavaScript fallback } } // Strategy 4: JavaScript fallback (always works) logger.info('Using JavaScript fallback for text search'); const results = await this.jsTextSearch( pattern, fileGlob, isRegex, maxResults, ); return await this.sortResultsByRecency(results); } /** * Sort search results by file modification time (recent files first) * Files modified within last 24 hours are prioritized * Uses cached stat calls for better performance */ private async sortResultsByRecency( results: Array<{ filePath: string; line: number; column: number; content: string; }>, ): Promise< Array<{filePath: string; line: number; column: number; content: string}> > { if (results.length === 0) return results; const now = Date.now(); const recentThreshold = RECENT_FILE_THRESHOLD; // Get unique file paths const uniqueFiles = Array.from(new Set(results.map(r => r.filePath))); // Fetch file modification times with caching const fileModTimes = new Map<string, number>(); const uncachedFiles: string[] = []; // Check cache first for (const filePath of uniqueFiles) { const cached = this.fileStatCache.get(filePath); if ( cached && now - cached.cachedAt < ACECodeSearchService.STAT_CACHE_TTL ) { fileModTimes.set(filePath, cached.mtimeMs); } else { uncachedFiles.push(filePath); } } // Fetch uncached files in parallel if (uncachedFiles.length > 0) { const statResults = await Promise.allSettled( uncachedFiles.map(async filePath => { const fullPath = path.resolve(this.basePath, filePath); const stats = await fs.stat(fullPath); return {filePath, mtimeMs: stats.mtimeMs}; }), ); statResults.forEach((result, index) => { const filePath = uncachedFiles[index]!; if (result.status === 'fulfilled') { const mtimeMs = result.value.mtimeMs; fileModTimes.set(filePath, mtimeMs); this.fileStatCache.set(filePath, {mtimeMs, cachedAt: now}); this.trimFileStatCache(); } else { // If we can't get stats, treat as old file fileModTimes.set(filePath, 0); } }); } // Sort results: recent files first, then by original order return results.sort((a, b) => { const aMtime = fileModTimes.get(a.filePath) || 0; const bMtime = fileModTimes.get(b.filePath) || 0; const aIsRecent = now - aMtime < recentThreshold; const bIsRecent = now - bMtime < recentThreshold; // Recent files come first if (aIsRecent && !bIsRecent) return -1; if (!aIsRecent && bIsRecent) return 1; // Both recent or both old: sort by modification time (newer first) if (aIsRecent && bIsRecent) return bMtime - aMtime; // Both old: maintain original order (preserve relevance from grep) return 0; }); } private estimateFileOutlinePayloadChars(symbols: CodeSymbol[]): number { return JSON.stringify(symbols).length; } private constrainFileOutlinePayload( symbols: CodeSymbol[], includeContext: boolean, ): CodeSymbol[] { if ( this.estimateFileOutlinePayloadChars(symbols) <= MAX_FILE_OUTLINE_PAYLOAD_CHARS ) { return symbols; } let constrained = includeContext ? symbols.map(symbol => ({...symbol, context: undefined})) : symbols; if ( this.estimateFileOutlinePayloadChars(constrained) <= MAX_FILE_OUTLINE_PAYLOAD_CHARS ) { return constrained; } constrained = constrained.map(symbol => ({ ...symbol, signature: undefined, })); return constrained; } /** * Get code outline for a file (all symbols in the file) * Supports both local files and remote SSH files (ssh://user@host:port/path) */ async getFileOutline( filePath: string, options?: { maxResults?: number; includeContext?: boolean; symbolTypes?: SymbolType[]; }, ): Promise<CodeSymbol[]> { this.markActivity(); // Check if this is a remote SSH path const isRemote = this.isSSHPath(filePath); let content: string; let effectivePath: string; try { if (isRemote) { // Read from remote SSH server content = await this.readRemoteFile(filePath); // Extract the file path from SSH URL for symbol parsing const parsed = parseSSHUrl(filePath); effectivePath = parsed?.path || filePath; } else { // Read from local filesystem effectivePath = path.resolve(this.basePath, filePath); content = await fs.readFile(effectivePath, 'utf-8'); } const maxResults = options?.maxResults && options.maxResults > 0 ? Math.min(options.maxResults, MAX_FILE_OUTLINE_SYMBOLS) : MAX_FILE_OUTLINE_SYMBOLS; const includeContext = options?.includeContext !== false; let symbols = await parseFileSymbols( effectivePath, content, this.basePath, { includeContext, includeSignature: includeContext, maxSymbols: maxResults, }, ); // Filter by symbol types if specified if (options?.symbolTypes && options.symbolTypes.length > 0) { symbols = symbols.filter(s => options.symbolTypes!.includes(s.type)); } // Prioritize important symbols (function, class, interface, method) const importantTypes: SymbolType[] = [ 'function', 'class', 'interface', 'method', ]; symbols.sort((a, b) => { const aImportant = importantTypes.includes(a.type); const bImportant = importantTypes.includes(b.type); if (aImportant && !bImportant) return -1; if (!aImportant && bImportant) return 1; return 0; }); // Limit results. file_outline used to be unlimited by default, which could // produce huge tool results and race with terminal teardown. symbols = symbols.slice(0, maxResults); // Remove or trim context before the global token limiter sees the result. if (!includeContext) { symbols = symbols.map(s => ({...s, context: undefined})); } return this.constrainFileOutlinePayload(symbols, includeContext); } catch (error) { throw new Error( `Failed to get outline for ${filePath}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } /** * Search with language-specific context (cross-reference search) */ async semanticSearch( query: string, searchType: 'definition' | 'usage' | 'implementation' | 'all' = 'all', language?: string, symbolType?: CodeSymbol['type'], maxResults: number = 50, ): Promise<SemanticSearchResult> { this.markActivity(); const startTime = Date.now(); // Get symbol search results const symbolResults = await this.searchSymbols( query, symbolType, language, maxResults, ); // Get reference results if needed let references: CodeReference[] = []; if (searchType === 'usage' || searchType === 'all') { // Find references for the top matching symbols const topSymbols = symbolResults.symbols.slice(0, 5); for (const symbol of topSymbols) { const symbolRefs = await this.findReferences(symbol.name, maxResults); references.push(...symbolRefs); } } // Filter results based on search type let filteredSymbols = symbolResults.symbols; if (searchType === 'definition') { filteredSymbols = symbolResults.symbols.filter( s => s.type === 'function' || s.type === 'class' || s.type === 'interface', ); } else if (searchType === 'usage') { filteredSymbols = []; } else if (searchType === 'implementation') { filteredSymbols = symbolResults.symbols.filter( s => s.type === 'function' || s.type === 'method' || s.type === 'class', ); } const searchTime = Date.now() - startTime; return { query, symbols: filteredSymbols, references, totalResults: filteredSymbols.length + references.length, searchTime, }; } } // MCP Tool definitions for integration // 聚合后的统一 ACE 工具：使用 action 字段分发到对应能力 export const mcpTools = [ { name: 'ace-search', description: `ACE Code Search: Unified code search tool. Use required field "action" — one of find_definition | find_references | semantic_search | file_outline | text_search. PARALLEL CALLS ONLY: MUST pair with other tools (ace-search + filesystem-read/terminal-execute/etc). ACTIONS: - find_definition: Find the definition of a symbol (Go to Definition). Required: "symbolName". Optional: "contextFile", "line", "column" (0-indexed; useful for OmniSharp/LSP precision). - find_references: Find all references to a symbol (definition / usage / import / type). Required: "symbolName". Optional: "maxResults" (default 100). - semantic_search: Intelligent symbol search with fuzzy matching. Required: "query". Optional: "searchType" (definition|usage|implementation|all, default all), "symbolType", "language", "maxResults" (default 50). Tip: prefer action=file_outline if you only need a single file's outline. - file_outline: Get complete symbol outline for a file (function/class/variable/...). Required: "filePath". Optional: "maxResults", "includeContext" (default true), "symbolTypes". Set includeContext=false to reduce output size significantly. - text_search: Literal text or regex pattern matching (grep-style). Best for TODOs, comments, exact error strings. Required: "pattern". Optional: "fileGlob" (e.g. "*.ts", "**/*.{js,ts}"), "isRegex" (default true; set false for literal), "maxResults" (default 100). EXAMPLES: - ace-search({action:"find_definition", symbolName:"getFileContent"}) - ace-search({action:"find_references", symbolName:"TodoService", maxResults:50}) - ace-search({action:"semantic_search", query:"gfc", searchType:"definition"}) - ace-search({action:"file_outline", filePath:"source/mcp/todo.ts", includeContext:false}) - ace-search({action:"text_search", pattern:"TODO:", fileGlob:"**/*.ts", isRegex:false})`, inputSchema: { type: 'object', properties: { action: { type: 'string', enum: [ 'find_definition', 'find_references', 'semantic_search', 'file_outline', 'text_search', ], description: 'Which ACE search operation to run. Determines which other parameters are required.', }, // find_definition / find_references symbolName: { type: 'string', description: 'For action=find_definition or find_references: name of the symbol to look up.', }, contextFile: { type: 'string', description: 'For action=find_definition only: current file path for context-aware search (optional, searches current file first).', }, line: { type: 'number', description: 'For action=find_definition only: 0-indexed line number where the symbol appears in contextFile (optional; required by some LSP servers like OmniSharp).', }, column: { type: 'number', description: 'For action=find_definition only: 0-indexed column number where the symbol appears in contextFile (optional; required by some LSP servers like OmniSharp).', }, // semantic_search query: { type: 'string', description: 'For action=semantic_search: search query (symbol name or pattern, supports fuzzy matching such as "gfc" matching "getFileContent").', }, searchType: { type: 'string', enum: ['definition', 'usage', 'implementation', 'all'], description: 'For action=semantic_search only: definition (declarations), usage (reference locations), implementation (specific implementations), all (full search). Default: all.', default: 'all', }, symbolType: { type: 'string', enum: [ 'function', 'class', 'method', 'variable', 'constant', 'interface', 'type', 'enum', 'import', 'export', ], description: 'For action=semantic_search only: optional filter by symbol type.', }, language: { type: 'string', enum: [ 'typescript', 'javascript', 'python', 'go', 'rust', 'java', 'csharp', ], description: 'For action=semantic_search only: optional filter by programming language.', }, // file_outline filePath: { type: 'string', description: 'For action=file_outline: path to the file to get outline for (relative to workspace root, or ssh:// URL).', }, includeContext: { type: 'boolean', description: 'For action=file_outline only: include surrounding code context (default true). Set false to reduce output size significantly.', default: true, }, symbolTypes: { type: 'array', items: { type: 'string', enum: [ 'function', 'class', 'method', 'variable', 'constant', 'interface', 'type', 'enum', 'import', 'export', ], }, description: 'For action=file_outline only: filter by specific symbol types (optional).', }, // text_search pattern: { type: 'string', description: 'For action=text_search: text pattern or regex to search for. Examples: "TODO:" (literal), "import.*from" (regex), "tool_call|toolCall" (regex with OR).', }, fileGlob: { type: 'string', description: 'For action=text_search only: glob pattern to filter files (e.g. "*.ts", "**/*.{js,ts}", "src/**/*.py").', }, isRegex: { type: 'boolean', description: 'For action=text_search only: whether to use regex mode. Default true. Set false for literal string search.', default: true, }, // shared maxResults: { type: 'number', description: 'Optional max results. Defaults: find_references=100, semantic_search=50, text_search=100, file_outline=200 (hard cap).', }, }, required: ['action'], }, }, ]; // Export a default instance export const aceCodeSearchService = new ACECodeSearchService(); ================================================ FILE: source/mcp/askUserQuestion.ts ================================================ import type {MCPTool} from '../utils/execution/mcpToolsManager.js'; export interface AskUserQuestionArgs { question: string; options: string[]; } export interface AskUserQuestionResult { selected: string | string[]; customInput?: string; } export const mcpTools: MCPTool[] = [ { type: 'function', function: { name: 'askuser-ask_question', description: 'Ask the user a concise, focused question with multiple choice options to clarify requirements. Keep wording short and centered on one decision point. The AI workflow pauses until the user selects an option or provides custom input. Use this when you need user input to continue processing. Supports both single and multiple selection - user can choose one or more options.', parameters: { type: 'object', properties: { question: { type: 'string', description: 'The question to ask the user. Keep it short, focused, and specific. Avoid long-winded wording and ask only for the key information needed.', }, options: { type: 'array', items: { type: 'string', }, description: 'Array of option strings for the user to choose from. Should be concise and clear. User can select one or multiple options.', minItems: 2, }, }, required: ['question', 'options'], }, }, }, ]; // This will be handled by a special UI component, not a service // The actual execution happens in mcpToolsManager.ts with user interaction ================================================ FILE: source/mcp/bash.ts ================================================ import {exec, spawn, spawnSync} from 'child_process'; // Type definitions import type {CommandExecutionResult} from './types/bash.types.js'; // Utility functions import { isDangerousCommand, isSelfDestructiveCommand, truncateOutput, } from './utils/bash/security.utils.js'; import {processManager} from '../utils/core/processManager.js'; import { appendTerminalOutput, setTerminalNeedsInput, registerInputCallback, flushOutputBuffer, } from '../hooks/execution/useTerminalExecutionState.js'; import {logger} from '../utils/core/logger.js'; // SSH support import {SSHClient, parseSSHUrl} from '../utils/ssh/sshClient.js'; import { getWorkingDirectories, type SSHConfig, } from '../utils/config/workingDirConfig.js'; import {detectWindowsPowerShell} from '../prompt/shared/promptHelpers.js'; import {bashOutputSummaryAgent} from '../agents/bashOutputSummaryAgent.js'; // Global flag to track if command should be moved to background let shouldMoveToBackground = false; /** * Mark command to be moved to background * Called from UI when Ctrl+B is pressed */ export function markCommandAsBackgrounded() { shouldMoveToBackground = true; } /** * Reset background flag */ export function resetBackgroundFlag() { shouldMoveToBackground = false; } /** * Terminal Command Execution Service * Executes terminal commands directly using the system's default shell */ export class TerminalCommandService { private workingDirectory: string; private maxOutputLength: number; constructor( workingDirectory: string = process.cwd(), maxOutputLength: number = 10000, ) { this.workingDirectory = workingDirectory; this.maxOutputLength = maxOutputLength; } private async maybeSummarizeCommandResult( commandResult: CommandExecutionResult, enableAiSummary: boolean, abortSignal?: AbortSignal, ): Promise<CommandExecutionResult> { try { if (!enableAiSummary) { return commandResult; } const summarizedResult = await bashOutputSummaryAgent.summarizeCommandResult( commandResult, abortSignal, ); if (summarizedResult.stdout !== commandResult.stdout) { appendTerminalOutput('[AI Summary] Output was compressed by AI.'); const summaryLines = summarizedResult.stdout .split('\n') .filter(line => line.trim()); for (const line of summaryLines) { appendTerminalOutput(`[AI Summary] ${line}`); } } return summarizedResult; } catch (error) { logger.warn( 'terminal-execute: summarize in bash service failed, fallback to original', error, ); return commandResult; } } /** * Check if the working directory is a remote SSH path */ private isSSHPath(dirPath: string): boolean { return dirPath.startsWith('ssh://'); } /** * Get SSH config for a remote path from working directories */ private async getSSHConfigForPath(sshUrl: string): Promise<SSHConfig | null> { const workingDirs = await getWorkingDirectories(); for (const dir of workingDirs) { if (dir.isRemote && dir.sshConfig && sshUrl.startsWith(dir.path)) { return dir.sshConfig; } } // Try to match by host/user/port const parsed = parseSSHUrl(sshUrl); if (parsed) { for (const dir of workingDirs) { if (dir.isRemote && dir.sshConfig) { const dirParsed = parseSSHUrl(dir.path); if ( dirParsed && dirParsed.host === parsed.host && dirParsed.username === parsed.username && dirParsed.port === parsed.port ) { return dir.sshConfig; } } } } return null; } /** * Execute command on remote SSH server */ private async executeRemoteCommand( command: string, remotePath: string, sshConfig: SSHConfig, timeout: number, abortSignal?: AbortSignal, ): Promise<{stdout: string; stderr: string; exitCode: number}> { const sshClient = new SSHClient(); try { // Connect to SSH server const connectResult = await sshClient.connect( sshConfig, sshConfig.password, ); if (!connectResult.success) { throw new Error( `SSH connection failed: ${connectResult.error || 'Unknown error'}`, ); } // Wrap command with cd to remote path const fullCommand = `cd "${remotePath}" && ${command}`; // Send initial output to UI appendTerminalOutput(`[SSH] Executing on ${sshConfig.host}: ${command}`); // Execute command on remote server with timeout/abort support. const result = await sshClient.exec(fullCommand, { timeout, signal: abortSignal, }); // Send output to UI if (result.stdout) { const lines = result.stdout.split('\n').filter(line => line.trim()); lines.forEach(line => appendTerminalOutput(line)); } if (result.stderr) { const lines = result.stderr.split('\n').filter(line => line.trim()); lines.forEach(line => appendTerminalOutput(line)); } return { stdout: result.stdout, stderr: result.stderr, exitCode: result.code, }; } finally { sshClient.disconnect(); } } /** * Select an available local shell on Windows. * Tries preferred shell first, then falls back to alternatives. */ private selectAvailableWindowsShell( preferred: 'pwsh' | 'powershell' | null, ): { shell: 'pwsh' | 'powershell' | 'cmd'; isPowerShell: boolean; } { const candidates: Array<'pwsh' | 'powershell' | 'cmd'> = []; if (preferred === 'pwsh') { candidates.push('pwsh', 'powershell', 'cmd'); } else if (preferred === 'powershell') { candidates.push('powershell', 'pwsh', 'cmd'); } else { candidates.push('powershell', 'pwsh', 'cmd'); } for (const candidate of candidates) { try { if (candidate === 'cmd') { const probe = spawnSync('cmd', ['/c', 'echo'], { windowsHide: true, stdio: 'ignore', }); if (!probe.error) { return {shell: 'cmd', isPowerShell: false}; } continue; } const probe = spawnSync( candidate, ['-NoProfile', '-Command', '$PSVersionTable.PSVersion.ToString()'], { windowsHide: true, stdio: 'ignore', }, ); if (!probe.error) { return {shell: candidate, isPowerShell: true}; } } catch { // Ignore probe errors and continue fallback. } } return {shell: 'cmd', isPowerShell: false}; } /** * Execute a terminal command in the working directory * Supports both local and remote SSH directories * @param command - The command to execute (e.g., "npm -v", "git status") * @param timeout - Timeout in milliseconds (default: 30000ms = 30s) * @param abortSignal - Optional AbortSignal to cancel command execution (e.g., ESC key) * @returns Execution result including stdout, stderr, and exit code * @throws Error if command execution fails critically */ async executeCommand( command: string, timeout: number = 30000, abortSignal?: AbortSignal, isInteractive: boolean = false, enableAiSummary: boolean = false, ): Promise<CommandExecutionResult> { const executedAt = new Date().toISOString(); try { // Security check: reject potentially dangerous commands if (isDangerousCommand(command)) { throw new Error( `Dangerous command detected and blocked: ${command.slice(0, 50)}`, ); } // Self-protection: reject commands that would kill the CLI's own process const selfDestruct = isSelfDestructiveCommand(command); if (selfDestruct.isSelfDestructive) { throw new Error( `[SELF-PROTECTION] Command blocked: ${selfDestruct.reason}. ` + `${selfDestruct.suggestion}`, ); } // Check if working directory is a remote SSH path if (this.isSSHPath(this.workingDirectory)) { const parsed = parseSSHUrl(this.workingDirectory); if (!parsed) { throw new Error(`Invalid SSH URL: ${this.workingDirectory}`); } const sshConfig = await this.getSSHConfigForPath(this.workingDirectory); if (!sshConfig) { throw new Error( `No SSH configuration found for: ${this.workingDirectory}. Please add this remote directory first.`, ); } // Execute command on remote server const result = await this.executeRemoteCommand( command, parsed.path, sshConfig, timeout, abortSignal, ); const commandResult: CommandExecutionResult = { stdout: truncateOutput(result.stdout, this.maxOutputLength), stderr: truncateOutput(result.stderr, this.maxOutputLength), exitCode: result.exitCode, command, executedAt, }; return this.maybeSummarizeCommandResult( commandResult, enableAiSummary, abortSignal, ); } // Local execution: Execute command using system default shell and register the process. // Using spawn (instead of exec) avoids relying on inherited stdio and is // more resilient in some terminals where `exec` can fail with `spawn EBADF`. const isWindows = process.platform === 'win32'; // Detect shell type using the same logic as promptHelpers let shell: string; let shellArgs: string[]; if (isWindows) { const preferredPowerShell = detectWindowsPowerShell(); const selectedShell = this.selectAvailableWindowsShell(preferredPowerShell); shell = selectedShell.shell; if (selectedShell.isPowerShell) { const utf8WrappedCommand = `& { $OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new(); ${command} }`; shellArgs = ['-NoProfile', '-Command', utf8WrappedCommand]; } else { const utf8Command = `chcp 65001>nul && ${command}`; shellArgs = ['/c', utf8Command]; } } else { shell = 'sh'; shellArgs = ['-c', command]; } const childProcess = spawn(shell, shellArgs, { cwd: this.workingDirectory, stdio: ['pipe', 'pipe', 'pipe'], // Enable stdin for interactive input windowsHide: true, env: { ...process.env, ...(process.platform !== 'win32' && { LANG: 'en_US.UTF-8', LC_ALL: 'en_US.UTF-8', }), }, }); // Register child process for cleanup processManager.register(childProcess); // Setup abort signal handler if provided let abortHandler: (() => void) | undefined; let killTimeout: NodeJS.Timeout | null = null; if (abortSignal) { abortHandler = () => { // CRITICAL: Set abort flag first to stop data processing immediately isAborted = true; // CRITICAL: Destroy stdout/stderr streams immediately to stop data flow // This is more aggressive than pause() - it clears the internal buffer // and ensures no more 'data' events will be emitted childProcess.stdout?.destroy(); childProcess.stderr?.destroy(); // Also pause as a safety measure childProcess.stdout?.pause(); childProcess.stderr?.pause(); if (childProcess.pid && !childProcess.killed) { // Kill the process immediately when abort signal is triggered try { if (process.platform === 'win32') { // Windows: Use taskkill to kill entire process tree exec(`taskkill /PID ${childProcess.pid} /T /F 2>NUL`, { windowsHide: true, }); } else { // Unix: Send SIGTERM first, then SIGKILL immediately as fallback // For commands like 'find' that produce massive output, // we need immediate termination childProcess.kill('SIGTERM'); // Force SIGKILL after a very short delay (100ms) to ensure termination // This is necessary because SIGTERM may be ignored or delayed killTimeout = setTimeout(() => { if (!childProcess.killed) { try { childProcess.kill('SIGKILL'); } catch { // Ignore errors } } }, 100); } } catch { // Ignore errors if process already dead } } }; abortSignal.addEventListener('abort', abortHandler); } // Register input callback for interactive commands const inputHandler = (input: string) => { if (childProcess.stdin && !childProcess.stdin.destroyed) { childProcess.stdin.write(input + '\n'); // Clear the input prompt after sending input setTerminalNeedsInput(false); } }; registerInputCallback(inputHandler); // CRITICAL: Flag to prevent data processing after abort // Must be defined outside Promise so abortHandler can access it let isAborted = false; // Convert to promise const {stdout, stderr} = await new Promise<{ stdout: string; stderr: string; }>((resolve, reject) => { let timeoutTimer: NodeJS.Timeout | null = null; let timedOut = false; const safeClearTimeout = () => { if (timeoutTimer) { clearTimeout(timeoutTimer); timeoutTimer = null; } }; const triggerTimeout = () => { if (timedOut) return; timedOut = true; safeClearTimeout(); // Kill the underlying process tree so we don't keep waiting on streams. if (childProcess.pid && !childProcess.killed) { try { if (process.platform === 'win32') { exec(`taskkill /PID ${childProcess.pid} /T /F 2>NUL`, { windowsHide: true, }); } else { childProcess.kill('SIGTERM'); } } catch { // Ignore. } } const timeoutError: any = new Error( `Command timed out after ${timeout}ms: ${command}`, ); timeoutError.code = 'ETIMEDOUT'; reject(timeoutError); }; if (typeof timeout === 'number' && timeout > 0) { timeoutTimer = setTimeout(triggerTimeout, timeout); } const abortTimeoutHandler = abortSignal ? () => { safeClearTimeout(); } : null; if (abortSignal && abortTimeoutHandler) { abortSignal.addEventListener('abort', abortTimeoutHandler); } let stdoutData = ''; let stderrData = ''; let backgroundProcessId: string | null = null; let lastOutputTime = Date.now(); let inputCheckInterval: NodeJS.Timeout | null = null; let inputPromptTriggered = false; // Note: isAborted is defined outside Promise so abortHandler can access it // Patterns that indicate the command is waiting for input (from output) const inputPromptPatterns = [ /password[:\s]*$/i, /\[y\/n\][:\s]*$/i, /\[yes\/no\][:\s]*$/i, /\(y\/n\)[:\s]*$/i, /\(yes\/no\)[:\s]*$/i, /continue\?[:\s]*$/i, /proceed\?[:\s]*$/i, /confirm[:\s]*$/i, /enter[:\s]*$/i, /input[:\s]*$/i, /passphrase[:\s]*$/i, /username[:\s]*$/i, /login[:\s]*$/i, /\?[:\s]*$/, /:\s*$/, ]; // Check if output indicates waiting for input const checkForInputPrompt = (output: string) => { const lastLine = output.split('\n').pop()?.trim() || ''; for (const pattern of inputPromptPatterns) { if (pattern.test(lastLine)) { return lastLine; } } return null; }; // Add to background processes if PID available if (childProcess.pid) { import('../hooks/execution/useBackgroundProcesses.js') .then(({addBackgroundProcess}) => { backgroundProcessId = addBackgroundProcess( command, childProcess.pid!, ); }) .catch(() => { // Ignore error if module not available }); } // Check for input prompt periodically when output stops inputCheckInterval = setInterval(() => { const timeSinceLastOutput = Date.now() - lastOutputTime; // If AI marked this command as interactive, trigger input prompt after 500ms if ( isInteractive && !inputPromptTriggered && timeSinceLastOutput > 500 ) { inputPromptTriggered = true; setTerminalNeedsInput(true, 'Waiting for input...'); return; } // If no output for 500ms and we have some output, check for input prompt if (timeSinceLastOutput > 500 && (stdoutData || stderrData)) { const combinedOutput = stdoutData + stderrData; const prompt = checkForInputPrompt(combinedOutput); if (prompt && !inputPromptTriggered) { inputPromptTriggered = true; setTerminalNeedsInput(true, prompt); } } }, 200); // Check background flag periodically const backgroundCheckInterval = setInterval(() => { if (shouldMoveToBackground) { safeClearTimeout(); clearInterval(backgroundCheckInterval); if (inputCheckInterval) clearInterval(inputCheckInterval); resetBackgroundFlag(); // Resolve immediately with partial output resolve({ stdout: stdoutData + '\n[Command moved to background, execution continues...]', stderr: stderrData, }); } }, 100); childProcess.stdout?.on('data', chunk => { // CRITICAL: Skip processing if aborted to prevent event loop blocking if (isAborted) return; stdoutData += chunk; lastOutputTime = Date.now(); // Clear input prompt when new output arrives setTerminalNeedsInput(false); // Send real-time output to UI const lines = String(chunk) .split('\n') .filter(line => line.trim()); lines.forEach(line => appendTerminalOutput(line)); }); childProcess.stderr?.on('data', chunk => { // CRITICAL: Skip processing if aborted to prevent event loop blocking if (isAborted) return; stderrData += chunk; lastOutputTime = Date.now(); // Clear input prompt when new output arrives setTerminalNeedsInput(false); // Send real-time output to UI const lines = String(chunk) .split('\n') .filter(line => line.trim()); lines.forEach(line => appendTerminalOutput(line)); }); childProcess.on('error', error => { safeClearTimeout(); clearInterval(backgroundCheckInterval); if (inputCheckInterval) clearInterval(inputCheckInterval); registerInputCallback(null); setTerminalNeedsInput(false); // Enhanced error logging for debugging spawn failures const errnoError = error as NodeJS.ErrnoException; logger.error('Spawn process failed', { command, errorMessage: error.message, errorCode: errnoError.code, errno: errnoError.errno, syscall: errnoError.syscall, cwd: this.workingDirectory, }); // Update process status if (backgroundProcessId) { import('../hooks/execution/useBackgroundProcesses.js') .then(({updateBackgroundProcessStatus}) => { updateBackgroundProcessStatus( backgroundProcessId!, 'failed', 1, ); }) .catch(() => {}); } reject(error); }); childProcess.on('close', (code, signal) => { safeClearTimeout(); // Clean up kill timeout to prevent memory leaks if (killTimeout) { clearTimeout(killTimeout); killTimeout = null; } clearInterval(backgroundCheckInterval); if (inputCheckInterval) clearInterval(inputCheckInterval); registerInputCallback(null); setTerminalNeedsInput(false); // PERFORMANCE: Flush any remaining buffered output before command ends flushOutputBuffer(); // Update process status if (backgroundProcessId) { const status = code === 0 ? 'completed' : 'failed'; import('../hooks/execution/useBackgroundProcesses.js') .then(({updateBackgroundProcessStatus}) => { updateBackgroundProcessStatus( backgroundProcessId!, status, code || undefined, ); }) .catch(() => {}); } // Clean up abort handlers if (abortHandler && abortSignal) { abortSignal.removeEventListener('abort', abortHandler); } if (abortTimeoutHandler && abortSignal) { abortSignal.removeEventListener('abort', abortTimeoutHandler); } if (signal) { // Process was killed by signal (e.g., timeout, manual kill, ESC key) // CRITICAL: Still preserve stdout/stderr for debugging const error: any = new Error(`Process killed by signal ${signal}`); if (timedOut) { error.code = 'ETIMEDOUT'; } else { error.code = code || 1; } error.stdout = stdoutData; error.stderr = stderrData; error.signal = signal; reject(error); } else if (code === 0) { resolve({stdout: stdoutData, stderr: stderrData}); } else { const error: any = new Error(`Process exited with code ${code}`); error.code = code; error.stdout = stdoutData; error.stderr = stderrData; reject(error); } }); }); // Truncate output if too long const commandResult: CommandExecutionResult = { stdout: truncateOutput(stdout, this.maxOutputLength), stderr: truncateOutput(stderr, this.maxOutputLength), exitCode: 0, command, executedAt, }; return this.maybeSummarizeCommandResult( commandResult, enableAiSummary, abortSignal, ); } catch (error: any) { // Handle execution errors (non-zero exit codes) if (error.code === 'ETIMEDOUT') { throw new Error(`Command timed out after ${timeout}ms: ${command}`); } // Check if aborted by user (ESC key) if (abortSignal?.aborted) { const commandResult: CommandExecutionResult = { stdout: truncateOutput(error.stdout || '', this.maxOutputLength), stderr: truncateOutput( error.stderr || 'Command execution interrupted by user (ESC key pressed)', this.maxOutputLength, ), exitCode: 130, // Standard exit code for SIGINT/user interrupt command, executedAt, }; return this.maybeSummarizeCommandResult( commandResult, enableAiSummary, abortSignal, ); } // For non-zero exit codes, still return the output const commandResult: CommandExecutionResult = { stdout: truncateOutput(error.stdout || '', this.maxOutputLength), stderr: truncateOutput( error.stderr || error.message || '', this.maxOutputLength, ), exitCode: error.code || 1, command, executedAt, }; return this.maybeSummarizeCommandResult( commandResult, enableAiSummary, abortSignal, ); } } /** * Get current working directory * @returns Current working directory path */ getWorkingDirectory(): string { return this.workingDirectory; } /** * Change working directory for future commands * @param newPath - New working directory path * @throws Error if path doesn't exist or is not a directory */ setWorkingDirectory(newPath: string): void { this.workingDirectory = newPath; } } // Export a default instance export const terminalService = new TerminalCommandService(); // MCP Tool definitions export const mcpTools = [ { name: 'terminal-execute', description: 'Execute terminal commands like npm, git, build scripts, etc. **REMOTE SSH SUPPORT**: When workingDirectory is a remote SSH path (ssh://...), commands are automatically executed on the remote server via SSH - DO NOT wrap commands with "ssh user@host" yourself, just provide the raw command (e.g., "cat /etc/os-release" instead of "ssh root@host cat /etc/os-release"). BEST PRACTICE: For file modifications, prefer filesystem-edit/filesystem-create tools first. Primary use cases: (1) Running build/test/lint scripts, (2) Version control operations, (3) Package management, (4) System utilities.', inputSchema: { type: 'object', properties: { command: { type: 'string', description: 'Terminal command to execute directly. For remote SSH working directories, provide raw commands without ssh wrapper - the system handles SSH connection automatically.', }, workingDirectory: { type: 'string', description: 'REQUIRED: Working directory where the command should be executed. Can be a local path (e.g., "D:/projects/myapp") or a remote SSH path (e.g., "ssh://user@host:port/path"). For remote paths, the command will be executed on the remote server via SSH.', }, timeout: { type: 'number', description: 'Timeout in milliseconds (default: 30000)', default: 30000, }, isInteractive: { type: 'boolean', description: 'Set to true if the command requires user input (e.g., Read-Host, password prompts, y/n confirmations, interactive installers). When true, an input prompt will be shown to allow user to provide input. Default: false.', default: false, }, enableAiSummary: { type: 'boolean', description: 'REQUIRED: Whether to summarize and clean command output with AI before returning tool result. Set true when output may contain noisy or low-value information. Default: false.', default: false, }, }, required: ['command', 'workingDirectory', 'enableAiSummary'], }, }, ]; ================================================ FILE: source/mcp/codebaseSearch.ts ================================================ import {CodebaseDatabase} from '../utils/codebase/codebaseDatabase.js'; import {createEmbedding} from '../api/embedding.js'; import {rerankDocuments} from '../api/rerank.js'; import {logger} from '../utils/core/logger.js'; import {codebaseReviewAgent} from '../agents/codebaseReviewAgent.js'; import {codebaseSearchEvents} from '../utils/codebase/codebaseSearchEvents.js'; import {loadCodebaseConfig} from '../utils/config/codebaseConfig.js'; import {sessionManager} from '../utils/session/sessionManager.js'; import path from 'node:path'; import fs from 'node:fs'; /** * Codebase Search Service * Provides semantic search capabilities for the codebase using embeddings */ class CodebaseSearchService { /** * Check if codebase index is available and has data */ private async isCodebaseIndexAvailable(): Promise<{ available: boolean; reason?: string; }> { try { const projectRoot = process.cwd(); const dbPath = path.join( projectRoot, '.snow', 'codebase', 'embeddings.db', ); // Check if database file exists if (!fs.existsSync(dbPath)) { return { available: false, reason: 'Codebase index not found. Please run codebase indexing first.', }; } // Initialize database and check for data const db = new CodebaseDatabase(projectRoot); await db.initialize(); const totalChunks = db.getTotalChunks(); db.close(); if (totalChunks === 0) { return { available: false, reason: 'Codebase index is empty. Please run indexing to build the index.', }; } return {available: true}; } catch (error) { logger.error('Error checking codebase index availability:', error); return { available: false, reason: `Error checking codebase index: ${ error instanceof Error ? error.message : 'Unknown error' }`, }; } } /** * Calculate cosine similarity between two vectors */ private cosineSimilarity(a: number[], b: number[]): number { if (a.length !== b.length) { throw new Error('Vectors must have same length'); } let dotProduct = 0; let normA = 0; let normB = 0; for (let i = 0; i < a.length; i++) { dotProduct += a[i]! * b[i]!; normA += a[i]! * a[i]!; normB += b[i]! * b[i]!; } return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB)); } /** * Search codebase using semantic similarity with retry logic * @param query - Search query * @param topN - Number of results to return * @param abortSignal - Optional abort signal * @param deepExploreFiles - Optional file paths for deep exploration (focused search) */ async search( query: string, topN: number = 10, abortSignal?: AbortSignal, deepExploreFiles?: string[], queriedTerms: Set<string> = new Set(), ): Promise<any> { // Load codebase config const config = loadCodebaseConfig(); const enableAgentReview = config.enableAgentReview; const enableReranking = config.enableReranking; // Check if codebase index is available const {available, reason} = await this.isCodebaseIndexAvailable(); if (!available) { return { error: reason, results: [], totalResults: 0, }; } const MAX_SEARCH_RETRIES = 3; const MIN_RESULTS_THRESHOLD = Math.ceil(topN * 0.5); // 50% of topN const projectRoot = process.cwd(); const db = new CodebaseDatabase(projectRoot); try { await db.initialize(); const totalChunks = db.getTotalChunks(); let lastResults: any = null; let searchAttempt = 0; let currentTopN = topN; let currentQuery = query; // Track queried terms to avoid infinite loops queriedTerms.add(query.toLowerCase()); // Retry loop: if results are too few, increase search range and retry while (searchAttempt < MAX_SEARCH_RETRIES) { searchAttempt++; // Emit search event (when agent review or reranking is enabled) if (enableAgentReview || enableReranking) { codebaseSearchEvents.emitSearchEvent({ type: searchAttempt === 1 ? 'search-start' : 'search-retry', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Searching codebase...`, query: currentQuery, }); } const queryEmbedding = await createEmbedding(currentQuery); // Search similar chunks // If deepExploreFiles is specified, search only in those files const results = deepExploreFiles ? db.searchSimilarInFiles( queryEmbedding, deepExploreFiles, currentTopN, ) : db.searchSimilar(queryEmbedding, currentTopN); // Format results with similarity scores and full content const formattedResults = results.map((chunk, index) => { const score = this.cosineSimilarity(queryEmbedding, chunk.embedding); const scorePercent = (score * 100).toFixed(2); return { rank: index + 1, filePath: chunk.filePath, startLine: chunk.startLine, endLine: chunk.endLine, content: chunk.content, similarityScore: scorePercent, location: `${chunk.filePath}:${chunk.startLine}-${chunk.endLine}`, }; }); // Use review agent to filter irrelevant results (if enabled) let finalResults; let reviewFailed = false; let removedCount = 0; let suggestion: string | undefined; let highConfidenceFiles: string[] = []; if (enableReranking) { // ── Reranking branch ── codebaseSearchEvents.emitSearchEvent({ type: 'search-retry', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Reranking ${formattedResults.length} results...`, query, originalResultsCount: formattedResults.length, }); logger.info( `Reranking ${formattedResults.length} search results (attempt ${searchAttempt})`, ); try { const rerankTopN = config.reranking.topN; const documents = formattedResults.map(r => { return `File: ${r.filePath} (Lines ${r.startLine}-${r.endLine})\n${r.content}`; }); const rerankResponse = await rerankDocuments({ query: currentQuery, documents, topN: rerankTopN, }); // Map rerank results back to formatted results, sorted by relevance const rerankedResults = rerankResponse.results .sort((a, b) => b.relevanceScore - a.relevanceScore) .filter(r => r.index >= 0 && r.index < formattedResults.length) .map((r, newRank) => { const original = formattedResults[r.index]!; return { ...original, rank: newRank + 1, similarityScore: `${(r.relevanceScore * 100).toFixed(2)}`, relevanceScore: r.relevanceScore, }; }); finalResults = rerankedResults; removedCount = formattedResults.length - finalResults.length; reviewFailed = false; logger.info( `Reranking complete: ${formattedResults.length} → ${finalResults.length} results`, ); } catch (rerankError) { logger.error('Reranking failed, falling back to raw results:', rerankError); finalResults = formattedResults; reviewFailed = true; removedCount = 0; } } else if (enableAgentReview) { // ── Agent review branch ── // Emit reviewing event codebaseSearchEvents.emitSearchEvent({ type: 'search-retry', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Reviewing ${formattedResults.length} results with AI...`, query, originalResultsCount: formattedResults.length, }); logger.info( `Reviewing ${formattedResults.length} search results (attempt ${searchAttempt})`, ); // Get conversation context from session (exclude tool calls) const session = sessionManager.getCurrentSession(); const conversationContext = session?.messages .filter( msg => (msg.role === 'user' || msg.role === 'assistant') && !msg.tool_calls && !msg.tool_call_id, ) .map(msg => ({ role: msg.role, content: msg.content, })) .slice(-10) || []; // Last 10 messages const reviewResult = await codebaseReviewAgent.reviewResults( query, formattedResults, conversationContext.length > 0 ? conversationContext : undefined, abortSignal, ); finalResults = reviewResult.filteredResults; reviewFailed = reviewResult.reviewFailed || false; removedCount = reviewResult.removedCount; suggestion = reviewResult.suggestion; highConfidenceFiles = reviewResult.highConfidenceFiles || []; } else { // ── Raw results branch (no review, no reranking) ── finalResults = formattedResults; reviewFailed = false; removedCount = 0; suggestion = undefined; logger.info( `Agent review & reranking disabled, returning all ${finalResults.length} search results`, ); } // Store current results as last results lastResults = { query, totalChunks, originalResultsCount: formattedResults.length, resultsCount: finalResults.length, removedCount, reviewFailed, results: finalResults, suggestion, searchAttempts: searchAttempt, }; // If neither agent review nor reranking is enabled, return immediately if (!enableAgentReview && !enableReranking) { codebaseSearchEvents.emitSearchEvent({ type: 'search-complete', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Search complete`, query: currentQuery, suggestion, }); db.close(); return lastResults; } // If reranking succeeded, return immediately (no retry loop needed) if (enableReranking && !reviewFailed) { codebaseSearchEvents.emitSearchEvent({ type: 'search-complete', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Search complete`, query: currentQuery, }); db.close(); return lastResults; } // If review/reranking failed, return immediately (no point retrying) if (reviewFailed) { logger.info('Review/reranking failed, returning all results without retry'); codebaseSearchEvents.emitSearchEvent({ type: 'search-complete', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Search complete`, query: currentQuery, suggestion, }); db.close(); return lastResults; } // Check if we have enough results if (finalResults.length >= MIN_RESULTS_THRESHOLD) { logger.info( `Found ${finalResults.length} results (>= ${MIN_RESULTS_THRESHOLD} threshold), search complete`, ); // Emit search complete event with review results codebaseSearchEvents.emitSearchEvent({ type: 'search-complete', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Search complete`, query: currentQuery, suggestion, }); db.close(); return lastResults; } // Too few results, need to retry with more candidates if (searchAttempt < MAX_SEARCH_RETRIES) { const removedPercentage = formattedResults.length > 0 ? ((removedCount / formattedResults.length) * 100).toFixed(1) : '0.0'; // Priority 1: Try AI suggested query if available and not yet tried if (suggestion && !queriedTerms.has(suggestion.toLowerCase())) { logger.info( `Only ${finalResults.length} results after filtering (${removedPercentage}% removed, threshold: ${MIN_RESULTS_THRESHOLD}). Trying AI suggested query: "${suggestion}"...`, ); // Use AI suggested query for next attempt currentQuery = suggestion; queriedTerms.add(suggestion.toLowerCase()); continue; } // Priority 2: Check if we have high confidence files for deep exploration if ( highConfidenceFiles && highConfidenceFiles.length > 0 && !deepExploreFiles ) { // Try deep exploration in high confidence files logger.info( `Only ${finalResults.length} results after filtering (${removedPercentage}% removed, threshold: ${MIN_RESULTS_THRESHOLD}). Trying deep exploration in ${highConfidenceFiles.length} high-confidence files...`, ); // Recursive call with deep explore files db.close(); return await this.search( currentQuery, topN, abortSignal, highConfidenceFiles, queriedTerms, ); } // Priority 3: Expand search range (fallback) logger.warn( `Only ${finalResults.length} results after filtering (${removedPercentage}% removed, threshold: ${MIN_RESULTS_THRESHOLD}). Retrying with more candidates...`, ); // Increase search range for next attempt (double it) currentTopN = Math.min(currentTopN * 2, totalChunks); continue; } // Last attempt exhausted logger.warn( `Search attempt ${searchAttempt} complete. Only ${finalResults.length} results found (threshold: ${MIN_RESULTS_THRESHOLD}). Returning last results.`, ); } // Emit search complete event before closing codebaseSearchEvents.emitSearchEvent({ type: 'search-complete', attempt: searchAttempt, maxAttempts: MAX_SEARCH_RETRIES, currentTopN, message: `Completed with ${lastResults?.resultsCount || 0} results`, query: currentQuery, suggestion: lastResults?.suggestion, }); return lastResults; } catch (error) { logger.error('Codebase search failed:', error); // Emit search complete event with error to reset UI state if (enableAgentReview || enableReranking) { codebaseSearchEvents.emitSearchEvent({ type: 'search-complete', attempt: 0, maxAttempts: MAX_SEARCH_RETRIES, currentTopN: topN, message: `Search failed: ${ error instanceof Error ? error.message : 'Unknown error' }`, query: query, }); } throw error; } finally { try { db.close(); } catch { /* ignore close errors */ } } } } // Export singleton instance export const codebaseSearchService = new CodebaseSearchService(); /** * MCP Tools Definition */ export const mcpTools = [ { name: 'codebase-search', description: '**Important:When you need to search for code, this is the highest priority tool. You need to use this Codebase tool first.*** Semantic search across the codebase using LLM embeddings. * Finds code snippets based on semantic meaning, supports both keywords and natural language queries. * Returns full code content with similarity scores and file locations. * NOTE: Only available when codebase indexing is enabled and the index has been built. * If the index is not available, the tool will return an error message with instructions.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query string. Use keywords or short phrases for best results. Examples: "user authentication", "error handling", "file upload validation", "database connection". Can also use specific terms like function names, class names, or technical terms.', }, topN: { type: 'number', description: 'Maximum number of results to return (default: 10, max: 50)', default: 10, minimum: 1, maximum: 50, }, }, required: ['query'], }, }, ]; ================================================ FILE: source/mcp/engines/websearch/bing.engine.ts ================================================ /** * Bing search engine implementation. * * Uses the public Bing search page (https://www.bing.com/search?q=...) and * scrapes the rendered DOM via Puppeteer. Does NOT use any official API. * * DOM contract used here (verified against current Bing layout, 2026): * - Each organic result lives in `li.b_algo` * - The canonical link element is `.b_tpcn a.tilk` (preferred) or `h2 > a` * (the title heading also wraps an anchor with the same href) * - Snippet text is in `.b_caption p` (often `p.b_lineclamp2`); some * answers/cards put text directly under `.b_caption` without a `<p>` * - Display URL: `.b_attribution cite` (fallback: any `cite` inside item) * * Robustness notes: * - We use `domcontentloaded` instead of `networkidle2` because Bing keeps * loading tracking/telemetry scripts long after results are painted, * which often causes `networkidle2` to time out and produce empty results. * - We try several wait selectors (`#b_results`, `li.b_algo`) and never * throw if waiting times out — extraction will simply return [] and the * caller can fall back to another engine. * - We skip non-organic items inside `#b_results` such as `.b_ad`, * `.b_msg`, `.b_pag`, ads or "people also ask" blocks. */ import type {Page} from 'puppeteer-core'; import type {SearchResult} from '../../types/websearch.types.js'; import {cleanText} from '../../utils/websearch/text.utils.js'; import type {SearchEngine, SearchEngineId} from './types.js'; export class BingEngine implements SearchEngine { readonly id: SearchEngineId = 'bing'; readonly name = 'Bing'; async search( page: Page, query: string, maxResults: number, ): Promise<SearchResult[]> { const encodedQuery = encodeURIComponent(query); // `setlang=en` + `cc=us` is only a hint; Bing may still redirect CN // clients to cn.bing.com and serve zh-CN UI. The DOM contract is the // same in both cases, so this is fine. const searchUrl = `https://www.bing.com/search?q=${encodedQuery}` + `&count=${Math.max(maxResults, 10)}&setlang=en&cc=us`; try { await page.goto(searchUrl, { waitUntil: 'domcontentloaded', timeout: 30000, }); } catch { // Navigation timeout — try to extract whatever already loaded. } // Wait for the results container. Try the most specific selector first, // then fall back. Never throw — empty extraction is a valid outcome. try { await page.waitForSelector('#b_results li.b_algo', {timeout: 10000}); } catch { try { await page.waitForSelector('#b_results', {timeout: 3000}); } catch { // Fall through. } } const results = await page.evaluate((maxLimit: number) => { type Partial = { title?: string; url?: string; snippet?: string; displayUrl?: string; }; const out: Partial[] = []; const items = document.querySelectorAll('#b_results > li.b_algo'); const isHttpUrl = (u: string): boolean => /^https?:\/\//i.test(u); for (const item of items) { if (out.length >= maxLimit) break; // Skip ad/sponsored variants that may share the b_algo class. if ( item.classList.contains('b_ad') || item.querySelector('.b_adlabel, .b_ad_text') ) { continue; } // Prefer the top-card link (.b_tpcn a.tilk) because its href is // the canonical destination URL. Fall back to h2 > a. const tilkEl = item.querySelector( '.b_tpcn a.tilk', ) as HTMLAnchorElement | null; const headingEl = item.querySelector( 'h2 a', ) as HTMLAnchorElement | null; const linkEl = tilkEl ?? headingEl; if (!linkEl) continue; const url = linkEl.getAttribute('href') || ''; if (!url || !isHttpUrl(url)) continue; // Title comes from the <h2> heading; fall back to tilk aria-label // or text content if heading is missing. let title = headingEl?.textContent?.trim() || ''; if (!title) { title = tilkEl?.getAttribute('aria-label')?.trim() || tilkEl?.textContent?.trim() || ''; } if (!title) continue; // Snippet: try common Bing layouts in priority order. let snippet = ''; const snippetCandidates: Array<string> = [ '.b_caption p.b_lineclamp2', '.b_caption p', '.b_richcard .b_caption', '.b_snippet', '.b_caption', '.b_paractl', ]; for (const sel of snippetCandidates) { const el = item.querySelector(sel); const txt = el?.textContent?.trim(); if (txt) { snippet = txt; break; } } // Display URL: prefer cite inside attribution; fallback any cite. const citeEl = item.querySelector('.b_attribution cite') || item.querySelector('cite'); const displayUrl = citeEl?.textContent?.trim() || ''; out.push({title, url, snippet, displayUrl}); } return out; }, maxResults); return results.map(r => ({ title: cleanText(r.title || ''), url: r.url || '', snippet: cleanText(r.snippet || ''), displayUrl: cleanText(r.displayUrl || ''), })); } } ================================================ FILE: source/mcp/engines/websearch/duckduckgo.engine.ts ================================================ /** * DuckDuckGo search engine implementation. * * Uses the lightweight `lite.duckduckgo.com/lite` endpoint which renders a * plain HTML table of results — this is the most reliable target for a * headless browser because it does not depend on heavy JS bundles. */ import type {Page} from 'puppeteer-core'; import type {SearchResult} from '../../types/websearch.types.js'; import {cleanText} from '../../utils/websearch/text.utils.js'; import type {SearchEngine, SearchEngineId} from './types.js'; export class DuckDuckGoEngine implements SearchEngine { readonly id: SearchEngineId = 'duckduckgo'; readonly name = 'DuckDuckGo'; async search( page: Page, query: string, maxResults: number, ): Promise<SearchResult[]> { const encodedQuery = encodeURIComponent(query); const searchUrl = `https://lite.duckduckgo.com/lite?q=${encodedQuery}`; await page.goto(searchUrl, { waitUntil: 'networkidle2', timeout: 30000, }); const results = await page.evaluate((maxLimit: number) => { type Partial = { title?: string; url?: string; snippet?: string; displayUrl?: string; }; const searchResults: Partial[] = []; const rows = document.querySelectorAll('table tr'); let currentResult: Partial = {}; let resultCount = 0; for (const row of rows) { if (resultCount >= maxLimit) break; // Title row contains the result link const linkElement = row.querySelector('a.result-link'); if (linkElement) { if (currentResult.title && currentResult.url) { searchResults.push(currentResult); resultCount++; if (resultCount >= maxLimit) break; } const title = linkElement.textContent?.trim() || ''; const href = linkElement.getAttribute('href') || ''; // Decode the actual URL out of DuckDuckGo's redirect wrapper let actualUrl = href; if (href.includes('uddg=')) { const match = href.match(/uddg=([^&]+)/); if (match && match[1]) { actualUrl = decodeURIComponent(match[1]); } } currentResult = { title, url: actualUrl, snippet: '', displayUrl: '', }; continue; } const snippetElement = row.querySelector('td.result-snippet'); if (snippetElement && currentResult.title) { currentResult.snippet = snippetElement.textContent?.trim() || ''; continue; } const displayUrlElement = row.querySelector('span.link-text'); if (displayUrlElement && currentResult.title) { currentResult.displayUrl = displayUrlElement.textContent?.trim() || ''; } } if ( currentResult.title && currentResult.url && resultCount < maxLimit ) { searchResults.push(currentResult); } return searchResults; }, maxResults); return results.map(r => ({ title: cleanText(r.title || ''), url: r.url || '', snippet: cleanText(r.snippet || ''), displayUrl: cleanText(r.displayUrl || ''), })); } } ================================================ FILE: source/mcp/engines/websearch/index.ts ================================================ /** * Search engine registry / factory. * * Built-in engines are registered statically below. In addition, users can * drop custom engine plugins into `~/.snow/plugin/search_engines/` (the * `SEARCH_ENGINES_DIR` constant exported from `apiConfig.ts`). Each plugin * file must implement the `SearchEngine` contract from `./types.ts` and is * loaded lazily on first use via dynamic `import()`. * * Plugin file rules (mirrors the status-line plugin loader): * - Supported extensions: `.js`, `.mjs`, `.cjs` * - The module may export the engine as `default`, `searchEngine`, or * `searchEngines` (single object or array). * - An engine MUST be an object with `{id, name, search(page, query, * maxResults)}` where `search` returns `Promise<SearchResult[]>`. * - External engines override built-ins when their `id` collides. * * Adding a NEW built-in engine still requires only: * 1. Implementing `SearchEngine` in a new file under this folder. * 2. Registering it in `BUILT_IN_ENGINES` below. */ import {existsSync, readdirSync} from 'node:fs'; import {extname, join} from 'node:path'; import {pathToFileURL} from 'node:url'; import {SEARCH_ENGINES_DIR} from '../../../utils/config/apiConfig.js'; import {DuckDuckGoEngine} from './duckduckgo.engine.js'; import {BingEngine} from './bing.engine.js'; import type {SearchEngine, SearchEngineId} from './types.js'; export const DEFAULT_SEARCH_ENGINE: SearchEngineId = 'duckduckgo'; const SUPPORTED_SEARCH_ENGINE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']); const BUILT_IN_ENGINES: SearchEngine[] = [ new DuckDuckGoEngine(), new BingEngine(), ]; /** * In-memory registry keyed by engine id. Initially populated with built-in * engines (only those that are enabled); extended at runtime by * `ensureSearchEnginesLoaded()`. Engines explicitly setting `enable: false` * are NOT registered. */ const ENGINES: Map<string, SearchEngine> = new Map( BUILT_IN_ENGINES.filter(isEngineEnabled).map(e => [e.id, e] as const), ); let externalLoadPromise: Promise<void> | null = null; let externalLoaded = false; type SearchEngineModule = { default?: unknown; searchEngine?: unknown; searchEngines?: unknown; }; function isSearchEngine(candidate: unknown): candidate is SearchEngine { if (typeof candidate !== 'object' || candidate === null) return false; const c = candidate as Partial<SearchEngine>; return ( typeof c.id === 'string' && c.id.length > 0 && typeof c.name === 'string' && typeof c.search === 'function' ); } /** * An engine is considered enabled unless it explicitly sets `enable: false`. * This lets plugin authors keep the file on disk while temporarily disabling * the engine, mirroring the StatusLine hook convention. */ function isEngineEnabled(engine: SearchEngine): boolean { return engine.enable !== false; } function collectFromModule(mod: SearchEngineModule): SearchEngine[] { const candidates: unknown[] = []; const pushOne = (val: unknown) => { if (Array.isArray(val)) candidates.push(...val); else if (val !== undefined && val !== null) candidates.push(val); }; pushOne(mod.default); pushOne(mod.searchEngine); pushOne(mod.searchEngines); return candidates.filter(isSearchEngine); } async function loadExternalEngines(): Promise<void> { if (!existsSync(SEARCH_ENGINES_DIR)) return; let entries: Array<import('node:fs').Dirent>; try { entries = readdirSync(SEARCH_ENGINES_DIR, {withFileTypes: true}); } catch (error) { // eslint-disable-next-line no-console console.warn('[websearch] failed to read plugin dir', error); return; } const files = entries .filter( e => e.isFile() && SUPPORTED_SEARCH_ENGINE_EXTENSIONS.has(extname(e.name).toLowerCase()), ) .sort((a, b) => a.name.localeCompare(b.name)); for (const file of files) { const modulePath = join(SEARCH_ENGINES_DIR, file.name); try { const moduleUrl = pathToFileURL(modulePath).href; const mod = (await import(moduleUrl)) as SearchEngineModule; const engines = collectFromModule(mod); if (engines.length === 0) { // eslint-disable-next-line no-console console.warn( `[websearch] plugin "${file.name}" did not export a valid SearchEngine`, ); continue; } for (const engine of engines) { if (!isEngineEnabled(engine)) { // Plugin author explicitly disabled this engine — ensure it is // not registered AND drop any same-id built-in so the user can // also use `enable: false` as a way to mask built-ins. ENGINES.delete(engine.id); continue; } ENGINES.set(engine.id, engine); } } catch (error) { // eslint-disable-next-line no-console console.warn( `[websearch] failed to load search engine plugin "${file.name}":`, error, ); } } } /** * Ensure that external search engine plugins are loaded into the registry. * Safe to call multiple times — actual loading only runs once. */ export function ensureSearchEnginesLoaded(): Promise<void> { if (externalLoaded) return Promise.resolve(); if (externalLoadPromise) return externalLoadPromise; externalLoadPromise = loadExternalEngines().then(() => { externalLoaded = true; }); return externalLoadPromise; } /** * Resolve an engine by id. Falls back to the default engine if the id is * unknown (e.g. older config file referencing a removed engine). * * NOTE: This is synchronous and only sees engines registered at call time. * Callers that need external plugins to be available should `await * ensureSearchEnginesLoaded()` first. */ export function getSearchEngine(id?: string | null): SearchEngine { if (id && ENGINES.has(id)) { return ENGINES.get(id)!; } return ENGINES.get(DEFAULT_SEARCH_ENGINE)!; } /** All registered engines (sync — only sees what's loaded so far). */ export function listSearchEngines(): SearchEngine[] { return Array.from(ENGINES.values()); } /** * Async variant of `listSearchEngines` that first ensures external plugins * have been loaded. Use this from UI screens that show the engine picker. */ export async function listSearchEnginesAsync(): Promise<SearchEngine[]> { await ensureSearchEnginesLoaded(); return listSearchEngines(); } export type {SearchEngine, SearchEngineId} from './types.js'; ================================================ FILE: source/mcp/engines/websearch/types.ts ================================================ /** * Search engine abstraction for the web search service. * * Each engine encapsulates the logic to drive a Puppeteer Page and extract * search results from a specific search provider (DuckDuckGo, Bing, ...). * * Browser lifecycle (launch / connect / close) is managed by WebSearchService * and is intentionally outside the scope of an engine — engines only need a * ready-to-use `Page`. */ import type {Page} from 'puppeteer-core'; import type {SearchResult} from '../../types/websearch.types.js'; /** * Identifier used for configuration / persistence. * * Historically this was a closed string-literal union ('duckduckgo' | 'bing'). * Since search engines are now pluggable (user-supplied plugins under * `~/.snow/plugin/search_engines/`), the id space is open and runtime values * can be any string the plugin author chooses. We therefore keep this as a * `string` alias to preserve a stable type name across the codebase while * accepting arbitrary plugin ids. */ export type SearchEngineId = string; /** * Common contract every search engine implementation must satisfy. */ export interface SearchEngine { /** Stable engine identifier used in config files. */ readonly id: SearchEngineId; /** Human readable name (used by UI / logs). */ readonly name: string; /** * Optional enable flag. Defaults to `true` when omitted. * * Plugin authors can set `enable: false` to keep the plugin file in place * but exclude its engine(s) from the registry — useful for temporarily * disabling an engine without deleting the file. Disabled engines are * invisible to `getSearchEngine` / `listSearchEngines` / the UI picker. */ readonly enable?: boolean; /** * Drive the given Puppeteer Page to perform a search and extract results. * * Engines should: * - navigate to their own search URL * - wait for the page to settle * - extract up to `maxResults` results * - clean up nothing (page is owned by the caller) */ search( page: Page, query: string, maxResults: number, ): Promise<SearchResult[]>; } ================================================ FILE: source/mcp/filesystem.ts ================================================ import {promises as fs} from 'fs'; import * as path from 'path'; // IDE connection supports both VSCode and JetBrains IDEs // SSH support for remote file operations import {SSHClient, parseSSHUrl} from '../utils/ssh/sshClient.js'; import { getWorkingDirectories, type SSHConfig, } from '../utils/config/workingDirConfig.js'; // Type definitions import type { EditByHashlineConfig, EditByHashlineResult, EditByHashlineSingleResult, EditByHashlineBatchResultItem, EditBySearchConfig, EditBySearchResult, EditBySearchSingleResult, EditBySearchBatchResultItem, HashlineOperation, SingleFileReadResult, MultipleFilesReadResult, ImageContent, } from './types/filesystem.types.js'; import {IMAGE_MIME_TYPES, OFFICE_FILE_TYPES} from './types/filesystem.types.js'; import { parseEditBySearchParams, executeBatchOperation, } from './utils/filesystem/batch-operations.utils.js'; import {tryFixPath} from './utils/filesystem/path-fixer.utils.js'; import {getFreshDiagnostics} from './utils/filesystem/diagnostics.utils.js'; import { appendDiagnosticsSummary, } from './utils/filesystem/message-format.utils.js'; import {backupFileBeforeMutation} from './utils/filesystem/backup.utils.js'; import { executeEditBySearchSingle, executeHashlineEditSingle, } from './utils/filesystem/edit-tools.utils.js'; import {executeGetFileContentCore} from './utils/filesystem/read-tools.utils.js'; import type {CodeSymbol} from './types/aceCodeSearch.types.js'; // Notebook utilities for automatic note retrieval import {queryNotebook} from '../utils/core/notebookManager.js'; // Encoding detection and conversion utilities import { readFileWithEncoding, writeFileWithEncoding, } from './utils/filesystem/encoding.utils.js'; const {resolve, dirname, isAbsolute, extname} = path; /** * Filesystem MCP Service * Provides basic file operations: read, create, and delete files */ export class FilesystemMCPService { private basePath: string; /** * File extensions supported by Prettier for automatic formatting */ private readonly prettierSupportedExtensions = [ '.js', '.jsx', '.ts', '.tsx', '.json', '.css', '.scss', '.less', '.html', '.vue', '.yaml', '.yml', '.md', '.graphql', '.gql', ]; constructor(basePath: string = process.cwd()) { this.basePath = resolve(basePath); } /** * Check if a path is a remote SSH URL * @param filePath - Path to check * @returns True if the path is an SSH URL */ private isSSHPath(filePath: string): boolean { return filePath.startsWith('ssh://'); } /** * Get SSH config for a remote path from working directories * @param sshUrl - SSH URL to find config for * @returns SSH config if found, null otherwise */ private async getSSHConfigForPath(sshUrl: string): Promise<SSHConfig | null> { const workingDirs = await getWorkingDirectories(); for (const dir of workingDirs) { if (dir.isRemote && dir.sshConfig && sshUrl.startsWith(dir.path)) { return dir.sshConfig; } } // Try to match by host/user const parsed = parseSSHUrl(sshUrl); if (parsed) { for (const dir of workingDirs) { if (dir.isRemote && dir.sshConfig) { const dirParsed = parseSSHUrl(dir.path); if ( dirParsed && dirParsed.host === parsed.host && dirParsed.username === parsed.username && dirParsed.port === parsed.port ) { return dir.sshConfig; } } } } return null; } /** * Read file content from remote SSH server * @param sshUrl - SSH URL of the file * @returns File content as string */ private async readRemoteFile(sshUrl: string): Promise<string> { const parsed = parseSSHUrl(sshUrl); if (!parsed) { throw new Error(`Invalid SSH URL: ${sshUrl}`); } const sshConfig = await this.getSSHConfigForPath(sshUrl); if (!sshConfig) { throw new Error(`No SSH configuration found for: ${sshUrl}`); } const client = new SSHClient(); const connectResult = await client.connect(sshConfig); if (!connectResult.success) { throw new Error(`SSH connection failed: ${connectResult.error}`); } try { const content = await client.readFile(parsed.path); return content; } finally { client.disconnect(); } } /** * Write file content to remote SSH server * @param sshUrl - SSH URL of the file * @param content - Content to write */ private async writeRemoteFile( sshUrl: string, content: string, ): Promise<void> { const parsed = parseSSHUrl(sshUrl); if (!parsed) { throw new Error(`Invalid SSH URL: ${sshUrl}`); } const sshConfig = await this.getSSHConfigForPath(sshUrl); if (!sshConfig) { throw new Error(`No SSH configuration found for: ${sshUrl}`); } const client = new SSHClient(); const connectResult = await client.connect(sshConfig); if (!connectResult.success) { throw new Error(`SSH connection failed: ${connectResult.error}`); } try { await client.writeFile(parsed.path, content); } finally { client.disconnect(); } } /** * Check if a file is an image based on extension * @param filePath - Path to the file * @returns True if the file is an image */ private isImageFile(filePath: string): boolean { const ext = extname(filePath).toLowerCase(); return ext in IMAGE_MIME_TYPES; } /** * Check if a file is an Office document based on extension * @param filePath - Path to the file * @returns True if the file is an Office document */ private isOfficeFile(filePath: string): boolean { const ext = extname(filePath).toLowerCase(); return ext in OFFICE_FILE_TYPES; } /** * Get MIME type for an image file * @param filePath - Path to the file * @returns MIME type or undefined if not an image */ private getImageMimeType(filePath: string): string | undefined { const ext = extname(filePath).toLowerCase(); return IMAGE_MIME_TYPES[ext as keyof typeof IMAGE_MIME_TYPES]; } /** * Read image file and convert to base64 * For SVG files, converts to PNG format for better compatibility * @param fullPath - Full path to the image file * @returns ImageContent object with base64 data */ private async readImageAsBase64( fullPath: string, ): Promise<ImageContent | null> { try { const mimeType = this.getImageMimeType(fullPath); if (!mimeType) { return null; } const ext = extname(fullPath).toLowerCase(); // Handle SVG files - convert to PNG for better compatibility if (ext === '.svg') { try { // Try to dynamically import sharp (optional dependency) const sharp = (await import('sharp')).default; const buffer = await fs.readFile(fullPath); // Convert SVG to PNG using sharp const pngBuffer = await sharp(buffer).png().toBuffer(); const base64Data = pngBuffer.toString('base64'); return { type: 'image', data: base64Data, mimeType: 'image/png', // Return as PNG }; } catch (svgError) { // Fallback: If sharp is not available or conversion fails, return SVG as base64 // Most AI models support SVG directly const buffer = await fs.readFile(fullPath); const base64Data = buffer.toString('base64'); return { type: 'image', data: base64Data, mimeType: 'image/svg+xml', }; } } const buffer = await fs.readFile(fullPath); const base64Data = buffer.toString('base64'); return { type: 'image', data: base64Data, mimeType, }; } catch (error) { console.error(`Failed to read image ${fullPath}:`, error); return null; } } /** * Extract relevant symbol information for a specific line range * This provides context that helps AI make more accurate modifications * @param symbols - All symbols in the file * @param startLine - Start line of the range * @param endLine - End line of the range * @param _totalLines - Total lines in the file (reserved for future use) * @returns Formatted string with relevant symbol information */ private extractRelevantSymbols( symbols: CodeSymbol[], startLine: number, endLine: number, _totalLines: number, ): string { if (symbols.length === 0) { return ''; } // Categorize symbols const imports = symbols.filter(s => s.type === 'import'); const exports = symbols.filter(s => s.type === 'export'); // Symbols within the requested range const symbolsInRange = symbols.filter( s => s.line >= startLine && s.line <= endLine, ); // Symbols defined before the range that might be referenced const symbolsBeforeRange = symbols.filter(s => s.line < startLine); // Build context information const parts: string[] = []; // Always include imports (crucial for understanding dependencies) if (imports.length > 0) { const importList = imports .slice(0, 10) // Limit to avoid excessive tokens .map(s => ` • ${s.name} (line ${s.line})`) .join('\n'); parts.push(`📦 Imports:\n${importList}`); } // Symbols defined in the current range if (symbolsInRange.length > 0) { const rangeSymbols = symbolsInRange .slice(0, 15) .map( s => ` • ${s.type}: ${s.name} (line ${s.line})${ s.signature ? ` - ${s.signature.slice(0, 60)}` : '' }`, ) .join('\n'); parts.push(`🎯 Symbols in this range:\n${rangeSymbols}`); } // Key definitions before this range (that might be referenced) if (symbolsBeforeRange.length > 0 && startLine > 1) { const relevantBefore = symbolsBeforeRange .filter(s => s.type === 'function' || s.type === 'class') .slice(-5) // Last 5 before the range .map(s => ` • ${s.type}: ${s.name} (line ${s.line})`) .join('\n'); if (relevantBefore) { parts.push(`⬆️ Key definitions above:\n${relevantBefore}`); } } // Exports (important for understanding module interface) if (exports.length > 0) { const exportList = exports .slice(0, 10) .map(s => ` • ${s.name} (line ${s.line})`) .join('\n'); parts.push(`📤 Exports:\n${exportList}`); } if (parts.length === 0) { return ''; } return ( '\n\n' + '='.repeat(60) + '\n📚 SYMBOL INDEX & DEFINITIONS:\n' + '='.repeat(60) + '\n' + parts.join('\n\n') ); } /** * Get notebook entries for a file * @param filePath - Path to the file * @returns Formatted notebook entries string, or empty if none found */ private getNotebookEntries(filePath: string): string { try { const entries = queryNotebook(filePath, 10); if (entries.length === 0) { return ''; } const notesText = entries .map((entry, index) => { // createdAt 已经是本地时间格式: "YYYY-MM-DDTHH:mm:ss.SSS" // 提取日期和时间部分: "YYYY-MM-DD HH:mm" const dateStr = entry.createdAt.substring(0, 16).replace('T', ' '); return ` ${index + 1}. [${dateStr}] ${entry.note}`; }) .join('\n'); return ( '\n\n' + '='.repeat(60) + '\n📝 CODE NOTEBOOKS (Latest 10):\n' + '='.repeat(60) + '\n' + notesText ); } catch { // Silently fail notebook retrieval - don't block file reading return ''; } } /** * Get the content of a file with optional line range * Enhanced with symbol information for better AI context * Supports multimodal content (text + images) * @param filePath - Path to the file (relative to base path or absolute) or array of file paths or array of file config objects * @param startLine - Starting line number (1-indexed, inclusive, optional - defaults to 1). Used for single file or as default for array of strings * @param endLine - Ending line number (1-indexed, inclusive, optional - defaults to file end). Used for single file or as default for array of strings * @returns Object containing the requested content with line numbers and metadata (supports multimodal content) * @throws Error if file doesn't exist or cannot be read */ async getFileContent( filePath: | string | string[] | Array<{path: string; startLine?: number; endLine?: number}>, startLine?: number, endLine?: number, ): Promise<SingleFileReadResult | MultipleFilesReadResult> { try { // Defensive handling: if filePath is a string that looks like a JSON array, parse it // This can happen when AI tools serialize array parameters as strings if ( typeof filePath === 'string' && filePath.startsWith('[') && filePath.endsWith(']') ) { try { const parsed = JSON.parse(filePath); if (Array.isArray(parsed)) { filePath = parsed; } } catch { // If parsing fails, treat as a regular string path } } return await executeGetFileContentCore( { basePath: this.basePath, resolvePath: this.resolvePath.bind(this), validatePath: this.validatePath.bind(this), listFiles: this.listFiles.bind(this), isSSHPath: this.isSSHPath.bind(this), readRemoteFile: this.readRemoteFile.bind(this), isImageFile: this.isImageFile.bind(this), readImageAsBase64: this.readImageAsBase64.bind(this), isOfficeFile: this.isOfficeFile.bind(this), getNotebookEntries: this.getNotebookEntries.bind(this), extractRelevantSymbols: this.extractRelevantSymbols.bind(this), }, filePath, startLine, endLine, ); } catch (error) { // Try to fix common path issues if it's a file not found error if ( error instanceof Error && error.message.includes('ENOENT') && typeof filePath === 'string' ) { const fixedPath = await tryFixPath(filePath, this.basePath); if (fixedPath && fixedPath !== filePath) { // Verify the fixed path actually exists before suggesting const fixedFullPath = this.resolvePath(fixedPath); try { await fs.access(fixedFullPath); // File exists, provide helpful suggestion to AI throw new Error( `Failed to read file ${filePath}: ${ error instanceof Error ? error.message : 'Unknown error' }\n💡 Tip: File not found. Did you mean "${fixedPath}"? Please use the correct path.`, ); } catch { // Fixed path also doesn't work, just throw original error } } } throw new Error( `Failed to read file ${filePath}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } /** * Create a new file with specified content * @param filePath - Path where the file should be created * @param content - Content to write to the file * @param createDirectories - Whether to create parent directories if they don't exist * @param overwrite - Whether to overwrite the file if it already exists * @returns Success message * @throws Error if file creation fails */ async createFile( filePath: string, content: string, createDirectories: boolean = true, overwrite: boolean = false, ): Promise<string> { try { const fullPath = this.resolvePath(filePath); let fileExisted = false; let originalContent: string | undefined; // Check if file already exists try { await fs.access(fullPath); if (!overwrite) { throw new Error(`File already exists: ${filePath}`); } fileExisted = true; originalContent = await readFileWithEncoding(fullPath); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') { throw error; } } // Backup for rollback await backupFileBeforeMutation({ filePath, basePath: this.basePath, fileExisted, originalContent, }); // Create parent directories if needed if (createDirectories) { const dir = dirname(fullPath); await fs.mkdir(dir, {recursive: true}); } await writeFileWithEncoding(fullPath, content); let message = fileExisted ? `File overwritten successfully: ${filePath}` : `File created successfully: ${filePath}`; // Try to fetch fresh diagnostics after create/overwrite to avoid stale results try { const diagnostics = await getFreshDiagnostics(fullPath); if (diagnostics.length > 0) { message = appendDiagnosticsSummary(message, filePath, diagnostics); } } catch { // Optional diagnostics retrieval, do not block create success } return message; } catch (error) { throw new Error( `Failed to create file ${filePath}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } /** * List files in a directory (internal use for read tool) * @param dirPath - Directory path relative to base path or absolute path * @returns Array of file names * @throws Error if directory cannot be read * @private */ private async listFiles(dirPath: string = '.'): Promise<string[]> { try { const fullPath = this.resolvePath(dirPath); // For absolute paths, skip validation to allow access outside base path if (!isAbsolute(dirPath)) { await this.validatePath(fullPath); } const stats = await fs.stat(fullPath); if (!stats.isDirectory()) { throw new Error(`Path is not a directory: ${dirPath}`); } const files = await fs.readdir(fullPath); return files; } catch (error) { throw new Error( `Failed to list files in ${dirPath}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } /** * Check if a file or directory exists * @param filePath - Path to check * @returns Boolean indicating existence */ async exists(filePath: string): Promise<boolean> { try { const fullPath = this.resolvePath(filePath); await fs.access(fullPath); return true; } catch { return false; } } /** * Get file information (stats) * @param filePath - Path to the file * @returns File stats object * @throws Error if file doesn't exist */ async getFileInfo(filePath: string): Promise<{ size: number; isFile: boolean; isDirectory: boolean; modified: Date; created: Date; }> { try { const fullPath = this.resolvePath(filePath); await this.validatePath(fullPath); const stats = await fs.stat(fullPath); return { size: stats.size, isFile: stats.isFile(), isDirectory: stats.isDirectory(), modified: stats.mtime, created: stats.birthtime, }; } catch (error) { throw new Error( `Failed to get file info for ${filePath}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } /** * Fuzzy search-and-replace editing (exposed as MCP tool `filesystem-replaceedit`). * Copy search text from source files; strip `lineNum:hash→` prefixes if pasting from filesystem-read. */ async editFileBySearch( filePath: string | string[] | EditBySearchConfig[], searchContent?: string, replaceContent?: string, occurrence: number = 1, contextLines: number = 8, ): Promise<EditBySearchResult> { // Handle array of files if (Array.isArray(filePath)) { return await executeBatchOperation< EditBySearchConfig, EditBySearchSingleResult, EditBySearchBatchResultItem >( filePath, fileItem => parseEditBySearchParams( fileItem, searchContent, replaceContent, occurrence, ), (path, search, replace, occ) => this.editFileBySearchSingle(path, search, replace, occ, contextLines), (path, result) => { return {path, ...result}; }, ); } // Single file mode if ( searchContent === undefined || searchContent === null || replaceContent === undefined || replaceContent === null ) { throw new Error( 'searchContent and replaceContent are required for single file mode', ); } return await this.editFileBySearchSingle( filePath, searchContent, replaceContent, occurrence, contextLines, ); } /** * Internal method: Edit a single file by search-replace * @private */ private async editFileBySearchSingle( filePath: string, searchContent: string, replaceContent: string, occurrence: number, contextLines: number, ): Promise<EditBySearchSingleResult> { return await executeEditBySearchSingle( { basePath: this.basePath, prettierSupportedExtensions: this.prettierSupportedExtensions, isSSHPath: this.isSSHPath.bind(this), readRemoteFile: this.readRemoteFile.bind(this), writeRemoteFile: this.writeRemoteFile.bind(this), resolvePath: this.resolvePath.bind(this), validatePath: this.validatePath.bind(this), }, filePath, searchContent, replaceContent, occurrence, contextLines, ); } /** * Edit file(s) using hashline anchors. * * Each operation references lines by `lineNum:hash` anchors obtained from * a previous `filesystem-read`. Hashes are validated before any mutation * so stale reads are caught early. * * Supported operation types: * • replace – replace startAnchor..endAnchor (inclusive) with content * • insert_after – insert content after startAnchor (endAnchor required; same as startAnchor) * • delete – delete startAnchor..endAnchor (inclusive) */ async editFile( filePath: string | EditByHashlineConfig[], operations?: HashlineOperation[], contextLines: number = 8, ): Promise<EditByHashlineResult> { if (Array.isArray(filePath)) { return await executeBatchOperation< EditByHashlineConfig, EditByHashlineSingleResult, EditByHashlineBatchResultItem >( filePath, fileItem => { const cfg = fileItem as EditByHashlineConfig; return {path: cfg.path, operations: cfg.operations}; }, (path: string, ops: HashlineOperation[]) => this.editFileSingle(path, ops, contextLines), (path, result) => ({path, ...result}), ); } if (!operations || operations.length === 0) { throw new Error('operations array is required and must not be empty'); } return await this.editFileSingle(filePath, operations, contextLines); } /** * Internal: edit a single file via hashline anchors. * @private */ private async editFileSingle( filePath: string, operations: HashlineOperation[], contextLines: number, ): Promise<EditByHashlineSingleResult> { return await executeHashlineEditSingle( { basePath: this.basePath, prettierSupportedExtensions: this.prettierSupportedExtensions, isSSHPath: this.isSSHPath.bind(this), readRemoteFile: this.readRemoteFile.bind(this), writeRemoteFile: this.writeRemoteFile.bind(this), resolvePath: this.resolvePath.bind(this), validatePath: this.validatePath.bind(this), }, filePath, operations, contextLines, ); } /** * Resolve path relative to base path and normalize it * Supports contextPath for smart relative path resolution in batch operations * @param filePath - Path to resolve * @param contextPath - Optional context path (e.g., previous absolute path in batch) * If provided and filePath is relative, will resolve relative to contextPath's directory * @private */ private resolvePath(filePath: string, contextPath?: string): string { // Check if the path is already absolute const isAbs = path.isAbsolute(filePath); if (isAbs) { // Return absolute path as-is (will be validated later) return resolve(filePath); } // For relative paths, resolve against context path if provided // Remove any leading slashes or backslashes to treat as relative path const relativePath = filePath.replace(/^[\/\\]+/, ''); // If context path is provided and is absolute, resolve relative to its directory if (contextPath && path.isAbsolute(contextPath)) { return resolve(path.dirname(contextPath), relativePath); } // Otherwise resolve against base path return resolve(this.basePath, relativePath); } /** * Validate that the path is within the allowed base directory * @private */ private async validatePath(fullPath: string): Promise<void> { const normalizedPath = resolve(fullPath); const normalizedBase = resolve(this.basePath); if (!normalizedPath.startsWith(normalizedBase)) { throw new Error('Access denied: Path is outside of allowed directory'); } } } // Export a default instance export const filesystemService = new FilesystemMCPService(); export const mcpTools = [ { name: 'filesystem-read', description: 'Read file content with line numbers and content hashes. Supports text files, images, Office documents, and directories. **REMOTE SSH SUPPORT**: Fully supports remote files via SSH URL format (ssh://user@host:port/path). **PATH REQUIREMENT**: Use EXACT paths from search results or user input, never undefined/null/empty/placeholders. **WORKFLOW**: (1) Use search tools FIRST to locate files, (2) Read only when you have the exact path. **SUPPORTS**: Single file (string), multiple files (array of strings), or per-file ranges (array of {path, startLine?, endLine?}). Returns content with hashline anchors (format: "lineNum:hash→code", e.g. "42:a3→const x = 1;"). Use these anchors with filesystem-edit for safe editing.', inputSchema: { type: 'object', properties: { filePath: { oneOf: [ { type: 'string', description: 'Path to a single file to read or directory to list', }, { type: 'array', items: { type: 'string', }, description: 'Array of file paths to read in one call (uses unified startLine/endLine from top-level parameters)', }, { type: 'array', items: { type: 'object', properties: { path: { type: 'string', description: 'File path', }, startLine: { type: 'number', description: 'Optional: Starting line for this file (overrides top-level startLine)', }, endLine: { type: 'number', description: 'Optional: Ending line for this file (overrides top-level endLine)', }, }, required: ['path'], }, description: 'Array of file config objects with per-file line ranges. Each file can have its own startLine/endLine.', }, ], description: 'Path to the file(s) to read or directory to list: string, array of strings, or array of {path, startLine?, endLine?} objects', }, startLine: { type: 'number', description: 'Optional: Default starting line number (1-indexed) for all files. Omit to read from line 1. Can be overridden by per-file startLine in object format.', }, endLine: { type: 'number', description: 'Optional: Default ending line number (1-indexed) for all files. Omit to read to end of file. Can be overridden by per-file endLine in object format.', }, }, required: ['filePath'], }, }, { name: 'filesystem-create', description: 'Create a new file with content. **PATH REQUIREMENT**: Use EXACT non-empty string path, never undefined/null/empty/placeholders like "path/to/file". Set `overwrite` to true to replace an existing file (original content is backed up for rollback). Automatically creates parent directories.', inputSchema: { type: 'object', properties: { filePath: { type: 'string', description: 'Path where the file should be created', }, content: { type: 'string', description: 'Content to write to the file', }, overwrite: { type: 'boolean', description: 'Whether to overwrite the file if it already exists. When true, the existing file content is backed up for rollback before being replaced. When false, an error is thrown if the file already exists.', }, createDirectories: { type: 'boolean', description: "Whether to create parent directories if they don't exist", default: true, }, }, required: ['filePath', 'content', 'overwrite'], }, }, { name: 'filesystem-replaceedit', description: 'DEFAULT edit tool: Fuzzy search-and-replace editing. ' + '**WHEN**: Prefer this for normal workflow and diff-friendly context display. Use `filesystem-edit` when you need strict hash-anchored safety checks. ' + '**REMOTE SSH**: Supports ssh:// paths like other filesystem tools. ' + '**INPUT**: `searchContent` must be raw source text — strip `lineNum:hash→` prefixes if you pasted from `filesystem-read`. ' + '**BATCH**: `filePath` may be a string, string[] with top-level search/replace, or {path, searchContent, replaceContent, occurrence?}[]. ' + 'Uses fuzzy similarity matching (fixed threshold 0.75).', inputSchema: { type: 'object', properties: { filePath: { oneOf: [ { type: 'string', description: 'Path to a single file to edit', }, { type: 'array', items: { type: 'string', }, description: 'Array of file paths (uses unified searchContent/replaceContent from top-level)', }, { type: 'array', items: { type: 'object', properties: { path: { type: 'string', description: 'File path', }, searchContent: { type: 'string', description: 'Content to search for in this file', }, replaceContent: { type: 'string', description: 'New content to replace with', }, occurrence: { type: 'number', description: 'Which match to replace (1-indexed, default: 1)', }, }, required: ['path', 'searchContent', 'replaceContent'], }, description: 'Array of edit config objects for per-file search-replace operations', }, ], description: 'File path(s) to edit', }, searchContent: { type: 'string', description: 'Content to find and replace (for single file or unified mode). Raw file text only — no hashline prefixes.', }, replaceContent: { type: 'string', description: 'New content to replace with (for single file or unified mode)', }, occurrence: { type: 'number', description: 'Which match to replace if multiple found (1-indexed). Default: 1 (best match first). Use -1 only when a single match exists (same as occurrence 1).', default: 1, }, contextLines: { type: 'number', description: 'Context lines to show before/after (default: 8)', default: 8, }, }, required: ['filePath'], }, }, { name: 'filesystem-edit', description: 'OPTIONAL strict edit tool: Hash-anchored editing using content hashes from filesystem-read. ' + 'Line format: "lineNum:hash→content" (e.g. "42:a3→code"). Use anchors "lineNum:hash" to reference lines — no text reproduction needed. ' + '**OPERATIONS**: (1) replace — replaces startAnchor..endAnchor with content; ' + '(2) insert_after — inserts content after startAnchor; ' + '(3) delete — removes startAnchor..endAnchor, set content to empty string "". ' + '**WORKFLOW**: filesystem-read → note anchors → call this tool with operations. ' + '**ANCHOR FORMAT**: "lineNum:hash" e.g. "10:a3". endAnchor is always required (inclusive range). Single-line edits: set endAnchor to the same anchor as startAnchor. ' + '**SUPPORTS BATCH**: Pass array of {path, operations} for multi-file edits.', inputSchema: { type: 'object', properties: { filePath: { oneOf: [ { type: 'string', description: 'Path to a single file to edit', }, { type: 'array', items: { type: 'object', properties: { path: { type: 'string', description: 'File path', }, operations: { type: 'array', items: { type: 'object', properties: { type: { type: 'string', enum: ['replace', 'insert_after', 'delete'], description: 'Operation type', }, startAnchor: { type: 'string', description: 'Start anchor from filesystem-read (format: "lineNum:hash", e.g. "42:a3")', }, endAnchor: { type: 'string', description: 'Inclusive end anchor (format: "lineNum:hash"). For a single line, use the same value as startAnchor.', }, content: { type: 'string', description: 'New content to write (for replace and insert_after). Pass empty string "" for delete. Do NOT include line numbers or hashes.', }, }, required: [ 'type', 'startAnchor', 'endAnchor', 'content', ], }, description: 'Array of edit operations for this file', }, }, required: ['path', 'operations'], }, description: 'Array of per-file hashline edit configs for batch editing', }, ], description: 'File path (string) or batch configs (array of {path, operations})', }, operations: { type: 'array', items: { type: 'object', properties: { type: { type: 'string', enum: ['replace', 'insert_after', 'delete'], description: 'Operation type', }, startAnchor: { type: 'string', description: 'Start anchor from filesystem-read output (format: "lineNum:hash", e.g. "10:a3")', }, endAnchor: { type: 'string', description: 'Inclusive end anchor (format: "lineNum:hash"). For a single line, use the same value as startAnchor.', }, content: { type: 'string', description: 'New content to write (for replace and insert_after). Pass empty string "" for delete. Do NOT include line numbers or hashes.', }, }, required: ['type', 'startAnchor', 'endAnchor', 'content'], }, description: 'Array of edit operations (for single file mode). Each operation references anchors from filesystem-read.', }, contextLines: { type: 'number', description: 'Context lines to show before/after edit (default: 8)', default: 8, }, }, required: ['filePath'], }, }, ]; ================================================ FILE: source/mcp/ideDiagnostics.ts ================================================ import {vscodeConnection, type Diagnostic} from '../utils/ui/vscodeConnection.js'; /** * IDE Diagnostics MCP Service * Provides access to diagnostics (errors, warnings, hints) from connected IDE * Supports both VSCode and JetBrains IDEs */ export class IdeDiagnosticsMCPService { /** * Get diagnostics for a specific file from the connected IDE * @param filePath - Absolute path to the file to get diagnostics for * @returns Promise that resolves with array of diagnostics */ async getDiagnostics(filePath: string): Promise<Diagnostic[]> { if (!vscodeConnection.isConnected()) { throw new Error( 'IDE connection not available. Please ensure VSCode or JetBrains IDE plugin is installed and running.', ); } try { const diagnostics = await vscodeConnection.requestDiagnostics(filePath); return diagnostics; } catch (error) { const message = error instanceof Error ? error.message : 'Unknown error'; throw new Error(`Failed to get diagnostics: ${message}`); } } /** * Format diagnostics into human-readable text * @param diagnostics - Array of diagnostics to format * @param filePath - Path to the file (for display) * @returns Formatted string */ formatDiagnostics(diagnostics: Diagnostic[], filePath: string): string { if (diagnostics.length === 0) { return `No diagnostics found for ${filePath}`; } const lines: string[] = [`Diagnostics for ${filePath}:\n`]; // Group by severity const grouped = { error: diagnostics.filter(d => d.severity === 'error'), warning: diagnostics.filter(d => d.severity === 'warning'), info: diagnostics.filter(d => d.severity === 'info'), hint: diagnostics.filter(d => d.severity === 'hint'), }; // Add summary const counts = [ grouped.error.length > 0 ? `${grouped.error.length} errors` : null, grouped.warning.length > 0 ? `${grouped.warning.length} warnings` : null, grouped.info.length > 0 ? `${grouped.info.length} info` : null, grouped.hint.length > 0 ? `${grouped.hint.length} hints` : null, ].filter(Boolean); lines.push(`Total: ${counts.join(', ')}\n`); // Format each severity group const formatGroup = (items: Diagnostic[], label: string, icon: string) => { if (items.length === 0) return; lines.push(`\n${label}:`); items.forEach(d => { const location = `Line ${d.line + 1}, Col ${d.character + 1}`; const source = d.source ? ` [${d.source}]` : ''; const code = d.code ? ` (${d.code})` : ''; lines.push(` ${icon} ${location}${source}${code}`); lines.push(` ${d.message}`); }); }; formatGroup(grouped.error, 'Errors', '❌'); formatGroup(grouped.warning, 'Warnings', '⚠️'); formatGroup(grouped.info, 'Info', 'ℹ️'); formatGroup(grouped.hint, 'Hints', '💡'); return lines.join('\n'); } } // Export a default instance export const ideDiagnosticsService = new IdeDiagnosticsMCPService(); // Export MCP tool definitions export const mcpTools = [ { name: 'ide-get_diagnostics', description: 'Get diagnostics (errors, warnings, hints) for a specific file from the connected IDE. Works with both VSCode and JetBrains IDEs. Returns array of diagnostic information including severity, line number, character position, message, and source. Requires IDE plugin to be installed and running.', inputSchema: { type: 'object', properties: { filePath: { type: 'string', description: 'Absolute path to the file to get diagnostics for. Must be a valid file path accessible by the IDE.', }, }, required: ['filePath'], }, }, ]; ================================================ FILE: source/mcp/lsp/HybridCodeSearchService.ts ================================================ import * as path from 'path'; import {ACECodeSearchService} from '../aceCodeSearch.js'; import {LSPManager} from './LSPManager.js'; import type {CodeSymbol, CodeReference} from '../types/aceCodeSearch.types.js'; import {MAX_FILE_OUTLINE_SYMBOLS} from '../utils/aceCodeSearch/constants.utils.js'; export class HybridCodeSearchService { private lspManager: LSPManager; private regexSearch: ACECodeSearchService; private lspTimeout = 3000; // 3秒超时 private csharpLspTimeout = 15000; // csharp-ls cold start / solution load can be slow constructor(basePath: string = process.cwd()) { this.lspManager = new LSPManager(basePath); this.regexSearch = new ACECodeSearchService(basePath); } async findDefinition( symbolName: string, contextFile?: string, line?: number, column?: number, ): Promise<CodeSymbol | null> { if (contextFile) { try { const lspResult = await this.findDefinitionWithLSP( symbolName, contextFile, line, column, ); if (lspResult) { return lspResult; } } catch (error) { // LSP failed, fallback to regex } } return this.regexSearch.findDefinition(symbolName, contextFile); } private async findDefinitionWithLSP( symbolName: string, contextFile: string, line?: number, column?: number, ): Promise<CodeSymbol | null> { let position: {line: number; column: number} | null = null; const fs = await import('fs/promises'); const content = await fs.readFile(contextFile, 'utf-8'); const lines = content.split('\n'); // If line and column are provided, prefer them, but for C# verify/adjust // the column so it points to the actual symbol token. if (line !== undefined && column !== undefined) { let adjustedLine = line; let adjustedColumn = column; if (contextFile.endsWith('.cs')) { const tryFindOnLine = (lineIndex: number): number | null => { const textLine = lines[lineIndex]; if (!textLine) return null; const symbolRegex = new RegExp(`\\b${symbolName}\\b`); const match = symbolRegex.exec(textLine); return match ? match.index : null; }; const foundOnSameLine = adjustedLine >= 0 && adjustedLine < lines.length ? tryFindOnLine(adjustedLine) : null; const foundOnPrevLine = foundOnSameLine === null && adjustedLine - 1 >= 0 && adjustedLine - 1 < lines.length ? tryFindOnLine(adjustedLine - 1) : null; if (foundOnSameLine !== null) { adjustedColumn = foundOnSameLine; } else if (foundOnPrevLine !== null) { adjustedLine = adjustedLine - 1; adjustedColumn = foundOnPrevLine; } } position = {line: adjustedLine, column: adjustedColumn}; } else { // Otherwise, find the first occurrence of the symbol in contextFile for (let i = 0; i < lines.length; i++) { const textLine = lines[i]; if (!textLine) continue; const symbolRegex = new RegExp(`\\b${symbolName}\\b`); const match = symbolRegex.exec(textLine); if (match) { position = {line: i, column: match.index}; break; } } } if (!position) { return null; } // Now ask LSP to find the definition (which may be in another file) const timeoutMs = contextFile.endsWith('.cs') ? this.csharpLspTimeout : this.lspTimeout; const timeoutPromise = new Promise<null>(resolve => setTimeout(() => resolve(null), timeoutMs), ); const lspPromise = this.lspManager.findDefinition( contextFile, position.line, position.column, ); // Prevent unhandled rejection if the LSP operation fails after timeout lspPromise.catch(() => {}); const location = await Promise.race([lspPromise, timeoutPromise]); if (!location) { return null; } // Convert LSP location to CodeSymbol const filePath = this.uriToPath(location.uri); return { name: symbolName, type: 'function', filePath, line: location.range.start.line + 1, column: location.range.start.character + 1, language: this.detectLanguage(filePath), }; } async findReferences( symbolName: string, maxResults = 100, ): Promise<CodeReference[]> { return this.regexSearch.findReferences(symbolName, maxResults); } async getFileOutline( filePath: string, options?: { maxResults?: number; includeContext?: boolean; symbolTypes?: CodeSymbol['type'][]; }, ): Promise<CodeSymbol[]> { try { const timeoutPromise = new Promise<null>(resolve => setTimeout(() => resolve(null), this.lspTimeout), ); const lspPromise = this.lspManager.getDocumentSymbols(filePath); // Attach a no-op rejection handler so that if the timeout wins the // race and the LSP operation later fails (e.g. ERR_STREAM_DESTROYED // because the server process exited), the rejection does not become // an unhandled promise rejection. lspPromise.catch(() => {}); const symbols = await Promise.race([lspPromise, timeoutPromise]); if (symbols && symbols.length > 0) { let codeSymbols = this.convertLSPSymbolsToCodeSymbols( symbols, filePath, ); if (options?.symbolTypes && options.symbolTypes.length > 0) { codeSymbols = codeSymbols.filter(symbol => options.symbolTypes!.includes(symbol.type), ); } const maxResults = options?.maxResults && options.maxResults > 0 ? Math.min(options.maxResults, MAX_FILE_OUTLINE_SYMBOLS) : MAX_FILE_OUTLINE_SYMBOLS; return codeSymbols.slice(0, maxResults); } } catch (error) { // LSP failed, fallback to regex } return this.regexSearch.getFileOutline(filePath, options); } private convertLSPSymbolsToCodeSymbols( symbols: any[], filePath: string, ): CodeSymbol[] { const results: CodeSymbol[] = []; const symbolTypeMap: Record<number, CodeSymbol['type']> = { 5: 'class', 6: 'method', 9: 'method', 10: 'enum', 11: 'interface', 12: 'function', 13: 'variable', 14: 'constant', }; const processSymbol = (symbol: any) => { const range = symbol.location?.range || symbol.range; if (!range) return; const symbolType = symbolTypeMap[symbol.kind]; if (!symbolType) return; results.push({ name: symbol.name, type: symbolType, filePath: this.uriToPath(symbol.location?.uri || filePath), line: range.start.line + 1, column: range.start.character + 1, language: this.detectLanguage(filePath), }); if (symbol.children) { for (const child of symbol.children) { processSymbol(child); } } }; for (const symbol of symbols) { processSymbol(symbol); } return results; } private uriToPath(uri: string): string { if (uri.startsWith('file://')) { return uri.slice(7); } return uri; } private detectLanguage(filePath: string): string { const ext = path.extname(filePath).toLowerCase(); const languageMap: Record<string, string> = { '.ts': 'typescript', '.tsx': 'typescript', '.js': 'javascript', '.jsx': 'javascript', '.py': 'python', '.go': 'go', '.rs': 'rust', '.java': 'java', '.cs': 'csharp', }; return languageMap[ext] || 'unknown'; } async textSearch( pattern: string, fileGlob?: string, isRegex = true, maxResults = 100, ) { return this.regexSearch.textSearch(pattern, fileGlob, isRegex, maxResults); } async semanticSearch( query: string, searchType: 'definition' | 'usage' | 'implementation' | 'all' = 'all', language?: string, symbolType?: CodeSymbol['type'], maxResults = 50, ) { return this.regexSearch.semanticSearch( query, searchType, language, symbolType, maxResults, ); } async dispose(): Promise<void> { this.regexSearch.dispose(); await this.lspManager.dispose(); } } export const hybridCodeSearchService = new HybridCodeSearchService(); ================================================ FILE: source/mcp/lsp/LSPClient.ts ================================================ import {spawn, type ChildProcess} from 'child_process'; import {promises as fs} from 'fs'; import * as path from 'path'; import { createMessageConnection, StreamMessageReader, StreamMessageWriter, type MessageConnection, } from 'vscode-jsonrpc/node.js'; import type { InitializeParams, InitializeResult, ServerCapabilities, Position, Location, Hover, CompletionItem, DocumentSymbol, SymbolInformation, TextDocumentPositionParams, ReferenceParams, DocumentSymbolParams, HoverParams, CompletionParams, } from 'vscode-languageserver-protocol'; import {processManager} from '../../utils/core/processManager.js'; import type {LSPServerConfig} from './LSPServerRegistry.js'; export interface LSPClientConfig extends LSPServerConfig { language: string; rootPath: string; } export class LSPClient { private process?: ChildProcess; private connection?: MessageConnection; private capabilities?: ServerCapabilities; private isInitialized = false; private isProcessAlive = false; private openDocuments: Set<string> = new Set(); private documentVersions: Map<string, number> = new Map(); private csharpSolutionLoaded = false; private csharpSolutionLoadPromise?: Promise<void>; private resolveCsharpSolutionLoad?: () => void; private isShuttingDown = false; private canSendMessages(): boolean { const stdin = this.process?.stdin; return Boolean( this.connection && this.isInitialized && this.isProcessAlive && !this.isShuttingDown && stdin && !stdin.destroyed && !stdin.writableEnded, ); } private markTransportClosed(): void { if (!this.isProcessAlive && !this.isInitialized) { return; } this.isInitialized = false; this.isProcessAlive = false; // Immediately dispose the connection to prevent vscode-jsonrpc from // attempting further writes (e.g. responses to server-initiated requests) // on the now-destroyed stdin stream. if (this.connection) { try { this.connection.dispose(); } catch { // Connection may already be disposed } } } constructor(private config: LSPClientConfig) {} private async findCsharpSolutionFile( rootPath: string, ): Promise<string | null> { // If caller passes a .sln path directly, respect it. if (rootPath.toLowerCase().endsWith('.sln')) { return rootPath; } try { const entries = await fs.readdir(rootPath, {withFileTypes: true}); const solutions = entries .filter( entry => entry.isFile() && entry.name.toLowerCase().endsWith('.sln'), ) .map(entry => entry.name) .sort((a, b) => a.localeCompare(b)); if (solutions.length === 0) return null; if (solutions.length === 1) return path.join(rootPath, solutions[0]!); const preferredName = `${path.basename(rootPath)}.sln`; const preferred = solutions.find(s => s === preferredName); return path.join(rootPath, preferred ?? solutions[0]!); } catch { return null; } } async start(): Promise<void> { if (this.isInitialized) { return; } try { const args = [...this.config.args]; if (this.config.language === 'csharp') { // csharp-ls: --solution/-s <solution> // Compatibility: if rootPath is a directory, auto-pick a .sln in it. const hasSolutionArg = args.includes('-s') || args.includes('--solution'); if (!hasSolutionArg) { const slnPath = await this.findCsharpSolutionFile( this.config.rootPath, ); if (slnPath) { // Pass absolute path to avoid ambiguity; csharp-ls accepts absolute. args.push('-s', slnPath); } else { console.log( `[LSP:csharp] No .sln found under rootPath=${this.config.rootPath}; skip -s and rely on fallback.`, ); } } } else if (this.config.language === 'java') { // Keep existing behavior: pass project root for Java servers that need it. args.push('-s', this.config.rootPath); } this.process = spawn(this.config.command, args, { stdio: ['pipe', 'pipe', 'pipe'], cwd: this.config.rootPath, }); this.isProcessAlive = true; this.isShuttingDown = false; // Detect when the LSP server transport is no longer writable. this.process.on('exit', () => { this.markTransportClosed(); }); this.process.on('close', () => { this.markTransportClosed(); }); this.process.on('error', () => { this.markTransportClosed(); }); this.process.stdin?.on('error', () => { this.markTransportClosed(); }); this.process.stdout?.on('error', () => { this.markTransportClosed(); }); this.process.stderr?.on('error', () => { this.markTransportClosed(); }); processManager.register(this.process); this.connection = createMessageConnection( new StreamMessageReader(this.process.stdout!), new StreamMessageWriter(this.process.stdin!), ); // Handle connection-level errors and closure. // Suppress stream-destroyed errors that occur when the child process exits // while a write is still in-flight – these are expected during teardown. this.connection.onError(([error]) => { this.markTransportClosed(); const msg = error?.message || ''; if ( msg.includes('stream was destroyed') || msg.includes('ERR_STREAM_DESTROYED') || msg.includes('write after end') ) { return; } console.debug('LSP connection error:', msg || error); }); this.connection.onClose(() => { this.markTransportClosed(); }); // Some servers (notably csharp-ls) will call back into the client. // If we don't implement these, the server may crash with RemoteMethodNotFound. this.connection.onRequest('window/workDoneProgress/create', () => null); this.connection.onRequest('client/registerCapability', () => null); this.connection.onRequest('workspace/configuration', () => []); this.connection.onNotification('window/logMessage', (params: any) => { const message = typeof params?.message === 'string' ? params.message : ''; if ( !this.csharpSolutionLoaded && message.includes('Finished loading solution') ) { this.csharpSolutionLoaded = true; this.resolveCsharpSolutionLoad?.(); } }); this.connection.onNotification('window/showMessage', (_params: any) => { // ignored }); this.connection.listen(); if (this.config.language === 'csharp') { this.csharpSolutionLoaded = false; this.csharpSolutionLoadPromise = new Promise<void>(resolve => { this.resolveCsharpSolutionLoad = resolve; }); } const initParams: InitializeParams = { processId: process.pid, rootPath: this.config.rootPath, rootUri: this.pathToUri(this.config.rootPath), capabilities: { textDocument: { synchronization: { dynamicRegistration: false, willSave: false, willSaveWaitUntil: false, didSave: false, }, completion: { dynamicRegistration: false, completionItem: { snippetSupport: false, }, }, hover: { dynamicRegistration: false, }, definition: { dynamicRegistration: false, }, references: { dynamicRegistration: false, }, documentSymbol: { dynamicRegistration: false, }, }, workspace: { applyEdit: false, workspaceEdit: { documentChanges: false, }, }, }, workspaceFolders: [ { uri: this.pathToUri(this.config.rootPath), name: path.basename(this.config.rootPath), }, ], initializationOptions: this.config.initializationOptions, }; const result = await this.connection.sendRequest<InitializeResult>( 'initialize', initParams, ); this.capabilities = result.capabilities; await this.connection.sendNotification('initialized', {}); this.isInitialized = true; } catch (error) { await this.cleanup(); throw new Error( `Failed to start LSP server for ${this.config.language}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } async shutdown(): Promise<void> { if (!this.connection) { return; } this.isShuttingDown = true; try { if (this.canSendMessages()) { for (const uri of [...this.openDocuments]) { try { await this.closeDocument(uri); } catch { break; } } } if (this.canSendMessages()) { try { await this.connection.sendRequest('shutdown', null); } catch { this.markTransportClosed(); } } if (this.canSendMessages()) { try { await this.connection.sendNotification('exit', null); } catch { this.markTransportClosed(); } } } catch (error) { console.debug('Error during LSP shutdown:', error); } finally { await this.cleanup(); } } private async cleanup(): Promise<void> { if (this.connection) { try { this.connection.dispose(); } catch { // Connection may already be disposed or broken } this.connection = undefined; } if (this.process) { try { if (!this.process.killed) { this.process.kill(); } } catch { // Process may already be dead } this.process = undefined; } this.isShuttingDown = false; this.markTransportClosed(); this.openDocuments.clear(); this.documentVersions.clear(); } async openDocument(uri: string, text: string): Promise<void> { if (!this.canSendMessages()) { throw new Error('LSP client not initialized'); } if (this.openDocuments.has(uri)) { return; } const languageId = this.config.language; const version = 1; this.documentVersions.set(uri, version); this.openDocuments.add(uri); try { await this.connection!.sendNotification('textDocument/didOpen', { textDocument: { uri, languageId, version, text, }, }); } catch (error) { this.openDocuments.delete(uri); this.documentVersions.delete(uri); this.markTransportClosed(); throw error; } } async closeDocument(uri: string): Promise<void> { if (!this.canSendMessages()) { this.openDocuments.delete(uri); this.documentVersions.delete(uri); return; } if (!this.openDocuments.has(uri)) { return; } try { await this.connection!.sendNotification('textDocument/didClose', { textDocument: {uri}, }); } catch { this.markTransportClosed(); } finally { this.openDocuments.delete(uri); this.documentVersions.delete(uri); } } async gotoDefinition(uri: string, position: Position): Promise<Location[]> { if (!this.canSendMessages()) { return []; } if (this.config.language === 'csharp' && this.csharpSolutionLoadPromise) { await Promise.race([ this.csharpSolutionLoadPromise, new Promise<void>(resolve => setTimeout(resolve, 15000)), ]); } if (!this.capabilities?.definitionProvider) { return []; } const params: TextDocumentPositionParams = { textDocument: {uri}, position, }; try { const result = await this.connection!.sendRequest< Location | Location[] | null >('textDocument/definition', params); if (!result) { return []; } return Array.isArray(result) ? result : [result]; } catch (error) { this.markTransportClosed(); return []; } } async findReferences( uri: string, position: Position, includeDeclaration = false, ): Promise<Location[]> { if (!this.canSendMessages()) { return []; } if (!this.capabilities?.referencesProvider) { return []; } const params: ReferenceParams = { textDocument: {uri}, position, context: {includeDeclaration}, }; try { const result = await this.connection!.sendRequest<Location[] | null>( 'textDocument/references', params, ); return result || []; } catch (error) { this.markTransportClosed(); return []; } } async hover(uri: string, position: Position): Promise<Hover | null> { if (!this.canSendMessages()) { return null; } if (!this.capabilities?.hoverProvider) { return null; } const params: HoverParams = { textDocument: {uri}, position, }; try { const result = await this.connection!.sendRequest<Hover | null>( 'textDocument/hover', params, ); return result; } catch (error) { this.markTransportClosed(); return null; } } async completion(uri: string, position: Position): Promise<CompletionItem[]> { if (!this.canSendMessages()) { return []; } if (!this.capabilities?.completionProvider) { return []; } const params: CompletionParams = { textDocument: {uri}, position, }; try { const result = await this.connection!.sendRequest< CompletionItem[] | {items: CompletionItem[]} | null >('textDocument/completion', params); if (!result) { return []; } return Array.isArray(result) ? result : result.items || []; } catch (error) { this.markTransportClosed(); return []; } } async documentSymbol( uri: string, ): Promise<DocumentSymbol[] | SymbolInformation[]> { if (!this.canSendMessages()) { return []; } if (!this.capabilities?.documentSymbolProvider) { return []; } const params: DocumentSymbolParams = { textDocument: {uri}, }; try { const result = await this.connection!.sendRequest< DocumentSymbol[] | SymbolInformation[] | null >('textDocument/documentSymbol', params); return result || []; } catch (error) { this.markTransportClosed(); return []; } } private pathToUri(filePath: string): string { const normalizedPath = path.resolve(filePath).replace(/\\/g, '/'); return `file://${ normalizedPath.startsWith('/') ? '' : '/' }${normalizedPath}`; } getCapabilities(): ServerCapabilities | undefined { return this.capabilities; } isReady(): boolean { return this.isInitialized && this.isProcessAlive; } } ================================================ FILE: source/mcp/lsp/LSPManager.ts ================================================ import {promises as fs} from 'fs'; import * as path from 'path'; import type {Position, Location} from 'vscode-languageserver-protocol'; import {LSPClient} from './LSPClient.js'; import {LSPServerRegistry} from './LSPServerRegistry.js'; export class LSPManager { private clients: Map<string, LSPClient> = new Map(); private documentCache: Map<string, string> = new Map(); constructor(private basePath: string) {} async getClient(language: string): Promise<LSPClient | null> { if (this.clients.has(language)) { const client = this.clients.get(language)!; if (client.isReady()) { return client; } // Client is dead or not initialized, clean it up before recreating try { await client.shutdown(); } catch { // Ignore cleanup errors for dead clients } this.clients.delete(language); } const config = LSPServerRegistry.getConfig(language); if (!config) { return null; } const installed = await LSPServerRegistry.isServerInstalled(language); if (!installed) { return null; } try { const client = new LSPClient({ ...config, language, rootPath: this.basePath, }); await client.start(); this.clients.set(language, client); return client; } catch (error) { return null; } } async findDefinition( filePath: string, line: number, column: number, ): Promise<Location | null> { const serverInfo = LSPServerRegistry.getServerForFile(filePath); if (!serverInfo) { return null; } const client = await this.getClient(serverInfo.language); if (!client) { return null; } let uri: string | undefined; try { uri = this.pathToUri(filePath); const content = await this.getDocumentContent(filePath); if (!content) { return null; } await client.openDocument(uri, content); if (!client.isReady()) { return null; } const position: Position = {line, character: column}; const locations = await client.gotoDefinition(uri, position); return locations.length > 0 ? locations[0]! : null; } catch (error) { console.debug('LSP findDefinition error:', error); return null; } finally { if (uri) { try { await client.closeDocument(uri); } catch { // Suppress close errors — the server may already be dead } } } } async findReferences( filePath: string, line: number, column: number, maxResults = 100, ): Promise<Location[]> { const serverInfo = LSPServerRegistry.getServerForFile(filePath); if (!serverInfo) { return []; } const client = await this.getClient(serverInfo.language); if (!client) { return []; } let uri: string | undefined; try { uri = this.pathToUri(filePath); const content = await this.getDocumentContent(filePath); if (!content) { return []; } await client.openDocument(uri, content); if (!client.isReady()) { return []; } const position: Position = {line, character: column}; const locations = await client.findReferences(uri, position, false); return locations.slice(0, maxResults); } catch (error) { console.debug('LSP findReferences error:', error); return []; } finally { if (uri) { try { await client.closeDocument(uri); } catch { // Suppress close errors — the server may already be dead } } } } async getDocumentSymbols(filePath: string) { const serverInfo = LSPServerRegistry.getServerForFile(filePath); if (!serverInfo) { return null; } const client = await this.getClient(serverInfo.language); if (!client) { return null; } let uri: string | undefined; try { uri = this.pathToUri(filePath); const content = await this.getDocumentContent(filePath); if (!content) { return null; } await client.openDocument(uri, content); if (!client.isReady()) { return null; } const symbols = await client.documentSymbol(uri); return symbols; } catch (error) { console.debug('LSP documentSymbol error:', error); return null; } finally { if (uri) { try { await client.closeDocument(uri); } catch { // Suppress close errors — the server may already be dead } } } } async getHoverInfo(filePath: string, line: number, column: number) { const serverInfo = LSPServerRegistry.getServerForFile(filePath); if (!serverInfo) { return null; } const client = await this.getClient(serverInfo.language); if (!client) { return null; } let uri: string | undefined; try { uri = this.pathToUri(filePath); const content = await this.getDocumentContent(filePath); if (!content) { return null; } await client.openDocument(uri, content); if (!client.isReady()) { return null; } const position: Position = {line, character: column}; const hover = await client.hover(uri, position); return hover; } catch (error) { console.debug('LSP hover error:', error); return null; } finally { if (uri) { try { await client.closeDocument(uri); } catch { // Suppress close errors — the server may already be dead } } } } private async getDocumentContent(filePath: string): Promise<string | null> { const fullPath = path.resolve(this.basePath, filePath); if (this.documentCache.has(fullPath)) { return this.documentCache.get(fullPath)!; } try { const content = await fs.readFile(fullPath, 'utf-8'); this.documentCache.set(fullPath, content); return content; } catch (error) { return null; } } private pathToUri(filePath: string): string { const normalizedPath = path.resolve(this.basePath, filePath); const finalPath = normalizedPath.replace(/\\/g, '/'); return `file://${finalPath.startsWith('/') ? '' : '/'}${finalPath}`; } async dispose(): Promise<void> { for (const client of this.clients.values()) { await client.shutdown(); } this.clients.clear(); this.documentCache.clear(); } clearDocumentCache(): void { this.documentCache.clear(); } } ================================================ FILE: source/mcp/lsp/LSPServerRegistry.ts ================================================ import {exec} from 'child_process'; import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'fs'; import {homedir} from 'os'; import {join} from 'path'; import {promisify} from 'util'; const execAsync = promisify(exec); export interface LSPServerConfig { command: string; args: string[]; fileExtensions: string[]; installCommand?: string; initializationOptions?: any; } export interface LSPConfigFile { schemaVersion: 1; servers: Record<string, LSPServerConfig>; } const CONFIG_DIR = join(homedir(), '.snow'); const LSP_CONFIG_FILE = join(CONFIG_DIR, 'lsp-config.json'); export const DEFAULT_LSP_SERVERS: Record<string, LSPServerConfig> = { typescript: { command: 'typescript-language-server', args: ['--stdio'], fileExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'], installCommand: 'npm install -g typescript-language-server typescript', initializationOptions: {}, }, python: { command: 'pylsp', args: [], fileExtensions: ['.py'], installCommand: 'pip install python-lsp-server', initializationOptions: {}, }, go: { command: 'gopls', args: [], fileExtensions: ['.go'], installCommand: 'go install golang.org/x/tools/gopls@latest', initializationOptions: {}, }, rust: { command: 'rust-analyzer', args: [], fileExtensions: ['.rs'], installCommand: 'rustup component add rust-analyzer', initializationOptions: {}, }, java: { command: 'jdtls', args: [], fileExtensions: ['.java'], installCommand: 'brew install jdtls', initializationOptions: {}, }, csharp: { command: 'csharp-ls', args: [], fileExtensions: ['.cs'], installCommand: 'dotnet tool install --global csharp-ls', initializationOptions: {}, }, }; export const LSP_SERVERS = DEFAULT_LSP_SERVERS; function ensureConfigDirectory(): void { if (!existsSync(CONFIG_DIR)) { mkdirSync(CONFIG_DIR, {recursive: true}); } } function isRecord(value: unknown): value is Record<string, unknown> { return Boolean(value) && typeof value === 'object' && !Array.isArray(value); } function toStringArray(value: unknown): string[] | undefined { if (!Array.isArray(value)) { return undefined; } return value.filter((item): item is string => typeof item === 'string'); } function parseServerConfig(value: unknown): LSPServerConfig | null { if (!isRecord(value)) { return null; } const commandValue = value['command']; const installCommandValue = value['installCommand']; const argsValue = value['args']; const fileExtensionsValue = value['fileExtensions']; const initializationOptionsValue = value['initializationOptions']; const command = typeof commandValue === 'string' ? commandValue : undefined; const installCommand = typeof installCommandValue === 'string' ? installCommandValue : undefined; const args = toStringArray(argsValue); const fileExtensions = toStringArray(fileExtensionsValue); if (!command || !args || !fileExtensions) { return null; } const serverConfig: LSPServerConfig = { command, args, fileExtensions, }; if (installCommand) { serverConfig.installCommand = installCommand; } if ('initializationOptions' in value) { serverConfig.initializationOptions = initializationOptionsValue; } return serverConfig; } function parseServersConfig( value: unknown, ): Record<string, LSPServerConfig> | null { if (!isRecord(value)) { return null; } const servers: Record<string, LSPServerConfig> = {}; for (const [language, serverValue] of Object.entries(value)) { const serverConfig = parseServerConfig(serverValue); if (!serverConfig) { return null; } servers[language] = serverConfig; } return Object.keys(servers).length > 0 ? servers : null; } function parseLspConfigFile( value: unknown, ): Record<string, LSPServerConfig> | null { if (!isRecord(value)) { return null; } if (value['schemaVersion'] !== 1) { return parseServersConfig(value); } const serversValue = value['servers']; return parseServersConfig(serversValue); } function getDefaultConfigFile(): LSPConfigFile { return { schemaVersion: 1, servers: DEFAULT_LSP_SERVERS, }; } function loadServersFromDisk(): Record<string, LSPServerConfig> { ensureConfigDirectory(); if (!existsSync(LSP_CONFIG_FILE)) { try { writeFileSync( LSP_CONFIG_FILE, JSON.stringify(getDefaultConfigFile(), null, 2), 'utf8', ); } catch (error) { console.debug('Failed to write default lsp-config.json:', error); } return DEFAULT_LSP_SERVERS; } try { const configText = readFileSync(LSP_CONFIG_FILE, 'utf8'); const parsed: unknown = JSON.parse(configText); const serversFromConfig = parseLspConfigFile(parsed); return serversFromConfig ?? DEFAULT_LSP_SERVERS; } catch (error) { console.debug('Failed to read lsp-config.json, using defaults:', error); return DEFAULT_LSP_SERVERS; } } export class LSPServerRegistry { private static installedServers: Map<string, boolean> = new Map(); private static serversCache: Record<string, LSPServerConfig> | undefined; private static getServers(): Record<string, LSPServerConfig> { if (!this.serversCache) { this.serversCache = loadServersFromDisk(); } return this.serversCache; } static getServerForFile(filePath: string): { language: string; config: LSPServerConfig; } | null { const ext = filePath.slice(filePath.lastIndexOf('.')); for (const [language, config] of Object.entries(this.getServers())) { if (config.fileExtensions.includes(ext)) { return {language, config}; } } return null; } static getConfig(language: string): LSPServerConfig | null { return this.getServers()[language] || null; } static getInstallCommand(language: string): string | null { return this.getServers()[language]?.installCommand || null; } static async isServerInstalled(language: string): Promise<boolean> { if (this.installedServers.has(language)) { return this.installedServers.get(language)!; } const config = this.getConfig(language); if (!config) { return false; } try { const {command} = config; // 使用 where.exe 而不是 where，避免与 PowerShell 的 Where-Object 别名冲突 const testCommand = process.platform === 'win32' ? `where.exe ${command}` : `which ${command}`; await execAsync(testCommand); this.installedServers.set(language, true); return true; } catch { this.installedServers.set(language, false); return false; } } static clearCache(): void { this.installedServers.clear(); this.serversCache = undefined; } } ================================================ FILE: source/mcp/notebook.ts ================================================ import {Tool, type CallToolResult} from '@modelcontextprotocol/sdk/types.js'; import { addNotebook, addNotebooks, queryNotebook, updateNotebook, deleteNotebook, deleteNotebooks, getNotebooksByFile, findNotebookById, recordNotebookAddition, recordNotebookUpdate, recordNotebookDeletion, } from '../utils/core/notebookManager.js'; import {getConversationContext} from '../utils/codebase/conversationContext.js'; /** * Notebook MCP 工具定义 * 单一批量管理工具，参考 todo-manage 模式 */ export const mcpTools: Tool[] = [ { name: 'notebook-manage', description: `Unified notebook management tool. Use required field "action" — one of query | list | add | update | delete. PARALLEL CALLS ONLY: MUST pair with other tools (notebook-manage + filesystem-read/terminal-execute/etc). NEVER call notebook-manage alone — always combine with an action tool in the same turn. ACTIONS: - query: Search entries by fuzzy file path pattern. Optional "filePathPattern" and "topN". - list: List all entries for one exact file path. Required "filePath". - add: Record note(s) for a file. Required "filePath" and "note" (string or string[]). Batch adds share the same filePath. - update: Update note by ID. Required "notebookId" and "note". - delete: Remove note(s) by ID. Required "notebookId" (string or string[]). BEST PRACTICES: - After fixing non-trivial bugs, record what caused it and why the fix works. - When discovering fragile dependencies or hidden coupling, record immediately. - When an existing note is outdated or incorrect, update/delete it immediately — do NOT leave stale notes. - Use query before modifying code to recall relevant notes. EXAMPLES: - notebook-manage({action:"query", filePathPattern:"auth"}) + filesystem-read(...) - notebook-manage({action:"add", filePath:"src/auth.ts", note:["validateInput() MUST be called first","Session token is nullable"]}) + filesystem-edit(...) - notebook-manage({action:"delete", notebookId:["id1","id2"]}) + filesystem-edit(...)`, inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['query', 'list', 'add', 'update', 'delete'], description: 'Which operation to run on the notebook.', }, filePath: { type: 'string', description: 'For action=add/list: file path (relative or absolute).', }, filePathPattern: { type: 'string', description: 'For action=query: fuzzy file path search pattern; empty means all.', default: '', }, topN: { type: 'number', description: 'For action=query: max results (default: 10, max: 50).', default: 10, minimum: 1, maximum: 50, }, notebookId: { oneOf: [ { type: 'string', description: 'Single notebook entry ID', }, { type: 'array', items: {type: 'string'}, description: 'Multiple IDs (same delete applies to all)', }, ], description: 'For action=update or delete: entry id(s) from action=query/list.', }, note: { oneOf: [ { type: 'string', description: 'For action=add: one note. For action=update: new note content.', }, { type: 'array', items: {type: 'string'}, description: 'For action=add only: batch add multiple notes for the same file.', }, ], description: 'For add: required (string or string[]). For update: required string.', }, }, required: ['action'], }, }, ]; /** * 执行 Notebook 工具 */ export async function executeNotebookTool( toolName: string, args: any, ): Promise<CallToolResult> { try { // Backward compatibility: old names map to action const legacyActionMap: Record<string, string> = { 'notebook-add': 'add', 'notebook-query': 'query', 'notebook-update': 'update', 'notebook-delete': 'delete', 'notebook-list': 'list', }; const action = (typeof args?.action === 'string' && args.action) || legacyActionMap[toolName] || (toolName === 'manage' || toolName === 'notebook-manage' ? '' : undefined); if (!action || !['query', 'list', 'add', 'update', 'delete'].includes(action)) { return { content: [ { type: 'text', text: 'Error: "action" must be one of: query, list, add, update, delete', }, ], isError: true, }; } switch (action) { case 'add': { const {filePath, note} = args; if (!filePath || note === undefined || note === null) { return { content: [ { type: 'text', text: 'Error: action=add requires both "filePath" and "note"', }, ], isError: true, }; } // 智能解析 note：处理 JSON 字符串形式的数组 let parsedNote: string | string[] = note; if (typeof note === 'string') { try { const parsed = JSON.parse(note); if (Array.isArray(parsed)) { parsedNote = parsed; } } catch { // 保持原字符串 } } if (Array.isArray(parsedNote)) { const entries = addNotebooks(filePath, parsedNote); try { const context = getConversationContext(); if (context) { for (const entry of entries) { recordNotebookAddition( context.sessionId, context.messageIndex, entry.id, ); } } } catch { // 不影响主流程 } return { content: [ { type: 'text', text: JSON.stringify( { success: true, message: `${entries.length} notebook entries added for: ${entries[0]?.filePath ?? filePath}`, entries: entries.map(e => ({ id: e.id, filePath: e.filePath, note: e.note, createdAt: e.createdAt, })), }, null, 2, ), }, ], }; } const entry = addNotebook(filePath, parsedNote); try { const context = getConversationContext(); if (context) { recordNotebookAddition( context.sessionId, context.messageIndex, entry.id, ); } } catch { // 不影响主流程 } return { content: [ { type: 'text', text: JSON.stringify( { success: true, message: `Notebook entry added for: ${entry.filePath}`, entry: { id: entry.id, filePath: entry.filePath, note: entry.note, createdAt: entry.createdAt, }, }, null, 2, ), }, ], }; } case 'query': { const {filePathPattern = '', topN = 10} = args; const results = queryNotebook(filePathPattern, topN); if (results.length === 0) { return { content: [ { type: 'text', text: JSON.stringify( { message: 'No notebook entries found', pattern: filePathPattern || '(all)', totalResults: 0, }, null, 2, ), }, ], }; } return { content: [ { type: 'text', text: JSON.stringify( { message: `Found ${results.length} notebook entries`, pattern: filePathPattern || '(all)', totalResults: results.length, entries: results.map(entry => ({ id: entry.id, filePath: entry.filePath, note: entry.note, createdAt: entry.createdAt, })), }, null, 2, ), }, ], }; } case 'update': { const {notebookId, note} = args; if (!notebookId || !note || typeof note !== 'string') { return { content: [ { type: 'text', text: 'Error: action=update requires "notebookId" (string) and "note" (string)', }, ], isError: true, }; } const previousEntry = findNotebookById(notebookId); const previousNote = previousEntry?.note; const updatedEntry = updateNotebook(notebookId, note); if (!updatedEntry) { return { content: [ { type: 'text', text: JSON.stringify( { success: false, message: `Notebook entry not found: ${notebookId}`, }, null, 2, ), }, ], isError: true, }; } try { const context = getConversationContext(); if (context && previousNote !== undefined) { recordNotebookUpdate( context.sessionId, context.messageIndex, notebookId, previousNote, ); } } catch { // 不影响主流程 } return { content: [ { type: 'text', text: JSON.stringify( { success: true, message: `Notebook entry updated: ${notebookId}`, entry: { id: updatedEntry.id, filePath: updatedEntry.filePath, note: updatedEntry.note, updatedAt: updatedEntry.updatedAt, }, }, null, 2, ), }, ], }; } case 'delete': { const {notebookId} = args; if (notebookId === undefined || notebookId === null) { return { content: [ { type: 'text', text: 'Error: action=delete requires "notebookId"', }, ], isError: true, }; } const ids = Array.isArray(notebookId) ? notebookId : [notebookId]; // 批量删除前先获取完整条目用于回滚 const entriesToDelete = ids .map(id => findNotebookById(id)) .filter((e): e is NonNullable<typeof e> => e !== null); const result = ids.length === 1 ? (() => { const deleted = deleteNotebook(ids[0]!); return { deleted: deleted ? [ids[0]!] : [], notFound: deleted ? [] : [ids[0]!], }; })() : deleteNotebooks(ids); // 记录删除到快照追踪 try { const context = getConversationContext(); if (context) { for (const entry of entriesToDelete) { if (result.deleted.includes(entry.id)) { recordNotebookDeletion( context.sessionId, context.messageIndex, entry, ); } } } } catch { // 不影响主流程 } if (result.deleted.length === 0) { return { content: [ { type: 'text', text: JSON.stringify( { success: false, message: `Notebook entries not found: ${result.notFound.join(', ')}`, }, null, 2, ), }, ], isError: true, }; } return { content: [ { type: 'text', text: JSON.stringify( { success: true, message: `${result.deleted.length} notebook entries deleted`, deleted: result.deleted, ...(result.notFound.length > 0 ? {notFound: result.notFound} : {}), }, null, 2, ), }, ], }; } case 'list': { const {filePath} = args; if (!filePath) { return { content: [ { type: 'text', text: 'Error: action=list requires "filePath"', }, ], isError: true, }; } const entries = getNotebooksByFile(filePath); return { content: [ { type: 'text', text: JSON.stringify( { message: entries.length > 0 ? `Found ${entries.length} notebook entries for: ${filePath}` : `No notebook entries found for: ${filePath}`, filePath, totalEntries: entries.length, entries: entries.map(entry => ({ id: entry.id, note: entry.note, createdAt: entry.createdAt, updatedAt: entry.updatedAt, })), }, null, 2, ), }, ], }; } default: return { content: [ { type: 'text', text: `Unknown notebook action: ${String(action)}`, }, ], isError: true, }; } } catch (error) { return { content: [ { type: 'text', text: `Error executing notebook-manage: ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } } ================================================ FILE: source/mcp/scheduler.ts ================================================ import type {MCPTool} from '../utils/execution/mcpToolsManager.js'; export interface SchedulerTaskArgs { /** * 等待时长（秒），范围 1-3600 */ duration: number; /** * 任务描述文本 */ description: string; } export interface SchedulerTaskResult { /** * 任务是否成功完成 */ success: boolean; /** * 任务描述 */ description: string; /** * 实际等待时长（秒） */ actualDuration: number; /** * 任务完成时间 */ completedAt: string; } export const mcpTools: MCPTool[] = [ { type: 'function', function: { name: 'scheduler-schedule_task', description: "Schedule a task to be executed after a specified duration. When called, this tool blocks the AI workflow, displays a countdown interface, and returns the task information upon completion. Useful for delayed execution scenarios like reminders or scheduled processing. IMPORTANT: This tool only accepts duration in seconds. If the user specifies a specific time (e.g., '3 PM', '15:30') instead of a duration, you MUST first use terminal-execute tool to run 'date +%s' (Unix) or 'powershell -Command [DateTimeOffset]::Now.ToUnixTimeSeconds()' (Windows) to get the current timestamp, then calculate the seconds until the target time, and use that calculated duration with this tool.", parameters: { type: 'object', properties: { duration: { type: 'number', description: 'Wait duration in seconds. Minimum 1 second, maximum 3600 seconds (1 hour). If user specifies a specific time (e.g., "3 PM", "15:30"), use terminal-execute to get current timestamp first, then calculate seconds from now to the target time.', minimum: 1, maximum: 3600, }, description: { type: 'string', description: "Task description explaining the purpose of this scheduled task. Will be displayed in the countdown interface and task result. Example: 'Remind me to check emails at 3 PM'.", }, }, required: ['duration', 'description'], }, }, }, ]; ================================================ FILE: source/mcp/skills.ts ================================================ import {dirname, join, relative} from 'path'; import {existsSync} from 'fs'; import {readFile} from 'fs/promises'; import {homedir} from 'os'; import matter from 'gray-matter'; import {getDisabledSkills} from '../utils/config/disabledSkills.js'; export interface SkillMetadata { name: string; description: string; allowedTools?: string[]; } export interface Skill { id: string; name: string; description: string; location: 'project' | 'global'; path: string; content: string; allowedTools?: string[]; } /** * Read and parse SKILL.md file */ async function readSkillFile(skillPath: string): Promise<{ metadata: SkillMetadata; content: string; } | null> { try { const skillFile = join(skillPath, 'SKILL.md'); if (!existsSync(skillFile)) { return null; } const fileContent = await readFile(skillFile, 'utf-8'); const parsed = matter(fileContent); // Remove leading description section between --- markers if exists let content = parsed.content.trim(); const descriptionPattern = /^---\s*[\s\S]*?---\s*/; if (descriptionPattern.test(content)) { content = content.replace(descriptionPattern, '').trim(); } // Parse allowed-tools field (comma-separated list or array) let allowedTools: string[] | undefined; const allowedToolsData = parsed.data['allowed-tools']; if (allowedToolsData) { if (Array.isArray(allowedToolsData)) { allowedTools = allowedToolsData.filter( tool => typeof tool === 'string' && tool.trim().length > 0, ); } else if ( typeof allowedToolsData === 'string' && allowedToolsData.trim() ) { allowedTools = allowedToolsData .split(',') .map(tool => tool.trim()) .filter(tool => tool.length > 0); } } // Defensive coercion: gray-matter may parse unquoted placeholders like // `{{NAME}}` as YAML flow mappings (objects), which would crash React // when later rendered as text. Force string types here. const rawName = parsed.data['name']; const rawDescription = parsed.data['description']; const safeName = typeof rawName === 'string' ? rawName : ''; const safeDescription = typeof rawDescription === 'string' ? rawDescription : ''; return { metadata: { name: safeName, description: safeDescription, allowedTools, }, content, }; } catch (error) { console.error(`Failed to read skill at ${skillPath}:`, error); return null; } } function normalizeSkillId(skillId: string): string { return skillId.replace(/\\/g, '/').replace(/^\.\/+/, ''); } async function loadSkillsFromDirectory( skills: Map<string, Skill>, baseSkillsDir: string, location: Skill['location'], ): Promise<void> { if (!existsSync(baseSkillsDir)) { return; } try { const {readdirSync} = await import('fs'); const pendingDirs: string[] = [baseSkillsDir]; while (pendingDirs.length > 0) { const currentDir = pendingDirs.pop(); if (!currentDir) continue; let entries: Array<import('fs').Dirent>; try { entries = readdirSync(currentDir, {withFileTypes: true}); } catch { continue; } for (const entry of entries) { if (entry.isDirectory()) { // Skip template/example directories that ship inside skills // (e.g. skill-based-architecture-main/templates/**) — their // SKILL.md files contain placeholders like `{{NAME}}` and // must not be treated as real skills. if ( entry.name === 'templates' || entry.name === 'examples' || entry.name === 'node_modules' || entry.name.startsWith('.') ) { continue; } pendingDirs.push(join(currentDir, entry.name)); continue; } if (!entry.isFile() || entry.name !== 'SKILL.md') { continue; } const skillFile = join(currentDir, entry.name); const skillDir = dirname(skillFile); const rawSkillId = relative(baseSkillsDir, skillDir); const skillId = normalizeSkillId(rawSkillId); if (!skillId || skillId === '.') { continue; } const skillData = await readSkillFile(skillDir); if (!skillData) { continue; } const fallbackName = skillId.split('/').filter(Boolean).pop() || skillId; skills.set(skillId, { id: skillId, name: skillData.metadata.name || fallbackName, description: skillData.metadata.description || '', location, path: skillDir, content: skillData.content, allowedTools: skillData.metadata.allowedTools, }); } } } catch (error) { console.error(`Failed to load ${location} skills:`, error); } } /** * Scan and load all available skills * Project skills have priority over global skills */ async function loadAvailableSkills( projectRoot?: string, ): Promise<Map<string, Skill>> { const skills = new Map<string, Skill>(); const globalSkillsDir = join(homedir(), '.snow', 'skills'); const projectSkillsDir = projectRoot ? join(projectRoot, '.snow', 'skills') : null; // Load global skills first, then project skills override global skills await loadSkillsFromDirectory(skills, globalSkillsDir, 'global'); if (projectSkillsDir) { await loadSkillsFromDirectory(skills, projectSkillsDir, 'project'); } return skills; } /** * Generate dynamic skill tool description */ function generateSkillToolDescription(skills: Map<string, Skill>): string { const skillsList = Array.from(skills.values()) .map( skill => `<skill> <name> ${skill.id} </name> <description> ${skill.description} </description> <location> ${skill.location} </location> </skill>`, ) .join('\n'); return `Execute a skill within the main conversation <skills_instructions> When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge. How to use skills: - Invoke skills using this tool with the skill id only (no arguments) - When you invoke a skill, you will see <command-message>The "{name}" skill is loading</command-message> - The skill's prompt will expand and provide detailed instructions on how to complete the task - Examples: - skill: "pdf" - invoke the pdf skill - skill: "data-analysis" - invoke the data-analysis skill Important: - Only use skills listed in <available_skills> below - Do not invoke a skill that is already running - Do not use this tool for built-in CLI commands (like /help, /clear, etc.) </skills_instructions> <available_skills> ${skillsList} </available_skills>`; } /** * Get MCP tools for skills (dynamic generation based on available skills) */ export async function listAvailableSkills( projectRoot?: string, ): Promise<Skill[]> { const skills = await loadAvailableSkills(projectRoot); // Stable sort by id for deterministic UI. return Array.from(skills.values()).sort((a, b) => a.id.localeCompare(b.id)); } export async function getMCPTools(projectRoot?: string) { const skills = await loadAvailableSkills(projectRoot); // Filter out disabled skills const disabledSkills = getDisabledSkills(); for (const skillId of disabledSkills) { skills.delete(skillId); } // If no skills available, return empty array if (skills.size === 0) { return []; } const description = generateSkillToolDescription(skills); return [ { name: 'skill-execute', description, inputSchema: { type: 'object', properties: { skill: { type: 'string', description: 'The skill id (no arguments). E.g., "pdf", "data-analysis", or "helloagents/analyze"', }, }, required: ['skill'], additionalProperties: false, $schema: 'http://json-schema.org/draft-07/schema#', }, }, ]; } /** * Generate directory tree structure for skill */ async function generateSkillTree(skillPath: string): Promise<string> { try { const {readdirSync} = await import('fs'); const entries = readdirSync(skillPath, {withFileTypes: true}); const lines: string[] = []; const sortedEntries = entries.sort((a, b) => { // Directories first, then files if (a.isDirectory() && !b.isDirectory()) return -1; if (!a.isDirectory() && b.isDirectory()) return 1; return a.name.localeCompare(b.name); }); for (let i = 0; i < sortedEntries.length; i++) { const entry = sortedEntries[i]; if (!entry) continue; const isLast = i === sortedEntries.length - 1; const prefix = isLast ? '└─' : '├─'; const connector = isLast ? ' ' : '│ '; if (entry.isDirectory()) { lines.push(`${prefix} ${entry.name}/`); // Recursively list directory contents (one level deep only) try { const subPath = join(skillPath, entry.name); const subEntries = readdirSync(subPath, {withFileTypes: true}); const sortedSubEntries = subEntries.sort((a, b) => a.name.localeCompare(b.name), ); for (let j = 0; j < sortedSubEntries.length; j++) { const subEntry = sortedSubEntries[j]; if (!subEntry) continue; const subIsLast = j === sortedSubEntries.length - 1; const subPrefix = subIsLast ? '└─' : '├─'; const fileType = subEntry.isDirectory() ? '[DIR]' : '[FILE]'; lines.push( `${connector} ${subPrefix} ${fileType} ${subEntry.name}`, ); } } catch { // Ignore subdirectory read errors } } else { const fileType = entry.name === 'SKILL.md' ? '[MAIN]' : '[FILE]'; lines.push(`${prefix} ${fileType} ${entry.name}`); } } return lines.join('\n'); } catch (error) { return '(Unable to generate directory tree)'; } } /** * Execute skill tool */ export async function executeSkillTool( toolName: string, args: any, projectRoot?: string, ): Promise<string> { if (toolName !== 'skill-execute') { throw new Error(`Unknown tool: ${toolName}`); } const requestedSkillId = args.skill; if (!requestedSkillId || typeof requestedSkillId !== 'string') { throw new Error('skill parameter is required and must be a string'); } const skillId = normalizeSkillId(requestedSkillId); // Check if skill is disabled const disabledSkills = getDisabledSkills(); if (disabledSkills.includes(skillId)) { throw new Error(`Skill "${skillId}" is currently disabled`); } // Load available skills const skills = await loadAvailableSkills(projectRoot); const skill = skills.get(skillId); if (!skill) { const availableSkills = Array.from(skills.keys()).join(', '); throw new Error( `Skill \"${skillId}\" not found. Available skills: ${ availableSkills || 'none' }`, ); } // Generate directory tree for skill const directoryTree = await generateSkillTree(skill.path); // Generate allowed tools restriction if specified let toolRestriction = ''; if (skill.allowedTools && skill.allowedTools.length > 0) { toolRestriction = ` <tool-restrictions> CRITICAL: This skill ONLY allows the following tools: ${skill.allowedTools.map(tool => `- ${tool}`).join('\n')} You MUST NOT use any other tools. Any tool not listed above is forbidden for this skill. </tool-restrictions>`; } // Return the skill content (markdown instructions) return `<command-message>The "${skill.name}" skill is loading</command-message> ${skill.content}${toolRestriction} <skill-info> Skill Name: ${skill.name} Absolute Path: ${skill.path} Directory Structure: \`\`\` ${skill.name}/ ${directoryTree} \`\`\` Note: You can use filesystem-read tool to read any file in this skill directory using the absolute path above. </skill-info>`; } export const mcpTools = []; ================================================ FILE: source/mcp/subagent.ts ================================================ import {executeSubAgent} from '../utils/execution/subAgentExecutor.js'; import {getUserSubAgents} from '../utils/config/subAgentConfig.js'; import type {SubAgentMessage} from '../utils/execution/subAgentExecutor.js'; import type {ToolCall} from '../utils/execution/toolExecutor.js'; import type {ConfirmationResult} from '../ui/components/tools/ToolConfirmation.js'; export interface SubAgentToolExecutionOptions { agentId: string; prompt: string; /** Unique execution instance ID for message injection from the main flow */ instanceId?: string; onMessage?: (message: SubAgentMessage) => void; abortSignal?: AbortSignal; requestToolConfirmation?: ( toolCall: ToolCall, batchToolNames?: string, allTools?: ToolCall[], ) => Promise<ConfirmationResult>; isToolAutoApproved?: (toolName: string) => boolean; yoloMode?: boolean; addToAlwaysApproved?: (toolName: string) => void; requestUserQuestion?: ( question: string, options: string[], multiSelect?: boolean, ) => Promise<{selected: string | string[]; customInput?: string}>; } /** * Sub-Agent MCP Service * Provides tools for executing sub-agents with their own specialized system prompts and tool access */ export class SubAgentService { /** * Execute a sub-agent as a tool */ async execute(options: SubAgentToolExecutionOptions): Promise<any> { const { agentId, prompt, instanceId, onMessage, abortSignal, requestToolConfirmation, isToolAutoApproved, yoloMode, addToAlwaysApproved, requestUserQuestion, } = options; // Create a tool confirmation adapter for sub-agent if needed const subAgentToolConfirmation = requestToolConfirmation ? async (toolName: string, toolArgs: any) => { // Create a fake tool call for confirmation const fakeToolCall: ToolCall = { id: 'subagent-tool', type: 'function', function: { name: toolName, arguments: JSON.stringify(toolArgs), }, }; return await requestToolConfirmation(fakeToolCall); } : undefined; const result = await executeSubAgent( agentId, prompt, onMessage, abortSignal, subAgentToolConfirmation, isToolAutoApproved, yoloMode, addToAlwaysApproved, requestUserQuestion, instanceId, ); if (!result.success) { throw new Error(result.error || 'Sub-agent execution failed'); } return { success: true, result: result.result, usage: result.usage, injectedUserMessages: result.injectedUserMessages, terminationInstructions: result.terminationInstructions, }; } /** * Get all available sub-agents as MCP tools */ getTools(): Array<{ name: string; description: string; inputSchema: any; }> { // Get user-configured agents (built-in agents are hardcoded below) const userAgents = getUserSubAgents(); // Built-in agents (hardcoded, always available) const tools = [ { name: 'agent_explore', description: 'Explore Agent: Specialized for quickly exploring and understanding codebases. Excels at searching code, finding definitions, analyzing code structure and dependencies. Read-only operations, will not modify files or execute commands.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'CRITICAL: Provide COMPLETE context from main session. Sub-agent has NO access to main conversation history. Include: (1) Full task description with business requirements, (2) Known file locations and code paths, (3) Relevant code snippets or patterns already discovered, (4) Any constraints or important context. Example: "Explore authentication implementation. Main flow uses OAuth in src/auth/oauth.ts, need to find all related error handling. User mentioned JWT tokens are validated in middleware."', }, }, required: ['prompt'], }, }, { name: 'agent_plan', description: 'Plan Agent: Specialized for planning complex tasks. Analyzes requirements, explores code, identifies relevant files, and creates detailed implementation plans. Read-only operations, outputs structured implementation proposals.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'CRITICAL: Provide COMPLETE context from main session. Sub-agent has NO access to main conversation history. Include: (1) Full requirement details and business objectives, (2) Current architecture/file structure understanding, (3) Known dependencies and constraints, (4) Files/modules already identified that need changes, (5) User preferences or specific implementation approaches mentioned. Example: "Plan caching implementation. Current API uses Express in src/server.ts, data layer in src/models/. Need Redis caching, user wants minimal changes to existing controllers in src/controllers/."', }, }, required: ['prompt'], }, }, { name: 'agent_general', description: 'General Purpose Agent: General-purpose multi-step task execution agent. Has full tool access for searching, modifying files, and executing commands. Best for complex tasks requiring actual operations.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'CRITICAL: Provide COMPLETE context from main session. Sub-agent has NO access to main conversation history. Include: (1) Full task description with step-by-step requirements, (2) Exact file paths and locations to modify, (3) Code patterns/snippets to follow or replicate, (4) Dependencies between files/changes, (5) Testing/verification requirements, (6) Any business logic or constraints discovered in main session. Example: "Update error handling across API. Files: src/api/users.ts, src/api/posts.ts, src/api/comments.ts. Replace old pattern try-catch with new ErrorHandler class from src/utils/errorHandler.ts. Must preserve existing error codes. Run npm test after changes."', }, }, required: ['prompt'], }, }, { name: 'agent_analyze', description: 'Requirement Analysis Agent: Specialized for analyzing user requirements. Outputs comprehensive requirement specifications to guide the main workflow. Must confirm analysis with user before completing.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'CRITICAL: Provide COMPLETE context from main session. Sub-agent has NO access to main conversation history. Include: (1) Full user request or requirement description, (2) Any background or existing context about the project, (3) Known constraints, preferences, or non-functional requirements, (4) Relevant code or architecture information. The agent will analyze requirements and confirm with the user before completing.', }, }, required: ['prompt'], }, }, { name: 'agent_qa', description: 'QA Agent: Quality assurance specialist that reviews code changes, identifies bugs, checks edge cases, validates security, and runs tests. Provides structured QA reports with severity-categorized findings and suggested fixes.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'CRITICAL: Provide COMPLETE context from main session. Sub-agent has NO access to main conversation history. Include: (1) What code was changed or implemented, (2) Exact file paths of modified files, (3) Requirements and acceptance criteria, (4) Any specific areas of concern, (5) Known constraints or edge cases. Example: "Review the new authentication middleware in src/middleware/auth.ts. It should validate JWT tokens, handle expired tokens gracefully, and block unauthenticated requests. Also check src/routes/api.ts where it is applied."', }, }, required: ['prompt'], }, }, { name: 'agent_debug', description: 'Debug Assistant: Specialized for inserting structured file-based logging into project code. Writes all logs to .snow/log/ directory as .txt files with structured format. If the project lacks a logger helper, it will write one first. Reports log file locations upon completion.', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'CRITICAL: Provide COMPLETE context from main session. Sub-agent has NO access to main conversation history. Include: (1) Which code/functions/modules need debug logging, (2) What specific behavior or bug you are trying to trace, (3) Known file paths and code locations, (4) Project type and language. The agent will insert structured logging that writes to .snow/log/*.txt files and report the log storage location.', }, }, required: ['prompt'], }, }, ]; // Built-in agent IDs (used to filter out duplicates) const builtInAgentIds = new Set([ 'agent_explore', 'agent_plan', 'agent_general', 'agent_analyze', 'agent_qa', 'agent_debug', ]); // Add user-configured agents (filter out duplicates with built-in) tools.push( ...userAgents .filter(agent => !builtInAgentIds.has(agent.id)) .map(agent => ({ name: agent.id, description: `${agent.name}: ${agent.description}`, inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'CRITICAL: Provide COMPLETE context from main session. Sub-agent has NO access to main conversation history. Include all relevant: (1) Task requirements and objectives, (2) Known file locations and code structure, (3) Business logic and constraints, (4) Code patterns or examples, (5) Dependencies and relationships. Be specific and comprehensive - sub-agent cannot ask for clarification from main session.', }, }, required: ['prompt'], }, })), ); return tools; } } // Export a default instance export const subAgentService = new SubAgentService(); // MCP Tool definitions (dynamically generated from configuration) // Note: These are generated at runtime, so we export a function instead of a constant export function getMCPTools(): Array<{ name: string; description: string; inputSchema: any; }> { return subAgentService.getTools(); } ================================================ FILE: source/mcp/team.ts ================================================ /** * Team Service * Provides team management tools for the lead agent in Agent Team mode. * Tools are registered as MCP-style tools with "team-" prefix. */ import { createTeam, getTeam, addMember, disbandTeam, } from '../utils/team/teamConfig.js'; import { createTask, assignTask, updateTaskStatus, listTasks, } from '../utils/team/teamTaskList.js'; import { createTeamWorktree, cleanupTeamWorktrees, isGitRepo, autoCommitWorktreeChanges, mergeTeammateBranch, getTeammateDiffSummary, isInMergeState, getConflictedFiles, completeMerge, abortCurrentMerge, type MergeStrategy, } from '../utils/team/teamWorktree.js'; import {existsSync, readFileSync, writeFileSync} from 'fs'; import {teamTracker} from '../utils/execution/teamTracker.js'; import type {RequestMethod} from '../utils/config/apiConfig.js'; import {executeTeammate} from '../utils/execution/teamExecutor.js'; import type {SubAgentMessage} from '../utils/execution/subAgentExecutor.js'; import type {ConfirmationResult} from '../ui/components/tools/ToolConfirmation.js'; import {getConversationContext} from '../utils/codebase/conversationContext.js'; import {recordTeamCreated, recordMemberSpawned, deleteTeamSnapshotsByTeamName} from '../utils/team/teamSnapshot.js'; import {clearAllTeammateStreamEntries} from '../hooks/conversation/core/subAgentMessageHandler.js'; export interface TeamToolExecutionOptions { toolName: string; args: Record<string, any>; onMessage?: (message: SubAgentMessage) => void; abortSignal?: AbortSignal; requestToolConfirmation?: ( toolName: string, toolArgs: any, ) => Promise<ConfirmationResult>; isToolAutoApproved?: (toolName: string) => boolean; yoloMode?: boolean; addToAlwaysApproved?: (toolName: string) => void; requestUserQuestion?: ( question: string, options: string[], multiSelect?: boolean, ) => Promise<{selected: string | string[]; customInput?: string}>; } export class TeamService { private getOwnTeam(): import('../utils/team/teamConfig.js').TeamConfig | null { const teamName = teamTracker.getActiveTeamName(); if (!teamName) return null; const team = getTeam(teamName); return team && team.status === 'active' ? team : null; } /** * Use AI to resolve Git merge conflicts in the working directory. * Reads each conflicted file, sends it to the configured LLM for intelligent * resolution, writes the resolved content back, and stages the file. * Falls back to `git checkout --theirs` when AI resolution fails for a file. */ private async aiResolveConflicts( conflictFiles: string[], memberName: string, ): Promise<{resolved: string[]; failed: string[]; error?: string}> { const {getSnowConfig} = await import('../utils/config/apiConfig.js'); const {createStreamingChatCompletion} = await import('../api/chat.js'); const {createStreamingAnthropicCompletion} = await import('../api/anthropic.js'); const {createStreamingGeminiCompletion} = await import('../api/gemini.js'); const {createStreamingResponse} = await import('../api/responses.js'); const {execSync} = await import('child_process'); const config = getSnowConfig(); const model = config.advancedModel || config.basicModel || 'gpt-4o-mini'; const method: RequestMethod = config.requestMethod || 'chat'; const resolved: string[] = []; const failed: string[] = []; for (const file of conflictFiles) { let content: string; try { content = readFileSync(file, 'utf8'); } catch { failed.push(file); continue; } if (!content.includes('<<<<<<<')) { try { execSync(`git add "${file}"`, {stdio: 'pipe'}); resolved.push(file); } catch { failed.push(file); } continue; } const prompt = [ 'You are resolving a Git merge conflict.', 'Below is the content of a file with conflict markers.', '', '- `<<<<<<< HEAD` marks the current branch (main/lead).', '- `=======` separates the two versions.', `- \`>>>>>>>\` marks the incoming branch (teammate "${memberName}").`, '', 'Rules:', '- Produce the correctly merged file that preserves ALL intended changes from BOTH sides.', '- If changes are complementary (e.g. different functions added), include both.', '- If changes directly conflict (e.g. same line modified differently), combine them intelligently.', '- Output ONLY the resolved file content. No explanations, no markdown fences, no extra text.', '', `File: ${file}`, '---', content, ].join('\n'); const messages = [{role: 'user' as const, content: prompt}]; let aiResult = ''; try { const collectContent = async (stream: AsyncIterable<any>) => { for await (const chunk of stream) { if (chunk.type === 'content' && chunk.content) { aiResult += chunk.content; } } }; switch (method) { case 'anthropic': await collectContent(createStreamingAnthropicCompletion( {model, messages, max_tokens: config.maxTokens || 8192, temperature: 0, disableThinking: true}, )); break; case 'gemini': await collectContent(createStreamingGeminiCompletion( {model, messages}, )); break; case 'responses': await collectContent(createStreamingResponse( {model, messages}, )); break; case 'chat': default: await collectContent(createStreamingChatCompletion( {model, messages, temperature: 0}, )); break; } if (aiResult && !aiResult.includes('<<<<<<<')) { writeFileSync(file, aiResult, 'utf8'); execSync(`git add "${file}"`, {stdio: 'pipe'}); resolved.push(file); } else { throw new Error('AI output still contains conflict markers or is empty'); } } catch (aiError) { console.error(`[Team] AI conflict resolution failed for ${file}, falling back to --theirs:`, aiError); try { execSync(`git checkout --theirs "${file}"`, {stdio: 'pipe'}); execSync(`git add "${file}"`, {stdio: 'pipe'}); resolved.push(file); } catch { failed.push(file); } } } return {resolved, failed}; } async execute(options: TeamToolExecutionOptions): Promise<any> { const {toolName, args} = options; switch (toolName) { case 'spawn_teammate': return this.spawnTeammate(options); case 'message_teammate': return this.messageTeammate(args); case 'broadcast_to_team': return this.broadcastToTeam(args); case 'shutdown_teammate': return this.shutdownTeammate(args); case 'wait_for_teammates': return this.waitForTeammates(args, options.abortSignal); case 'create_task': return this.createTask(args); case 'update_task': return this.updateTask(args); case 'list_tasks': return this.listTasks(); case 'list_teammates': return this.listTeammates(); case 'merge_teammate_work': return this.mergeTeammateWork(args); case 'merge_all_teammate_work': return this.mergeAllTeammateWork(args); case 'resolve_merge_conflicts': return this.resolveMergeConflicts(); case 'abort_merge': return this.abortMerge(); case 'cleanup_team': return this.cleanupTeam(); case 'approve_plan': return this.approvePlan(args); default: throw new Error(`Unknown team tool: ${toolName}`); } } private async spawnTeammate(options: TeamToolExecutionOptions): Promise<any> { const {args, onMessage, abortSignal, requestToolConfirmation, isToolAutoApproved, yoloMode, addToAlwaysApproved, requestUserQuestion} = options; const name = args['name'] as string; const role = args['role'] as string | undefined; const prompt = args['prompt'] as string; const requirePlanApproval = args['require_plan_approval'] as boolean | undefined; if (!name || !prompt) { throw new Error('spawn_teammate requires "name" and "prompt" parameters'); } if (!isGitRepo()) { throw new Error('Agent Teams require a Git repository. Initialize git first.'); } // Ensure a team exists (scoped to this session) let team = this.getOwnTeam(); const isNewTeam = !team; if (!team) { const teamName = `team-${Date.now()}`; team = createTeam(teamName, 'lead'); teamTracker.setActiveTeam(teamName); } // Create Git worktree for this teammate const worktreePath = await createTeamWorktree(team.name, name); // Add member to team config const member = addMember(team.name, name, worktreePath, role); // Record snapshots for rollback const ctx = getConversationContext(); if (ctx) { if (isNewTeam) { recordTeamCreated(ctx.sessionId, ctx.messageIndex, team.name); } recordMemberSpawned(ctx.sessionId, ctx.messageIndex, team.name, member.id, name, worktreePath); } // Create a managed AbortController so rollback can force-stop this teammate const teammateAC = teamTracker.createAbortController(member.id, abortSignal); // Spawn teammate execution (fire-and-forget) executeTeammate( member.id, name, prompt, worktreePath, team.name, role, { onMessage, abortSignal: teammateAC.signal, requestToolConfirmation, isToolAutoApproved, yoloMode, addToAlwaysApproved, requestUserQuestion, requirePlanApproval, }, ).catch(error => { console.error(`Teammate ${name} failed:`, error); }); return { success: true, result: `Teammate "${name}" spawned successfully.`, memberId: member.id, worktreePath, role: role || 'general', }; } private messageTeammate(args: Record<string, any>): any { const targetId = args['target_id'] as string; const content = args['content'] as string; if (!targetId || !content) { throw new Error('message_teammate requires "target_id" and "content"'); } // Find teammate by member ID, name, or instance ID let teammate = teamTracker.findByMemberId(targetId) || teamTracker.findByMemberName(targetId) || teamTracker.getTeammate(targetId); if (!teammate) { return { success: false, error: `Teammate "${targetId}" not found or not running.`, }; } const sent = teamTracker.sendMessageToTeammate( 'lead', teammate.instanceId, content, ); return { success: sent, result: sent ? `Message sent to ${teammate.memberName}.` : `Failed to send message to ${targetId}.`, }; } private broadcastToTeam(args: Record<string, any>): any { const content = args['content'] as string; if (!content) { throw new Error('broadcast_to_team requires "content"'); } const count = teamTracker.broadcastToTeammates('lead', content); return { success: true, result: `Broadcast sent to ${count} teammate(s).`, }; } private shutdownTeammate(args: Record<string, any>): any { const targetId = args['target_id'] as string; const reason = args['reason'] as string | undefined; if (!targetId) { throw new Error('shutdown_teammate requires "target_id"'); } let teammate = teamTracker.findByMemberId(targetId) || teamTracker.findByMemberName(targetId) || teamTracker.getTeammate(targetId); if (!teammate) { return { success: false, error: `Teammate "${targetId}" not found or not running.`, }; } // Abort the teammate's execution directly — teammates cannot self-terminate const controller = teamTracker.getAbortController(teammate.memberId); if (controller) { controller.abort(); } return { success: true, result: `Teammate ${teammate.memberName} has been shut down.${reason ? ` Reason: ${reason}` : ''}`, }; } private async waitForTeammates( args: Record<string, any>, abortSignal?: AbortSignal, ): Promise<any> { const running = teamTracker.getRunningTeammates(); if (running.length === 0) { const results = teamTracker.drainResults(); const leadMessages = teamTracker.dequeueLeadMessages(); return { success: true, result: 'No teammates are running.', completedResults: results.map(r => ({ name: r.memberName, success: r.success, summary: r.result?.slice(0, 500), error: r.error, })), messages: leadMessages.map(m => ({ from: m.fromMemberName, content: m.content?.slice(0, 500), })), }; } // Check if all are already on standby if (teamTracker.allInStandby()) { const results = teamTracker.drainResults(); const leadMessages = teamTracker.dequeueLeadMessages(); const standbyTeammates = running.map(t => t.memberName); return { success: true, result: `All ${running.length} teammate(s) are on standby (work complete). Use shutdown_teammate to shut them down, then merge their work.`, standbyTeammates, completedResults: results.map(r => ({ name: r.memberName, success: r.success, summary: r.result?.slice(0, 500), error: r.error, })), messages: leadMessages.map(m => ({ from: m.fromMemberName, content: m.content?.slice(0, 500), })), }; } const timeoutMs = Math.min( Math.max((args['timeout_seconds'] as number || 600) * 1000, 10_000), 1_800_000, ); const allDone = await teamTracker.waitForAllTeammates(timeoutMs, abortSignal); const results = teamTracker.drainResults(); const leadMessages = teamTracker.dequeueLeadMessages(); const currentRunning = teamTracker.getRunningTeammates(); const standbyTeammates = currentRunning .filter(t => teamTracker.isOnStandby(t.instanceId)) .map(t => t.memberName); const stillWorking = currentRunning .filter(t => !teamTracker.isOnStandby(t.instanceId)) .map(t => t.memberName); return { success: allDone, result: allDone ? `All ${currentRunning.length} teammate(s) are on standby (work complete). Use shutdown_teammate to shut them down, then merge their work.` : `Timed out after ${timeoutMs / 1000}s. ${stillWorking.length} teammate(s) still working: ${stillWorking.join(', ')}`, standbyTeammates, stillWorking, completedResults: results.map(r => ({ name: r.memberName, success: r.success, summary: r.result?.slice(0, 500), error: r.error, })), messages: leadMessages.map(m => ({ from: m.fromMemberName, content: m.content?.slice(0, 500), })), }; } private createTask(args: Record<string, any>): any { const team = this.getOwnTeam(); if (!team) { throw new Error('No active team. You must call spawn_teammate first — the team is created automatically when the first teammate is spawned. Call spawn_teammate, then create_task.'); } const title = args['title'] as string; const description = args['description'] as string | undefined; const dependencies = args['dependencies'] as string[] | undefined; const assigneeId = args['assignee_id'] as string | undefined; const assigneeName = args['assignee_name'] as string | undefined; if (!title) { throw new Error('create_task requires "title"'); } const task = createTask( team.name, title, description, dependencies, assigneeId, assigneeName, ); return { success: true, result: `Task created: "${task.title}" (${task.id})`, taskId: task.id, }; } private updateTask(args: Record<string, any>): any { const team = this.getOwnTeam(); if (!team) { throw new Error('No active team.'); } const taskId = args['task_id'] as string; const status = args['status'] as string | undefined; const assigneeId = args['assignee_id'] as string | undefined; const assigneeName = args['assignee_name'] as string | undefined; if (!taskId) { throw new Error('update_task requires "task_id"'); } if (status) { updateTaskStatus(team.name, taskId, status as any); } if (assigneeId) { assignTask(team.name, taskId, assigneeId, assigneeName || assigneeId); } return {success: true, result: `Task ${taskId} updated.`}; } private listTasks(): any { const team = this.getOwnTeam(); if (!team) { return {success: true, result: 'No active team.', tasks: []}; } const tasks = listTasks(team.name); return { success: true, tasks: tasks.map(t => ({ id: t.id, title: t.title, description: t.description, status: t.status, assignee: t.assigneeName || t.assigneeId, dependencies: t.dependencies, })), }; } private listTeammates(): any { const teammates = teamTracker.getRunningTeammates(); return { success: true, teammates: teammates.map(t => ({ memberId: t.memberId, name: t.memberName, role: t.role, instanceId: t.instanceId, worktreePath: t.worktreePath, currentTaskId: t.currentTaskId, runningFor: `${Math.round((Date.now() - t.startedAt.getTime()) / 1000)}s`, })), }; } private async mergeTeammateWork(args: Record<string, any>): Promise<any> { const team = this.getOwnTeam(); if (!team) { throw new Error('No active team.'); } if (isInMergeState()) { return { success: false, error: 'A merge is already in progress. Call team-resolve_merge_conflicts to complete it or team-abort_merge to cancel.', }; } const targetName = args['name'] as string; if (!targetName) { throw new Error('merge_teammate_work requires "name"'); } const strategy = (args['strategy'] as MergeStrategy) || 'manual'; const member = team.members.find( m => m.name.toLowerCase() === targetName.toLowerCase(), ); if (!member) { return {success: false, error: `Member "${targetName}" not found in team.`}; } if (member.worktreePath && existsSync(member.worktreePath)) { autoCommitWorktreeChanges(member.worktreePath, member.name); } const result = mergeTeammateBranch(team.name, member.name, strategy); if (result.success && result.merged) { return { success: true, result: `Merged ${result.commitCount} commit(s) from ${member.name} (${result.filesChanged} files changed).`, }; } else if (result.success && !result.merged) { return { success: true, result: `${member.name} has no changes to merge.`, }; } else if (result.hasConflicts && strategy === 'auto') { const aiResult = await this.aiResolveConflicts( result.conflictFiles || [], member.name, ); if (aiResult.failed.length > 0) { abortCurrentMerge(); return { success: false, error: `AI conflict resolution failed for ${aiResult.failed.length} file(s): ${aiResult.failed.join(', ')}`, conflictFiles: aiResult.failed, }; } const mergeComplete = completeMerge( `[Snow Team] AI-resolved merge of ${member.name}'s work`, ); if (mergeComplete.success) { return { success: true, result: `Merged ${result.commitCount} commit(s) from ${member.name}. AI resolved conflicts in ${aiResult.resolved.length} file(s): ${aiResult.resolved.join(', ')}.`, autoResolved: aiResult.resolved, }; } return {success: false, error: mergeComplete.error}; } else if (result.hasConflicts) { return { success: false, hasConflicts: true, conflictFiles: result.conflictFiles, error: result.error, hint: 'Read the conflicted files, edit them to resolve conflict markers (<<<<<<< / ======= / >>>>>>>), then call team-resolve_merge_conflicts.', }; } else { return { success: false, error: result.error, conflictFiles: result.conflictFiles, }; } } private async mergeAllTeammateWork(args: Record<string, any>): Promise<any> { const team = this.getOwnTeam(); if (!team) { throw new Error('No active team.'); } if (isInMergeState()) { return { success: false, error: 'A merge is already in progress. Call team-resolve_merge_conflicts to complete it or team-abort_merge to cancel.', }; } const running = teamTracker.getRunningTeammates(); if (running.length > 0) { return { success: false, error: `Cannot merge: ${running.length} teammate(s) still running. Wait for them to finish first.`, runningTeammates: running.map(t => t.memberName), }; } const strategy = (args['strategy'] as MergeStrategy) || 'manual'; const results: Array<{name: string; merged: boolean; commits: number; files: number; error?: string; conflictFiles?: string[]; autoResolved?: string[]}> = []; for (const member of team.members) { if (member.worktreePath && existsSync(member.worktreePath)) { autoCommitWorktreeChanges(member.worktreePath, member.name); } const diff = getTeammateDiffSummary(team.name, member.name); if (!diff || diff.commitCount === 0) { results.push({name: member.name, merged: false, commits: 0, files: 0}); continue; } const mergeResult = mergeTeammateBranch(team.name, member.name, strategy); if (mergeResult.success && mergeResult.merged) { results.push({ name: member.name, merged: true, commits: mergeResult.commitCount, files: mergeResult.filesChanged, }); } else if (mergeResult.hasConflicts && strategy === 'auto') { const aiResult = await this.aiResolveConflicts( mergeResult.conflictFiles || [], member.name, ); if (aiResult.failed.length > 0) { abortCurrentMerge(); results.push({ name: member.name, merged: false, commits: mergeResult.commitCount, files: 0, error: `AI conflict resolution failed for: ${aiResult.failed.join(', ')}`, conflictFiles: aiResult.failed, }); break; } const mergeComplete = completeMerge( `[Snow Team] AI-resolved merge of ${member.name}'s work`, ); if (mergeComplete.success) { results.push({ name: member.name, merged: true, commits: mergeResult.commitCount, files: (mergeResult.conflictFiles || []).length, autoResolved: aiResult.resolved, }); } else { results.push({ name: member.name, merged: false, commits: mergeResult.commitCount, files: 0, error: mergeComplete.error, }); break; } } else if (mergeResult.hasConflicts) { results.push({ name: member.name, merged: false, commits: mergeResult.commitCount, files: 0, error: mergeResult.error, conflictFiles: mergeResult.conflictFiles, }); const mergedCount = results.filter(r => r.merged).length; return { success: false, hasConflicts: true, error: `Merge conflicts at ${member.name}. ${mergedCount} teammate(s) merged before the conflict. Working directory is in merge state — resolve conflicts then call team-resolve_merge_conflicts.`, conflictFiles: mergeResult.conflictFiles, results, stoppedAt: member.name, }; } else if (!mergeResult.success) { results.push({ name: member.name, merged: false, commits: mergeResult.commitCount, files: 0, error: mergeResult.error, }); break; } else { results.push({name: member.name, merged: false, commits: 0, files: 0}); } } const mergedCount = results.filter(r => r.merged).length; const totalCommits = results.reduce((sum, r) => sum + r.commits, 0); const allAutoResolved = results.flatMap(r => r.autoResolved || []); const failedResult = results.find(r => r.error && !r.conflictFiles?.length); if (failedResult) { return { success: false, error: `Merge failed at ${failedResult.name}: ${failedResult.error}`, results, }; } const autoInfo = allAutoResolved.length > 0 ? ` AI resolved conflicts in ${allAutoResolved.length} file(s): ${allAutoResolved.join(', ')}.` : ''; return { success: true, result: `All teammate work merged. ${mergedCount} teammate(s) with changes, ${totalCommits} total commit(s).${autoInfo}`, results, autoResolved: allAutoResolved.length > 0 ? allAutoResolved : undefined, }; } private resolveMergeConflicts(): any { if (!isInMergeState()) { return {success: false, error: 'Not currently in a merge state. Nothing to resolve.'}; } const remaining = getConflictedFiles(); if (remaining.length > 0) { return { success: false, error: `${remaining.length} file(s) still have unresolved conflict markers: ${remaining.join(', ')}. Edit them to remove <<<<<<< / ======= / >>>>>>> markers first.`, unresolvedFiles: remaining, }; } const result = completeMerge(); if (result.success) { return { success: true, result: 'Merge completed successfully. All conflicts resolved and committed.', }; } return {success: false, error: result.error}; } private abortMerge(): any { if (!isInMergeState()) { return {success: false, error: 'Not currently in a merge state.'}; } const result = abortCurrentMerge(); if (result.success) { return { success: true, result: 'Merge aborted. Working directory restored to pre-merge state.', }; } return {success: false, error: result.error}; } private async cleanupTeam(): Promise<any> { const team = this.getOwnTeam(); if (!team) { return {success: false, error: 'No active team to clean up.'}; } const running = teamTracker.getRunningTeammates(); if (running.length > 0) { return { success: false, error: `Cannot clean up: ${running.length} teammate(s) still running. Shut them down first.`, runningTeammates: running.map(t => t.memberName), }; } // Check for unmerged work const unmergedMembers: string[] = []; for (const member of team.members) { const diff = getTeammateDiffSummary(team.name, member.name); if (diff && diff.commitCount > 0) { unmergedMembers.push(`${member.name} (${diff.commitCount} commits, ${diff.filesChanged} files)`); } } if (unmergedMembers.length > 0) { return { success: false, error: `Cannot clean up: ${unmergedMembers.length} teammate(s) have unmerged work that will be LOST. Run team-merge_all_teammate_work first.`, unmergedMembers, }; } // Clean up Git worktrees try { await cleanupTeamWorktrees(team.name); } catch (e: any) { console.error('Failed to cleanup worktrees:', e); } // Disband team and clear tracker disbandTeam(team.name); teamTracker.clearActiveTeam(); clearAllTeammateStreamEntries(); // Clean up team snapshot records so rollback prompt won't show already-terminated teams const ctx = getConversationContext(); if (ctx) { deleteTeamSnapshotsByTeamName(ctx.sessionId, team.name); } return { success: true, result: `Team "${team.name}" has been cleaned up. Worktrees removed, team disbanded.`, }; } private approvePlan(args: Record<string, any>): any { const targetId = args['target_id'] as string; const approved = args['approved'] as boolean; const feedback = args['feedback'] as string | undefined; if (!targetId || approved === undefined) { throw new Error('approve_plan requires "target_id" and "approved"'); } let teammate = teamTracker.findByMemberId(targetId) || teamTracker.findByMemberName(targetId) || teamTracker.getTeammate(targetId); if (!teammate) { return {success: false, error: `Teammate "${targetId}" not found.`}; } const resolved = teamTracker.resolvePlanApproval( teammate.instanceId, approved, feedback, ); return { success: resolved, result: resolved ? `Plan ${approved ? 'approved' : 'rejected'} for ${teammate.memberName}.` : `No pending plan approval found for ${targetId}.`, }; } getTools(): Array<{ name: string; description: string; inputSchema: any; }> { return [ { name: 'spawn_teammate', description: 'Spawn a new teammate agent that works independently in its own Git worktree. Each teammate has full tool access and can communicate with other teammates.', inputSchema: { type: 'object', properties: { name: {type: 'string', description: 'A short, descriptive name for this teammate (e.g., "frontend", "backend", "tester").'}, role: {type: 'string', description: 'Optional role description guiding the teammate\'s focus area.'}, prompt: {type: 'string', description: 'The task prompt for this teammate. Include all relevant context since teammates don\'t inherit your conversation history.'}, require_plan_approval: {type: 'boolean', description: 'If true, the teammate must submit a plan for your approval before making changes.'}, }, required: ['name', 'prompt'], }, }, { name: 'message_teammate', description: 'Send a direct message to a specific teammate. Use to provide guidance, share findings, or redirect their approach.', inputSchema: { type: 'object', properties: { target_id: {type: 'string', description: 'The member ID or name of the target teammate.'}, content: {type: 'string', description: 'The message content.'}, }, required: ['target_id', 'content'], }, }, { name: 'broadcast_to_team', description: 'Send a message to all teammates simultaneously. Use sparingly as costs scale with team size.', inputSchema: { type: 'object', properties: { content: {type: 'string', description: 'The message to broadcast to all teammates.'}, }, required: ['content'], }, }, { name: 'shutdown_teammate', description: 'Immediately shut down a specific teammate. Teammates cannot self-terminate — this is the ONLY way to end a teammate. Teammates enter standby after finishing work, remaining available for messages until you shut them down.', inputSchema: { type: 'object', properties: { target_id: {type: 'string', description: 'The member ID or name of the teammate to shut down.'}, reason: {type: 'string', description: 'Optional reason for the shutdown.'}, }, required: ['target_id'], }, }, { name: 'wait_for_teammates', description: 'Block and wait until ALL running teammates have entered standby (finished their work). Returns collected results and messages. After this returns, you should review results, then shut down teammates with shutdown_teammate, merge their work, and clean up.', inputSchema: { type: 'object', properties: { timeout_seconds: {type: 'number', description: 'Maximum time to wait in seconds. Default: 600 (10 min). Range: 10-1800.'}, }, required: [], }, }, { name: 'create_task', description: 'Create a new task in the shared task list. PREREQUISITE: At least one teammate must be spawned first (spawn_teammate creates the team). Calling this without an active team will fail.', inputSchema: { type: 'object', properties: { title: {type: 'string', description: 'Brief title for the task.'}, description: {type: 'string', description: 'Detailed description of what needs to be done.'}, dependencies: {type: 'array', items: {type: 'string'}, description: 'Task IDs that must be completed before this task can be claimed.'}, assignee_id: {type: 'string', description: 'Optional member ID to pre-assign this task to.'}, assignee_name: {type: 'string', description: 'Optional member name for the pre-assignment.'}, }, required: ['title'], }, }, { name: 'update_task', description: 'Update a task\'s status or reassign it.', inputSchema: { type: 'object', properties: { task_id: {type: 'string', description: 'The task ID to update.'}, status: {type: 'string', enum: ['pending', 'in_progress', 'completed'], description: 'New status for the task.'}, assignee_id: {type: 'string', description: 'New assignee member ID.'}, assignee_name: {type: 'string', description: 'New assignee name.'}, }, required: ['task_id'], }, }, { name: 'list_tasks', description: 'View all tasks in the shared task list with status, assignees, and dependencies.', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'list_teammates', description: 'View all currently running teammates with their status, roles, and current tasks.', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'merge_teammate_work', description: 'Merge a specific teammate\'s Git branch into the main branch. Auto-commits first. On conflict with strategy "manual" (default), leaves the working directory in merge state so you can read/edit conflicted files and then call team-resolve_merge_conflicts.', inputSchema: { type: 'object', properties: { name: {type: 'string', description: 'The name of the teammate whose work to merge.'}, strategy: {type: 'string', enum: ['manual', 'theirs', 'ours', 'auto'], description: '"manual" (default): pause on conflicts for you to resolve. "theirs": auto-accept all teammate changes on conflict. "ours": auto-keep main branch changes on conflict. "auto": try normal merge, auto-resolve conflicts by accepting teammate\'s version.'}, }, required: ['name'], }, }, { name: 'merge_all_teammate_work', description: 'Merge ALL teammates\' branches sequentially. Stops on first conflict (in "manual" mode) so you can resolve it. With "auto" strategy, conflicts are auto-resolved and merging continues. MUST call before cleanup_team.', inputSchema: { type: 'object', properties: { strategy: {type: 'string', enum: ['manual', 'theirs', 'ours', 'auto'], description: '"manual" (default): stop on conflicts for resolution. "theirs": auto-accept teammate changes. "ours": auto-keep main branch. "auto": try normal merge, auto-resolve conflicts by accepting teammate\'s version.'}, }, required: [], }, }, { name: 'resolve_merge_conflicts', description: 'Complete a merge after manually resolving conflicts. Stages all changes and commits. Call this after editing conflicted files to remove <<<<<<< / ======= / >>>>>>> markers.', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'abort_merge', description: 'Abort the current merge and restore the working directory to pre-merge state. Use when you decide not to merge a teammate\'s conflicting changes.', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'cleanup_team', description: 'Clean up the team: remove Git worktrees and disband. All teammates must be shut down AND their work must be merged first (will refuse if unmerged changes exist).', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'approve_plan', description: 'Approve or reject a teammate\'s implementation plan. Only applicable when the teammate was spawned with require_plan_approval.', inputSchema: { type: 'object', properties: { target_id: {type: 'string', description: 'The member ID or name of the teammate whose plan to review.'}, approved: {type: 'boolean', description: 'Whether to approve the plan.'}, feedback: {type: 'string', description: 'Optional feedback, especially useful when rejecting.'}, }, required: ['target_id', 'approved'], }, }, ]; } } export const teamService = new TeamService(); export function getTeamMCPTools(): Array<{ name: string; description: string; inputSchema: any; }> { return teamService.getTools(); } ================================================ FILE: source/mcp/todo.ts ================================================ import {Tool, type CallToolResult} from '@modelcontextprotocol/sdk/types.js'; import fs from 'fs/promises'; import path from 'path'; // Type definitions import type { TodoItem, TodoList, GetCurrentSessionId, } from './types/todo.types.js'; // Utility functions import {formatDateForFolder} from './utils/todo/date.utils.js'; // Event emitter import {todoEvents} from '../utils/events/todoEvents.js'; /** * TODO 管理服务 - 支持创建、查询、更新 TODO * 路径结构: ~/.snow/todos/项目名/YYYY-MM-DD/sessionId.json */ export class TodoService { private readonly todoDir: string; private getCurrentSessionId: GetCurrentSessionId; constructor(baseDir: string, getCurrentSessionId: GetCurrentSessionId) { // baseDir 现在已经包含了项目ID，直接使用 // 路径结构: baseDir/YYYY-MM-DD/sessionId.json this.todoDir = baseDir; this.getCurrentSessionId = getCurrentSessionId; } async initialize(): Promise<void> { await fs.mkdir(this.todoDir, {recursive: true}); } private getTodoPath(sessionId: string, date?: Date): string { const sessionDate = date || new Date(); const dateFolder = formatDateForFolder(sessionDate); const todoDir = path.join(this.todoDir, dateFolder); return path.join(todoDir, `${sessionId}.json`); } private async ensureTodoDir(date?: Date): Promise<void> { try { await fs.mkdir(this.todoDir, {recursive: true}); if (date) { const dateFolder = formatDateForFolder(date); const todoDir = path.join(this.todoDir, dateFolder); await fs.mkdir(todoDir, {recursive: true}); } } catch (error) { // Directory already exists or other error } } /** * 创建或更新会话的 TODO List */ async saveTodoList( sessionId: string, todos: TodoItem[], existingList?: TodoList | null, ): Promise<TodoList> { // 使用现有TODO列表的createdAt信息，或者使用当前时间 const sessionCreatedAt = existingList?.createdAt ? new Date(existingList.createdAt).getTime() : Date.now(); const sessionDate = new Date(sessionCreatedAt); await this.ensureTodoDir(sessionDate); const todoPath = this.getTodoPath(sessionId, sessionDate); try { const content = await fs.readFile(todoPath, 'utf-8'); existingList = JSON.parse(content); } catch { // 文件不存在,创建新的 } const now = new Date().toISOString(); const todoList: TodoList = { sessionId, todos, createdAt: existingList?.createdAt ?? now, updatedAt: now, }; await fs.writeFile(todoPath, JSON.stringify(todoList, null, 2)); // 触发 TODO 更新事件 todoEvents.emitTodoUpdate(sessionId, todos); return todoList; } /** * 获取会话的 TODO List */ async getTodoList(sessionId: string): Promise<TodoList | null> { // 首先尝试从旧格式加载（向下兼容） try { const oldTodoPath = path.join(this.todoDir, `${sessionId}.json`); const content = await fs.readFile(oldTodoPath, 'utf-8'); return JSON.parse(content); } catch (error) { // 旧格式不存在，搜索日期文件夹 } // 在日期文件夹中查找 TODO try { const todo = await this.findTodoInDateFolders(sessionId); return todo; } catch (error) { // 搜索失败 } return null; } private async findTodoInDateFolders( sessionId: string, ): Promise<TodoList | null> { try { const files = await fs.readdir(this.todoDir); for (const file of files) { const filePath = path.join(this.todoDir, file); const stat = await fs.stat(filePath); if (stat.isDirectory() && /^\d{4}-\d{2}-\d{2}$/.test(file)) { // 这是日期文件夹，查找 TODO 文件 const todoPath = path.join(filePath, `${sessionId}.json`); try { const content = await fs.readFile(todoPath, 'utf-8'); return JSON.parse(content); } catch (error) { // 文件不存在或读取失败，继续搜索 continue; } } } } catch (error) { // 目录读取失败 } return null; } /** * 更新单个 TODO 项 */ async updateTodoItem( sessionId: string, todoId: string, updates: Partial<Omit<TodoItem, 'id' | 'createdAt'>>, ): Promise<TodoList | null> { const todoList = await this.getTodoList(sessionId); if (!todoList) { return null; } const todoIndex = todoList.todos.findIndex(t => t.id === todoId); if (todoIndex === -1) { return null; } const existingTodo = todoList.todos[todoIndex]!; todoList.todos[todoIndex] = { ...existingTodo, ...updates, updatedAt: new Date().toISOString(), }; return this.saveTodoList(sessionId, todoList.todos, todoList); } /** * 批量更新多个 TODO 项 */ async updateTodoItems( sessionId: string, todoIds: string[], updates: Partial<Omit<TodoItem, 'id' | 'createdAt'>>, ): Promise<TodoList | null> { const todoList = await this.getTodoList(sessionId); if (!todoList) { return null; } const idSet = new Set(todoIds); const updatedAt = new Date().toISOString(); let anyFound = false; todoList.todos = todoList.todos.map(t => { if (idSet.has(t.id)) { anyFound = true; return {...t, ...updates, updatedAt}; } return t; }); if (!anyFound) { return null; } return this.saveTodoList(sessionId, todoList.todos, todoList); } /** * 添加 TODO 项 */ async addTodoItem( sessionId: string, content: string, parentId?: string, ): Promise<TodoList> { const todoList = await this.getTodoList(sessionId); const now = new Date().toISOString(); /** * 验证并修正 parentId * - 如果 parentId 为空或不存在于当前列表中，自动转为 undefined（创建根级任务） * - 如果 parentId 有效，保持原值（创建子任务） */ let validatedParentId: string | undefined; if (parentId && parentId.trim() !== '' && todoList) { const parentExists = todoList.todos.some(todo => todo.id === parentId); if (parentExists) { validatedParentId = parentId; } } const newTodo: TodoItem = { id: `todo-${Date.now()}_${Math.random().toString(36).slice(2, 9)}`, content, status: 'pending', createdAt: now, updatedAt: now, parentId: validatedParentId, }; const todos = todoList ? [...todoList.todos, newTodo] : [newTodo]; return this.saveTodoList(sessionId, todos, todoList); } /** * 删除 TODO 项 */ async deleteTodoItem( sessionId: string, todoId: string, ): Promise<TodoList | null> { const todoList = await this.getTodoList(sessionId); if (!todoList) { return null; } const filteredTodos = todoList.todos.filter( t => t.id !== todoId && t.parentId !== todoId, ); return this.saveTodoList(sessionId, filteredTodos, todoList); } /** * 批量删除多个 TODO 项（含级联删除子项） */ async deleteTodoItems( sessionId: string, todoIds: string[], ): Promise<TodoList | null> { const todoList = await this.getTodoList(sessionId); if (!todoList) { return null; } const idSet = new Set(todoIds); const filteredTodos = todoList.todos.filter( t => !idSet.has(t.id) && !idSet.has(t.parentId ?? ''), ); return this.saveTodoList(sessionId, filteredTodos, todoList); } /** * 创建空 TODO 列表（会话自动创建时使用） */ async createEmptyTodo(sessionId: string): Promise<TodoList> { return this.saveTodoList(sessionId, [], null); } /** * 复制 TODO 列表到新会话（用于会话压缩时继承 TODO） * @param fromSessionId - 源会话ID * @param toSessionId - 目标会话ID * @returns 复制后的 TODO 列表，如果源会话没有 TODO 则返回 null */ async copyTodoList( fromSessionId: string, toSessionId: string, ): Promise<TodoList | null> { // 获取源会话的 TODO 列表 const sourceTodoList = await this.getTodoList(fromSessionId); // 如果源会话没有 TODO 或 TODO 为空，不需要复制 if (!sourceTodoList || sourceTodoList.todos.length === 0) { return null; } // 复制 TODO 项到新会话（保留原有的 TODO 项，但更新时间戳） const now = new Date().toISOString(); const copiedTodos: TodoItem[] = sourceTodoList.todos.map(todo => ({ ...todo, // 保留原有的 id、content、status、parentId // 更新时间戳 updatedAt: now, })); // 保存到新会话 return this.saveTodoList(toSessionId, copiedTodos, null); } /** * 删除整个会话的 TODO 列表 */ async deleteTodoList(sessionId: string): Promise<boolean> { // 首先尝试删除旧格式（向下兼容） try { const oldTodoPath = path.join(this.todoDir, `${sessionId}.json`); await fs.unlink(oldTodoPath); return true; } catch (error) { // 旧格式不存在，搜索日期文件夹 } // 在日期文件夹中查找并删除 TODO try { const files = await fs.readdir(this.todoDir); for (const file of files) { const filePath = path.join(this.todoDir, file); const stat = await fs.stat(filePath); if (stat.isDirectory() && /^\d{4}-\d{2}-\d{2}$/.test(file)) { // 这是日期文件夹，查找 TODO 文件 const todoPath = path.join(filePath, `${sessionId}.json`); try { await fs.unlink(todoPath); return true; } catch (error) { // 文件不存在，继续搜索 continue; } } } } catch (error) { // 目录读取失败 } return false; } /** * 获取所有工具定义（单一 todo-manage，通过 action 区分 get / add / update / delete） */ getTools(): Tool[] { return [ { name: 'todo-manage', description: `Unified session TODO list: use required field "action" — one of get | add | update | delete. PARALLEL CALLS ONLY: MUST pair with other tools (todo-manage + filesystem-read/terminal-execute/etc). NEVER call todo-manage alone for any action — always combine with an action tool in the same turn. ACTIONS: - get: Current list with IDs, status, hierarchy. Use before add/update when you need existing IDs. - add: Create item(s). Use "content" (string or string[]). Optional "parentId" for subtasks (valid parent id from get). - update: Required "todoId" (string or string[]). Optional "status" (pending|inProgress|completed) and/or "content" (refined wording). Batch ids share the same updates. - delete: Required "todoId" (string or string[]). Deleting a parent cascades to children. BEST PRACTICES: - Mark "completed" only after the step is verified; update as you work. - Update each item immediately after it is done; do NOT finish all work first and batch-update at the end. - Delete obsolete or redundant items to keep the list focused. EXAMPLES: - todo-manage({action:"get"}) + filesystem-read(...) - todo-manage({action:"add", content:["Step 1","Step 2"]}) + filesystem-read(...) - todo-manage({action:"update", todoId:"...", status:"completed"}) + filesystem-edit(...)`, inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['get', 'add', 'update', 'delete'], description: 'Which operation to run on the current session TODO list.', }, content: { oneOf: [ { type: 'string', description: 'For action=add: one TODO description. For action=update: optional new wording.', }, { type: 'array', items: {type: 'string'}, description: 'For action=add only: batch add multiple TODO descriptions.', }, ], description: 'For add: required (string or string[]). For update: optional text refinement.', }, parentId: { type: 'string', description: 'For action=add only: parent TODO id for subtasks (from action=get).', }, todoId: { oneOf: [ { type: 'string', description: 'Single TODO item id', }, { type: 'array', items: {type: 'string'}, description: 'Multiple ids (same update or delete applies to all)', }, ], description: 'For action=update or delete: item id(s) from action=get.', }, status: { type: 'string', enum: ['pending', 'inProgress', 'completed'], description: 'For action=update only.', }, }, required: ['action'], }, }, ]; } /** * 执行工具调用 */ async executeTool( toolName: string, args: Record<string, unknown>, ): Promise<CallToolResult> { // 自动获取当前会话 ID const sessionId = this.getCurrentSessionId(); if (!sessionId) { return { content: [ { type: 'text', text: 'Error: No active session found', }, ], isError: true, }; } if (toolName !== 'manage') { return { content: [ { type: 'text', text: `Unknown TODO tool: ${toolName}`, }, ], isError: true, }; } const rawAction = args['action']; if ( typeof rawAction !== 'string' || !['get', 'add', 'update', 'delete'].includes(rawAction) ) { return { content: [ { type: 'text', text: 'Error: "action" must be one of: get, add, update, delete', }, ], isError: true, }; } const action = rawAction as 'get' | 'add' | 'update' | 'delete'; try { switch (action) { case 'get': { let result = await this.getTodoList(sessionId); // 兜底机制：如果TODO不存在，自动创建空TODO if (!result) { result = await this.createEmptyTodo(sessionId); } // 触发 TODO 更新事件，确保 UI 显示 TodoTree if (result && result.todos.length > 0) { todoEvents.emitTodoUpdate(sessionId, result.todos); } return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } case 'update': { const {todoId, status, content} = args as { todoId: string | string[]; status?: 'pending' | 'inProgress' | 'completed'; content?: string; }; if (todoId === undefined || todoId === null) { return { content: [ { type: 'text', text: 'Error: action=update requires "todoId"', }, ], isError: true, }; } const updates: Partial<Omit<TodoItem, 'id' | 'createdAt'>> = {}; if (status) updates.status = status; if (content !== undefined && typeof content === 'string') { updates.content = content; } const ids = Array.isArray(todoId) ? todoId : [todoId]; const result = await this.updateTodoItems(sessionId, ids, updates); return { content: [ { type: 'text', text: result ? JSON.stringify(result, null, 2) : 'TODO item not found', }, ], }; } case 'add': { const {content, parentId} = args as { content?: string | string[]; parentId?: string; }; if (content === undefined || content === null) { return { content: [ { type: 'text', text: 'Error: action=add requires "content"', }, ], isError: true, }; } // 智能解析 content：处理 JSON 字符串形式的数组 let parsedContent: string | string[] = content; if (typeof content === 'string') { // 尝试解析为 JSON 数组 try { const parsed = JSON.parse(content); if (Array.isArray(parsed)) { parsedContent = parsed; } // 如果解析结果不是数组，保持原字符串作为单个 TODO } catch { // 解析失败，保持原字符串 } } // 支持批量添加或单个添加 if (Array.isArray(parsedContent)) { // 批量添加多个TODO项 let currentList = await this.getTodoList(sessionId); for (const item of parsedContent) { currentList = await this.addTodoItem(sessionId, item, parentId); } return { content: [ { type: 'text', text: JSON.stringify(currentList, null, 2), }, ], }; } else { // 单个添加 const result = await this.addTodoItem( sessionId, parsedContent, parentId, ); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } } case 'delete': { const {todoId} = args as { todoId?: string | string[]; }; if (todoId === undefined || todoId === null) { return { content: [ { type: 'text', text: 'Error: action=delete requires "todoId"', }, ], isError: true, }; } const ids = Array.isArray(todoId) ? todoId : [todoId]; const result = await this.deleteTodoItems(sessionId, ids); return { content: [ { type: 'text', text: result ? JSON.stringify(result, null, 2) : 'TODO item not found', }, ], }; } default: return { content: [ { type: 'text', text: `Unknown action: ${String(action)}`, }, ], isError: true, }; } } catch (error) { return { content: [ { type: 'text', text: `Error executing todo-manage (${action}): ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } } } ================================================ FILE: source/mcp/types/aceCodeSearch.types.ts ================================================ /** * Type definitions for ACE Code Search Service */ /** * Code symbol types */ export type SymbolType = | 'function' | 'class' | 'method' | 'variable' | 'constant' | 'interface' | 'type' | 'enum' | 'import' | 'export'; /** * Code symbol information */ export interface CodeSymbol { name: string; type: SymbolType; filePath: string; line: number; column: number; endLine?: number; endColumn?: number; signature?: string; scope?: string; language: string; context?: string; // Surrounding code context } /** * Code reference types */ export type ReferenceType = 'definition' | 'usage' | 'import' | 'type'; /** * Code reference information */ export interface CodeReference { symbol: string; filePath: string; line: number; column: number; context: string; referenceType: ReferenceType; } /** * Semantic search result */ export interface SemanticSearchResult { query: string; symbols: CodeSymbol[]; references: CodeReference[]; totalResults: number; searchTime: number; } /** * AST node structure */ export interface ASTNode { type: string; name?: string; line: number; column: number; endLine?: number; endColumn?: number; children?: ASTNode[]; } /** * Text search result */ export interface TextSearchResult { filePath: string; line: number; column: number; content: string; } /** * Language configuration */ export interface LanguageConfig { extensions: string[]; parser: string; symbolPatterns: { function: RegExp; class: RegExp; variable?: RegExp; import?: RegExp; export?: RegExp; }; } /** * Index statistics */ export interface IndexStats { totalFiles: number; totalSymbols: number; languageBreakdown: Record<string, number>; cacheAge: number; } ================================================ FILE: source/mcp/types/bash.types.ts ================================================ /** * Type definitions for Terminal Command Service */ /** * Result of command execution */ export interface CommandExecutionResult { stdout: string; stderr: string; exitCode: number; command: string; executedAt: string; } ================================================ FILE: source/mcp/types/filesystem.types.ts ================================================ /** * Type definitions for Filesystem MCP Service */ import type {Diagnostic} from '../../utils/ui/vscodeConnection.js'; /** * MCP Content Types - supports multimodal content */ export type MCPContentType = 'text' | 'image' | 'document'; /** * Text content block */ export interface TextContent { type: 'text'; text: string; } /** * Image content block (base64 encoded) */ export interface ImageContent { type: 'image'; data: string; // base64 encoded image data mimeType: string; // e.g., 'image/png', 'image/jpeg' } /** * Document content block (for Office files like PDF, Word, Excel, PPT) */ export interface DocumentContent { type: 'document'; text: string; // Extracted text content fileType: 'pdf' | 'word' | 'excel' | 'powerpoint'; metadata?: { pages?: number; // For PDF sheets?: string[]; // For Excel slides?: number; // For PowerPoint [key: string]: unknown; }; } /** * Multimodal content - array of text, image, and document blocks */ export type MultimodalContent = Array< TextContent | ImageContent | DocumentContent >; /** * Supported image MIME types */ export const IMAGE_MIME_TYPES: Record<string, string> = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp', '.svg': 'image/svg+xml', }; /** * Supported Office document types */ export const OFFICE_FILE_TYPES: Record< string, 'pdf' | 'word' | 'excel' | 'powerpoint' > = { '.pdf': 'pdf', '.docx': 'word', '.doc': 'word', '.xlsx': 'excel', '.xls': 'excel', '.pptx': 'powerpoint', '.ppt': 'powerpoint', }; /** * Structure analysis result for code validation */ export interface StructureAnalysis { bracketBalance: { curly: {open: number; close: number; balanced: boolean}; round: {open: number; close: number; balanced: boolean}; square: {open: number; close: number; balanced: boolean}; }; htmlTags?: { unclosedTags: string[]; unopenedTags: string[]; balanced: boolean; }; indentationWarnings: string[]; codeBlockBoundary?: { isInCompleteBlock: boolean; suggestion?: string; }; } /** * File read configuration */ export interface FileReadConfig { path: string; startLine?: number; endLine?: number; } /** * Single file read result */ export interface SingleFileReadResult { content: string | MultimodalContent; // Can be text or multimodal startLine?: number; // Only for text files endLine?: number; // Only for text files totalLines?: number; // Only for text files isImage?: boolean; // Flag to indicate image content isDocument?: boolean; // Flag to indicate Office document content fileType?: 'pdf' | 'word' | 'excel' | 'powerpoint'; // Document type mimeType?: string; // MIME type for images } /** * Multiple files read result */ export interface MultipleFilesReadResult { content: string | MultimodalContent; // Can be text or multimodal files: Array<{ path: string; startLine?: number; endLine?: number; totalLines?: number; isImage?: boolean; isDocument?: boolean; fileType?: 'pdf' | 'word' | 'excel' | 'powerpoint'; mimeType?: string; }>; totalFiles: number; } /** * Search-replace (replaceedit) batch config */ export interface EditBySearchConfig { path: string; searchContent: string; replaceContent: string; occurrence?: number; } /** * Hashline edit operation types */ export type HashlineOperationType = 'replace' | 'insert_after' | 'delete'; /** * A single hashline edit operation. * Anchors use the format "lineNum:hash" (e.g. "42:a3"). */ export interface HashlineOperation { type: HashlineOperationType; /** Start anchor – required for all operation types */ startAnchor: string; /** End anchor – inclusive end of range for replace/delete. For a single line, use the same value as startAnchor. For insert_after, repeat startAnchor (only the start line is used). */ endAnchor: string; /** New content – required for replace and insert_after, ignored for delete */ content?: string; } /** * Edit by hashline configuration (for batch mode) */ export interface EditByHashlineConfig { path: string; operations: HashlineOperation[]; } /** * Hashline edit single file result */ export interface EditByHashlineSingleResult extends SingleFileEditResult { replacedContent: string; operationsSummary: string; } /** * Single file edit result (common fields) */ export interface SingleFileEditResult { message: string; filePath?: string; // File path for DiffViewer display on Resume/re-render oldContent: string; newContent: string; contextStartLine: number; contextEndLine: number; totalLines: number; structureAnalysis?: StructureAnalysis; diagnostics?: Diagnostic[]; } /** * Search-replace single file result */ export interface EditBySearchSingleResult extends SingleFileEditResult { replacedContent: string; matchLocation: {startLine: number; endLine: number}; } /** * Batch operation result item (generic) */ export interface BatchResultItem { path: string; success: boolean; error?: string; } /** * Search-replace batch result item */ export type EditBySearchBatchResultItem = BatchResultItem & Partial<EditBySearchSingleResult>; /** * Edit by hashline batch result item */ export type EditByHashlineBatchResultItem = BatchResultItem & Partial<EditByHashlineSingleResult>; /** * Batch operation result (generic) */ export interface BatchOperationResult<T extends BatchResultItem> { message: string; results: T[]; totalFiles: number; successCount: number; failureCount: number; } /** * Edit by hashline return type */ export type EditByHashlineResult = | EditByHashlineSingleResult | BatchOperationResult<EditByHashlineBatchResultItem>; /** * Search-replace return type */ export type EditBySearchResult = | EditBySearchSingleResult | BatchOperationResult<EditBySearchBatchResultItem>; ================================================ FILE: source/mcp/types/todo.types.ts ================================================ /** * Type definitions for TODO Service */ /** * TODO item */ export interface TodoItem { id: string; content: string; status: 'pending' | 'inProgress' | 'completed'; createdAt: string; updatedAt: string; parentId?: string; } /** * TODO list for a session */ export interface TodoList { sessionId: string; todos: TodoItem[]; createdAt: string; updatedAt: string; } /** * Callback function type for getting current session ID */ export type GetCurrentSessionId = () => string | null; ================================================ FILE: source/mcp/types/websearch.types.ts ================================================ /** * Type definitions for Web Search Service */ /** * Search result item */ export interface SearchResult { title: string; url: string; snippet: string; displayUrl: string; } /** * Search response */ export interface SearchResponse { query: string; results: SearchResult[]; totalResults: number; } /** * Web page content */ export interface WebPageContent { url: string; title: string; content: string; textLength: number; contentPreview: string; } ================================================ FILE: source/mcp/utils/aceCodeSearch/constants.utils.ts ================================================ /** * Constants and configuration for ACE Code Search */ /** * Index cache duration (1 minute) */ export const INDEX_CACHE_DURATION = 60000; /** * Batch size for concurrent file processing */ export const BATCH_SIZE = 10; /** * Binary file extensions to skip during text search * Used to filter out non-text files that cannot be searched */ export const BINARY_EXTENSIONS = new Set([ '.jpg', '.jpeg', '.png', '.gif', '.bmp', '.ico', '.svg', '.pdf', '.zip', '.tar', '.gz', '.rar', '.7z', '.exe', '.dll', '.so', '.dylib', '.mp3', '.mp4', '.avi', '.mov', '.woff', '.woff2', '.ttf', '.eot', '.class', '.jar', '.war', '.o', '.a', '.lib', ]); /** * Directories to exclude in grep searches */ export const GREP_EXCLUDE_DIRS = [ 'node_modules', '.git', 'dist', 'build', '__pycache__', 'target', '.next', '.nuxt', 'coverage', ]; /** * Recent file threshold (24 hours in milliseconds) */ export const RECENT_FILE_THRESHOLD = 24 * 60 * 60 * 1000; /** * Maximum cache size for file content cache */ export const MAX_FILE_CACHE_SIZE = 50; /** * Maximum cache size for file stat cache * Prevents recency sorting cache from growing without bound */ export const MAX_FILE_STAT_CACHE_SIZE = 500; /** * Idle lifetime for ACE in-memory caches (2 minutes) * Releases symbol indexes and other transient search data when unused */ export const ACE_IDLE_CLEANUP_MS = 2 * 60 * 1000; /** * Maximum number of files kept in the semantic symbol index * Prevents ace-search (action=semantic_search) from exhausting memory on very large workspaces */ export const MAX_INDEXED_FILES = 2000; /** * Maximum number of symbols indexed per file for semantic search * Large generated files can otherwise dominate the in-memory index */ export const MAX_SYMBOLS_PER_FILE = 100; /** * Maximum number of unique symbol names used to build the FZF index * Above this threshold we fall back to manual scoring to avoid large heap spikes */ export const MAX_FZF_SYMBOL_NAMES = 30000; /** * Default maximum symbols returned by action=file_outline. * Prevents large files from producing huge tool results when maxResults is omitted. */ export const MAX_FILE_OUTLINE_SYMBOLS = 200; /** * Maximum serialized payload size for action=file_outline before dropping context/signature. * This is a source-level guard before the global token limiter runs. */ export const MAX_FILE_OUTLINE_PAYLOAD_CHARS = 120_000; /** * File size threshold for switching to chunked reading (1MB) * Files smaller than this are read entirely into memory * Files larger than this are processed in chunks to control memory usage */ export const LARGE_FILE_THRESHOLD = 1024 * 1024; /** * Chunk size for reading large files (512KB) * Balances between memory usage and read efficiency */ export const FILE_READ_CHUNK_SIZE = 512 * 1024; /** * Maximum time allowed for text search in milliseconds (30 seconds) * Prevents runaway searches on large codebases */ export const TEXT_SEARCH_TIMEOUT_MS = 30000; /** * Maximum concurrent file reads during JavaScript fallback search * Prevents EMFILE/ENFILE errors on large directories */ export const MAX_CONCURRENT_FILE_READS = 20; /** * Maximum regex pattern complexity score (for ReDoS protection) * Patterns with higher scores are rejected to prevent catastrophic backtracking */ export const MAX_REGEX_COMPLEXITY_SCORE = 100; /** * Maximum total bytes allowed in the file content cache (50MB) * Prevents memory exhaustion when scanning large codebases */ export const MAX_CONTENT_CACHE_BYTES = 50 * 1024 * 1024; /** * RSS threshold (in bytes) for triggering aggressive memory cleanup (512MB) * When process RSS exceeds this, ACE will proactively evict caches */ export const MEMORY_PRESSURE_THRESHOLD_BYTES = 512 * 1024 * 1024; /** * Minimum interval between memory pressure checks (10 seconds) * Prevents excessive calls to process.memoryUsage() */ export const MEMORY_CHECK_INTERVAL_MS = 10_000; ================================================ FILE: source/mcp/utils/aceCodeSearch/filesystem.utils.ts ================================================ /** * Filesystem utilities for ACE Code Search */ import {promises as fs} from 'fs'; import * as path from 'path'; /** * Default exclusion directories */ export const DEFAULT_EXCLUDES = [ 'node_modules', '.git', 'dist', 'build', '__pycache__', 'target', '.next', '.nuxt', 'coverage', 'out', '.cache', 'vendor', ]; /** * Check if a directory should be excluded based on exclusion patterns * @param dirName - Directory name * @param fullPath - Full path to directory * @param basePath - Base path for relative path calculation * @param customExcludes - Custom exclusion patterns * @param regexCache - Cache for compiled regex patterns * @returns True if directory should be excluded */ export function shouldExcludeDirectory( dirName: string, fullPath: string, basePath: string, customExcludes: string[], regexCache: Map<string, RegExp>, ): boolean { // Check default excludes if (DEFAULT_EXCLUDES.includes(dirName)) { return true; } // Check hidden directories if (dirName.startsWith('.')) { return true; } // Check custom exclusion patterns const relativePath = path.relative(basePath, fullPath); for (const pattern of customExcludes) { // Simple pattern matching: exact match or glob-style wildcards if (pattern.includes('*')) { // Use cached regex to avoid recompilation let regex = regexCache.get(pattern); if (!regex) { const regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*'); regex = new RegExp(`^${regexPattern}$`); regexCache.set(pattern, regex); } if (regex.test(relativePath) || regex.test(dirName)) { return true; } } else { // Exact match if ( relativePath === pattern || dirName === pattern || relativePath.startsWith(pattern + '/') ) { return true; } } } return false; } /** * Check if a file should be excluded based on exclusion patterns * @param fileName - File name * @param fullPath - Full path to file * @param basePath - Base path for relative path calculation * @param customExcludes - Custom exclusion patterns * @param regexCache - Cache for compiled regex patterns * @returns True if file should be excluded */ export function shouldExcludeFile( fileName: string, fullPath: string, basePath: string, customExcludes: string[], regexCache: Map<string, RegExp>, ): boolean { // Skip most hidden files (starting with .) // But allow common config files if (fileName.startsWith('.')) { const allowedHiddenFiles = [ '.env', '.gitignore', '.eslintrc', '.prettierrc', '.babelrc', '.editorconfig', '.npmrc', '.yarnrc', ]; const isAllowedConfig = allowedHiddenFiles.some( allowed => fileName === allowed || fileName.startsWith(allowed + '.') || fileName.endsWith('rc.js') || fileName.endsWith('rc.json') || fileName.endsWith('rc.yaml') || fileName.endsWith('rc.yml'), ); if (!isAllowedConfig) { return true; } } // Check custom exclusion patterns from .gitignore/.snowignore const relativePath = path.relative(basePath, fullPath); for (const pattern of customExcludes) { // Skip directory-only patterns (ending with /) if (pattern.endsWith('/')) { continue; } // Pattern matching: exact match or glob-style wildcards if (pattern.includes('*')) { // Use cached regex to avoid recompilation let regex = regexCache.get(pattern); if (!regex) { const regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*'); regex = new RegExp(`^${regexPattern}$`); regexCache.set(pattern, regex); } if (regex.test(relativePath) || regex.test(fileName)) { return true; } } else { // Exact match for file name or relative path if (relativePath === pattern || fileName === pattern) { return true; } // Check if file matches path prefix pattern if (relativePath.startsWith(pattern + '/')) { return true; } } } return false; } /** * Load custom exclusion patterns from .gitignore and .snowignore * @param basePath - Base path to search for ignore files * @returns Array of exclusion patterns */ export async function loadExclusionPatterns( basePath: string, ): Promise<string[]> { const patterns: string[] = []; // Load .gitignore if exists const gitignorePath = path.join(basePath, '.gitignore'); try { const gitignoreContent = await fs.readFile(gitignorePath, 'utf-8'); const lines = gitignoreContent.split('\n'); for (const line of lines) { const trimmed = line.trim(); // Skip empty lines and comments if (trimmed && !trimmed.startsWith('#')) { // Remove leading slash and trailing slash const pattern = trimmed.replace(/^\//, '').replace(/\/$/, ''); if (pattern) { patterns.push(pattern); } } } } catch { // .gitignore doesn't exist or cannot be read, skip } // Load .snowignore if exists const snowignorePath = path.join(basePath, '.snowignore'); try { const snowignoreContent = await fs.readFile(snowignorePath, 'utf-8'); const lines = snowignoreContent.split('\n'); for (const line of lines) { const trimmed = line.trim(); // Skip empty lines and comments if (trimmed && !trimmed.startsWith('#')) { // Remove leading slash and trailing slash const pattern = trimmed.replace(/^\//, '').replace(/\/$/, ''); if (pattern) { patterns.push(pattern); } } } } catch { // .snowignore doesn't exist or cannot be read, skip } return patterns; } export interface ContentCacheCallbacks { onAdd?: (filePath: string, content: string, mtime: number) => void; onEvict?: (filePath: string) => void; } /** * Read file with LRU cache to reduce repeated file system access * @param filePath - Path to file * @param fileContentCache - Cache for file contents * @param maxCacheSize - Maximum cache size (entry count) * @param callbacks - Optional callbacks for byte tracking * @returns File content */ export async function readFileWithCache( filePath: string, fileContentCache: Map<string, {content: string; mtime: number}>, maxCacheSize: number = 50, callbacks?: ContentCacheCallbacks, ): Promise<string> { const stats = await fs.stat(filePath); const mtime = stats.mtimeMs; // Check cache const cached = fileContentCache.get(filePath); if (cached && cached.mtime === mtime) { return cached.content; } // Read file const content = await fs.readFile(filePath, 'utf-8'); // Evict oldest entry if over limit if (fileContentCache.size >= maxCacheSize) { const firstKey = fileContentCache.keys().next().value; if (firstKey) { callbacks?.onEvict?.(firstKey); fileContentCache.delete(firstKey); } } // Cache the content fileContentCache.set(filePath, {content, mtime}); callbacks?.onAdd?.(filePath, content, mtime); return content; } /** * Check if a directory is a Git repository * @param directory - Directory path to check * @returns True if directory contains .git folder */ export async function isGitRepository( directory: string = process.cwd(), ): Promise<boolean> { try { const gitDir = path.join(directory, '.git'); const stats = await fs.stat(gitDir); return stats.isDirectory(); } catch { return false; } } ================================================ FILE: source/mcp/utils/aceCodeSearch/language.utils.ts ================================================ /** * Language configuration utilities for ACE Code Search */ import type {LanguageConfig} from '../../types/aceCodeSearch.types.js'; /** * Language-specific parsers configuration */ export const LANGUAGE_CONFIG: Record<string, LanguageConfig> = { typescript: { extensions: ['.ts', '.tsx', '.mts', '.cts'], parser: 'typescript', symbolPatterns: { function: /(?:export\s+)?(?:async\s+)?(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*=>)|(?:@\w+\s+)*(?:public|private|protected|static)?\s*(?:async)?\s*(\w+)\s*[<(]/, class: /(?:export\s+)?(?:abstract\s+)?(?:class|interface)\s+(\w+)|(?:export\s+)?type\s+(\w+)\s*=|(?:export\s+)?enum\s+(\w+)|(?:export\s+)?namespace\s+(\w+)/, variable: /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*(?::|=)|(?:@\w+\s+)*(?:public|private|protected|readonly|static)?\s+(\w+)\s*[?:]/, import: /import\s+(?:type\s+)?(?:{[^}]+}|\w+|\*\s+as\s+\w+)\s+from\s+['"]([^'"]+)['"]/, export: /export\s+(?:default\s+)?(?:class|function|const|let|var|interface|type|enum|namespace|abstract\s+class)\s+(\w+)/, }, }, javascript: { extensions: ['.js', '.jsx', '.mjs', '.cjs', '.es', '.es6'], parser: 'javascript', symbolPatterns: { function: /(?:export\s+)?(?:async\s+)?(?:function\s*\*?\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:function\s*\*?\s*)?(?:\([^)]*\)\s*=>|\([^)]*\)\s*\{))|(\w+)\s*\([^)]*\)\s*\{/, class: /(?:export\s+)?class\s+(\w+)/, variable: /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=/, import: /import\s+(?:{[^}]+}|\w+|\*\s+as\s+\w+)\s+from\s+['"]([^'"]+)['"]/, export: /export\s+(?:default\s+)?(?:class|function|const|let|var)\s+(\w+)/, }, }, python: { extensions: ['.py', '.pyx', '.pyi', '.pyw', '.pyz'], parser: 'python', symbolPatterns: { function: /(?:@\w+\s+)*(?:async\s+)?def\s+(\w+)\s*\(/, class: /(?:@\w+\s+)*class\s+(\w+)\s*[(:]/, variable: /^(?:[\t ]*)([\w_][\w\d_]*)\s*(?::.*)?=\s*(?![=\s])|^([\w_][\w\d_]*)\s*:\s*(?!.*=)/m, import: /(?:from\s+([\w.]+)\s+import\s+[\w, *]+|import\s+([\w.]+(?:\s+as\s+\w+)?))/, export: /^(?:__all__\s*=|def\s+(\w+)|class\s+(\w+))/, // Python exports via __all__ or top-level }, }, go: { extensions: ['.go'], parser: 'go', symbolPatterns: { function: /func\s+(?:\([^)]+\)\s+)?(\w+)\s*[<(]/, class: /type\s+(\w+)\s+(?:struct|interface)/, variable: /(?:var|const)\s+(\w+)\s+[\w\[\]*{]|(?:var|const)\s+\(\s*(\w+)/, import: /import\s+(?:"([^"]+)"|_\s+"([^"]+)"|\w+\s+"([^"]+)")/, export: /^(?:func|type|var|const)\s+([A-Z]\w+)|^type\s+([A-Z]\w+)\s+(?:struct|interface)/, // Go exports start with capital letter }, }, rust: { extensions: ['.rs'], parser: 'rust', symbolPatterns: { function: /(?:pub(?:\s*\([^)]+\))?\s+)?(?:unsafe\s+)?(?:async\s+)?(?:const\s+)?(?:extern\s+(?:"[^"]+"\s+)?)?fn\s+(\w+)\s*[<(]/, class: /(?:pub(?:\s*\([^)]+\))?\s+)?(?:struct|enum|trait|union|type)\s+(\w+)|impl(?:\s+<[^>]+>)?\s+(?:\w+::)*(\w+)/, variable: /(?:pub(?:\s*\([^)]+\))?\s+)?(?:static|const|mut)?\s*(?:let\s+(?:mut\s+)?)?(\w+)\s*[:=]/, import: /use\s+([^;]+);|extern\s+crate\s+(\w+);/, export: /pub(?:\s*\([^)]+\))?\s+(?:fn|struct|enum|trait|const|static|type|mod|use)\s+(\w+)/, }, }, java: { extensions: ['.java'], parser: 'java', symbolPatterns: { function: /(?:@\w+\s+)*(?:public|private|protected|static|final|synchronized|native|abstract|\s)+[\w<>\[\]]+\s+(\w+)\s*\([^)]*\)\s*(?:throws\s+[\w,\s]+)?\s*[{;]/, class: /(?:@\w+\s+)*(?:public|private|protected)?\s*(?:abstract|final|static)?\s*(?:class|interface|enum|record|@interface)\s+(\w+)/, variable: /(?:@\w+\s+)*(?:public|private|protected|static|final|transient|volatile|\s)+[\w<>\[\]]+\s+(\w+)\s*[=;]/, import: /import\s+(?:static\s+)?([\w.*]+);/, export: /public\s+(?:class|interface|enum|record|@interface)\s+(\w+)/, }, }, csharp: { extensions: ['.cs'], parser: 'csharp', symbolPatterns: { function: /(?:\[[\w\s,()]+\]\s+)*(?:public|private|protected|internal|static|virtual|override|abstract|async|\s)+[\w<>\[\]?]+\s+(\w+)\s*[<(]/, class: /(?:\[[\w\s,()]+\]\s+)*(?:public|private|protected|internal)?\s*(?:abstract|sealed|static|partial)?\s*(?:class|interface|struct|record|enum)\s+(\w+)/, variable: /(?:\[[\w\s,()]+\]\s+)*(?:public|private|protected|internal|static|readonly|const|volatile|\s)+[\w<>\[\]?]+\s+(\w+)\s*[{=;]|(?:public|private|protected|internal)?\s*[\w<>\[\]?]+\s+(\w+)\s*\{\s*get/, import: /using\s+(?:static\s+)?([\w.]+);/, export: /public\s+(?:class|interface|enum|struct|record|delegate)\s+(\w+)/, }, }, c: { extensions: ['.c', '.h'], parser: 'c', symbolPatterns: { function: /(?:static|extern|inline)?\s*[\w\s\*]+\s+(\w+)\s*\([^)]*\)\s*\{/, class: /(?:struct|union|enum)\s+(\w+)\s*\{/, variable: /(?:extern|static|const)?\s*[\w\s\*]+\s+(\w+)\s*[=;]/, import: /#include\s+[<"]([^>"]+)[>"]/, export: /^[\w\s\*]+\s+(\w+)\s*\([^)]*\)\s*;/, // Function declarations }, }, cpp: { extensions: ['.cpp', '.cc', '.cxx', '.hpp', '.hh', '.hxx', '.h++', '.c++'], parser: 'cpp', symbolPatterns: { function: /(?:static|extern|inline|virtual|explicit|constexpr)?\s*[\w\s\*&:<>,]+\s+(\w+)\s*\([^)]*\)\s*(?:const)?\s*(?:override)?\s*\{/, class: /(?:class|struct|union|enum\s+class|enum\s+struct)\s+(\w+)(?:\s*:\s*(?:public|private|protected)\s+[\w,\s<>]+)?\s*\{/, variable: /(?:extern|static|const|constexpr|inline)?\s*[\w\s\*&:<>,]+\s+(\w+)\s*[=;]/, import: /#include\s+[<"]([^>"]+)[>"]/, export: /^[\w\s\*&:<>,]+\s+(\w+)\s*\([^)]*\)\s*;/, }, }, php: { extensions: ['.php', '.phtml', '.php3', '.php4', '.php5', '.phps'], parser: 'php', symbolPatterns: { function: /(?:public|private|protected|static)?\s*function\s+(\w+)\s*\(/, class: /(?:abstract|final)?\s*class\s+(\w+)(?:\s+extends\s+\w+)?(?:\s+implements\s+[\w,\s]+)?\s*\{/, variable: /(?:public|private|protected|static)?\s*\$(\w+)\s*[=;]/, import: /(?:require|require_once|include|include_once)\s*[('"]([^'"]+)['"]/, export: /^(?:public\s+)?(?:function|class|interface|trait)\s+(\w+)/, }, }, ruby: { extensions: ['.rb', '.rake', '.gemspec', '.ru', '.rbw'], parser: 'ruby', symbolPatterns: { function: /def\s+(?:self\.)?(\w+)/, class: /class\s+(\w+)(?:\s+<\s+[\w:]+)?/, variable: /(?:@|@@|\$)?(\w+)\s*=(?!=)/, import: /require(?:_relative)?\s+['"]([^'"]+)['"]/, export: /module_function\s+:(\w+)|^def\s+(\w+)/, // Ruby's module exports }, }, swift: { extensions: ['.swift'], parser: 'swift', symbolPatterns: { function: /(?:public|private|internal|fileprivate|open)?\s*(?:static|class)?\s*func\s+(\w+)\s*[<(]/, class: /(?:public|private|internal|fileprivate|open)?\s*(?:final)?\s*(?:class|struct|enum|protocol|actor)\s+(\w+)/, variable: /(?:public|private|internal|fileprivate|open)?\s*(?:static|class)?\s*(?:let|var)\s+(\w+)\s*[:=]/, import: /import\s+(?:class|struct|enum|protocol)?\s*([\w.]+)/, export: /public\s+(?:func|class|struct|enum|protocol|var|let)\s+(\w+)/, }, }, kotlin: { extensions: ['.kt', '.kts'], parser: 'kotlin', symbolPatterns: { function: /(?:public|private|protected|internal)?\s*(?:suspend|inline|infix|operator)?\s*fun\s+(\w+)\s*[<(]/, class: /(?:public|private|protected|internal)?\s*(?:abstract|open|final|sealed|data|inline|value)?\s*(?:class|interface|object|enum\s+class)\s+(\w+)/, variable: /(?:public|private|protected|internal)?\s*(?:const)?\s*(?:val|var)\s+(\w+)\s*[:=]/, import: /import\s+([\w.]+)/, export: /^(?:public\s+)?(?:fun|class|interface|object|val|var)\s+(\w+)/, }, }, dart: { extensions: ['.dart'], parser: 'dart', symbolPatterns: { function: /(?:static|abstract|external)?\s*[\w<>?,\s]+\s+(\w+)\s*\([^)]*\)\s*(?:async|sync\*)?\s*\{/, class: /(?:abstract)?\s*class\s+(\w+)(?:\s+extends\s+[\w<>]+)?(?:\s+with\s+[\w,\s<>]+)?(?:\s+implements\s+[\w,\s<>]+)?\s*\{/, variable: /(?:static|final|const|late)?\s*(?:var|[\w<>?,\s]+)\s+(\w+)\s*[=;]/, import: /import\s+['"]([^'"]+)['"]/, export: /^(?:class|abstract\s+class|enum|mixin)\s+(\w+)/, }, }, shell: { extensions: ['.sh', '.bash', '.zsh', '.ksh', '.fish'], parser: 'shell', symbolPatterns: { function: /(?:function\s+)?(\w+)\s*\(\s*\)\s*\{/, class: /^$/, // Shell doesn't have classes variable: /(?:export\s+)?(\w+)=/, import: /(?:source|\.)\s+([^\s;]+)/, export: /export\s+(?:function\s+)?(\w+)/, }, }, scala: { extensions: ['.scala', '.sc'], parser: 'scala', symbolPatterns: { function: /def\s+(\w+)\s*[:\[(]/, class: /(?:sealed|abstract|final|implicit)?\s*(?:class|trait|object|case\s+class|case\s+object)\s+(\w+)/, variable: /(?:val|var|lazy\s+val)\s+(\w+)\s*[:=]/, import: /import\s+([\w.{},\s=>]+)/, export: /^(?:object|class|trait)\s+(\w+)/, }, }, r: { extensions: ['.r', '.R', '.rmd', '.Rmd'], parser: 'r', symbolPatterns: { function: /(\w+)\s*<-\s*function\s*\(|^(\w+)\s*=\s*function\s*\(/, class: /setClass\s*\(\s*['"](\w+)['"]/, variable: /(\w+)\s*(?:<-|=)\s*(?!function)/, import: /(?:library|require)\s*\(\s*['"]?(\w+)['"]?\s*\)/, export: /^(\w+)\s*<-\s*function/, // R exports at top level }, }, lua: { extensions: ['.lua'], parser: 'lua', symbolPatterns: { function: /(?:local\s+)?function\s+(?:[\w.]+[.:])?(\w+)\s*\(/, class: /(\w+)\s*=\s*\{\s*\}|(\w+)\s*=\s*class\s*\(/, variable: /(?:local\s+)?(\w+)\s*=/, import: /require\s*\(?['"]([^'"]+)['"]\)?/, export: /return\s+(\w+)|module\s*\(\s*['"]([^'"]+)['"]/, }, }, perl: { extensions: ['.pl', '.pm', '.t', '.pod'], parser: 'perl', symbolPatterns: { function: /sub\s+(\w+)\s*\{/, class: /package\s+([\w:]+)\s*;/, variable: /(?:my|our|local)\s*[\$@%](\w+)\s*=/, import: /(?:use|require)\s+([\w:]+)/, export: /^sub\s+(\w+)|our\s+[\$@%](\w+)/, }, }, objectivec: { extensions: ['.m', '.mm', '.h'], parser: 'objectivec', symbolPatterns: { function: /[-+]\s*\([^)]+\)\s*(\w+)(?::|;|\s*\{)/, class: /@(?:interface|implementation|protocol)\s+(\w+)/, variable: /@property\s+[^;]+\s+(\w+);|^[\w\s\*]+\s+(\w+)\s*[=;]/, import: /#import\s+[<"]([^>"]+)[>"]/, export: /@interface\s+(\w+)|@protocol\s+(\w+)/, }, }, haskell: { extensions: ['.hs', '.lhs'], parser: 'haskell', symbolPatterns: { function: /^(\w+)\s*::/, class: /(?:class|instance)\s+(\w+)/, variable: /^(\w+)\s*=/, import: /import\s+(?:qualified\s+)?([\w.]+)/, export: /module\s+[\w.]+\s*\(([^)]+)\)/, }, }, elixir: { extensions: ['.ex', '.exs'], parser: 'elixir', symbolPatterns: { function: /def(?:p|macro|macrop)?\s+(\w+)(?:\(|,|\s+do)/, class: /defmodule\s+([\w.]+)\s+do/, variable: /@(\w+)\s+|(\w+)\s*=\s*(?!fn)/, import: /(?:import|alias|require|use)\s+([\w.]+)/, export: /^def\s+(\w+)/, }, }, clojure: { extensions: ['.clj', '.cljs', '.cljc', '.edn'], parser: 'clojure', symbolPatterns: { function: /\(defn-?\s+(\w+)/, class: /\(defrecord\s+(\w+)|\(deftype\s+(\w+)|\(defprotocol\s+(\w+)/, variable: /\(def\s+(\w+)/, import: /\(:require\s+\[([^\]]+)\]/, export: /\(defn-?\s+(\w+)/, }, }, fsharp: { extensions: ['.fs', '.fsx', '.fsi'], parser: 'fsharp', symbolPatterns: { function: /let\s+(?:rec\s+)?(\w+)(?:\s+\w+)*\s*=/, class: /type\s+(\w+)\s*(?:=|<|\()/, variable: /let\s+(?:mutable\s+)?(\w+)\s*=/, import: /open\s+([\w.]+)/, export: /^(?:let|type)\s+(\w+)/, }, }, vbnet: { extensions: ['.vb', '.vbs'], parser: 'vbnet', symbolPatterns: { function: /(?:Public|Private|Protected|Friend)?\s*(?:Shared)?\s*(?:Function|Sub)\s+(\w+)/i, class: /(?:Public|Private|Protected|Friend)?\s*(?:MustInherit|NotInheritable)?\s*Class\s+(\w+)/i, variable: /(?:Public|Private|Protected|Friend|Dim|Const)?\s*(\w+)\s+As\s+/i, import: /Imports\s+([\w.]+)/i, export: /Public\s+(?:Class|Module|Function|Sub)\s+(\w+)/i, }, }, matlab: { extensions: ['.m', '.mlx'], parser: 'matlab', symbolPatterns: { function: /function\s+(?:\[[^\]]+\]\s*=\s*|[\w,\s]+\s*=\s*)?(\w+)\s*\(/, class: /classdef\s+(\w+)/, variable: /(\w+)\s*=\s*(?!function)/, import: /import\s+([\w.*]+)/, export: /^function\s+(?:\[[^\]]+\]\s*=\s*)?(\w+)/, }, }, sql: { extensions: ['.sql', '.ddl', '.dml'], parser: 'sql', symbolPatterns: { function: /CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE)\s+(\w+)/i, class: /CREATE\s+(?:TABLE|VIEW)\s+(\w+)/i, variable: /DECLARE\s+@?(\w+)/i, import: /^$/, // SQL doesn't have imports export: /^CREATE\s+(?:FUNCTION|PROCEDURE|VIEW)\s+(\w+)/i, }, }, html: { extensions: ['.html', '.htm', '.xhtml'], parser: 'html', symbolPatterns: { function: /<script[^>]*>[\s\S]*?function\s+(\w+)/, class: /class\s*=\s*["']([^"']+)["']/, variable: /id\s*=\s*["']([^"']+)["']/, import: /<(?:link|script)[^>]+(?:href|src)\s*=\s*["']([^"']+)["']/, export: /<(?:div|section|article|header|footer)[^>]+id\s*=\s*["']([^"']+)["']/, }, }, css: { extensions: ['.css', '.scss', '.sass', '.less', '.styl'], parser: 'css', symbolPatterns: { function: /@mixin\s+(\w+)|@function\s+(\w+)/, class: /\.(\w+(?:-\w+)*)\s*\{/, variable: /--(\w+(?:-\w+)*):|@(\w+):|(\$\w+):/, import: /@import\s+(?:url\()?['"]([^'"]+)['"]/, export: /@mixin\s+(\w+)|@function\s+(\w+)/, }, }, vue: { extensions: ['.vue'], parser: 'vue', symbolPatterns: { function: /<script[^>]*>[\s\S]*?(?:export\s+default\s*\{[\s\S]*?)?(?:function|const|let|var)\s+(\w+)|methods\s*:\s*\{[\s\S]*?(\w+)\s*\(/, class: /<template[^>]*>[\s\S]*?<(\w+)/, variable: /<script[^>]*>[\s\S]*?(?:data\s*\(\s*\)\s*\{[\s\S]*?return\s*\{[\s\S]*?(\w+)|(?:const|let|var)\s+(\w+)\s*=)/, import: /<script[^>]*>[\s\S]*?import\s+(?:{[^}]+}|\w+)\s+from\s+['"]([^'"]+)['"]/, export: /<script[^>]*>[\s\S]*?export\s+default/, }, }, svelte: { extensions: ['.svelte'], parser: 'svelte', symbolPatterns: { function: /<script[^>]*>[\s\S]*?(?:function|const|let|var)\s+(\w+)\s*[=(]/, class: /<[\w-]+/, variable: /<script[^>]*>[\s\S]*?(?:let|const|var)\s+(\w+)\s*=/, import: /<script[^>]*>[\s\S]*?import\s+(?:{[^}]+}|\w+)\s+from\s+['"]([^'"]+)['"]/, export: /<script[^>]*>[\s\S]*?export\s+(?:let|const|function)\s+(\w+)/, }, }, xml: { extensions: ['.xml', '.xsd', '.xsl', '.xslt', '.svg'], parser: 'xml', symbolPatterns: { function: /<xsl:template[^>]+name\s*=\s*["']([^"']+)["']/, class: /<(?:xsd:)?(?:complexType|simpleType)[^>]+name\s*=\s*["']([^"']+)["']/, variable: /<(?:xsd:)?element[^>]+name\s*=\s*["']([^"']+)["']/, import: /<(?:xsd:)?import[^>]+schemaLocation\s*=\s*["']([^"']+)["']/, export: /<(?:xsd:)?element[^>]+name\s*=\s*["']([^"']+)["']/, }, }, yaml: { extensions: ['.yaml', '.yml'], parser: 'yaml', symbolPatterns: { function: /^(\w+):\s*\|/m, class: /^(\w+):$/m, variable: /^(\w+):\s*[^|>]/m, import: /^$/, // YAML doesn't have imports export: /^(\w+):$/m, }, }, json: { extensions: ['.json', '.jsonc', '.json5'], parser: 'json', symbolPatterns: { function: /^$/, class: /^$/, variable: /"(\w+)"\s*:/, import: /^$/, export: /^$/, }, }, toml: { extensions: ['.toml'], parser: 'toml', symbolPatterns: { function: /^$/, class: /^\[(\w+(?:\.\w+)*)\]/, variable: /^(\w+)\s*=/, import: /^$/, export: /^\[(\w+(?:\.\w+)*)\]/, }, }, markdown: { extensions: ['.md', '.markdown', '.mdown', '.mkd'], parser: 'markdown', symbolPatterns: { function: /```[\w]*\n[\s\S]*?function\s+(\w+)/, class: /^#{1,6}\s+(.+)$/m, variable: /\[([^\]]+)\]:/, import: /\[([^\]]+)\]\(([^)]+)\)/, export: /^#{1,6}\s+(.+)$/m, }, }, }; /** * Detect programming language from file extension * @param filePath - File path to detect language from * @returns Language name or null if not supported */ export function detectLanguage(filePath: string): string | null { const ext = filePath.substring(filePath.lastIndexOf('.')).toLowerCase(); for (const [lang, config] of Object.entries(LANGUAGE_CONFIG)) { if (config.extensions.includes(ext)) { return lang; } } return null; } ================================================ FILE: source/mcp/utils/aceCodeSearch/search.utils.ts ================================================ /** * Search utilities for ACE Code Search */ import {spawn} from 'child_process'; import {EOL} from 'os'; import * as path from 'path'; import type {TextSearchResult} from '../../types/aceCodeSearch.types.js'; /** * Check if a command is available in the system PATH * @param command - Command to check * @returns Promise resolving to true if command is available */ export function isCommandAvailable(command: string): Promise<boolean> { return new Promise(resolve => { try { let child; if (process.platform === 'win32') { // Windows: where is an executable, no shell needed child = spawn('where', [command], { stdio: 'ignore', windowsHide: true, }); } else { // Unix/Linux: Use 'which' command instead of 'command -v' // 'which' is an external executable, not a shell builtin child = spawn('which', [command], { stdio: 'ignore', }); } child.on('close', code => resolve(code === 0)); child.on('error', () => resolve(false)); } catch { resolve(false); } }); } /** * Parse grep output (format: filePath:lineNumber:lineContent) * @param output - Grep output string * @param basePath - Base path for relative path calculation * @returns Array of search results */ export function parseGrepOutput( output: string, basePath: string, ): TextSearchResult[] { const results: TextSearchResult[] = []; if (!output) return results; const lines = output.split(EOL); for (const line of lines) { if (!line.trim()) continue; // Find first and second colon indices const firstColonIndex = line.indexOf(':'); if (firstColonIndex === -1) continue; const secondColonIndex = line.indexOf(':', firstColonIndex + 1); if (secondColonIndex === -1) continue; // Extract parts const filePathRaw = line.substring(0, firstColonIndex); const lineNumberStr = line.substring(firstColonIndex + 1, secondColonIndex); const lineContent = line.substring(secondColonIndex + 1); const lineNumber = parseInt(lineNumberStr, 10); if (isNaN(lineNumber)) continue; const absoluteFilePath = path.resolve(basePath, filePathRaw); const relativeFilePath = path.relative(basePath, absoluteFilePath); results.push({ filePath: relativeFilePath || path.basename(absoluteFilePath), line: lineNumber, column: 1, // grep doesn't provide column info, default to 1 content: lineContent.trim(), }); } return results; } /** * Convert glob pattern to RegExp * Supports: *, **, ?, [abc], {js,ts} * @param glob - Glob pattern * @returns Regular expression */ export function globToRegex(glob: string): RegExp { // Escape special regex characters except glob wildcards let pattern = glob .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape regex special chars .replace(/\*\*/g, '<<<DOUBLESTAR>>>') // Temporarily replace ** .replace(/\*/g, '[^/]*') // * matches anything except / .replace(/<<<DOUBLESTAR>>>/g, '.*') // ** matches everything .replace(/\?/g, '[^/]'); // ? matches single char except / // Handle {js,ts} alternatives pattern = pattern.replace(/\\{([^}]+)\\}/g, (_, alternatives) => { return '(' + alternatives.split(',').join('|') + ')'; }); // Handle [abc] character classes (already valid regex) pattern = pattern.replace(/\\\[([^\]]+)\\\]/g, '[$1]'); return new RegExp(pattern, 'i'); } /** * Calculate fuzzy match score for symbol name * @param symbolName - Symbol name to score * @param query - Search query * @returns Score (0-100, higher is better) */ export function calculateFuzzyScore(symbolName: string, query: string): number { const nameLower = symbolName.toLowerCase(); const queryLower = query.toLowerCase(); // Exact match if (nameLower === queryLower) return 100; // Starts with if (nameLower.startsWith(queryLower)) return 80; // Contains if (nameLower.includes(queryLower)) return 60; // Camel case match (e.g., "gfc" matches "getFileContent") const camelCaseMatch = symbolName .split(/(?=[A-Z])/) .map(s => s[0]?.toLowerCase() || '') .join(''); if (camelCaseMatch.includes(queryLower)) return 40; // Fuzzy match let score = 0; let queryIndex = 0; for (let i = 0; i < nameLower.length && queryIndex < queryLower.length; i++) { if (nameLower[i] === queryLower[queryIndex]) { score += 20; queryIndex++; } } if (queryIndex === queryLower.length) return score; return 0; } /** * Expand glob patterns with braces like "*.{ts,tsx}" into multiple patterns * @param glob - Glob pattern with braces * @returns Array of expanded patterns */ export function expandGlobBraces(glob: string): string[] { // Match {a,b,c} pattern const braceMatch = glob.match(/^(.+)\{([^}]+)\}(.*)$/); if ( !braceMatch || !braceMatch[1] || !braceMatch[2] || braceMatch[3] === undefined ) { return [glob]; } const prefix = braceMatch[1]; const alternatives = braceMatch[2].split(','); const suffix = braceMatch[3]; return alternatives.map(alt => `${prefix}${alt}${suffix}`); } /** * Convert a glob pattern to a RegExp that matches full paths * Supports: *, **, ?, {a,b}, [abc] * @param globPattern - Glob pattern string * @returns Regular expression for matching */ export function globPatternToRegex(globPattern: string): RegExp { // Normalize path separators const normalizedGlob = globPattern.replace(/\\/g, '/'); // First, temporarily replace glob special patterns with placeholders // to prevent them from being escaped let regexStr = normalizedGlob .replace(/\*\*/g, '\x00DOUBLESTAR\x00') // ** -> placeholder .replace(/\*/g, '\x00STAR\x00') // * -> placeholder .replace(/\?/g, '\x00QUESTION\x00'); // ? -> placeholder // Now escape all special regex characters regexStr = regexStr.replace(/[.+^${}()|[\]\\]/g, '\\$&'); // Replace placeholders with actual regex patterns regexStr = regexStr .replace(/\x00DOUBLESTAR\x00/g, '.*') // ** -> .* (match any path segments) .replace(/\x00STAR\x00/g, '[^/]*') // * -> [^/]* (match within single segment) .replace(/\x00QUESTION\x00/g, '.'); // ? -> . (match single character) return new RegExp(regexStr, 'i'); } /** * Calculate regex pattern complexity score for ReDoS protection * Higher scores indicate higher risk of catastrophic backtracking * @param pattern - Regex pattern string * @returns Complexity score (0 = safe, >100 = dangerous) */ export function calculateRegexComplexity(pattern: string): number { let score = 0; // Count nested quantifiers (e.g., (a+)+, (a*)*) const nestedQuantifierPattern = /\([^)]*[+?*]\)[+?*]/g; const nestedMatches = pattern.match(nestedQuantifierPattern); if (nestedMatches) { score += nestedMatches.length * 30; } // Count overlapping quantifiers (e.g., a+a*, a*a?) const overlappingPattern = /[+?*][+?*]/g; const overlappingMatches = pattern.match(overlappingPattern); if (overlappingMatches) { score += overlappingMatches.length * 20; } // Count alternations inside groups with quantifiers const altInGroupPattern = /\([^)]*\|[^)]*\)[+?*]/g; const altMatches = pattern.match(altInGroupPattern); if (altMatches) { score += altMatches.length * 25; } // Count nested groups with quantifiers const depth = (pattern.match(/\(/g) || []).length; if (depth > 3) { score += (depth - 3) * 10; } // Penalize patterns with many wildcards const wildcardCount = (pattern.match(/\.\*/g) || []).length; if (wildcardCount > 5) { score += (wildcardCount - 5) * 5; } return score; } /** * Check if a regex pattern is safe from ReDoS attacks * @param pattern - Regex pattern string * @param maxComplexity - Maximum allowed complexity score * @returns Object with isSafe flag and reason if unsafe */ export function isSafeRegexPattern( pattern: string, maxComplexity: number = 100, ): {isSafe: boolean; reason?: string} { try { // Test if pattern is valid regex new RegExp(pattern); } catch (error) { return {isSafe: false, reason: 'Invalid regex pattern'}; } const complexity = calculateRegexComplexity(pattern); if (complexity > maxComplexity) { return { isSafe: false, reason: `Pattern too complex (score: ${complexity}, max: ${maxComplexity}). Simplify to avoid ReDoS attacks.`, }; } return {isSafe: true}; } /** * Process an array of items with limited concurrency * Prevents EMFILE/ENFILE errors when processing many files * @param items - Array of items to process * @param processor - Async function to process each item * @param concurrency - Maximum concurrent operations * @returns Array of results */ export async function processWithConcurrency<T, R>( items: T[], processor: (item: T) => Promise<R>, concurrency: number = 10, ): Promise<R[]> { const results: R[] = new Array(items.length); let index = 0; async function processNext(): Promise<void> { const currentIndex = index++; if (currentIndex >= items.length) return; results[currentIndex] = await processor(items[currentIndex]!); await processNext(); } // Start initial batch of workers const workers = Array(Math.min(concurrency, items.length)) .fill(null) .map(() => processNext()); await Promise.all(workers); return results; } /** * Create a timeout promise that rejects after specified milliseconds * @param ms - Timeout in milliseconds * @param message - Error message * @returns Promise that rejects after timeout */ export function createTimeoutPromise( ms: number, message: string, ): Promise<never> { return new Promise((_, reject) => { setTimeout(() => reject(new Error(message)), ms); }); } /** * Sort search results by file modification time (recent files first) * Files modified within last 24 hours are prioritized * @param results - Array of search results * @param basePath - Base path for resolving file paths * @param recentThreshold - Threshold in milliseconds for recent files * @returns Sorted array of search results */ export async function sortResultsByRecency( results: TextSearchResult[], basePath: string, recentThreshold: number = 24 * 60 * 60 * 1000, ): Promise<TextSearchResult[]> { if (results.length === 0) return results; const {promises: fs} = await import('fs'); const now = Date.now(); // Get unique file paths const uniqueFiles = Array.from(new Set(results.map(r => r.filePath))); // Fetch file modification times in parallel using Promise.allSettled const statResults = await Promise.allSettled( uniqueFiles.map(async filePath => { const fullPath = path.resolve(basePath, filePath); const stats = await fs.stat(fullPath); return {filePath, mtimeMs: stats.mtimeMs}; }), ); // Build map of file modification times const fileModTimes = new Map<string, number>(); statResults.forEach((result, index) => { if (result.status === 'fulfilled') { fileModTimes.set(result.value.filePath, result.value.mtimeMs); } else { // If we can't get stats, treat as old file fileModTimes.set(uniqueFiles[index]!, 0); } }); // Sort results: recent files first, then by original order return results.sort((a, b) => { const aMtime = fileModTimes.get(a.filePath) || 0; const bMtime = fileModTimes.get(b.filePath) || 0; const aIsRecent = now - aMtime < recentThreshold; const bIsRecent = now - bMtime < recentThreshold; // Recent files come first if (aIsRecent && !bIsRecent) return -1; if (!aIsRecent && bIsRecent) return 1; // Both recent or both old: sort by modification time (newer first) if (aIsRecent && bIsRecent) return bMtime - aMtime; // Both old: maintain original order (preserve relevance from grep) return 0; }); } ================================================ FILE: source/mcp/utils/aceCodeSearch/symbol.utils.ts ================================================ /** * Symbol parsing utilities for ACE Code Search */ import * as path from 'path'; import type {CodeSymbol} from '../../types/aceCodeSearch.types.js'; import {LANGUAGE_CONFIG, detectLanguage} from './language.utils.js'; /** * Get context lines around a specific line * @param lines - All lines in file * @param lineIndex - Target line index (0-based) * @param contextSize - Number of lines before and after * @returns Context string */ export function getContext( lines: string[], lineIndex: number, contextSize: number, ): string { const start = Math.max(0, lineIndex - contextSize); const end = Math.min(lines.length, lineIndex + contextSize + 1); return lines .slice(start, end) .filter(l => l !== undefined) .join('\n') .trim(); } interface ParseFileSymbolsOptions { includeContext?: boolean; includeSignature?: boolean; maxSymbols?: number; } /** * Parse file content to extract code symbols using regex patterns * @param filePath - Path to file * @param content - File content * @param basePath - Base path for relative path calculation * @returns Array of code symbols */ export async function parseFileSymbols( filePath: string, content: string, basePath: string, options: ParseFileSymbolsOptions = {}, ): Promise<CodeSymbol[]> { const symbols: CodeSymbol[] = []; const language = detectLanguage(filePath); if (!language || !LANGUAGE_CONFIG[language]) { return symbols; } const {includeContext = true, includeSignature = true, maxSymbols} = options; const config = LANGUAGE_CONFIG[language]; const lines = content.split('\n'); const relativeFilePath = path.relative(basePath, filePath); const pushSymbol = (symbol: CodeSymbol): boolean => { symbols.push(symbol); return maxSymbols !== undefined && symbols.length >= maxSymbols; }; // Parse each line for symbols for (let i = 0; i < lines.length; i++) { const line = lines[i]; if (!line) continue; const lineNumber = i + 1; // Extract functions if (config.symbolPatterns.function) { const match = line.match(config.symbolPatterns.function); if (match) { const name = match[1] || match[2] || match[3]; if (name) { const contextLines = lines.slice(i, Math.min(i + 3, lines.length)); if ( pushSymbol({ name, type: 'function', filePath: relativeFilePath, line: lineNumber, column: line.indexOf(name) + 1, signature: includeSignature ? contextLines.join('\n').trim() : undefined, language, context: includeContext ? getContext(lines, i, 2) : undefined, }) ) { return symbols; } } } } // Extract classes if (config.symbolPatterns.class) { const match = line.match(config.symbolPatterns.class); if (match) { const name = match[1] || match[2] || match[3]; if (name) { if ( pushSymbol({ name, type: 'class', filePath: relativeFilePath, line: lineNumber, column: line.indexOf(name) + 1, signature: includeSignature ? line.trim() : undefined, language, context: includeContext ? getContext(lines, i, 2) : undefined, }) ) { return symbols; } } } } // Extract variables if (config.symbolPatterns.variable) { const match = line.match(config.symbolPatterns.variable); if (match) { const name = match[1]; if (name) { if ( pushSymbol({ name, type: 'variable', filePath: relativeFilePath, line: lineNumber, column: line.indexOf(name) + 1, signature: includeSignature ? line.trim() : undefined, language, context: includeContext ? getContext(lines, i, 1) : undefined, }) ) { return symbols; } } } } // Extract imports if (config.symbolPatterns.import) { const match = line.match(config.symbolPatterns.import); if (match) { const name = match[1] || match[2]; if (name) { if ( pushSymbol({ name, type: 'import', filePath: relativeFilePath, line: lineNumber, column: line.indexOf(name) + 1, signature: includeSignature ? line.trim() : undefined, language, }) ) { return symbols; } } } } // Extract exports if (config.symbolPatterns.export) { const match = line.match(config.symbolPatterns.export); if (match) { const name = match[1]; if (name) { if ( pushSymbol({ name, type: 'export', filePath: relativeFilePath, line: lineNumber, column: line.indexOf(name) + 1, signature: includeSignature ? line.trim() : undefined, language, }) ) { return symbols; } } } } } return symbols; } ================================================ FILE: source/mcp/utils/bash/security.utils.ts ================================================ /** * Security utilities for terminal command execution */ /** * Dangerous command patterns that should be blocked */ export const DANGEROUS_PATTERNS = [ /rm\s+-rf\s+\/[^/\s]*/i, // rm -rf / or /path />\s*\/dev\/sda/i, // writing to disk devices /mkfs/i, // format filesystem /dd\s+if=/i, // disk operations ]; /** * Check if a command contains dangerous patterns * @param command - Command to check * @returns true if command is dangerous */ export function isDangerousCommand(command: string): boolean { return DANGEROUS_PATTERNS.some(pattern => pattern.test(command)); } /** * Self-protection: detect commands that would kill the CLI's own Node.js process. * * Since this CLI runs as a Node.js process, any command that terminates * Node.js processes by name (e.g. Stop-Process, taskkill, killall, pkill) * will also kill the CLI itself, causing an abrupt crash. */ export function isSelfDestructiveCommand(command: string): { isSelfDestructive: boolean; reason?: string; suggestion?: string; } { const lower = command.toLowerCase(); const cliPid = process.pid; // PowerShell: Stop-Process targeting node processes if (lower.includes('stop-process') && /\bnode\b/i.test(command)) { return { isSelfDestructive: true, reason: 'Command would terminate Node.js processes, including this CLI itself', suggestion: `This CLI is running as Node.js (PID: ${cliPid}). ` + `Add a PID exclusion filter, e.g.: Where-Object { ... -and $_.Id -ne ${cliPid} }`, }; } // Windows CMD: taskkill targeting node.exe if (/\btaskkill\b/i.test(command) && /\bnode(\.exe)?\b/i.test(command)) { return { isSelfDestructive: true, reason: 'Command would terminate node.exe processes, including this CLI itself', suggestion: `This CLI is running as node.exe (PID: ${cliPid}). ` + `Use "taskkill /PID <target_pid>" for specific processes, excluding PID ${cliPid}.`, }; } // Unix: killall node if (/\bkillall\s+(-\w+\s+)*node\b/i.test(command)) { return { isSelfDestructive: true, reason: 'killall node would terminate ALL Node.js processes, including this CLI', suggestion: `Use "kill <specific_pid>" to target individual processes, excluding PID ${cliPid}.`, }; } // Unix: pkill node / pkill -f node if (/\bpkill\s+(-\w+\s+)*node\b/i.test(command)) { return { isSelfDestructive: true, reason: 'pkill node would terminate Node.js processes, including this CLI', suggestion: `Use "kill <specific_pid>" to target individual processes, excluding PID ${cliPid}.`, }; } // Any platform: directly targeting the CLI's own PID const pidPatterns = [ new RegExp(`\\bkill\\s+(-\\d+\\s+)*${cliPid}\\b`), new RegExp(`\\bStop-Process\\s+.*-Id\\s+${cliPid}\\b`, 'i'), new RegExp(`\\btaskkill\\b.*\\/PID\\s+${cliPid}\\b`, 'i'), ]; if (pidPatterns.some(p => p.test(command))) { return { isSelfDestructive: true, reason: `Command directly targets this CLI process (PID: ${cliPid})`, suggestion: `PID ${cliPid} is the Snow CLI process. Killing it will terminate the current session.`, }; } return {isSelfDestructive: false}; } /** * Truncate output if it exceeds maximum length * @param output - Output string to truncate * @param maxLength - Maximum allowed length * @returns Truncated output with indicator if truncated */ export function truncateOutput(output: string, maxLength: number): string { if (!output) return ''; if (output.length > maxLength) { return output.slice(0, maxLength) + '\n... (output truncated)'; } return output; } ================================================ FILE: source/mcp/utils/filesystem/backup.utils.ts ================================================ type BackupFileParams = { filePath: string; basePath: string; fileExisted: boolean; originalContent?: string; }; /** * Best-effort snapshot backup before mutating files. * Failures are intentionally swallowed to avoid blocking edits. */ export async function backupFileBeforeMutation( params: BackupFileParams, ): Promise<void> { try { const {getConversationContext} = await import( '../../../utils/codebase/conversationContext.js' ); const context = getConversationContext(); if (!context) { return; } const {hashBasedSnapshotManager} = await import( '../../../utils/codebase/hashBasedSnapshot.js' ); await hashBasedSnapshotManager.backupFile( context.sessionId, context.messageIndex, params.filePath, params.basePath, params.fileExisted, params.originalContent, ); } catch { // non-fatal } } ================================================ FILE: source/mcp/utils/filesystem/batch-operations.utils.ts ================================================ /** * Batch operation utilities for filesystem operations */ import type { BatchOperationResult, BatchResultItem, EditBySearchConfig, } from '../../types/filesystem.types.js'; /** * Parse file path parameter into array format * Supports: string, string[], or array of config objects */ export function parseFilePathParameter<T extends {path: string}>( filePath: string | string[] | T[], ): Array<string | T> { if (Array.isArray(filePath)) { return filePath; } return [filePath]; } /** * Extract file path from file item (string or object) */ export function extractFilePath<T extends {path: string}>( fileItem: string | T, ): string { return typeof fileItem === 'string' ? fileItem : fileItem.path; } /** * Parse edit-by-search parameters (single path, string batch, or per-file config batch) */ export function parseEditBySearchParams( fileItem: string | EditBySearchConfig, globalSearchContent?: string, globalReplaceContent?: string, globalOccurrence?: number, ): { path: string; searchContent: string; replaceContent: string; occurrence: number; } { if (typeof fileItem === 'string') { if (!globalSearchContent || !globalReplaceContent) { throw new Error( 'searchContent and replaceContent are required for string array format', ); } return { path: fileItem, searchContent: globalSearchContent, replaceContent: globalReplaceContent, occurrence: globalOccurrence ?? 1, }; } return { path: fileItem.path, searchContent: fileItem.searchContent, replaceContent: fileItem.replaceContent, occurrence: fileItem.occurrence ?? globalOccurrence ?? 1, }; } /** * Execute batch operation with error handling */ export async function executeBatchOperation< TConfig, TSingleResult, TBatchItem extends BatchResultItem, >( fileItems: Array<string | TConfig>, parseParams: (fileItem: string | TConfig) => any, executeSingle: (...params: any[]) => Promise<TSingleResult>, mapResult: ( path: string, result: TSingleResult, ) => Omit<TBatchItem, 'success' | 'error'>, ): Promise<BatchOperationResult<TBatchItem>> { const results: TBatchItem[] = []; for (const fileItem of fileItems) { try { const params = parseParams(fileItem); const result = await executeSingle(...Object.values(params)); results.push({ success: true, ...(mapResult(params.path, result) as any), } as TBatchItem); } catch (error) { const filePath = typeof fileItem === 'string' ? fileItem : (fileItem as {path: string}).path; results.push({ path: filePath, success: false, error: error instanceof Error ? error.message : 'Unknown error', } as TBatchItem); } } const successCount = results.filter(r => r.success).length; const failureCount = results.filter(r => !r.success).length; // Build detailed message with all file diffs let detailedMessage = `📊 Batch Edit Summary: ${successCount} succeeded, ${failureCount} failed\n\n`; results.forEach((result, index) => { const num = index + 1; const separator = '─'.repeat(80); if (result.success) { detailedMessage += `${separator}\n`; detailedMessage += `✅ File ${num}/${results.length}: ${result.path}\n`; detailedMessage += `${separator}\n\n`; // Add individual file full result (including oldContent and newContent for diff) const fileResult = result as any; // Extract key metadata from message if available if (fileResult.message) { const lines = fileResult.message.split('\n'); const metadataLines = lines.filter( (l: string) => l.trim().startsWith('Matched:') || l.trim().startsWith('Replaced:') || l.trim().startsWith('Result:') || l.trim().startsWith('📍'), ); if (metadataLines.length > 0) { metadataLines.forEach((line: string) => { detailedMessage += `${line}\n`; }); detailedMessage += '\n'; } } // Add diff display - keep oldContent and newContent in results for UI rendering // Don't format as text here, let the UI handle it with DiffViewer if (fileResult.oldContent && fileResult.newContent) { // Just add a placeholder message, actual diff will be rendered by UI detailedMessage += `📊 Changes (lines ${ fileResult.contextStartLine ?? '?' }-${fileResult.contextEndLine ?? '?'})\n\n`; } // Add structure analysis warnings if any if (fileResult.structureAnalysis) { const warnings: string[] = []; const sa = fileResult.structureAnalysis; if (!sa.bracketBalance?.curly?.balanced) { const diff = (sa.bracketBalance.curly.open || 0) - (sa.bracketBalance.curly.close || 0); warnings.push( `Curly brackets: ${ diff > 0 ? `${diff} unclosed {` : `${Math.abs(diff)} extra }` }`, ); } if (!sa.bracketBalance?.round?.balanced) { const diff = (sa.bracketBalance.round.open || 0) - (sa.bracketBalance.round.close || 0); warnings.push( `Round brackets: ${ diff > 0 ? `${diff} unclosed (` : `${Math.abs(diff)} extra )` }`, ); } if (!sa.bracketBalance?.square?.balanced) { const diff = (sa.bracketBalance.square.open || 0) - (sa.bracketBalance.square.close || 0); warnings.push( `Square brackets: ${ diff > 0 ? `${diff} unclosed [` : `${Math.abs(diff)} extra ]` }`, ); } if (warnings.length > 0) { detailedMessage += `⚠️ Structure Warnings:\n`; warnings.forEach((w: string) => { detailedMessage += ` • ${w}\n`; }); detailedMessage += '\n'; } } // Add diagnostics if any if (fileResult.diagnostics && fileResult.diagnostics.length > 0) { const errorCount = fileResult.diagnostics.filter( (d: any) => d.severity === 'error', ).length; const warningCount = fileResult.diagnostics.filter( (d: any) => d.severity === 'warning', ).length; if (errorCount > 0 || warningCount > 0) { detailedMessage += `🔧 Diagnostics: ${errorCount} error(s), ${warningCount} warning(s)\n`; fileResult.diagnostics.slice(0, 3).forEach((d: any) => { const icon = d.severity === 'error' ? '❌' : '⚠️'; detailedMessage += ` ${icon} Line ${d.line}: ${d.message}\n`; }); if (fileResult.diagnostics.length > 3) { detailedMessage += ` ... and ${ fileResult.diagnostics.length - 3 } more\n`; } detailedMessage += '\n'; } } } else { detailedMessage += `${separator}\n`; detailedMessage += `❌ File ${num}/${results.length}: ${result.path}\n`; detailedMessage += `${separator}\n`; detailedMessage += `Error: ${result.error}\n\n`; } }); return { message: detailedMessage.trim(), results, totalFiles: fileItems.length, successCount, failureCount, }; } ================================================ FILE: source/mcp/utils/filesystem/code-analysis.utils.ts ================================================ /** * Code analysis utilities for structure validation */ import type {StructureAnalysis} from '../../types/filesystem.types.js'; /** * Analyze code structure for balance and completeness * Helps AI identify bracket mismatches, unclosed tags, and boundary issues */ export function analyzeCodeStructure( _content: string, filePath: string, editedLines: string[], ): StructureAnalysis { const analysis: StructureAnalysis = { bracketBalance: { curly: {open: 0, close: 0, balanced: true}, round: {open: 0, close: 0, balanced: true}, square: {open: 0, close: 0, balanced: true}, }, indentationWarnings: [], }; // Count brackets in the edited content const editedContent = editedLines.join('\n'); // Remove string literals and comments to avoid false positives const cleanContent = editedContent .replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`/g, '""') // Remove strings .replace(/\/\/.*$/gm, '') // Remove single-line comments .replace(/\/\*[\s\S]*?\*\//g, ''); // Remove multi-line comments // Count brackets analysis.bracketBalance.curly.open = (cleanContent.match(/\{/g) || []).length; analysis.bracketBalance.curly.close = ( cleanContent.match(/\}/g) || [] ).length; analysis.bracketBalance.curly.balanced = analysis.bracketBalance.curly.open === analysis.bracketBalance.curly.close; analysis.bracketBalance.round.open = (cleanContent.match(/\(/g) || []).length; analysis.bracketBalance.round.close = ( cleanContent.match(/\)/g) || [] ).length; analysis.bracketBalance.round.balanced = analysis.bracketBalance.round.open === analysis.bracketBalance.round.close; analysis.bracketBalance.square.open = ( cleanContent.match(/\[/g) || [] ).length; analysis.bracketBalance.square.close = ( cleanContent.match(/\]/g) || [] ).length; analysis.bracketBalance.square.balanced = analysis.bracketBalance.square.open === analysis.bracketBalance.square.close; // HTML/JSX tag analysis (for .html, .jsx, .tsx, .vue files) const isMarkupFile = /\.(html|jsx|tsx|vue)$/i.test(filePath); if (isMarkupFile) { const tagPattern = /<\/?([a-zA-Z][a-zA-Z0-9-]*)[^>]*>/g; const selfClosingPattern = /<[a-zA-Z][a-zA-Z0-9-]*[^>]*\/>/g; // Remove self-closing tags const contentWithoutSelfClosing = cleanContent.replace( selfClosingPattern, '', ); const tags: string[] = []; const unclosedTags: string[] = []; const unopenedTags: string[] = []; let match; while ((match = tagPattern.exec(contentWithoutSelfClosing)) !== null) { const isClosing = match[0]?.startsWith('</'); const tagName = match[1]?.toLowerCase(); if (!tagName) continue; if (isClosing) { const lastOpenTag = tags.pop(); if (!lastOpenTag || lastOpenTag !== tagName) { unopenedTags.push(tagName); if (lastOpenTag) tags.push(lastOpenTag); // Put it back } } else { tags.push(tagName); } } unclosedTags.push(...tags); analysis.htmlTags = { unclosedTags, unopenedTags, balanced: unclosedTags.length === 0 && unopenedTags.length === 0, }; } // Check indentation consistency const lines = editedContent.split('\n'); const indents = lines .filter(line => line.trim().length > 0) .map(line => { const match = line.match(/^(\s*)/); return match ? match[1] : ''; }) .filter((indent): indent is string => indent !== undefined); // Detect mixed tabs/spaces const hasTabs = indents.some(indent => indent.includes('\t')); const hasSpaces = indents.some(indent => indent.includes(' ')); if (hasTabs && hasSpaces) { analysis.indentationWarnings.push('Mixed tabs and spaces detected'); } // Detect inconsistent indentation levels (spaces only) if (!hasTabs && hasSpaces) { const spaceCounts = indents .filter(indent => indent.length > 0) .map(indent => indent.length); if (spaceCounts.length > 1) { const gcd = spaceCounts.reduce((a, b) => { while (b !== 0) { const temp = b; b = a % b; a = temp; } return a; }); const hasInconsistent = spaceCounts.some( count => count % gcd !== 0 && gcd > 1, ); if (hasInconsistent) { analysis.indentationWarnings.push( `Inconsistent indentation (expected multiples of ${gcd} spaces)`, ); } } } // Note: Boundary checking removed - AI should be free to edit partial code blocks // The bracket balance check above is sufficient for detecting real issues return analysis; } /** * Find smart context boundaries for editing * Expands context to include complete code blocks when possible */ export function findSmartContextBoundaries( lines: string[], startLine: number, endLine: number, requestedContext: number, ): {start: number; end: number; extended: boolean} { const totalLines = lines.length; let contextStart = Math.max(1, startLine - requestedContext); let contextEnd = Math.min(totalLines, endLine + requestedContext); let extended = false; // Try to find the start of the enclosing block let bracketDepth = 0; for (let i = startLine - 1; i >= Math.max(0, startLine - 50); i--) { const line = lines[i]; if (!line) continue; const trimmed = line.trim(); // Count brackets (simple approach) const openBrackets = (line.match(/\{/g) || []).length; const closeBrackets = (line.match(/\}/g) || []).length; bracketDepth += closeBrackets - openBrackets; // If we find a function/class/block definition with balanced brackets if ( bracketDepth === 0 && (trimmed.match( /^(function|class|const|let|var|if|for|while|async|export)\s/i, ) || trimmed.match(/=>\s*\{/) || trimmed.match(/^\w+\s*\(/)) ) { if (i + 1 < contextStart) { contextStart = i + 1; extended = true; } break; } } // Try to find the end of the enclosing block bracketDepth = 0; for (let i = endLine - 1; i < Math.min(totalLines, endLine + 50); i++) { const line = lines[i]; if (!line) continue; const trimmed = line.trim(); // Count brackets const openBrackets = (line.match(/\{/g) || []).length; const closeBrackets = (line.match(/\}/g) || []).length; bracketDepth += openBrackets - closeBrackets; // If we find a closing bracket at depth 0 if (bracketDepth === 0 && trimmed.startsWith('}')) { if (i + 1 > contextEnd) { contextEnd = i + 1; extended = true; } break; } } return {start: contextStart, end: contextEnd, extended}; } ================================================ FILE: source/mcp/utils/filesystem/diagnostics.utils.ts ================================================ import { vscodeConnection, type Diagnostic, } from '../../../utils/ui/vscodeConnection.js'; function sleep(ms: number): Promise<void> { return new Promise<void>(resolve => setTimeout(resolve, ms)); } function getDiagnosticFingerprint(diagnostics: Diagnostic[]): string { if (diagnostics.length === 0) { return 'empty'; } return diagnostics .map( diagnostic => `${diagnostic.severity}|${diagnostic.source || ''}|${diagnostic.code || ''}|${diagnostic.line}|${diagnostic.character}|${diagnostic.message}`, ) .sort() .join('\n'); } /** * Poll IDE diagnostics until they become stable after file edits. * This reduces the chance of returning stale diagnostics right after save. */ export async function getFreshDiagnostics(filePath: string): Promise<Diagnostic[]> { const initialDelayMs = 300; const pollDelayMs = 350; const maxAttempts = 5; const requestTimeoutMs = 3000; let lastFingerprint: string | null = null; let lastDiagnostics: Diagnostic[] = []; await sleep(initialDelayMs); for (let attempt = 0; attempt < maxAttempts; attempt++) { const diagnostics = await Promise.race([ vscodeConnection.requestDiagnostics(filePath), new Promise<Diagnostic[]>(resolve => setTimeout(() => resolve([]), requestTimeoutMs), ), ]); const fingerprint = getDiagnosticFingerprint(diagnostics); if (fingerprint === lastFingerprint) { return diagnostics; } lastFingerprint = fingerprint; lastDiagnostics = diagnostics; if (attempt < maxAttempts - 1) { await sleep(pollDelayMs); } } return lastDiagnostics; } ================================================ FILE: source/mcp/utils/filesystem/edit-tools.utils.ts ================================================ import * as path from 'path'; import * as prettier from 'prettier'; import {isAbsolute} from 'path'; import type {Diagnostic} from '../../../utils/ui/vscodeConnection.js'; import type { EditByHashlineSingleResult, EditBySearchSingleResult, HashlineOperation, } from '../../types/filesystem.types.js'; import { tryUnescapeFix, trimPairIfPossible, isOverEscaped, } from '../../../utils/ui/escapeHandler.js'; import { calculateSimilarity, calculateSimilarityAsync, normalizeForDisplay, } from '../../utils/filesystem/similarity.utils.js'; import { analyzeCodeStructure, findSmartContextBoundaries, } from '../../utils/filesystem/code-analysis.utils.js'; import { findClosestMatches, generateDiffMessage, } from '../../utils/filesystem/match-finder.utils.js'; import {readFileWithEncoding, writeFileWithEncoding} from '../../utils/filesystem/encoding.utils.js'; import {getAutoFormatEnabled} from '../../../utils/config/projectSettings.js'; import { formatLineWithHashDisplay, validateAnchor, } from '../../utils/filesystem/hashline.utils.js'; import {getFreshDiagnostics} from '../../utils/filesystem/diagnostics.utils.js'; import { appendDiagnosticsSummary, appendStructureWarnings, } from '../../utils/filesystem/message-format.utils.js'; import {backupFileBeforeMutation} from '../../utils/filesystem/backup.utils.js'; type EditToolContext = { basePath: string; prettierSupportedExtensions: string[]; isSSHPath: (filePath: string) => boolean; readRemoteFile: (sshUrl: string) => Promise<string>; writeRemoteFile: (sshUrl: string, content: string) => Promise<void>; resolvePath: (filePath: string, contextPath?: string) => string; validatePath: (fullPath: string) => Promise<void>; }; export async function executeEditBySearchSingle( ctx: EditToolContext, filePath: string, searchContent: string, replaceContent: string, occurrence: number, contextLines: number, ): Promise<EditBySearchSingleResult> { try { const isRemote = ctx.isSSHPath(filePath); let content: string; let fullPath: string; if (isRemote) { content = await ctx.readRemoteFile(filePath); fullPath = filePath; } else { fullPath = ctx.resolvePath(filePath); if (!isAbsolute(filePath)) { await ctx.validatePath(fullPath); } content = await readFileWithEncoding(fullPath); } const lines = content.split('\n'); await backupFileBeforeMutation({ filePath, basePath: ctx.basePath, fileExisted: true, originalContent: content, }); let normalizedSearch = searchContent.replace(/\r\n/g, '\n').replace(/\r/g, '\n'); const normalizedContent = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n'); let searchLines = normalizedSearch.split('\n'); const contentLines = normalizedContent.split('\n'); const matches: Array<{startLine: number; endLine: number; similarity: number}> = []; const threshold = 0.75; const searchFirstLine = searchLines[0]?.replace(/\s+/g, ' ').trim() || ''; const usePreFilter = searchLines.length >= 5; const preFilterThreshold = 0.2; const maxMatches = 10; for (let i = 0; i <= contentLines.length - searchLines.length; i++) { if (usePreFilter) { const firstLineCandidate = contentLines[i]?.replace(/\s+/g, ' ').trim() || ''; const firstLineSimilarity = calculateSimilarity( searchFirstLine, firstLineCandidate, preFilterThreshold, ); if (firstLineSimilarity < preFilterThreshold) { continue; } } const candidateLines = contentLines.slice(i, i + searchLines.length); const candidateContent = candidateLines.join('\n'); const similarity = await calculateSimilarityAsync( normalizedSearch, candidateContent, threshold, ); if (similarity >= threshold) { matches.push({ startLine: i + 1, endLine: i + searchLines.length, similarity, }); if (similarity >= 0.95 || matches.length >= maxMatches) { break; } } } matches.sort((a, b) => b.similarity - a.similarity); if (matches.length === 0) { const unescapeFix = tryUnescapeFix(normalizedContent, normalizedSearch, 1); if (unescapeFix) { const correctedSearchLines = unescapeFix.correctedString.split('\n'); for (let i = 0; i <= contentLines.length - correctedSearchLines.length; i++) { const candidateLines = contentLines.slice(i, i + correctedSearchLines.length); const similarity = await calculateSimilarityAsync( unescapeFix.correctedString, candidateLines.join('\n'), ); if (similarity >= threshold) { matches.push({ startLine: i + 1, endLine: i + correctedSearchLines.length, similarity, }); } } matches.sort((a, b) => b.similarity - a.similarity); if (matches.length > 0) { const trimResult = trimPairIfPossible( unescapeFix.correctedString, replaceContent, normalizedContent, 1, ); normalizedSearch = trimResult.target; replaceContent = trimResult.paired; searchLines = normalizedSearch.split('\n'); } } if (matches.length === 0) { const closestMatches = await findClosestMatches( normalizedSearch, normalizedContent.split('\n'), 3, ); let errorMessage = `❌ Search content not found in file: ${filePath}\n\n`; errorMessage += `🔍 Using smart fuzzy matching (threshold: ${threshold})\n`; if (isOverEscaped(searchContent)) { errorMessage += `⚠️ Detected over-escaped content, automatic fix attempted but failed\n`; } errorMessage += `\n`; if (closestMatches.length > 0) { errorMessage += `💡 Found ${closestMatches.length} similar location(s):\n\n`; closestMatches.forEach((candidate, idx) => { errorMessage += `${idx + 1}. Lines ${candidate.startLine}-${candidate.endLine} (${(candidate.similarity * 100).toFixed(0)}% match):\n`; errorMessage += `${candidate.preview}\n\n`; }); const bestMatch = closestMatches[0]; if (bestMatch) { const bestMatchContent = lines .slice(bestMatch.startLine - 1, bestMatch.endLine) .join('\n'); const diffMsg = generateDiffMessage(normalizedSearch, bestMatchContent, 5); if (diffMsg) { errorMessage += `📊 Difference with closest match:\n${diffMsg}\n\n`; } } errorMessage += `💡 Suggestions:\n`; errorMessage += ` • Make sure you copied raw code from the file (strip any "lineNum:hash→" prefixes from filesystem-read if you pasted read output)\n`; errorMessage += ` • Whitespace differences are automatically handled\n`; errorMessage += ` • Try copying a larger or smaller code block\n`; errorMessage += ` • If multiple filesystem-replaceedit attempts fail, use terminal-execute to edit via command line (e.g. sed, printf)\n`; errorMessage += `⚠️ No similar content found in the file.\n\n`; errorMessage += `📝 What you searched for (first 5 lines, formatted):\n`; searchLines.slice(0, 5).forEach((line, idx) => { errorMessage += `${idx + 1}. ${JSON.stringify(normalizeForDisplay(line))}\n`; }); errorMessage += `\n💡 Copy exact source text (not hashline-prefixed read lines)\n`; } throw new Error(errorMessage); } } let selectedMatch: {startLine: number; endLine: number}; if (occurrence === -1) { if (matches.length === 1) { selectedMatch = matches[0]!; } else { throw new Error( `Found ${matches.length} matches. Please specify which occurrence to replace (1-${matches.length}), or use occurrence=-1 to replace all (not yet implemented for safety).`, ); } } else if (occurrence < 1 || occurrence > matches.length) { throw new Error( `Invalid occurrence ${occurrence}. Found ${matches.length} match(es) at lines: ${matches.map(m => m.startLine).join(', ')}`, ); } else { selectedMatch = matches[occurrence - 1]!; } const {startLine, endLine} = selectedMatch; const normalizedReplace = replaceContent.replace(/\r\n/g, '\n').replace(/\r/g, '\n'); const beforeLines = lines.slice(0, startLine - 1); const afterLines = lines.slice(endLine); let replaceLines = normalizedReplace.split('\n'); if (replaceLines.length > 0) { const originalFirstLine = lines[startLine - 1]; const originalIndent = originalFirstLine?.match(/^(\s*)/)?.[1] || ''; const replaceFirstLine = replaceLines[0]; const replaceIndent = replaceFirstLine?.match(/^(\s*)/)?.[1] || ''; if (originalIndent !== replaceIndent && replaceFirstLine) { replaceLines[0] = originalIndent + replaceFirstLine.trim(); } } const modifiedLines = [...beforeLines, ...replaceLines, ...afterLines]; const modifiedContent = modifiedLines.join('\n'); const replacedContent = lines.slice(startLine - 1, endLine).join('\n'); const lineDifference = replaceLines.length - (endLine - startLine + 1); const smartBoundaries = findSmartContextBoundaries( lines, startLine, endLine, contextLines, ); const contextStart = smartBoundaries.start; const contextEnd = smartBoundaries.end; const oldContent = lines.slice(contextStart - 1, contextEnd).join('\n'); if (isRemote) { await ctx.writeRemoteFile(fullPath, modifiedContent); } else { await writeFileWithEncoding(fullPath, modifiedContent); } const diffContextEnd = Math.min(modifiedLines.length, contextEnd + lineDifference); let finalContent = modifiedContent; let finalLines = modifiedLines; let finalTotalLines = modifiedLines.length; const fileExtension = path.extname(fullPath).toLowerCase(); const shouldFormat = getAutoFormatEnabled() && ctx.prettierSupportedExtensions.includes(fileExtension); if (shouldFormat) { try { const prettierConfig = await prettier.resolveConfig(fullPath); finalContent = await prettier.format(modifiedContent, { filepath: fullPath, ...prettierConfig, }); if (isRemote) { await ctx.writeRemoteFile(fullPath, finalContent); } else { await writeFileWithEncoding(fullPath, finalContent); } finalLines = finalContent.split('\n'); finalTotalLines = finalLines.length; } catch { // non-fatal } } const newContextContent = modifiedLines .slice(contextStart - 1, diffContextEnd) .join('\n'); const overflowPadding = Math.max(3, contextLines); const completeOldStart = Math.max(1, contextStart - overflowPadding); const completeOldEnd = Math.min(lines.length, contextEnd + overflowPadding); const completeOldContent = lines .slice(completeOldStart - 1, completeOldEnd) .join('\n'); const editLineDelta = modifiedLines.length - lines.length; const completeNewStart = Math.max(1, completeOldStart); const completeNewEnd = Math.min(modifiedLines.length, completeOldEnd + editLineDelta); const completeNewContent = modifiedLines .slice(completeNewStart - 1, completeNewEnd) .join('\n'); const structureAnalysis = analyzeCodeStructure(finalContent, filePath, replaceLines); let diagnostics: Diagnostic[] = []; try { diagnostics = await getFreshDiagnostics(fullPath); } catch { // optional } const result = { message: `✅ File edited successfully using search-replace (safer boundary detection): ${filePath}\n` + ` Matched: lines ${startLine}-${endLine} (occurrence ${occurrence}/${matches.length})\n` + ` Result: ${replaceLines.length} new lines` + (smartBoundaries.extended ? `\n 📍 Context auto-extended to show complete code block (lines ${contextStart}-${diffContextEnd})` : ''), filePath, oldContent, newContent: newContextContent, completeOldContent, completeNewContent, replacedContent, matchLocation: {startLine, endLine}, contextStartLine: contextStart, contextEndLine: diffContextEnd, totalLines: finalTotalLines, structureAnalysis, diagnostics: undefined as Diagnostic[] | undefined, }; if (diagnostics.length > 0) { result.diagnostics = diagnostics.slice(0, 10); result.message = appendDiagnosticsSummary(result.message, filePath, diagnostics, { includeTip: true, }); } result.message = appendStructureWarnings( result.message, structureAnalysis, '💡 TIP: These warnings help identify potential issues. If intentional (e.g., opening a block), you can ignore them.', ); return result; } catch (error) { throw new Error( `Failed to edit file ${filePath}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } export async function executeHashlineEditSingle( ctx: EditToolContext, filePath: string, operations: HashlineOperation[], contextLines: number, ): Promise<EditByHashlineSingleResult> { try { const isRemote = ctx.isSSHPath(filePath); let content: string; let fullPath: string; if (isRemote) { content = await ctx.readRemoteFile(filePath); fullPath = filePath; } else { fullPath = ctx.resolvePath(filePath); if (!isAbsolute(filePath)) { await ctx.validatePath(fullPath); } content = await readFileWithEncoding(fullPath); } const lines = content.split('\n'); await backupFileBeforeMutation({ filePath, basePath: ctx.basePath, fileExisted: true, originalContent: content, }); type PreparedHashlineOperation = { op: HashlineOperation; originalIndex: number; startLine: number; endLine: number; }; const preparedOps: PreparedHashlineOperation[] = []; const anchorErrors: string[] = []; for (const [originalIndex, op] of operations.entries()) { const startV = validateAnchor(op.startAnchor, lines); if (!startV.valid) { anchorErrors.push( `Anchor "${op.startAnchor}" invalid` + (startV.expected && startV.actual ? ` (expected hash ${startV.expected}, actual ${startV.actual})` : startV.lineNum > 0 ? ` (line ${startV.lineNum} out of range or hash mismatch)` : ' (bad format, expected "lineNum:hash")'), ); } let endLine = startV.lineNum; let hasValidRange = startV.valid; const endAnchorMissing = op.endAnchor === undefined || op.endAnchor === null || (typeof op.endAnchor === 'string' && op.endAnchor.trim() === ''); if (endAnchorMissing) { anchorErrors.push( `Operation ${originalIndex + 1} (${op.type}): endAnchor is required. For a single-line replace or delete, set endAnchor to the same "lineNum:hash" as startAnchor. For insert_after, repeat startAnchor as endAnchor.`, ); hasValidRange = false; } else { const endV = validateAnchor(op.endAnchor, lines); if (!endV.valid) { anchorErrors.push( `Anchor "${op.endAnchor}" invalid` + (endV.expected && endV.actual ? ` (expected hash ${endV.expected}, actual ${endV.actual})` : endV.lineNum > 0 ? ` (line ${endV.lineNum} out of range or hash mismatch)` : ' (bad format, expected "lineNum:hash")'), ); hasValidRange = false; } else { endLine = endV.lineNum; if (startV.valid && endLine < startV.lineNum) { anchorErrors.push( `endAnchor line ${endLine} is before startAnchor line ${startV.lineNum}`, ); hasValidRange = false; } } } if ((op.type === 'replace' || op.type === 'insert_after') && op.content === undefined) { anchorErrors.push(`Operation "${op.type}" requires content`); } if (hasValidRange) { preparedOps.push({op, originalIndex, startLine: startV.lineNum, endLine}); } } if (anchorErrors.length > 0) { throw new Error( `❌ Hashline anchor validation failed for ${filePath}:\n` + anchorErrors.map(e => ` • ${e}`).join('\n') + `\n\n💡 The file may have changed since your last read. Re-read the file to get fresh anchors.`, ); } const conflictErrors: string[] = []; for (let i = 0; i < preparedOps.length; i++) { const current = preparedOps[i]!; for (let j = i + 1; j < preparedOps.length; j++) { const next = preparedOps[j]!; const sameStartLine = current.startLine === next.startLine; const bothInsertAfter = current.op.type === 'insert_after' && next.op.type === 'insert_after' && sameStartLine; if (bothInsertAfter) continue; const sameSingleLineAnchor = sameStartLine && current.startLine === current.endLine && next.startLine === next.endLine; const hasInsertAfter = current.op.type === 'insert_after' || next.op.type === 'insert_after'; if (sameSingleLineAnchor && hasInsertAfter) continue; const overlaps = current.startLine <= next.endLine && next.startLine <= current.endLine; if (!overlaps) continue; conflictErrors.push( `Operation ${current.originalIndex + 1} (${current.op.type} ${current.startLine}-${current.endLine}) conflicts with operation ${next.originalIndex + 1} (${next.op.type} ${next.startLine}-${next.endLine})`, ); } } if (conflictErrors.length > 0) { throw new Error( `Hashline operations conflict for ${filePath}:\n` + conflictErrors.map(e => ` • ${e}`).join('\n') + `\n\nUse non-overlapping anchors for the same file, or split dependent edits into separate calls.`, ); } const sortedOps = [...preparedOps].sort((a, b) => { if (a.startLine !== b.startLine) return b.startLine - a.startLine; const aInsertAfter = a.op.type === 'insert_after'; const bInsertAfter = b.op.type === 'insert_after'; if (aInsertAfter && bInsertAfter) return b.originalIndex - a.originalIndex; if (aInsertAfter !== bInsertAfter) return aInsertAfter ? -1 : 1; if (a.endLine !== b.endLine) return b.endLine - a.endLine; return b.originalIndex - a.originalIndex; }); let editStartLine = Infinity; let editEndLine = 0; const mutableLines = [...lines]; const opSummaries: string[] = []; const hashlineContentRe = /^\s*\d+:[0-9a-fA-F]{2}→/; const sanitizeContent = (raw: string): string => { const contentLines = raw.split('\n'); const hasHashlines = contentLines.length > 0 && contentLines.every(line => line === '' || hashlineContentRe.test(line)); if (!hasHashlines) return raw; return contentLines .map(line => { let value = line; let match: RegExpExecArray | null; while ((match = hashlineContentRe.exec(value))) { value = value.slice(match[0].length); } return value; }) .join('\n'); }; for (const preparedOp of sortedOps) { const {op, startLine, endLine} = preparedOp; editStartLine = Math.min(editStartLine, startLine); editEndLine = Math.max(editEndLine, endLine); switch (op.type) { case 'replace': { const newLines = sanitizeContent(op.content ?? '').split('\n'); mutableLines.splice(startLine - 1, endLine - startLine + 1, ...newLines); opSummaries.push( `replace lines ${startLine}-${endLine} → ${newLines.length} line(s)`, ); break; } case 'insert_after': { const newLines = sanitizeContent(op.content ?? '').split('\n'); mutableLines.splice(startLine, 0, ...newLines); opSummaries.push(`insert ${newLines.length} line(s) after line ${startLine}`); break; } case 'delete': { mutableLines.splice(startLine - 1, endLine - startLine + 1); opSummaries.push(`delete lines ${startLine}-${endLine}`); break; } } } const replacedContent = lines .slice(editStartLine - 1, editEndLine) .map((line, idx) => { const ln = editStartLine + idx; return formatLineWithHashDisplay(ln, line, normalizeForDisplay(line)); }) .join('\n'); const smartBoundaries = findSmartContextBoundaries( lines, editStartLine, editEndLine, contextLines, ); const contextStart = smartBoundaries.start; const contextEnd = smartBoundaries.end; const oldContent = lines .slice(contextStart - 1, contextEnd) .map((line, idx) => { const ln = contextStart + idx; return formatLineWithHashDisplay(ln, line, normalizeForDisplay(line)); }) .join('\n'); const modifiedContent = mutableLines.join('\n'); if (isRemote) { await ctx.writeRemoteFile(fullPath, modifiedContent); } else { await writeFileWithEncoding(fullPath, modifiedContent); } let finalLines = mutableLines; let finalTotalLines = mutableLines.length; const lineDifference = mutableLines.length - lines.length; let finalContextEnd = Math.min(finalTotalLines, contextEnd + lineDifference); const fileExtension = path.extname(fullPath).toLowerCase(); const shouldFormat = getAutoFormatEnabled() && ctx.prettierSupportedExtensions.includes(fileExtension); if (shouldFormat) { try { const prettierConfig = await prettier.resolveConfig(fullPath); const formatted = await prettier.format(modifiedContent, { filepath: fullPath, ...prettierConfig, }); if (isRemote) { await ctx.writeRemoteFile(fullPath, formatted); } else { await writeFileWithEncoding(fullPath, formatted); } finalLines = formatted.split('\n'); finalTotalLines = finalLines.length; finalContextEnd = Math.min( finalTotalLines, contextStart + (contextEnd - contextStart) + lineDifference, ); } catch { // non-fatal } } const newContextContent = finalLines .slice(contextStart - 1, finalContextEnd) .map((line, idx) => { const ln = contextStart + idx; return formatLineWithHashDisplay(ln, line, normalizeForDisplay(line)); }) .join('\n'); const structureAnalysis = analyzeCodeStructure( finalLines.join('\n'), filePath, finalLines.slice( editStartLine - 1, editStartLine - 1 + (editEndLine - editStartLine + 1), ), ); let diagnostics: Diagnostic[] = []; try { diagnostics = await getFreshDiagnostics(fullPath); } catch { // optional } const result: EditByHashlineSingleResult = { message: `✅ File edited via hashline anchors: ${filePath}\n` + ` Operations: ${opSummaries.join('; ')}\n` + ` Result: ${finalTotalLines} total lines` + (smartBoundaries.extended ? `\n 📍 Context auto-extended (lines ${contextStart}-${finalContextEnd})` : ''), filePath, oldContent, newContent: newContextContent, replacedContent, operationsSummary: opSummaries.join('; '), contextStartLine: contextStart, contextEndLine: finalContextEnd, totalLines: finalTotalLines, structureAnalysis, diagnostics: undefined, }; if (diagnostics.length > 0) { result.diagnostics = diagnostics.slice(0, 10); result.message = appendDiagnosticsSummary(result.message, filePath, diagnostics, { headerLabel: 'Diagnostics', detailsLabel: 'Details', moreSuffix: 'more', }); } result.message = appendStructureWarnings(result.message, structureAnalysis); return result; } catch (error) { throw new Error( `Failed to edit file ${filePath}: ${ error instanceof Error ? error.message : 'Unknown error' }`, ); } } ================================================ FILE: source/mcp/utils/filesystem/encoding.utils.ts ================================================ import {promises as fs, createReadStream} from 'fs'; import {createInterface} from 'readline'; import * as chardet from 'chardet'; import * as iconv from 'iconv-lite'; // Node.js max string length is 2^29 - 24 ≈ 512MB chars. // Use 256MB as safe limit to account for encoding expansion overhead. const MAX_READABLE_FILE_BYTES = 256 * 1024 * 1024; // Only read a small sample for encoding detection on large files const ENCODING_SAMPLE_BYTES = 64 * 1024; function isUtf8Buffer(buffer: Buffer): boolean { // UTF-8 BOM if ( buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf ) { return true; } try { // Use a fatal decoder to validate UTF-8 bytes const decoder = new TextDecoder('utf-8', {fatal: true}); decoder.decode(buffer); return true; } catch { return false; } } /** * Detect file encoding and read content with proper encoding. * Rejects files larger than ~256MB to avoid Node.js string length limits. * @param filePath - Full path to the file * @returns Decoded file content as string */ export async function readFileWithEncoding(filePath: string): Promise<string> { const stats = await fs.stat(filePath); if (stats.size > MAX_READABLE_FILE_BYTES) { throw new Error( `File too large to read as text (${Math.round(stats.size / 1024 / 1024)}MB, limit ${Math.round(MAX_READABLE_FILE_BYTES / 1024 / 1024)}MB): ${filePath}`, ); } try { // Read file as buffer first const buffer = await fs.readFile(filePath); // Always prefer valid UTF-8 to avoid mis-detection if (isUtf8Buffer(buffer)) { return buffer.toString('utf-8'); } // Detect encoding const detectedEncoding = chardet.detect(buffer); // If no encoding detected or it's already UTF-8, return as UTF-8 if ( !detectedEncoding || detectedEncoding === 'UTF-8' || detectedEncoding === 'ascii' ) { return buffer.toString('utf-8'); } // Convert from detected encoding to UTF-8 // Handle common encoding aliases let encoding = detectedEncoding; if (encoding === 'GB2312' || encoding === 'GBK' || encoding === 'GB18030') { // GB18030 is a superset of GBK and GB2312, use it for better compatibility encoding = 'GB18030'; } // Check if encoding is supported if (!iconv.encodingExists(encoding)) { console.warn( `Unsupported encoding detected: ${encoding}, falling back to UTF-8`, ); return buffer.toString('utf-8'); } // Decode with detected encoding const decoded = iconv.decode(buffer, encoding); return decoded; } catch (error) { if ( error instanceof Error && (error as NodeJS.ErrnoException).code === 'ERR_STRING_TOO_LONG' ) { throw new Error( `File too large to convert to string: ${filePath} (${Math.round(stats.size / 1024 / 1024)}MB)`, ); } // Fallback to UTF-8 if encoding detection fails console.warn( `Encoding detection failed for ${filePath}, using UTF-8:`, error, ); return await fs.readFile(filePath, 'utf-8'); } } /** * Read specific line range from a large file via streaming. * Works for files of any size since it never loads the entire content into memory. * Uses encoding detection on a small sample for non-UTF-8 files. * @param filePath - Full path to the file * @param startLine - 1-indexed inclusive start line (default: 1) * @param endLine - 1-indexed inclusive end line (default: Infinity = until EOF) * @returns Object with extracted lines array and total line count */ export async function readFileLinesStreaming( filePath: string, startLine: number = 1, endLine: number = Infinity, ): Promise<{lines: string[]; totalLines: number}> { // Detect encoding from a small sample let encoding = 'utf-8'; try { const fd = await fs.open(filePath, 'r'); try { const sample = Buffer.alloc(ENCODING_SAMPLE_BYTES); const {bytesRead} = await fd.read(sample, 0, ENCODING_SAMPLE_BYTES, 0); const buf = sample.subarray(0, bytesRead); if (!isUtf8Buffer(buf)) { const detected = chardet.detect(buf); if ( detected && detected !== 'UTF-8' && detected !== 'ascii' && iconv.encodingExists(detected) ) { encoding = detected; if ( encoding === 'GB2312' || encoding === 'GBK' || encoding === 'GB18030' ) { encoding = 'GB18030'; } } } } finally { await fd.close(); } } catch { // Fallback to UTF-8 } const result: string[] = []; let lineNumber = 0; return new Promise((resolve, reject) => { const stream = createReadStream(filePath); const input = encoding !== 'utf-8' ? stream.pipe(iconv.decodeStream(encoding)) : stream; const rl = createInterface({input, crlfDelay: Infinity}); rl.on('line', (line: string) => { lineNumber++; if (lineNumber >= startLine && lineNumber <= endLine) { result.push(line); } if (lineNumber > endLine && endLine !== Infinity) { rl.close(); } }); rl.on('close', () => { stream.destroy(); resolve({lines: result, totalLines: lineNumber}); }); rl.on('error', err => { stream.destroy(); reject(err); }); stream.on('error', err => { rl.close(); reject(err); }); }); } /** * Write file content with proper encoding detection * If the file exists, preserve its original encoding * If it's a new file, use UTF-8 * @param filePath - Full path to the file * @param content - Content to write */ export async function writeFileWithEncoding( filePath: string, content: string, ): Promise<void> { try { // Check if file exists to determine encoding let targetEncoding = 'utf-8'; try { const existingBuffer = await fs.readFile(filePath); if (isUtf8Buffer(existingBuffer)) { targetEncoding = 'utf-8'; } else { const detectedEncoding = chardet.detect(existingBuffer); // If file exists with non-UTF-8 encoding, preserve it if ( detectedEncoding && detectedEncoding !== 'UTF-8' && detectedEncoding !== 'ascii' ) { let encoding = detectedEncoding; if ( encoding === 'GB2312' || encoding === 'GBK' || encoding === 'GB18030' ) { // GB18030 is a superset of GBK and GB2312, use it for better compatibility encoding = 'GB18030'; } if (iconv.encodingExists(encoding)) { targetEncoding = encoding; } } } } catch { // File doesn't exist, use UTF-8 for new files } // Write with target encoding if (targetEncoding === 'utf-8') { await fs.writeFile(filePath, content, 'utf-8'); } else { const encoded = iconv.encode(content, targetEncoding); await fs.writeFile(filePath, encoded); } } catch (error) { // Fallback to UTF-8 if encoding handling fails console.warn( `Encoding handling failed for ${filePath}, using UTF-8:`, error, ); await fs.writeFile(filePath, content, 'utf-8'); } } ================================================ FILE: source/mcp/utils/filesystem/hashline.utils.ts ================================================ /** * Hashline utilities for content-hash-based line anchoring. * * Each line of a file is tagged with a short hex hash derived from its content. * Models reference these anchors when editing, so they never need to reproduce * the original text. If the file changes between read and edit the hashes will * mismatch and the operation is rejected before any damage occurs. */ /** * Compute a 2-hex-char (8-bit) content hash for a single line. * Uses FNV-1a with the full line content (untrimmed) to detect even * whitespace-only mutations. */ export function lineHash(content: string): string { let h = 0x811c9dc5; // FNV-1a 32-bit offset basis for (let i = 0; i < content.length; i++) { h ^= content.charCodeAt(i); h = Math.imul(h, 0x01000193); // FNV-1a 32-bit prime } return ((h >>> 0) & 0xff).toString(16).padStart(2, '0'); } /** * Format a line for display with its hash anchor. * * Output: `lineNum:hash→content` * * @param lineNum - 1-indexed line number * @param content - Raw line content (no normalisation) */ export function formatLineWithHash(lineNum: number, content: string): string { return `${lineNum}:${lineHash(content)}→${content}`; } /** * Format a line for diff/display with its hash anchor (normalised content). * * @param lineNum - 1-indexed line number * @param rawContent - Original raw content (used to compute hash) * @param displayContent - Normalised content shown to the user */ export function formatLineWithHashDisplay( lineNum: number, rawContent: string, displayContent: string, ): string { return `${lineNum}:${lineHash(rawContent)}→${displayContent}`; } // ─── Anchor parsing & validation ──────────────────────────────────── export interface ParsedAnchor { lineNum: number; hash: string; } /** * Parse an anchor string of the form `lineNum:hash` (e.g. `42:a3`). * Returns null if the format is invalid. */ export function parseAnchor(anchor: string): ParsedAnchor | null { const m = anchor.match(/^(\d+):([0-9a-f]{2})$/i); if (!m) return null; return {lineNum: Number(m[1]), hash: m[2]!.toLowerCase()}; } /** * Validate that an anchor matches the current file content. * * @returns An object with `valid` (whether hash matches) and `lineNum`. * Returns `valid: false` if the anchor format is bad or the line * number is out of range. */ export function validateAnchor( anchor: string, lines: string[], ): {valid: boolean; lineNum: number; expected?: string; actual?: string} { const parsed = parseAnchor(anchor); if (!parsed) return {valid: false, lineNum: -1}; const {lineNum, hash} = parsed; if (lineNum < 1 || lineNum > lines.length) { return {valid: false, lineNum}; } const actual = lineHash(lines[lineNum - 1]!); return { valid: actual === hash, lineNum, expected: hash, actual, }; } /** * Build a complete hash map for a file (for bulk validation). * Returns an array indexed by 0-based line index. */ export function buildHashMap(lines: string[]): string[] { return lines.map(line => lineHash(line)); } ================================================ FILE: source/mcp/utils/filesystem/match-finder.utils.ts ================================================ /** * Match finding utilities for fuzzy search */ interface MatchCandidate { startLine: number; endLine: number; similarity: number; preview: string; } import {calculateSimilarity, normalizeForDisplay} from './similarity.utils.js'; /** * Find the closest matching candidates in the file content * Returns top N candidates sorted by similarity * Optimized with safe pre-filtering and early exit * ASYNC to prevent terminal freeze during search */ export async function findClosestMatches( searchContent: string, fileLines: string[], topN: number = 3, ): Promise<MatchCandidate[]> { const searchLines = searchContent.split('\n'); const candidates: MatchCandidate[] = []; // Fast pre-filter: use first line as anchor (only for multi-line searches) const searchFirstLine = searchLines[0]?.replace(/\s+/g, ' ').trim() || ''; const threshold = 0.5; const usePreFilter = searchLines.length >= 5; // Only for 5+ line searches const preFilterThreshold = 0.2; // Very conservative - only skip completely unrelated lines // Try to find candidates by sliding window with optimizations const maxCandidates = topN * 3; // Collect more candidates, then pick best const YIELD_INTERVAL = 100; // Yield control every 100 iterations for (let i = 0; i <= fileLines.length - searchLines.length; i++) { // Yield control periodically to prevent UI freeze if (i % YIELD_INTERVAL === 0) { await new Promise(resolve => setTimeout(resolve, 0)); } // Quick pre-filter: check first line similarity (only for multi-line) if (usePreFilter) { const firstLineCandidate = fileLines[i]?.replace(/\s+/g, ' ').trim() || ''; const firstLineSimilarity = calculateSimilarity( searchFirstLine, firstLineCandidate, preFilterThreshold, ); // Skip only if first line is very different if (firstLineSimilarity < preFilterThreshold) { continue; } } // Full candidate check const candidateLines = fileLines.slice(i, i + searchLines.length); const candidateContent = candidateLines.join('\n'); const similarity = calculateSimilarity( searchContent, candidateContent, threshold, ); // Only consider candidates with >50% similarity if (similarity > threshold) { candidates.push({ startLine: i + 1, endLine: i + searchLines.length, similarity, preview: candidateLines .map((line, idx) => `${i + idx + 1}→${normalizeForDisplay(line)}`) .join('\n'), }); // Early exit if we found a nearly perfect match if (similarity >= 0.95) { break; } // Limit candidates to avoid excessive computation if (candidates.length >= maxCandidates) { break; } } } // Sort by similarity descending and return top N return candidates.sort((a, b) => b.similarity - a.similarity).slice(0, topN); } /** * Generate a helpful diff message showing differences between search and actual content * Note: This is ONLY for display purposes. Tabs/spaces are normalized for better readability. */ export function generateDiffMessage( searchContent: string, actualContent: string, maxLines: number = 10, ): string { const searchLines = searchContent.split('\n'); const actualLines = actualContent.split('\n'); const diffLines: string[] = []; const maxLen = Math.max(searchLines.length, actualLines.length); for (let i = 0; i < Math.min(maxLen, maxLines); i++) { const searchLine = searchLines[i] || ''; const actualLine = actualLines[i] || ''; if (searchLine !== actualLine) { diffLines.push(`Line ${i + 1}:`); diffLines.push( ` Search: ${JSON.stringify(normalizeForDisplay(searchLine))}`, ); diffLines.push( ` Actual: ${JSON.stringify(normalizeForDisplay(actualLine))}`, ); } } if (maxLen > maxLines) { diffLines.push(`... (${maxLen - maxLines} more lines)`); } return diffLines.join('\n'); } ================================================ FILE: source/mcp/utils/filesystem/message-format.utils.ts ================================================ import type {Diagnostic} from '../../../utils/ui/vscodeConnection.js'; import type {StructureAnalysis} from '../../types/filesystem.types.js'; type DiagnosticsSummaryOptions = { headerLabel?: string; detailsLabel?: string; maxDetails?: number; moreSuffix?: string; includeTip?: boolean; tipText?: string; }; export function appendDiagnosticsSummary( baseMessage: string, filePath: string, diagnostics: Diagnostic[], options: DiagnosticsSummaryOptions = {}, ): string { const { headerLabel = 'Diagnostics detected', detailsLabel = 'Diagnostic Details', maxDetails = 5, moreSuffix = 'more issue(s)', includeTip = false, tipText = '⚡ TIP: Review the errors above and make another edit to fix them', } = options; const errorCount = diagnostics.filter(d => d.severity === 'error').length; const warningCount = diagnostics.filter(d => d.severity === 'warning').length; if (errorCount === 0 && warningCount === 0) { return baseMessage; } let message = `${baseMessage}\n\n⚠️ ${headerLabel}: ${errorCount} error(s), ${warningCount} warning(s)`; const formattedDiagnostics = diagnostics .filter(d => d.severity === 'error' || d.severity === 'warning') .slice(0, maxDetails) .map(d => { const icon = d.severity === 'error' ? '❌' : '⚠️'; const location = `${filePath}:${d.line}:${d.character}`; return ` ${icon} [${d.source || 'unknown'}] ${location}\n ${d.message}`; }) .join('\n\n'); message += `\n\n📋 ${detailsLabel}:\n${formattedDiagnostics}`; if (errorCount + warningCount > maxDetails) { message += `\n ... and ${errorCount + warningCount - maxDetails} ${moreSuffix}`; } if (includeTip) { message += `\n\n ${tipText}`; } return message; } function getStructureWarnings(structureAnalysis: StructureAnalysis): string[] { const warnings: string[] = []; if (!structureAnalysis.bracketBalance.curly.balanced) { const diff = structureAnalysis.bracketBalance.curly.open - structureAnalysis.bracketBalance.curly.close; warnings.push( `Curly brackets: ${ diff > 0 ? `${diff} unclosed {` : `${Math.abs(diff)} extra }` }`, ); } if (!structureAnalysis.bracketBalance.round.balanced) { const diff = structureAnalysis.bracketBalance.round.open - structureAnalysis.bracketBalance.round.close; warnings.push( `Round brackets: ${ diff > 0 ? `${diff} unclosed (` : `${Math.abs(diff)} extra )` }`, ); } if (!structureAnalysis.bracketBalance.square.balanced) { const diff = structureAnalysis.bracketBalance.square.open - structureAnalysis.bracketBalance.square.close; warnings.push( `Square brackets: ${ diff > 0 ? `${diff} unclosed [` : `${Math.abs(diff)} extra ]` }`, ); } if (structureAnalysis.htmlTags && !structureAnalysis.htmlTags.balanced) { if (structureAnalysis.htmlTags.unclosedTags.length > 0) { warnings.push( `Unclosed HTML tags: ${structureAnalysis.htmlTags.unclosedTags.join(', ')}`, ); } if (structureAnalysis.htmlTags.unopenedTags.length > 0) { warnings.push( `Unopened closing tags: ${structureAnalysis.htmlTags.unopenedTags.join(', ')}`, ); } } if (structureAnalysis.indentationWarnings.length > 0) { warnings.push( ...structureAnalysis.indentationWarnings.map( (warning: string) => `Indentation: ${warning}`, ), ); } return warnings; } export function appendStructureWarnings( baseMessage: string, structureAnalysis: StructureAnalysis, tipText: string = '💡 TIP: These warnings help identify potential issues.', ): string { const warnings = getStructureWarnings(structureAnalysis); if (warnings.length === 0) { return baseMessage; } let message = `${baseMessage}\n\n🔍 Structure Analysis:\n`; warnings.forEach(warning => { message += ` ⚠️ ${warning}\n`; }); message += `\n ${tipText}`; return message; } ================================================ FILE: source/mcp/utils/filesystem/office-parser.utils.ts ================================================ /** * Office file parsing utilities * Handles parsing of PDF, Word, Excel, and PowerPoint files */ import {promises as fs} from 'fs'; import mammoth from 'mammoth'; import * as XLSX from 'xlsx'; import type {DocumentContent} from '../../types/filesystem.types.js'; import {OFFICE_FILE_TYPES} from '../../types/filesystem.types.js'; import * as path from 'path'; /** * Parse Word document (.docx, .doc) * @param fullPath - Full path to the Word document * @returns DocumentContent object with extracted text */ export async function parseWordDocument( fullPath: string, ): Promise<DocumentContent | null> { try { const buffer = await fs.readFile(fullPath); const result = await mammoth.extractRawText({buffer}); return { type: 'document', text: result.value, fileType: 'word', metadata: { messages: result.messages.length > 0 ? result.messages : undefined, }, }; } catch (error) { console.error(`Failed to parse Word document ${fullPath}:`, error); return null; } } /** * Parse PDF document * @param fullPath - Full path to the PDF file * @returns DocumentContent object with extracted text */ export async function parsePDFDocument( fullPath: string, ): Promise<DocumentContent | null> { try { // DOMMatrix/ImageData/Path2D polyfills are injected via build.mjs banner // so they exist before pdfjs-dist module-level code executes in the bundle. const {PDFParse} = await import('pdf-parse'); const workerPath = new URL('pdf.worker.mjs', import.meta.url).href; PDFParse.setWorker(workerPath); const buffer = await fs.readFile(fullPath); const uint8Array = new Uint8Array(buffer); const parser = new PDFParse({data: uint8Array}); const data = await parser.getText(); return { type: 'document', text: data.text, fileType: 'pdf', metadata: { pages: data.total, }, }; } catch (error) { console.error(`Failed to parse PDF document ${fullPath}:`, error); return null; } } /** * Parse Excel spreadsheet (.xlsx, .xls) * @param fullPath - Full path to the Excel file * @returns DocumentContent object with extracted text */ export async function parseExcelDocument( fullPath: string, ): Promise<DocumentContent | null> { try { const buffer = await fs.readFile(fullPath); const workbook = XLSX.read(buffer, {type: 'buffer'}); const sheets: string[] = []; let allText = ''; workbook.SheetNames.forEach(sheetName => { sheets.push(sheetName); const worksheet = workbook.Sheets[sheetName]; if (worksheet) { const sheetText = XLSX.utils.sheet_to_txt(worksheet); allText += `\n\n=== Sheet: ${sheetName} ===\n${sheetText}`; } }); return { type: 'document', text: allText.trim(), fileType: 'excel', metadata: { sheets, sheetCount: sheets.length, }, }; } catch (error) { console.error(`Failed to parse Excel document ${fullPath}:`, error); return null; } } /** * Parse PowerPoint presentation (.pptx, .ppt) * Note: PowerPoint parsing is complex and requires unzipping the .pptx file * This is a placeholder implementation * @param fullPath - Full path to the PowerPoint file * @returns DocumentContent object with extracted text */ export async function parsePowerPointDocument( fullPath: string, ): Promise<DocumentContent | null> { try { // PowerPoint parsing requires extracting and parsing XML from the .pptx archive // A full implementation would use JSZip to extract slide XML files // and parse them to extract text content // For now, return a placeholder message return { type: 'document', text: '[PowerPoint parsing not fully implemented yet. Please use a specialized tool to extract text from .pptx files.]', fileType: 'powerpoint', metadata: { note: 'PowerPoint text extraction requires additional implementation', suggestion: 'Consider using external tools or libraries like python-pptx for full PowerPoint text extraction', }, }; } catch (error) { console.error(`Failed to parse PowerPoint document ${fullPath}:`, error); return null; } } /** * Get Office file type based on extension * @param filePath - Path to the file * @returns File type or undefined */ export function getOfficeFileType( filePath: string, ): 'pdf' | 'word' | 'excel' | 'powerpoint' | undefined { const ext = path.extname(filePath).toLowerCase(); return OFFICE_FILE_TYPES[ext]; } /** * Main entry point: Read and parse Office document * @param fullPath - Full path to the Office document * @returns DocumentContent object with extracted text */ export async function readOfficeDocument( fullPath: string, ): Promise<DocumentContent | null> { const fileType = getOfficeFileType(fullPath); if (!fileType) { return null; } let docContent: DocumentContent | null = null; switch (fileType) { case 'word': { docContent = await parseWordDocument(fullPath); break; } case 'pdf': { docContent = await parsePDFDocument(fullPath); break; } case 'excel': { docContent = await parseExcelDocument(fullPath); break; } case 'powerpoint': { docContent = await parsePowerPointDocument(fullPath); break; } } return docContent; } ================================================ FILE: source/mcp/utils/filesystem/path-fixer.utils.ts ================================================ import {promises as fs} from 'node:fs'; import {resolve} from 'node:path'; /** * Attempt to fix common path issues when file is not found * @param originalPath - The original path that failed * @param basePath - Base path for resolving relative paths * @returns Fixed path or null if cannot be fixed */ export async function tryFixPath( originalPath: string, basePath: string, ): Promise<string | null> { try { // Common pattern: "source/mcp/utils/filesystem.ts" should be "source/mcp/filesystem.ts" // Remove unnecessary intermediate directories const segments = originalPath.split('/'); // Try removing 'utils' directory if present if (segments.includes('utils')) { const withoutUtils = segments.filter(s => s !== 'utils').join('/'); const fixedPath = resolve(basePath, withoutUtils); try { await fs.access(fixedPath); return withoutUtils; } catch { // Continue to next attempt } } // Try parent directories for (let i = 0; i < segments.length - 1; i++) { const reducedPath = [ ...segments.slice(0, i), segments[segments.length - 1], ].join('/'); const fixedPath = resolve(basePath, reducedPath); try { await fs.access(fixedPath); return reducedPath; } catch { // Continue to next attempt } } // Try searching for the file by name in common directories const fileName = segments[segments.length - 1]; const commonDirs = ['source', 'src', 'lib', 'dist']; for (const dir of commonDirs) { const searchPath = `${dir}/${fileName}`; const fixedPath = resolve(basePath, searchPath); try { await fs.access(fixedPath); return searchPath; } catch { // Continue to next attempt } } return null; } catch { return null; } } ================================================ FILE: source/mcp/utils/filesystem/read-tools.utils.ts ================================================ import {promises as fs} from 'fs'; import {isAbsolute} from 'path'; import type { MultipleFilesReadResult, MultimodalContent, SingleFileReadResult, } from '../../types/filesystem.types.js'; import type {CodeSymbol} from '../../types/aceCodeSearch.types.js'; import {parseFileSymbols} from '../aceCodeSearch/symbol.utils.js'; import { readFileLinesStreaming, readFileWithEncoding, } from './encoding.utils.js'; import {readOfficeDocument} from './office-parser.utils.js'; import {formatLineWithHash} from './hashline.utils.js'; type GetFileContentContext = { basePath: string; resolvePath: (filePath: string, contextPath?: string) => string; validatePath: (fullPath: string) => Promise<void>; listFiles: (dirPath?: string) => Promise<string[]>; isSSHPath: (filePath: string) => boolean; readRemoteFile: (sshUrl: string) => Promise<string>; isImageFile: (filePath: string) => boolean; readImageAsBase64: (fullPath: string) => Promise< | { type: 'image'; data: string; mimeType: string; } | null >; isOfficeFile: (filePath: string) => boolean; getNotebookEntries: (filePath: string) => string; extractRelevantSymbols: ( symbols: CodeSymbol[], startLine: number, endLine: number, totalLines: number, ) => string; }; export async function executeGetFileContentCore( ctx: GetFileContentContext, filePath: | string | string[] | Array<{path: string; startLine?: number; endLine?: number}>, startLine?: number, endLine?: number, ): Promise<SingleFileReadResult | MultipleFilesReadResult> { // Handle array of files if (Array.isArray(filePath)) { const filesData: Array<{ path: string; startLine?: number; endLine?: number; totalLines?: number; isImage?: boolean; isDocument?: boolean; fileType?: 'pdf' | 'word' | 'excel' | 'powerpoint'; mimeType?: string; }> = []; const multimodalContent: MultimodalContent = []; let lastAbsolutePath: string | undefined; for (const fileItem of filePath) { try { let file: string; let fileStartLine: number | undefined; let fileEndLine: number | undefined; if (typeof fileItem === 'string') { file = fileItem; fileStartLine = startLine; fileEndLine = endLine; } else { file = fileItem.path; fileStartLine = fileItem.startLine ?? startLine; fileEndLine = fileItem.endLine ?? endLine; } const fullPath = ctx.resolvePath(file, lastAbsolutePath); if (isAbsolute(file)) { lastAbsolutePath = fullPath; } if (!isAbsolute(file)) { await ctx.validatePath(fullPath); } const stats = await fs.stat(fullPath); if (stats.isDirectory()) { const dirFiles = await ctx.listFiles(file); const fileList = dirFiles.join('\n'); multimodalContent.push({ type: 'text', text: `📁 Directory: ${file}\n${fileList}`, }); filesData.push({ path: file, startLine: 1, endLine: dirFiles.length, totalLines: dirFiles.length, }); continue; } if (ctx.isImageFile(fullPath)) { const imageContent = await ctx.readImageAsBase64(fullPath); if (imageContent) { multimodalContent.push({ type: 'text', text: `🖼️ Image: ${file} (${imageContent.mimeType})`, }); multimodalContent.push(imageContent); filesData.push({ path: file, isImage: true, mimeType: imageContent.mimeType, }); continue; } } if (ctx.isOfficeFile(fullPath)) { const docContent = await readOfficeDocument(fullPath); if (docContent) { multimodalContent.push({ type: 'text', text: `📄 ${docContent.fileType.toUpperCase()} Document: ${file}`, }); multimodalContent.push(docContent); filesData.push({ path: file, isDocument: true, fileType: docContent.fileType, }); continue; } } const fileSizeBytes = stats.size; const FILE_SIZE_LIMIT = 256 * 1024 * 1024; let content: string | undefined; let lines: string[]; let totalLines: number; if (fileSizeBytes > FILE_SIZE_LIMIT) { const actualStart = fileStartLine ?? 1; const actualEnd = fileEndLine ?? 500; if (actualStart < 1) { throw new Error(`Start line must be greater than 0 for ${file}`); } const streamed = await readFileLinesStreaming( fullPath, actualStart, actualEnd, ); lines = streamed.lines; totalLines = streamed.totalLines; } else { content = await readFileWithEncoding(fullPath); lines = content.split('\n'); totalLines = lines.length; } const actualStartLine = fileStartLine ?? 1; const actualEndLine = fileSizeBytes > FILE_SIZE_LIMIT ? fileEndLine ?? 500 : fileEndLine ?? totalLines; if (actualStartLine < 1) { throw new Error(`Start line must be greater than 0 for ${file}`); } if (actualEndLine < actualStartLine) { throw new Error( `End line must be greater than or equal to start line for ${file}`, ); } const start = Math.min(actualStartLine, totalLines); const end = Math.min(totalLines, actualEndLine); const selectedLines = fileSizeBytes > FILE_SIZE_LIMIT ? lines : lines.slice(start - 1, end); const numberedLines = selectedLines.map((line, index) => formatLineWithHash(start + index, line), ); const sizeWarning = fileSizeBytes > FILE_SIZE_LIMIT ? ` [Large file: ${Math.round(fileSizeBytes / 1024 / 1024)}MB]` : ''; let fileContent = `📄 ${file} (lines ${start}-${end}/${totalLines})${sizeWarning}\n${numberedLines.join('\n')}`; if (content) { try { const symbols = await parseFileSymbols(fullPath, content, ctx.basePath); const symbolInfo = ctx.extractRelevantSymbols( symbols, start, end, totalLines, ); if (symbolInfo) { fileContent += symbolInfo; } } catch { // optional } } const notebookInfo = ctx.getNotebookEntries(file); if (notebookInfo) { fileContent += notebookInfo; } multimodalContent.push({type: 'text', text: fileContent}); filesData.push({path: file, startLine: start, endLine: end, totalLines}); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown error'; const inputPath = typeof fileItem === 'string' ? fileItem : fileItem.path; let resolvedPathInfo = ''; try { const attemptedResolve = ctx.resolvePath(inputPath, lastAbsolutePath); if (attemptedResolve !== inputPath) { resolvedPathInfo = `\n Resolved to: ${attemptedResolve}`; } } catch { // ignore } multimodalContent.push({ type: 'text', text: `❌ ${inputPath}${resolvedPathInfo}\n Error: ${errorMsg}`, }); } } return { content: multimodalContent, files: filesData, totalFiles: filePath.length, }; } if (ctx.isSSHPath(filePath)) { const content = await ctx.readRemoteFile(filePath); const lines = content.split('\n'); const totalLines = lines.length; const actualStartLine = startLine ?? 1; const actualEndLine = endLine ?? totalLines; if (actualStartLine < 1) { throw new Error('Start line must be greater than 0'); } if (actualEndLine < actualStartLine) { throw new Error('End line must be greater than or equal to start line'); } const start = Math.min(actualStartLine, totalLines); const end = Math.min(totalLines, actualEndLine); const selectedLines = lines.slice(start - 1, end); const numberedLines = selectedLines.map( (line, index) => `${start + index}->${line}`, ); return { content: numberedLines.join('\n'), startLine: start, endLine: end, totalLines, }; } const fullPath = ctx.resolvePath(filePath); if (!isAbsolute(filePath)) { await ctx.validatePath(fullPath); } const stats = await fs.stat(fullPath); if (stats.isDirectory()) { const files = await ctx.listFiles(filePath); const fileList = files.join('\n'); const lines = fileList.split('\n'); return { content: `Directory: ${filePath}\n\n${fileList}`, startLine: 1, endLine: lines.length, totalLines: lines.length, }; } if (ctx.isImageFile(fullPath)) { const imageContent = await ctx.readImageAsBase64(fullPath); if (imageContent) { return { content: [ { type: 'text', text: `🖼️ Image: ${filePath} (${imageContent.mimeType})`, }, imageContent, ], isImage: true, mimeType: imageContent.mimeType, }; } } if (ctx.isOfficeFile(fullPath)) { const docContent = await readOfficeDocument(fullPath); if (docContent) { return { content: [ { type: 'text', text: `📄 ${docContent.fileType.toUpperCase()} Document: ${filePath}`, }, docContent, ], isDocument: true, fileType: docContent.fileType, }; } } let content: string | undefined; let lines: string[]; let totalLines: number; const fileSizeBytes = stats.size; const FILE_SIZE_LIMIT = 256 * 1024 * 1024; if (fileSizeBytes > FILE_SIZE_LIMIT) { const actualStartLine = startLine ?? 1; const actualEndLine = endLine ?? 500; if (actualStartLine < 1) { throw new Error('Start line must be greater than 0'); } const streamed = await readFileLinesStreaming( fullPath, actualStartLine, actualEndLine, ); lines = streamed.lines; totalLines = streamed.totalLines; const start = Math.min(actualStartLine, totalLines); const end = Math.min(totalLines, Math.min(actualEndLine, start + lines.length - 1)); const numberedLines = lines.map((line, index) => formatLineWithHash(start + index, line), ); const sizeInfo = `[File: ${Math.round(fileSizeBytes / 1024 / 1024)}MB, ${totalLines} lines total. Showing lines ${start}-${end}. Use startLine/endLine to read other sections.]`; return { content: `${sizeInfo}\n${numberedLines.join('\n')}`, startLine: start, endLine: end, totalLines, }; } content = await readFileWithEncoding(fullPath); lines = content.split('\n'); totalLines = lines.length; const actualStartLine = startLine ?? 1; const actualEndLine = endLine ?? totalLines; if (actualStartLine < 1) { throw new Error('Start line must be greater than 0'); } if (actualEndLine < actualStartLine) { throw new Error('End line must be greater than or equal to start line'); } const start = Math.min(actualStartLine, totalLines); const end = Math.min(totalLines, actualEndLine); const selectedLines = lines.slice(start - 1, end); const numberedLines = selectedLines.map((line, index) => formatLineWithHash(start + index, line), ); let partialContent = numberedLines.join('\n'); try { const symbols = await parseFileSymbols(fullPath, content, ctx.basePath); const symbolInfo = ctx.extractRelevantSymbols(symbols, start, end, totalLines); if (symbolInfo) { partialContent += symbolInfo; } } catch { // optional } const notebookInfo = ctx.getNotebookEntries(filePath); if (notebookInfo) { partialContent += notebookInfo; } return { content: partialContent, startLine: start, endLine: end, totalLines, }; } ================================================ FILE: source/mcp/utils/filesystem/similarity.utils.ts ================================================ /** * Similarity calculation utilities for fuzzy matching */ /** * Calculate similarity between two strings using a smarter algorithm * This normalizes whitespace first to avoid false negatives from spacing differences * Returns a value between 0 (completely different) and 1 (identical) */ export function calculateSimilarity( str1: string, str2: string, threshold: number = 0, ): number { // Normalize whitespace for comparison: collapse all whitespace to single spaces const normalize = (s: string) => s.replace(/\s+/g, ' ').trim(); const norm1 = normalize(str1); const norm2 = normalize(str2); const len1 = norm1.length; const len2 = norm2.length; if (len1 === 0) return len2 === 0 ? 1 : 0; if (len2 === 0) return 0; // Quick length check - if lengths differ too much, similarity can't be above threshold const maxLen = Math.max(len1, len2); const minLen = Math.min(len1, len2); const lengthRatio = minLen / maxLen; if (threshold > 0 && lengthRatio < threshold) { return lengthRatio; // Can't possibly meet threshold } // Use Levenshtein distance for better similarity calculation const distance = levenshteinDistance( norm1, norm2, Math.ceil(maxLen * (1 - threshold)), ); return 1 - distance / maxLen; } /** * Calculate Levenshtein distance between two strings with early termination * @param str1 First string * @param str2 Second string * @param maxDistance Maximum distance to compute (early exit if exceeded) * @returns Levenshtein distance, or maxDistance+1 if exceeded */ export function levenshteinDistance( str1: string, str2: string, maxDistance: number = Infinity, ): number { const len1 = str1.length; const len2 = str2.length; // Quick exit for identical strings if (str1 === str2) return 0; // Quick exit if length difference already exceeds maxDistance if (Math.abs(len1 - len2) > maxDistance) { return maxDistance + 1; } // Use single-row algorithm to save memory (only need previous row) let prevRow: number[] = Array.from({length: len2 + 1}, (_, i) => i); for (let i = 1; i <= len1; i++) { const currRow: number[] = [i]; let minInRow = i; // Track minimum value in current row for (let j = 1; j <= len2; j++) { const cost = str1[i - 1] === str2[j - 1] ? 0 : 1; const val = Math.min( prevRow[j]! + 1, // deletion currRow[j - 1]! + 1, // insertion prevRow[j - 1]! + cost, // substitution ); currRow[j] = val; minInRow = Math.min(minInRow, val); } // Early termination: if minimum in this row exceeds maxDistance, we can stop if (minInRow > maxDistance) { return maxDistance + 1; } prevRow = currRow; } return prevRow[len2]!; } /** * Async version of Levenshtein distance - yields to event loop periodically * Maintains 100% identical logic to sync version, just with async yielding * @param str1 First string * @param str2 Second string * @param maxDistance Maximum distance to compute (early exit if exceeded) * @param batchSize How many rows to process before yielding (default: 50) * @returns Promise<Levenshtein distance, or maxDistance+1 if exceeded> */ export async function levenshteinDistanceAsync( str1: string, str2: string, maxDistance: number = Infinity, batchSize: number = 50, ): Promise<number> { const len1 = str1.length; const len2 = str2.length; // Quick exit for identical strings if (str1 === str2) return 0; // Quick exit if length difference already exceeds maxDistance if (Math.abs(len1 - len2) > maxDistance) { return maxDistance + 1; } // Use single-row algorithm to save memory (only need previous row) let prevRow: number[] = Array.from({length: len2 + 1}, (_, i) => i); for (let i = 1; i <= len1; i++) { const currRow: number[] = [i]; let minInRow = i; // Track minimum value in current row for (let j = 1; j <= len2; j++) { const cost = str1[i - 1] === str2[j - 1] ? 0 : 1; const val = Math.min( prevRow[j]! + 1, // deletion currRow[j - 1]! + 1, // insertion prevRow[j - 1]! + cost, // substitution ); currRow[j] = val; minInRow = Math.min(minInRow, val); } // Early termination: if minimum in this row exceeds maxDistance, we can stop if (minInRow > maxDistance) { return maxDistance + 1; } prevRow = currRow; // Yield to event loop periodically to prevent UI freeze // This maintains the same computation but allows async execution if (i % batchSize === 0) { await new Promise(resolve => setImmediate(resolve)); } } return prevRow[len2]!; } /** * Async version of calculateSimilarity - preserves 100% precision * Uses async Levenshtein distance to prevent UI freeze on large searches * @param str1 First string * @param str2 Second string * @param threshold Similarity threshold for early exit consideration * @returns Promise<number> - Similarity value between 0 and 1 */ export async function calculateSimilarityAsync( str1: string, str2: string, threshold: number = 0, ): Promise<number> { // Normalize whitespace for comparison: collapse all whitespace to single spaces const normalize = (s: string) => s.replace(/\s+/g, ' ').trim(); const norm1 = normalize(str1); const norm2 = normalize(str2); const len1 = norm1.length; const len2 = norm2.length; if (len1 === 0) return len2 === 0 ? 1 : 0; if (len2 === 0) return 0; // Quick length check - if lengths differ too much, similarity can't be above threshold const maxLen = Math.max(len1, len2); const minLen = Math.min(len1, len2); const lengthRatio = minLen / maxLen; if (threshold > 0 && lengthRatio < threshold) { return lengthRatio; // Can't possibly meet threshold } // Use async Levenshtein distance for better similarity calculation // This yields to event loop periodically to prevent UI freeze const distance = await levenshteinDistanceAsync( norm1, norm2, Math.ceil(maxLen * (1 - threshold)), ); return 1 - distance / maxLen; } /** * Normalize whitespace for display purposes * Makes preview more readable by collapsing whitespace */ export function normalizeForDisplay(line: string): string { return line.replace(/\t/g, ' ').replace(/ +/g, ' ').replace(/\r/g, ''); } ================================================ FILE: source/mcp/utils/todo/date.utils.ts ================================================ /** * Date utilities for TODO service */ /** * Format date for folder name (YYYY-MM-DD) * @param date - Date to format * @returns Formatted date string */ export function formatDateForFolder(date: Date): string { const year = date.getFullYear(); const month = String(date.getMonth() + 1).padStart(2, '0'); const day = String(date.getDate()).padStart(2, '0'); return `${year}-${month}-${day}`; } ================================================ FILE: source/mcp/utils/websearch/browser.utils.ts ================================================ /** * Browser detection utilities for web search */ import {execSync, spawn, type ChildProcess} from 'node:child_process'; import {existsSync, readFileSync} from 'node:fs'; import {platform} from 'node:os'; import {request} from 'node:http'; /** * Check if running inside WSL (Windows Subsystem for Linux) * @returns true if running in WSL environment */ export function isWSL(): boolean { try { // Check /proc/version for Microsoft/WSL indicators if (existsSync('/proc/version')) { const version = readFileSync('/proc/version', 'utf8').toLowerCase(); return version.includes('microsoft') || version.includes('wsl'); } // Check for WSL-specific environment variables if (process.env['WSL_DISTRO_NAME'] || process.env['WSL_INTEROP']) { return true; } } catch { // Ignore errors } return false; } /** * Find Windows browser path when running in WSL * @returns Windows browser path accessible from WSL, or null */ export function findWindowsBrowserInWSL(): string | null { const windowsPaths = [ '/mnt/c/Program Files/Microsoft/Edge/Application/msedge.exe', '/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe', '/mnt/c/Program Files/Google/Chrome/Application/chrome.exe', '/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe', ]; for (const path of windowsPaths) { if (existsSync(path)) { return path; } } return null; } // Store reference to spawned browser process for cleanup let spawnedBrowserProcess: ChildProcess | null = null; /** * Launch Windows browser from WSL with remote debugging enabled * @param browserPath - Path to Windows browser executable * @param debugPort - Remote debugging port (default: 9222) * @returns WebSocket debugger URL or null if failed */ export async function launchWindowsBrowserFromWSL( browserPath: string, debugPort: number = 9222, ): Promise<string | null> { // Convert WSL path to Windows path for the user data directory const userDataDir = 'C:\\\\temp\\\\snow-browser-debug'; // Build the command to run via PowerShell // Convert /mnt/c/... path to C:\... for PowerShell const windowsPath = browserPath .replace(/^\/mnt\/([a-z])\//, '$1:\\\\') .replace(/\//g, '\\\\'); const args = [ '--headless=new', '--disable-gpu', '--no-sandbox', '--disable-dev-shm-usage', `--remote-debugging-port=${debugPort}`, `--user-data-dir=${userDataDir}`, ]; try { // Use PowerShell to start the browser process on Windows side const psCommand = `Start-Process -FilePath '${windowsPath}' -ArgumentList '${args.join( ' ', )}' -PassThru`; spawnedBrowserProcess = spawn('powershell.exe', ['-Command', psCommand], { detached: true, stdio: 'ignore', }); spawnedBrowserProcess.unref(); // Wait for browser to start and get WebSocket URL const maxRetries = 10; const retryDelay = 500; for (let i = 0; i < maxRetries; i++) { await new Promise(resolve => setTimeout(resolve, retryDelay)); // Use node:http to check if browser is ready (avoids proxy issues) const wsUrl = await getRunningBrowserWSEndpoint(debugPort); if (wsUrl) { return wsUrl; } } return null; } catch { return null; } } /** * Check if a browser is already running with remote debugging on specified port * Uses node:http instead of fetch to avoid proxy issues in WSL * @param debugPort - Remote debugging port to check * @returns WebSocket debugger URL if browser is running, null otherwise */ export async function getRunningBrowserWSEndpoint( debugPort: number = 9222, ): Promise<string | null> { return new Promise(resolve => { const req = request( { hostname: 'localhost', port: debugPort, path: '/json/version', method: 'GET', timeout: 3000, }, res => { let data = ''; res.on('data', chunk => { data += chunk; }); res.on('end', () => { try { const json = JSON.parse(data) as {webSocketDebuggerUrl?: string}; resolve(json.webSocketDebuggerUrl || null); } catch { resolve(null); } }); }, ); req.on('error', () => { resolve(null); }); req.on('timeout', () => { req.destroy(); resolve(null); }); req.end(); }); } /** * Detect system Chrome/Edge browser executable path * @returns Browser executable path or null if not found */ export function findBrowserExecutable(): string | null { const os = platform(); const paths: string[] = []; if (os === 'win32') { // Windows: Prioritize Edge (built-in), then Chrome const edgePaths = [ 'C:\\\\Program Files\\\\Microsoft\\\\Edge\\\\Application\\\\msedge.exe', 'C:\\\\Program Files (x86)\\\\Microsoft\\\\Edge\\\\Application\\\\msedge.exe', ]; const chromePaths = [ 'C:\\\\Program Files\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe', 'C:\\\\Program Files (x86)\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe', process.env['LOCALAPPDATA'] + '\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe', ]; paths.push(...edgePaths, ...chromePaths); } else if (os === 'darwin') { // macOS paths.push( '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', ); } else { // Linux (including WSL - but for WSL we prefer Windows browser) const binPaths = [ 'google-chrome', 'chromium', 'chromium-browser', 'microsoft-edge', ]; for (const bin of binPaths) { try { const path = execSync(`which ${bin}`, {encoding: 'utf8'}).trim(); if (path) { return path; } } catch { // Continue to next binary } } } // Check if any path exists for (const path of paths) { if (path && existsSync(path)) { return path; } } return null; } ================================================ FILE: source/mcp/utils/websearch/text.utils.ts ================================================ /** * Text processing utilities for web search */ import type {SearchResponse} from '../../types/websearch.types.js'; /** * Clean text by removing extra whitespace and HTML entities * @param text - Raw text to clean * @returns Cleaned text */ export function cleanText(text: string): string { return text .replace(/\s+/g, ' ') // Replace multiple spaces with single space .replace(/"/g, '"') .replace(/&/g, '&') .replace(/</g, '<') .replace(/>/g, '>') .replace(/<b>/g, '') .replace(/<\/b>/g, '') .trim(); } /** * Format search results as readable text for AI consumption * @param searchResponse - Search response object * @returns Formatted text representation */ export function formatSearchResults(searchResponse: SearchResponse): string { const {query, results, totalResults} = searchResponse; let output = `Search Results for: "${query}"\n`; output += `Found ${totalResults} results\n\n`; output += '='.repeat(80) + '\n\n'; results.forEach((result, index) => { output += `${index + 1}. ${result.title}\n`; output += ` URL: ${result.url}\n`; if (result.snippet) { output += ` ${result.snippet}\n`; } output += '\n'; }); return output; } ================================================ FILE: source/mcp/websearch.ts ================================================ import puppeteer, {type Browser, type Page} from 'puppeteer-core'; import {existsSync} from 'node:fs'; import {tmpdir} from 'node:os'; import {join} from 'node:path'; import {getProxyConfig} from '../utils/config/proxyConfig.js'; // Type definitions import type {SearchResponse, WebPageContent} from './types/websearch.types.js'; // Utility functions import { findBrowserExecutable, isWSL, findWindowsBrowserInWSL, launchWindowsBrowserFromWSL, getRunningBrowserWSEndpoint, } from './utils/websearch/browser.utils.js'; import {cleanText} from './utils/websearch/text.utils.js'; import { getSearchEngine, ensureSearchEnginesLoaded, } from './engines/websearch/index.js'; /** * Web Search Service using a pluggable search engine (DuckDuckGo / Bing / ...) * driven by Puppeteer Core. * * The browser lifecycle (launch / connect / close) is owned by this service; * the actual per-engine search/extraction logic lives under * `./engines/websearch/*`. To add a new engine, implement `SearchEngine` and * register it in `./engines/websearch/index.ts`. * * Uses system-installed Chrome/Edge to reduce package size and supports WSL * by connecting to a Windows browser via WebSocket. */ export class WebSearchService { private maxResults: number; private browser: Browser | null = null; private executablePath: string | null = null; private isWSLMode: boolean = false; private userDataDir: string | undefined; constructor(maxResults: number = 10) { this.maxResults = maxResults; // Detect WSL environment once this.isWSLMode = isWSL(); // Windows native mode: keep a stable profile per CLI process to avoid // lockfile cleanup issues while preventing cross-terminal profile conflicts. if (process.platform === 'win32' && !this.isWSLMode) { this.userDataDir = join( tmpdir(), `snow-cli-puppeteer-profile-${process.pid}`, ); } } /** * Launch browser with proxy settings from config * In WSL mode, connects to Windows browser via WebSocket */ private async launchBrowser(): Promise<Browser> { if (this.browser && this.browser.connected) { return this.browser; } const proxyConfig = getProxyConfig(); const debugPort = proxyConfig.browserDebugPort || 9222; // WSL Mode: Connect to Windows browser via WebSocket if (this.isWSLMode) { return this.launchBrowserWSL(proxyConfig, debugPort); } // Standard Mode: Launch browser directly return this.launchBrowserDirect(proxyConfig); } /** * Launch browser in WSL mode by connecting to Windows browser */ private async launchBrowserWSL( proxyConfig: ReturnType<typeof getProxyConfig>, debugPort: number, ): Promise<Browser> { // First check if browser is already running on debug port let wsEndpoint = await getRunningBrowserWSEndpoint(debugPort); if (!wsEndpoint) { // Need to launch Windows browser // Priority: 1. User-configured path, 2. Auto-detect Windows browser in WSL let browserPath: string | null | undefined = proxyConfig.browserPath; if (!browserPath || !existsSync(browserPath)) { browserPath = findWindowsBrowserInWSL(); } if (!browserPath) { throw new Error( 'No Windows browser found in WSL environment. Please install Chrome or Edge on Windows, ' + 'or configure browser path in ~/.snow/proxy-config.json (browserPath). ' + 'Expected paths: /mnt/c/Program Files/Microsoft/Edge/Application/msedge.exe', ); } // Launch Windows browser with remote debugging wsEndpoint = await launchWindowsBrowserFromWSL(browserPath, debugPort); if (!wsEndpoint) { throw new Error( `Failed to launch Windows browser from WSL. Browser path: ${browserPath}. ` + `Debug port: ${debugPort}. Make sure the browser is not already running ` + `or try a different port in ~/.snow/proxy-config.json (browserDebugPort).`, ); } } try { this.browser = await puppeteer.connect({ browserWSEndpoint: wsEndpoint, }); return this.browser; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); throw new Error( `Failed to connect to Windows browser via WebSocket. Endpoint: ${wsEndpoint}. ` + `Original error: ${errorMessage}`, ); } } /** * Launch browser directly (non-WSL mode) */ private async launchBrowserDirect( proxyConfig: ReturnType<typeof getProxyConfig>, ): Promise<Browser> { // Find browser executable path (cache it) // Priority: 1. User-configured path, 2. Auto-detect if (!this.executablePath) { // First try user-configured browser path if (proxyConfig.browserPath && existsSync(proxyConfig.browserPath)) { this.executablePath = proxyConfig.browserPath; } else { // Fallback to auto-detection this.executablePath = findBrowserExecutable(); if (!this.executablePath) { throw new Error( 'No system browser found. Please install Chrome or Edge browser, or configure browser path in Proxy settings.', ); } } } const launchArgs = [ '--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--disable-accelerated-2d-canvas', '--disable-gpu', ]; // Only add proxy if enabled if (proxyConfig.enabled) { launchArgs.unshift(`--proxy-server=http://127.0.0.1:${proxyConfig.port}`); } try { this.browser = await puppeteer.launch({ executablePath: this.executablePath, headless: true, args: launchArgs, userDataDir: this.userDataDir, }); } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : String(error); const browserPathInfo = this.executablePath ? `Browser path: ${this.executablePath}` : 'Browser path not set'; throw new Error( `Failed to launch the browser process. ${browserPathInfo}. On Linux, ensure Chromium/Chrome is installed and required dependencies are available. You can set a custom browser path in Settings > Proxy & Browser or in ~/.snow/proxy-config.json (browserPath). Original error: ${errorMessage}`, ); } return this.browser; } /** * Close browser instance */ async closeBrowser(): Promise<void> { if (this.browser) { if (this.isWSLMode) { // In WSL mode, just disconnect (don't close the Windows browser) try { this.browser.disconnect(); } catch { // Ignore disconnect errors } } else { try { await this.browser.close(); } catch { // Ignore close errors (e.g., Windows EBUSY/lockfile issues) } } this.browser = null; } } /** * Perform a web search using the engine selected in proxy config. * @param query - Search query string * @param maxResults - Maximum number of results to return (default: 10) * @returns Search results with title, URL, and snippet */ async search(query: string, maxResults?: number): Promise<SearchResponse> { const limit = maxResults || this.maxResults; let page: Page | null = null; try { // Resolve search engine from current proxy/search config. Ensure // user-supplied plugins under ~/.snow/plugin/search_engines/ are // loaded into the registry before resolving — this is a no-op after // the first call. await ensureSearchEnginesLoaded(); const proxyConfig = getProxyConfig(); const engine = getSearchEngine(proxyConfig.searchEngine); // Launch browser with proxy const browser = await this.launchBrowser(); page = await browser.newPage(); // Set realistic user agent await page.setUserAgent( 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36', ); // Delegate the actual search/extraction to the engine. const cleanedResults = await engine.search(page, query, limit); // Close the page await page.close(); return { query, results: cleanedResults, totalResults: cleanedResults.length, }; } catch (error: any) { // Clean up page on error if (page) { try { await page.close(); } catch { // Ignore close errors } } throw new Error(`Web search failed: ${error.message}`); } } /** * Fetch and extract content from a web page * @param url - URL of the web page to fetch * @param maxLength - Maximum content length (default: 50000 characters) * @param isUserProvided - Whether the URL is user-provided (true) or from search results (false) * @param userQuery - Optional user query for content extraction using compact model agent * @param abortSignal - Optional abort signal from main flow * @param onTokenUpdate - Optional callback to update token count during compression * @returns Cleaned page content */ async fetchPage( url: string, maxLength: number = 50000, isUserProvided: boolean = false, userQuery?: string, abortSignal?: AbortSignal, onTokenUpdate?: (tokenCount: number) => void, ): Promise<WebPageContent> { let page: Page | null = null; try { // Launch browser with proxy const browser = await this.launchBrowser(); page = await browser.newPage(); // Set realistic user agent await page.setUserAgent( 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36', ); // Navigate to page with timeout await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000, }); // Extract content using browser context const pageData = await page.evaluate(() => { // Remove unwanted elements const selectorsToRemove = [ 'script', 'style', 'nav', 'header', 'footer', 'iframe', 'noscript', 'svg', '.advertisement', '.ad', '.ads', '#cookie-banner', '.cookie-notice', '.social-share', '.comments', '.sidebar', '[role="banner"]', '[role="navigation"]', '[role="complementary"]', ]; selectorsToRemove.forEach(selector => { document.querySelectorAll(selector).forEach(el => el.remove()); }); // Get title const title = document.title || ''; // Try to find main content area let mainContent: Element | null = null; const mainSelectors = [ 'article', 'main', '[role="main"]', '.main-content', '.content', '#content', '.article-body', '.post-content', ]; for (const selector of mainSelectors) { mainContent = document.querySelector(selector); if (mainContent) break; } // Fallback to body if no main content found const contentElement = mainContent || document.body; // Extract text content const textContent = contentElement.textContent || ''; return { title, textContent, }; }); // Clean and process the text let cleanedContent = pageData.textContent .replace(/\s+/g, ' ') // Replace multiple spaces with single space .replace(/\n\s*\n/g, '\n') // Remove empty lines .trim(); // Limit content length if (cleanedContent.length > maxLength) { cleanedContent = cleanedContent.slice(0, maxLength) + '\n\n[Content truncated...]'; } // Create preview (first 500 characters) const contentPreview = cleanedContent.slice(0, 500) + (cleanedContent.length > 500 ? '...' : ''); // Close the page await page.close(); // Use compact agent to extract key information if userQuery is provided // Skip compression for user-provided URLs - return full cleaned content let finalContent = cleanedContent; if (userQuery && !isUserProvided) { try { const {compactAgent} = await import('../agents/compactAgent.js'); const isAvailable = await compactAgent.isAvailable(); if (isAvailable) { // Use compact model to extract relevant information // No timeout - let it run as long as needed finalContent = await compactAgent.extractWebPageContent( cleanedContent, userQuery, url, abortSignal, onTokenUpdate, ); } } catch (error: any) { // If compact agent fails, fallback to original content // Error is already logged in compactAgent } } return { url, title: cleanText(pageData.title), content: finalContent, textLength: finalContent.length, contentPreview, }; } catch (error: any) { // Clean up page on error if (page) { try { await page.close(); } catch { // Ignore close errors } } throw new Error(`Failed to fetch page: ${error.message}`); } } } // Export a default instance export const webSearchService = new WebSearchService(); // MCP Tool definitions export const mcpTools = [ { name: 'websearch-search', description: 'Search the web using the configured search engine (DuckDuckGo or Bing). Returns a list of search results with titles, URLs, and snippets. Best for finding current information, documentation, news, or general web content. **IMPORTANT WORKFLOW**: After getting search results, analyze them and choose ONLY ONE most credible and relevant page to fetch. Do NOT fetch multiple pages - reading one high-quality source is sufficient and more efficient.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query string (e.g., "Claude latest model", "TypeScript best practices")', }, maxResults: { type: 'number', description: 'Maximum number of results to return (default: 10, max: 20)', default: 10, minimum: 1, maximum: 20, }, }, required: ['query'], }, }, { name: 'websearch-fetch', description: 'Fetch and read the full content of a web page. Automatically cleans HTML and extracts the main text content, removing ads, navigation, and other noise. **USAGE RULE**: Only fetch ONE page per search - choose the most credible and relevant result (prefer official documentation, reputable tech sites, or well-known sources). **IMPORTANT**: The isUserProvided parameter determines whether content is compressed - user-provided URLs return full cleaned content, while search result URLs use AI compression.', inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Full URL of the web page to fetch (e.g., "https://example.com/article")', }, maxLength: { type: 'number', description: 'Maximum content length in characters (default: 50000, max: 100000)', default: 50000, minimum: 1000, maximum: 100000, }, isUserProvided: { type: 'boolean', description: 'REQUIRED: Whether the URL is directly provided by the user (true) or from search results (false). If true, returns full cleaned content without AI compression. If false, uses compact AI model to extract relevant information based on userQuery.', }, userQuery: { type: 'string', description: "Optional: User's original question or query. Only used when isUserProvided=false for intelligent content extraction - the compact AI model will extract only information relevant to this query, reducing content size by 80-95%.", }, }, required: ['url', 'isUserProvided'], }, }, ]; ================================================ FILE: source/prompt/planModeSystemPrompt.ts ================================================ /** * System prompt configuration for Plan Mode * * Plan Mode is a specialized agent that focuses on task analysis and planning, * creating structured execution plans for complex requirements. */ import { getSystemPromptWithRole as getSystemPromptWithRoleHelper, getSystemEnvironmentInfo, isCodebaseEnabled, getCurrentTimeInfo, appendSystemContext, getToolDiscoverySection as getToolDiscoverySectionHelper, } from './shared/promptHelpers.js'; const PLAN_MODE_SYSTEM_PROMPT = `You are Snow AI CLI - Plan Mode, a task planning and coordination agent that transforms complex requirements into structured, executable plans. ## Core Identity You are a **planner and coordinator**, not a code writer. Your value lies in: - Thorough analysis that catches issues before they become problems - Clear plans that make execution predictable and safe - Smart delegation that leverages specialized sub-agents - Rigorous verification that ensures quality at every step **Language Rule**: ALWAYS respond in the SAME language as the user's query. ## Workflow: Analyze → Confirm → Execute → Verify ### Step 1: Deep Analysis & Plan Creation Before writing any plan, thoroughly investigate the codebase: PLACEHOLDER_FOR_ANALYSIS_TOOLS_SECTION **Analysis Checklist**: - Understand the current architecture and patterns in use - Identify ALL files that will be affected (direct and indirect) - Map dependencies and potential ripple effects - Assess risks: What could go wrong? What are the edge cases? - Consider backward compatibility and migration needs **Create the plan document** in \`.snow/plan/[task-name].md\`: \`\`\`markdown # [Task Name] ## Context [Why this change is needed, what problem it solves] ## Analysis - **Affected files**: [list with brief reason for each] - **New files**: [list with purpose] - **Dependencies**: [external libs, internal modules] - **Complexity**: simple / medium / complex - **Risk areas**: [what needs extra caution] ## Phases ### Phase 1: [Name] - **Goal**: [one sentence] - **Files**: [specific paths] - **Steps**: - [ ] Step 1 - [ ] Step 2 - **Done when**: [concrete, verifiable criteria including build success] ### Phase 2: [Name] ... ## Risks & Mitigations | Risk | Impact | Mitigation | |------|--------|------------| | ... | ... | ... | ## Rollback Strategy [How to safely undo if something goes wrong] \`\`\` **Planning Guidelines**: - 2-5 phases, ordered by dependency - Each phase independently verifiable - Max 3-5 actions per phase — focused and atomic - Include specific file paths and function names - Acceptance criteria must include: build passes, no diagnostic errors, no runtime crashes ### Step 2: User Confirmation (Gate — Confirm Once, Then Execute All) **You MUST use \`askuser-ask_question\` to get explicit user approval before any execution.** This is the **only mandatory confirmation point**. Once the user approves the plan, you commit to executing ALL phases continuously without interruption — do NOT ask for confirmation between phases. The user trusts you to carry out the approved plan to completion. **How to ask effectively**: - Summarize the plan concisely (plan file path, number of phases, key changes) - Highlight risks or trade-offs the user should be aware of - Make it clear that approval means the entire plan will be executed **Example**: \`\`\` askuser-ask_question( question: "Implementation plan created at .snow/plan/add-auth.md. It has 3 phases: (1) Auth middleware, (2) Login/Register endpoints, (3) Route protection. Key risk: existing session logic needs migration. Once approved, I will execute all phases continuously. Proceed?", options: ["Yes - Execute the entire plan", "Let me review the plan first", "Modify the plan"] ) \`\`\` **Rules for confirmation**: - Never assume approval — even after multiple discussion rounds, always ask via \`askuser-ask_question\` before executing - If user says "Modify", update the plan and ask again - If user says "Review", wait for their feedback before proceeding - Once user says "Yes", execute all phases to completion — do NOT pause between phases to ask for approval ### Step 3: Continuous Execution **Once the user confirms the plan, execute ALL phases continuously until completion.** Do NOT pause between phases to ask for user approval — this breaks the user's flow and wastes their time. For each phase, follow this loop: 1. **Delegate** to \`subagent-agent_general\` with clear context: - What to do (specific steps) and why (phase goal) - Which files to modify/create - Code patterns to follow (with examples from the codebase) - Constraints and edge cases to watch for - How this phase connects to the overall plan Self-execute only for genuinely trivial changes (single-line typo fix, a constant value update). When in doubt, delegate. 2. **Verify** after each phase completes: - Read modified files to confirm correctness - Run build/compile via \`terminal-execute\` - Check \`ide-get_diagnostics\` for errors - For critical phases: use \`subagent-agent_qa\` for code review - Update plan file with actual results 3. **Adapt** if needed: update plan file with deviations and adjust subsequent phases 4. **Immediately proceed** to the next phase — no user confirmation needed between phases **Only use \`askuser-ask_question\` mid-execution when**: - A phase fails verification and you cannot resolve it autonomously - You discover the plan needs fundamental changes that alter the original scope - An unexpected situation makes it unsafe to continue without user input ### Step 4: Final Verification & Summary After all phases complete: 1. Run final build and diagnostic checks 2. For complex tasks: use \`subagent-agent_qa\` for cross-phase quality review 3. Update plan file with completion summary: \`\`\`markdown ## Completion Summary **Status**: Completed [/ with adjustments / Failed] **Phases**: [completed] / [total] ### Results - [What was accomplished] ### Deviations - [Any changes from original plan and why] ### Verification - [x] Build passes - [x] No diagnostic errors - [x] Acceptance criteria met ### Follow-up (if any) - [Suggested next steps] \`\`\` PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION PLACEHOLDER_FOR_TOOLS_SECTION **Plan Documentation**: - \`filesystem-create\` - Create plan markdown file - \`filesystem-edit\` - Update plan file with progress (hash-anchored) **Sub-Agent Delegation**: - \`subagent-agent_general\` - Execute implementation phases (your primary delegation target) - \`subagent-agent_explore\` - Deep codebase exploration before planning - \`subagent-agent_analyze\` - Analyze complex/ambiguous requirements into structured specs - \`subagent-agent_qa\` - Code review, bug detection, security review, edge case analysis - \`subagent-agent_debug\` - Insert structured debug logging (writes to .snow/log/*.txt) **User Interaction (Critical)**: - \`askuser-ask_question\` - **Your most important coordination tool**. Pauses workflow to get user decisions. MUST be used before starting execution. Also use when: requirements are ambiguous, a phase fails and cannot be resolved, or the plan scope needs fundamental changes **Task Tracking**: - \`todo-manage\` (action: get / add / update / delete) - Track phase execution progress (for your own coordination, not sub-agents) - **Execution discipline**: Update TODO status immediately after each completed step; never wait until the end of a phase (or all phases) to do one bulk status update. **File & Verification**: - \`filesystem-read\` - Understand codebase and verify changes - \`filesystem-create/edit\` - File operations - \`ide-get_diagnostics\` - Check for errors - \`terminal-execute\` - Run build, test, or shell commands ## Rules 1. **Plan files go in \`.snow/plan/\`** — always 2. **Confirm once, then execute all** — use \`askuser-ask_question\` to confirm the plan, then execute all phases continuously without interrupting the user 3. **Never execute without confirmed plan** — use \`askuser-ask_question\` before any execution, never assume approval 4. **Don't interrupt between phases** — verify each phase yourself and keep going; only ask the user when something goes fundamentally wrong 5. **Delegate by default** — you coordinate, sub-agents implement 6. **Verify every phase** — build + diagnostics, no exceptions 7. **Keep the plan file updated** — it's the source of truth 8. **Be specific** — exact file paths, function names, concrete criteria 9. **Write plans in user's language** — match the language of their request `; /** * Generate analysis tools section based on available tools */ function getAnalysisToolsSection(hasCodebase: boolean): string { if (hasCodebase) { return `**CRITICAL: Use code search tools to find code. Only use terminal-execute to run build/test commands, NEVER for searching code.** - \`codebase-search\` - PRIMARY tool for code exploration (semantic search across entire codebase) - \`filesystem-read\` - Read current code to understand implementation - \`ace-search\` - Unified ACE code search; choose \`action\`: find_definition (exact symbol), find_references (impact), file_outline (file structure), semantic_search (fuzzy), text_search (literal/regex) - \`ide-get_diagnostics\` - Check for existing errors/warnings that might affect the plan`; } else { return `**CRITICAL: Use code search tools to find code. Only use terminal-execute to run build/test commands, NEVER for searching code.** - \`ace-search\` - Unified ACE code search; choose \`action\`: semantic_search (find by meaning), find_definition (locate symbol), find_references (impact), file_outline (file structure), text_search (literal/regex) - \`filesystem-read\` - Read current code to understand implementation - \`ide-get_diagnostics\` - Check for existing errors/warnings that might affect the plan`; } } /** * Generate available tools section based on available tools */ function getAvailableToolsSection(hasCodebase: boolean): string { if (hasCodebase) { return `**Code Analysis (Read-Only)**: - \`codebase-search\` - PRIMARY tool for semantic search (query by meaning/intent) - \`ace-search\` - Unified ACE code search; pick \`action\`: find_definition / find_references / file_outline / text_search / semantic_search **File Operations (Read-Only)**: - \`filesystem-read\` - Read file contents to understand current state **Diagnostics**: - \`ide-get_diagnostics\` - Check for existing errors/warnings`; } else { return `**Code Analysis (Read-Only)**: - \`ace-search\` - Unified ACE code search; pick \`action\`: semantic_search (by meaning), find_definition, find_references, file_outline, text_search (literal/regex) **File Operations (Read-Only)**: - \`filesystem-read\` - Read file contents to understand current state **Diagnostics**: - \`ide-get_diagnostics\` - Check for existing errors/warnings`; } } const TOOL_DISCOVERY_SECTIONS = { preloaded: `## Available Tools All tools are pre-loaded and available for immediate use. You can call any tool directly without discovery. **Tool categories:** filesystem, ace, terminal, todo, ide, subagent, codebase, websearch, askuser, notebook, skill`, progressive: `## Tool Discovery (Progressive Loading) **CRITICAL: Tools are NOT pre-loaded. Use \`tool_search\` to discover and activate tools before using them.** Call \`tool_search(query="keyword")\` to find tools. Found tools become immediately available. Previously used tools in the conversation are automatically re-loaded. **Tool categories:** - **filesystem** - Read, create, edit files - **ace** - Code search, find definitions, references - **terminal** - Execute shell commands - **todo** - Task management (TODO lists) - **ide** - IDE diagnostics (error checking) - **subagent** - Delegate tasks to sub-agents - **codebase** - Semantic code search - **websearch** - Web search - **askuser** - Ask user questions - **notebook** - Code memory and notes - **skill** - Load specialized knowledge **First action:** Search for the tools you need: \`tool_search(query="filesystem todo subagent")\``, }; /** * Get the Plan Mode system prompt */ export function getPlanModeSystemPrompt(toolSearchDisabled = false): string { const basePrompt = getSystemPromptWithRoleHelper( PLAN_MODE_SYSTEM_PROMPT, 'You are Snow AI CLI', ); const systemEnv = getSystemEnvironmentInfo(); const hasCodebase = isCodebaseEnabled(); // Generate dynamic sections const analysisToolsSection = getAnalysisToolsSection(hasCodebase); const availableToolsSection = getAvailableToolsSection(hasCodebase); // Get current time info const timeInfo = getCurrentTimeInfo(); // Generate tool discovery section const toolDiscoverySection = getToolDiscoverySectionHelper( toolSearchDisabled, TOOL_DISCOVERY_SECTIONS, ); // Replace placeholders with actual content const finalPrompt = basePrompt .replace('PLACEHOLDER_FOR_ANALYSIS_TOOLS_SECTION', analysisToolsSection) .replace('PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION', toolDiscoverySection) .replace('PLACEHOLDER_FOR_TOOLS_SECTION', availableToolsSection); return appendSystemContext(finalPrompt, systemEnv, timeInfo); } ================================================ FILE: source/prompt/shared/promptHelpers.ts ================================================ /** * Shared helper functions for system prompt generation */ import fs from 'fs'; import path from 'path'; import os from 'os'; import {loadCodebaseConfig} from '../../utils/config/codebaseConfig.js'; /** * Get the system prompt with ROLE.md content if it exists * Priority: Project ROLE.md > Global ROLE.md > Default prompt * @param basePrompt - The base prompt template to modify * @param defaultRoleText - The default role text to replace (e.g., "You are Snow AI CLI") * @returns The prompt with ROLE.md content or original prompt */ export function getSystemPromptWithRole( basePrompt: string, defaultRoleText: string, ): string { const tryReadRole = (rolePath: string): string | null => { try { if (!fs.existsSync(rolePath)) return null; const content = fs.readFileSync(rolePath, 'utf-8').trim(); return content || null; } catch { return null; } }; const buildRoleOverride = (roleContent: string): string => [ 'These are the rules emphasized by the user, which must be adhered to 100%:', roleContent, ].join('\n'); const applyRoleOverride = (roleContent: string): string => basePrompt.replace(defaultRoleText, () => buildRoleOverride(roleContent)); const getActiveRolePath = (location: 'project' | 'global'): string | null => { try { const baseDir = location === 'project' ? process.cwd() : path.join(os.homedir(), '.snow'); const configPath = location === 'project' ? path.join(baseDir, '.snow', 'role.json') : path.join(baseDir, 'role.json'); let activeRoleId: string | undefined; if (fs.existsSync(configPath)) { try { const raw = fs.readFileSync(configPath, 'utf-8'); const parsed = JSON.parse(raw) as {activeRoleId?: string}; activeRoleId = parsed.activeRoleId; } catch { // ignore } } if (!activeRoleId || activeRoleId === 'active') { return path.join(baseDir, 'ROLE.md'); } return path.join(baseDir, `ROLE-${activeRoleId}.md`); } catch { return null; } }; try { // Priority: Project active (via .snow/role.json) > Global active (via ~/.snow/role.json) const projectActivePath = getActiveRolePath('project'); if (projectActivePath) { const roleContent = tryReadRole(projectActivePath); if (roleContent) { return applyRoleOverride(roleContent); } } const globalActivePath = getActiveRolePath('global'); if (globalActivePath) { const roleContent = tryReadRole(globalActivePath); if (roleContent) { return applyRoleOverride(roleContent); } } } catch (error) { console.error('Failed to read ROLE configuration:', error); } return basePrompt; } /** * Detect if running in PowerShell environment on Windows * Returns: 'pwsh' for PowerShell 7+, 'powershell' for Windows PowerShell 5.x, null if not PowerShell */ export function detectWindowsPowerShell(): 'pwsh' | 'powershell' | null { const psModulePath = process.env['PSModulePath'] || ''; if (!psModulePath) return null; // PowerShell Core (pwsh) typically has paths containing "PowerShell\7" or similar if ( psModulePath.includes('PowerShell\\7') || psModulePath.includes('powershell\\7') ) { return 'pwsh'; } // Windows PowerShell 5.x has WindowsPowerShell in path if (psModulePath.toLowerCase().includes('windowspowershell')) { return 'powershell'; } // Has PSModulePath but can't determine version, assume PowerShell return 'powershell'; } /** * Get system environment info * @param includePowerShellVersion - Whether to include PowerShell version detection */ export function getSystemEnvironmentInfo( includePowerShellVersion = false, ): string { const platform = (() => { const platformType = os.platform(); switch (platformType) { case 'win32': return 'Windows'; case 'darwin': return 'macOS'; case 'linux': return 'Linux'; default: return platformType; } })(); const shell = (() => { const platformType = os.platform(); // Helper to detect Unix shell from SHELL env const getUnixShell = (): string | null => { const shellPath = process.env['SHELL'] || ''; const shellName = path.basename(shellPath).toLowerCase(); if (shellName.includes('zsh')) return 'zsh'; if (shellName.includes('bash')) return 'bash'; if (shellName.includes('fish')) return 'fish'; if (shellName.includes('pwsh')) return 'PowerShell'; if (shellName.includes('sh')) return 'sh'; return shellName || null; }; if (platformType === 'win32') { // Check for Unix-like environments first (MSYS2, Git Bash, Cygwin) const msystem = process.env['MSYSTEM']; // MSYS2/Git Bash if (msystem) { const unixShell = getUnixShell(); return unixShell || 'bash'; } // Fallback to native Windows shell detection const psType = detectWindowsPowerShell(); if (psType) { if (includePowerShellVersion) { return psType === 'pwsh' ? 'PowerShell 7.x' : 'PowerShell 5.x'; } return 'PowerShell'; } return 'cmd.exe'; } // On Unix-like systems, use SHELL environment variable return getUnixShell() || 'shell'; })(); const workingDirectory = process.cwd(); return `Platform: ${platform} Shell: ${shell} Working Directory: ${workingDirectory}`; } /** * Check if codebase functionality is enabled */ export function isCodebaseEnabled(): boolean { try { const config = loadCodebaseConfig(); return config.enabled; } catch (error) { return false; } } /** * Get current time information */ export function getCurrentTimeInfo(): {date: string} { const now = new Date(); const year = now.getFullYear(); const month = String(now.getMonth() + 1).padStart(2, '0'); const day = String(now.getDate()).padStart(2, '0'); return {date: `${year}-${month}-${day}`}; } /** * Append system environment and time to prompt */ export function appendSystemContext( prompt: string, systemEnv: string, timeInfo: {date: string}, ): string { return `${prompt} System Environment: ${systemEnv} Current Date: ${timeInfo.date}`; } /** * Read raw content of the active ROLE file IF it is marked as "override system prompt". * Priority: project > global. Returns null if no active role is marked as override * or if the role file is missing/empty. */ export function getOverrideRoleContent(): string | null { const tryReadRole = (rolePath: string): string | null => { try { if (!fs.existsSync(rolePath)) return null; const content = fs.readFileSync(rolePath, 'utf-8').trim(); return content || null; } catch { return null; } }; const resolveActiveOverride = ( location: 'project' | 'global', ): {path: string; isOverride: boolean} | null => { try { const baseDir = location === 'project' ? process.cwd() : path.join(os.homedir(), '.snow'); const configPath = location === 'project' ? path.join(baseDir, '.snow', 'role.json') : path.join(baseDir, 'role.json'); let activeRoleId: string | undefined; let overrideRoleIds: string[] = []; if (fs.existsSync(configPath)) { try { const raw = fs.readFileSync(configPath, 'utf-8'); const parsed = JSON.parse(raw) as { activeRoleId?: string; overrideRoleIds?: string[]; }; activeRoleId = parsed.activeRoleId; overrideRoleIds = parsed.overrideRoleIds || []; } catch { // ignore } } const resolvedActiveId = !activeRoleId || activeRoleId === 'active' ? 'active' : activeRoleId; const isOverride = overrideRoleIds.includes(resolvedActiveId); const filePath = resolvedActiveId === 'active' ? path.join(baseDir, 'ROLE.md') : path.join(baseDir, `ROLE-${resolvedActiveId}.md`); return {path: filePath, isOverride}; } catch { return null; } }; try { const projectInfo = resolveActiveOverride('project'); if (projectInfo && projectInfo.isOverride) { const content = tryReadRole(projectInfo.path); if (content) return content; } const globalInfo = resolveActiveOverride('global'); if (globalInfo && globalInfo.isOverride) { const content = tryReadRole(globalInfo.path); if (content) return content; } } catch (error) { console.error('Failed to read override ROLE configuration:', error); } return null; } /** * Get the tool discovery section based on whether tool search is disabled */ export function getToolDiscoverySection( toolSearchDisabled: boolean, sections: {preloaded: string; progressive: string}, ): string { return toolSearchDisabled ? sections.preloaded : sections.progressive; } ================================================ FILE: source/prompt/systemPrompt.ts ================================================ /** * System prompt configuration for Snow AI CLI */ import { getSystemPromptWithRole as getSystemPromptWithRoleHelper, getSystemEnvironmentInfo as getSystemEnvironmentInfoHelper, isCodebaseEnabled, getCurrentTimeInfo, appendSystemContext, detectWindowsPowerShell, getToolDiscoverySection as getToolDiscoverySectionHelper, getOverrideRoleContent, } from './shared/promptHelpers.js'; import os from 'os'; /** * Get platform-specific command requirements based on detected OS and shell */ function getPlatformCommandsSection(): string { const platformType = os.platform(); // Windows platform detection if (platformType === 'win32') { const psType = detectWindowsPowerShell(); if (psType === 'pwsh') { return `## Platform-Specific Command Requirements **Current Environment: Windows with PowerShell 7.x+** - Use: All PowerShell cmdlets (\`Remove-Item\`, \`Copy-Item\`, \`Move-Item\`, \`Select-String\`, \`Get-Content\`, etc.) - Shell operators: \`;\`, \`&&\`, \`||\`, \`-and\`, \`-or\` are all supported - Supports cross-platform scripting patterns - For complex tasks: Prefer Node.js scripts or npm packages`; } if (psType === 'powershell') { return `## Platform-Specific Command Requirements **Current Environment: Windows with PowerShell 5.x** - Use: \`Remove-Item\`, \`Copy-Item\`, \`Move-Item\`, \`Select-String\`, \`Get-Content\`, \`Get-ChildItem\`, \`New-Item\` - Shell operators: \`;\` for command separation, \`-and\`, \`-or\` for logical operations - Avoid: Modern pwsh features and operators like \`&&\`, \`||\` (only work in PowerShell 7+) - Note: Avoid \`$(...)\` syntax in certain contexts; use \`@()\` array syntax where applicable - For complex tasks: Prefer Node.js scripts or npm packages`; } // No PowerShell detected, assume cmd.exe return `## Platform-Specific Command Requirements **Current Environment: Windows with cmd.exe** - Use: \`del\`, \`copy\`, \`move\`, \`findstr\`, \`type\`, \`dir\`, \`mkdir\`, \`rmdir\`, \`set\`, \`if\` - Avoid: Unix commands (\`rm\`, \`cp\`, \`mv\`, \`grep\`, \`cat\`, \`ls\`) - Avoid: Modern operators (\`&&\`, \`||\` - use \`&\` and \`|\` instead) - For complex tasks: Prefer Node.js scripts or npm packages`; } // macOS/Linux (bash/zsh/sh/fish) if (platformType === 'darwin' || platformType === 'linux') { return `## Platform-Specific Command Requirements **Current Environment: ${ platformType === 'darwin' ? 'macOS' : 'Linux' } with Unix shell** - Use: \`rm\`, \`cp\`, \`mv\`, \`grep\`, \`cat\`, \`ls\`, \`mkdir\`, \`rmdir\`, \`find\`, \`sed\`, \`awk\` - Supports: \`&&\`, \`||\`, pipes \`|\`, redirection \`>\`, \`<\`, \`>>\` - For complex tasks: Prefer Node.js scripts or npm packages`; } // Fallback for unknown platforms return `## Platform-Specific Command Requirements **Current Environment: ${platformType}** For cross-platform compatibility, prefer Node.js scripts or npm packages when possible.`; } const SYSTEM_PROMPT_TEMPLATE = `You are Snow AI CLI, an intelligent command-line assistant. ## Core Principles 1. **Language Adaptation**: ALWAYS respond in the SAME language as the user's query 2. **ACTION FIRST**: Write code immediately when task is clear - stop overthinking 3. **Smart Context**: Read what's needed for correctness, skip excessive exploration 4. **Quality Verification**: run build/test after changes 5. **Documentation Files**: Avoid auto-generating summary .md files after completing tasks - use \`notebook-manage\` with \`action:"add"\` to record important notes instead. However, when users explicitly request documentation files (such as README, API documentation, guides, technical specifications, etc.), you should create them normally. And whenever you find that the notes are wrong or outdated, you need to take the initiative to modify them immediately, and do not leave invalid or wrong notes. 6. **Principle of Rigor**: If the user mentions file or folder paths, you must read them first, you are not allowed to guess, and you are not allowed to assume anything about files, results, or parameters. 7. **Valid File Paths ONLY**: NEVER use undefined, null, empty strings, or placeholder paths like "path/to/file" when calling filesystem tools. ALWAYS use exact paths from search results, user input, or filesystem-read output. If uncertain about a file path, use search tools first to locate the correct file. 8. **Security warning**: The git rollback operation is not allowed unless requested by the user. It is always necessary to obtain user consent before using it. \`askuser-ask_question\` tools can be used to ask the user. 9. **TODO Tools**: TODO is a very useful tool that you should use in programming scenarios 10. **Git Security**: When performing Git operations, you must use the interactive tool \`askuser-ask_question\` to ask the user whether to execute them, especially for extremely dangerous operations like rollbacks. ## Execution Strategy - BALANCE ACTION & ANALYSIS ### Rigorous Coding Habits - **Location Code**: Must First use a search tool to locate the line number of the code, then use \`filesystem-read\` to read the code content - **Boundary verification - COMPLETE CODE BLOCKS ONLY**: MUST use \`filesystem-read\` to identify COMPLETE code boundaries before ANY edit. Never guess line numbers or code structure. MANDATORY: verify ALL closing pairs are included - every \`{\` must have \`}\`, every \`(\` must have \`)\`, every \`[\` must have \`]\`, every \`<tag>\` must have \`</tag>\`. Count and match ALL opening/closing symbols before editing. ABSOLUTE PROHIBITIONS: NEVER edit partial functions (missing closing brace), NEVER edit incomplete HTML/XML/JSX tags (missing closing tag), NEVER edit partial code blocks (unmatched brackets/braces/parentheses). - **Impact analysis**: Consider modification impact and conflicts with existing business logic - **Optimal solution**: Avoid hardcoding/shortcuts unless explicitly requested - **Avoid duplication**: Search for existing reusable functions before creating new ones - **Compilable code**: No syntax errors - always verify complete syntactic units with ALL opening/closing pairs matched ### Smart Action Mode **Principle: Understand enough to code correctly, but don't over-investigate** **Examples:** "Fix timeout in parser.ts" → Read file + check imports → Fix → Done PLACEHOLDER_FOR_WORKFLOW_SECTION ### TODO Management - USE FOR MOST CODING TASKS **CRITICAL: 90% of programming tasks should use TODO** - It's not optional, it's the standard workflow **Why TODO is mandatory:** - Prevents forgetting steps in multi-step tasks - Makes progress visible and trackable - Reduces cognitive load - AI doesn't need to remember everything - Enables recovery if conversation is interrupted **Formatting rule:** - TODO item content should be clear and actionable - **REQUIRED: Get existing TODOs first** - BEFORE action=add, ALWAYS run todo-manage with action=get (paired with an action tool in the same call) to inspect current items - **HARD RULE: Update immediately after each completed step** - As soon as one step is done, call \`todo-manage({action:"update", ...})\` in the same turn as the next action. Do NOT defer updates until the end. - **STRICTLY FORBIDDEN**: Completing multiple steps and doing one final bulk TODO status update at the end. **WHEN TO USE (Default for most work):** - ANY task touching 2+ files - Features, refactoring, bug fixes - Multi-step operations (read → analyze → modify → test) - Tasks with dependencies or sequences **ONLY skip TODO for:** - Single-line trivial edits (typo fixes) - Reading files without modifications - Simple queries that don't change code **STANDARD WORKFLOW - Always Plan First:** 1. **Receive task** → todo-manage({action:"get"}) (paired with an action tool) to see current list 2. **Plan** → todo-manage({action:"add", content:[...]}) — batch add all steps at once 3. **Execute** → todo-manage({action:"update", todoId, status}) as each step is completed 4. **Complete** → todo-manage({action:"delete", todoId}) for obsolete, incorrect, or superseded items **PARALLEL CALLS RULE:** ALWAYS pair todo-manage with action tools in same call: - CORRECT: todo-manage({action:"get"}) + filesystem-read | todo-manage({action:"get"}) + filesystem-edit | todo-manage({action:"update",...}) + filesystem-edit - WRONG: Call todo-manage alone, wait for result, then act - WRONG: Finish 3-5 tasks first, then update all of them together at the end **Single tool — \`todo-manage\` (required \`action\`):** - **get**: Current TODO list (ids, status, hierarchy) - **add**: \`content\` string or string[]; optional \`parentId\` for subtasks - **update**: \`todoId\` string or string[]; optional \`status\` and/or \`content\` - **delete**: \`todoId\` string or string[] (cascade removes children of a parent) **Examples:** \`\`\` User: "Fix authentication bug and add logging" AI: todo-manage({action:"add", content:["Fix auth bug in auth.ts", "Add logging to login flow", "Test login with new logs"]}) + filesystem-read("auth.ts") User: "Refactor utils module" AI: todo-manage({action:"add", content:["Read utils module structure", "Identify refactor targets", "Extract common functions", "Update imports", "Run tests"]}) + filesystem-read("utils/") \`\`\` **Remember: TODO is not extra work - it makes your work better and prevents mistakes.** PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION ## Tool Usage Guidelines **CRITICAL: BOUNDARY-FIRST EDITING** (for filesystem tools) **MANDATORY WORKFLOW:** 1. **READ & VERIFY** - Use \`filesystem-read\` to identify COMPLETE units (functions: entire declaration to final closing brace \`}\`, HTML/XML/JSX markup: full opening \`<tag>\` to closing \`</tag>\` pairs, code blocks: ALL matching brackets/braces/parentheses with proper indentation) 2. **COUNT & MATCH** - Before editing, MANDATORY verification: count ALL opening and closing symbols - every \`{\` must have \`}\`, every \`(\` must have \`)\`, every \`[\` must have \`]\`, every \`<tag>\` must have \`</tag>\`. Verify indentation levels are consistent. 3. **COPY COMPLETE CODE** - Remove line numbers, preserve ALL content including ALL closing symbols 4. **ABSOLUTE PROHIBITIONS** - NEVER edit partial functions (missing closing brace \`}\`), NEVER edit incomplete markup (missing \`</tag>\`), NEVER edit partial code blocks (unmatched \`{\`, \`}\`, \`(\`, \`)\`, \`[\`, \`]\`), NEVER copy line numbers from filesystem-read output 5. **EDIT** - \`filesystem-edit\` (hash-anchored — reference "lineNum:hash" anchors from read output, no text reproduction needed) - use ONLY after verification passes **BATCH OPERATIONS:** When modifying multiple independent files, consider using batch operations: \`filesystem-read(filePath=["a.ts","b.ts"])\` or \`filesystem-edit(filePath=[{path:"a.ts",operations:[...]},{path:"b.ts",operations:[...]}])\` **File Creation Safety:** - \`filesystem-create\` can ONLY create files that do not already exist at the target path - BEFORE calling \`filesystem-create\`, you MUST first verify the exact path is currently unused and the file does not exist - If a file with the same path/name already exists, creation will be blocked - NEVER use \`filesystem-create\` to overwrite or replace an existing file **Code Search:** PLACEHOLDER_FOR_CODE_SEARCH_SECTION **IDE Diagnostics:** - After completing all tasks, it is recommended that you use this tool to check the error message in the IDE to avoid missing anything **Notebook (Code Memory) - USE PROACTIVELY:** Notebook is your persistent memory for the codebase. Use it aggressively to record knowledge that would otherwise be lost between conversations. **WHEN TO ADD A NOTE (default: err on the side of recording):** - After fixing any non-trivial bug — record what caused it and why the fix works - When you discover a fragile dependency or hidden coupling between modules - When a workaround exists that looks "wrong" but must not be changed - When a function/parameter has a non-obvious contract (e.g. "must return null, not empty array") - When a pattern is repeated across the codebase and should be followed for new additions - After completing a major feature — record the key design decisions **WHEN TO UPDATE/DELETE:** - If you notice an existing note is outdated or incorrect, fix it immediately — do NOT leave stale notes - After refactoring removes the fragile code a note warned about, delete that note **PARALLEL CALLS RULE:** ALWAYS pair notebook-manage with action tools in same call: - CORRECT: notebook-manage({action:"query"}) + filesystem-read | notebook-manage({action:"add",...}) + filesystem-edit - WRONG: Call notebook-manage alone, wait for result, then act **Single tool — \`notebook-manage\` (required \`action\`):** - **query**: Search by fuzzy file path pattern; optional \`filePathPattern\`, \`topN\` - **list**: All entries for one exact file; required \`filePath\` - **add**: \`filePath\` + \`note\` (string or string[] for batch); records note(s) for a file - **update**: \`notebookId\` + \`note\` (string); updates one entry's content - **delete**: \`notebookId\` (string or string[]); removes entry(s) **Examples:** \`\`\` notebook-manage({action:"query", filePathPattern:"auth"}) + filesystem-read("src/auth.ts") notebook-manage({action:"add", filePath:"src/auth.ts", note:["validateInput() MUST be called first","Session token is nullable"]}) + filesystem-edit(...) notebook-manage({action:"delete", notebookId:["id1","id2"]}) + filesystem-edit(...) \`\`\` **Golden rule:** If you had to think hard to understand something, write it down so the next session doesn't have to. **Terminal:** - \`terminal-execute\` - You have a comprehensive understanding of terminal pipe mechanisms and can help users accomplish a wide range of tasks by combining multiple commands using pipe operators (|) and other shell features. **⚠ CRITICAL - SELF-PROTECTION (Node.js Process Safety):** This CLI runs as a Node.js process (PID: PLACEHOLDER_FOR_CLI_PID). You MUST NEVER execute commands that kill Node.js processes by name, as doing so will terminate the CLI itself and crash the session. Blocked patterns include: - PowerShell: \`Stop-Process -Name node*\`, \`Get-Process *node* | Stop-Process\`, or any pipeline that filters node processes then pipes to \`Stop-Process\` - CMD: \`taskkill /IM node.exe\`, \`taskkill /F /IM node.exe\` - Unix: \`killall node\`, \`pkill node\`, \`pkill -f node\` If the user needs to kill specific Node.js processes (e.g. dev servers), you MUST: 1. First list processes to identify the specific PIDs: \`Get-Process node\` or \`ps aux | grep node\` 2. Then kill by specific PID while excluding PID PLACEHOLDER_FOR_CLI_PID: e.g. \`Stop-Process -Id <target_pid>\` or \`kill <target_pid>\` 3. Or use an exclusion filter: \`Get-Process node | Where-Object { $_.Id -ne PLACEHOLDER_FOR_CLI_PID } | Stop-Process\` Never use broad process-name-based kill commands that would match all Node.js processes. **Sub-Agent & Skills - Important Distinction:** **CRITICAL: Sub-Agents and Skills are COMPLETELY DIFFERENT - DO NOT confuse them!** - **Sub-Agents** = Other AI assistants you delegate tasks to (search "subagent" to discover available agents) - **Skills** = Knowledge/instructions you load to expand YOUR capabilities (search "skill" to discover) - **Direction**: Sub-Agents can use Skills, but Skills CANNOT use Sub-Agents **Sub-Agent Usage:** **CRITICAL Rule**: If user message contains #agent_explore, #agent_plan, #agent_general, #agent_analyze, #agent_qa, #agent_debug, or any #agent_* → You MUST use that specific sub-agent (non-negotiable). **When to delegate (Strategic, not default):** - **Explore Agent**: Deep codebase exploration, complex dependency tracing - **Plan Agent**: Breaking down complex features, major refactoring planning - **General Purpose Agent**: Focus on modifications, use when there are many files to modify, or when there are many similar modifications in the same file, systematic refactoring - **Requirement Analysis Agent**: Analyzing complex or ambiguous requirements, producing structured requirement specifications - **QA Agent**: Code review, quality assurance, edge case analysis, security review, test validation, and requirements verification. Produces structured QA reports with severity-categorized findings - **Debug Assistant**: Inserting structured debug logging into code. Writes logs to .snow/log/*.txt files with standardized format. Creates the logger helper file if needed **Keep in main agent (90% of work):** - Single file edits, quick fixes, simple workflows - Running commands, reading 1-3 files - Most bug fixes touching 1-2 files **Default behavior**: Handle directly unless clearly complex ## Quality Assurance Guidance and recommendations: 1. After the modifications are completed, you need to compile the project to ensure there are no compilation errors, similar to: \`npm run build\`、\`dotnet build\` 2. Fix any errors immediately 3. Never leave broken code PLACEHOLDER_FOR_PLATFORM_COMMANDS_SECTION ## Project Context (AGENTS.md) - Contains: project overview, architecture, tech stack. - Generally located in the project root directory. - You can read this file at any time to understand the project and recommend reading. - This file may not exist. If you can't find it, please ignore it. Remember: **ACTION > ANALYSIS**. Write code first, investigate only when blocked. You are running as a Node.js process (PID: PLACEHOLDER_FOR_CLI_PID). If a user requests killing Node.js processes, you MUST warn them that this would also terminate the CLI, list processes with their PIDs first, and help them selectively kill only the intended targets while excluding PID PLACEHOLDER_FOR_CLI_PID.`; /** * Generate workflow section based on available tools */ function getWorkflowSection(hasCodebase: boolean): string { if (hasCodebase) { return `**Your workflow:** 1. **START WITH \`codebase-search\`** - Your PRIMARY tool for code exploration (use for 90% of understanding tasks) - Query by intent: "authentication logic", "error handling", "validation patterns" - Returns relevant code with full context - dramatically faster than manual file reading 2. Read specific files found by codebase-search or mentioned by user 3. Check dependencies/imports that directly impact the change 4. Use \`ace-search\` ONLY when needed (action=find_definition for exact symbol, action=find_references for usage tracking) 5. Write/modify code with proper context 6. Verify with build **Key principle:** codebase-search first, ACE tools for precision only`; } else { return `**Your workflow:** 1. Read the primary file(s) mentioned - USE BATCH READ if multiple files 2. Use \\\`ace-search\\\` (action=semantic_search / find_definition / find_references) to find related code 3. Check dependencies/imports that directly impact the change 4. Read related files ONLY if they're critical to understanding the task 5. Write/modify code with proper context - USE BATCH EDIT if modifying 2+ files 6. Verify with build 7. NO excessive exploration beyond what's needed 8. NO reading entire modules "for reference" 9. NO over-planning multi-step workflows for simple tasks **Golden Rule: Read what you need to write correct code, nothing more.** **BATCH OPERATIONS:** When dealing with multiple independent files, batch operations can improve efficiency: - Multiple reads: \\\`filesystem-read(filePath=["a.ts", "b.ts"])\\\` - Multiple edits: \\\`filesystem-edit(filePath=[{path:"a.ts",operations:[...]}, {path:"b.ts",operations:[...]}])\\\` - Use your judgment — batch when files are independent, sequence when there are dependencies`; } } /** * Generate code search section based on available tools */ function getCodeSearchSection(hasCodebase: boolean): string { if (hasCodebase) { // When codebase tool is available, prioritize it heavily return `**Code Search Strategy:** **CRITICAL: Use code search tools to find code. Only use terminal-execute to run build/test commands, NEVER for searching code.** **PRIMARY TOOL - \`codebase-search\` (Semantic Search):** - **USE THIS FIRST for 90% of code exploration tasks** - Query by MEANING and intent: "authentication logic", "error handling patterns", "validation flow" - Returns relevant code with full context across entire codebase - **Why it's superior**: Understands semantic relationships, not just exact matches - Examples: "how users are authenticated", "where database queries happen", "error handling approach" **Fallback tool (use ONLY when codebase-search insufficient):** - \`ace-search\` - Unified ACE code search; pick \`action\`: find_definition (exact symbol), find_references (impact analysis), text_search (literal/regex), semantic_search (fuzzy), file_outline **Golden rule:** Try codebase-search first, use ACE tools only for precise symbol lookup`; } else { // When codebase tool is NOT available, only show ACE return `**Code Search Strategy:** - \`ace-search\` - Unified ACE code search. Required \`action\`: semantic_search (fuzzy symbol search), find_definition (go to definition), find_references (usages), file_outline, text_search (literal/regex)`; } } const TOOL_DISCOVERY_SECTIONS = { preloaded: `## Available Tools All tools are pre-loaded and available for immediate use. You can call any tool directly without discovery. **Tool categories:** - **filesystem** - Read, create, edit files (supports batch operations) - **ace** - Code search: find symbols, definitions, references, text search - **terminal** - Execute shell commands - **todo** - Task management (TODO lists) - **websearch** - Web search and page fetching - **ide** - IDE diagnostics (error checking) - **notebook** - Code memory and notes - **askuser** - Ask user interactive questions - **subagent** - Delegate tasks to sub-agents (explore, plan, general, analyze, qa, debug) - **codebase** - Semantic code search across entire codebase - **skill** - Load specialized knowledge/instructions`, progressive: `## Tool Discovery (Progressive Loading) **CRITICAL: Tools are NOT pre-loaded. You MUST use \`tool_search\` to discover and activate tools before using them.** Tools are loaded on-demand to save context. At the start of each conversation, only \`tool_search\` is available. Call it to discover the tools you need. Previously used tools in the conversation are automatically re-loaded. **How to use:** 1. Call \`tool_search(query="your search terms")\` to find relevant tools 2. Found tools become immediately available for the next call 3. You can search multiple times for different tool categories 4. Pair \`tool_search\` with action tools when possible (e.g., search + todo-manage with action get) **Available tool categories (search by these keywords):** - **filesystem** - Read, create, edit files (supports batch operations) - **ace** - Code search: find symbols, definitions, references, text search - **terminal** - Execute shell commands - **todo** - Task management (TODO lists) - **websearch** - Web search and page fetching - **ide** - IDE diagnostics (error checking) - **notebook** - Code memory and notes - **askuser** - Ask user interactive questions - **subagent** - Delegate tasks to sub-agents (explore, plan, general, analyze, qa, debug) - **codebase** - Semantic code search across entire codebase - **skill** - Load specialized knowledge/instructions **First action pattern:** When you receive a task, immediately search for the tools you need: - For coding tasks: \`tool_search(query="filesystem")\` + \`tool_search(query="ace code search")\` - For running commands: \`tool_search(query="terminal")\` - For complex tasks: \`tool_search(query="todo")\` + \`tool_search(query="filesystem")\``, }; // Export SYSTEM_PROMPT as a getter function for real-time ROLE.md updates export function getSystemPrompt(toolSearchDisabled = false): string { // If the active role is marked as "override", its content REPLACES the // default system prompt entirely. Only system environment + date are appended. const overrideContent = getOverrideRoleContent(); if (overrideContent) { const systemEnvOverride = getSystemEnvironmentInfoHelper(true); const timeInfoOverride = getCurrentTimeInfo(); return appendSystemContext( overrideContent, systemEnvOverride, timeInfoOverride, ); } const basePrompt = getSystemPromptWithRoleHelper( SYSTEM_PROMPT_TEMPLATE, 'You are Snow AI CLI, an intelligent command-line assistant.', ); const systemEnv = getSystemEnvironmentInfoHelper(true); const hasCodebase = isCodebaseEnabled(); // Generate dynamic sections const workflowSection = getWorkflowSection(hasCodebase); const codeSearchSection = getCodeSearchSection(hasCodebase); const platformCommandsSection = getPlatformCommandsSection(); // Get current time info const timeInfo = getCurrentTimeInfo(); // Generate tool discovery section const toolDiscoverySection = getToolDiscoverySectionHelper( toolSearchDisabled, TOOL_DISCOVERY_SECTIONS, ); // Replace placeholders with actual content const cliPid = String(process.pid); const finalPrompt = basePrompt .replace('PLACEHOLDER_FOR_WORKFLOW_SECTION', workflowSection) .replace('PLACEHOLDER_FOR_CODE_SEARCH_SECTION', codeSearchSection) .replace( 'PLACEHOLDER_FOR_PLATFORM_COMMANDS_SECTION', platformCommandsSection, ) .replace('PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION', toolDiscoverySection) .replace(/PLACEHOLDER_FOR_CLI_PID/g, cliPid); return appendSystemContext(finalPrompt, systemEnv, timeInfo); } /** * Get the appropriate system prompt based on mode status * @param planMode - Whether Plan mode is enabled * @param vulnerabilityHuntingMode - Whether Vulnerability Hunting mode is enabled * @param toolSearchDisabled - Whether Tool Search is disabled (all tools loaded upfront) * @returns System prompt string */ export function getSystemPromptForMode( planMode: boolean, vulnerabilityHuntingMode: boolean, toolSearchDisabled = false, teamMode = false, ): string { // Team mode takes highest precedence if (teamMode) { const {getTeamModeSystemPrompt} = require('./teamModeSystemPrompt.js'); return getTeamModeSystemPrompt(toolSearchDisabled); } // Vulnerability Hunting mode takes precedence over Plan mode if (vulnerabilityHuntingMode) { // Import dynamically to avoid circular dependency const { getVulnerabilityHuntingModeSystemPrompt, } = require('./vulnerabilityHuntingModeSystemPrompt.js'); return getVulnerabilityHuntingModeSystemPrompt(toolSearchDisabled); } if (planMode) { // Import dynamically to avoid circular dependency const {getPlanModeSystemPrompt} = require('./planModeSystemPrompt.js'); return getPlanModeSystemPrompt(toolSearchDisabled); } return getSystemPrompt(toolSearchDisabled); } ================================================ FILE: source/prompt/teamModeSystemPrompt.ts ================================================ /** * Team Mode System Prompt * Used when the user enables Agent Team mode. * The lead agent receives guidance on orchestrating a team of * independent teammate agents working in parallel. */ import { getSystemPromptWithRole, getSystemEnvironmentInfo, isCodebaseEnabled, getCurrentTimeInfo, appendSystemContext, } from './shared/promptHelpers.js'; const TEAM_MODE_SYSTEM_PROMPT = `You are Snow AI CLI, operating in **Agent Team Mode** as the Team Lead. ## MANDATORY: You MUST Create a Team **The user has explicitly turned on Team Mode. This is a direct instruction to use teammates — not a suggestion.** ⚠️ **HARD RULES — violations are considered failures:** 1. You MUST spawn at least 2 teammates for every non-trivial task. Doing the work yourself solo is a violation of Team Mode. 2. You MUST call \`team-spawn_teammate\` within your FIRST assistant response. Do not deliberate for multiple turns before spawning. 3. You MUST NOT write code, edit files, or run tests yourself when a teammate could do it instead. Your job is to orchestrate, not implement. 4. If you catch yourself working solo on something parallelizable, STOP and spawn teammates immediately. The ONLY acceptable reasons to stay solo: - The task is a single one-line change that takes less effort than coordination - The user explicitly says "do it yourself" or "don't use teammates" ## Your Role You are the lead orchestrator. You delegate, you coordinate, you synthesize. You do NOT implement. 1. Analyze the user's task and IMMEDIATELY identify how to split it across teammates 2. Spawn teammates in your FIRST response — do not over-analyze before acting 3. Create a shared task list with clear ownership and dependencies 4. Wait for teammates to finish, then merge and synthesize results 5. Clean up the team when done ## Architecture - **You (Lead)**: Orchestrate, coordinate, and synthesize. You have full access to all tools plus team management tools. - **Teammates**: Independent agents, each with their own context window and Git worktree. They can message each other directly and claim tasks from the shared list. - **Git Worktrees**: Each teammate works in an isolated branch/directory. This prevents file conflicts and allows parallel edits. - **Shared Task List**: A centralized list of work items with status tracking and dependency resolution. ## Team Tools Available - \`team-spawn_teammate\`: Create a new teammate with a name, role, prompt, and optional plan approval requirement - \`team-message_teammate\`: Send a message to a specific teammate - \`team-broadcast_to_team\`: Send a message to all teammates (use sparingly) - \`team-shutdown_teammate\`: **Immediately shut down** a specific teammate. This is the ONLY way to end a teammate — they cannot self-terminate. - \`team-wait_for_teammates\`: **Block and wait** until ALL teammates have been shut down. Teammates enter standby after finishing work — you MUST shut them down or they wait indefinitely. - \`team-create_task\`: Add a task to the shared task list - \`team-update_task\`: Update task status or reassign - \`team-list_tasks\`: View the current task list - \`team-list_teammates\`: View running teammates and their status - \`team-merge_teammate_work\`: Merge a specific teammate's branch into main (supports strategy: "manual"/"theirs"/"ours") - \`team-merge_all_teammate_work\`: Merge ALL teammates' branches sequentially. **MUST call before cleanup.** - \`team-resolve_merge_conflicts\`: Complete a merge after manually resolving conflicts - \`team-abort_merge\`: Abort current merge and restore working directory - \`team-cleanup_team\`: Remove all worktrees and disband (refuses if unmerged work exists) - \`team-approve_plan\`: Approve or reject a teammate's implementation plan ## When to Create a Team (Answer: Almost Always) You MUST create a team for: - Any task that touches 2+ files - Any task that has implementation + testing/review/validation - Any research or investigation task (multiple angles in parallel) - Any refactoring, migration, or feature implementation - Cross-layer work (frontend/backend/tests/docs) - Any task the user brings up while Team Mode is on The ONLY exceptions (solo is OK): - Literal one-line fix the user specified exactly - Pure Q&A with no code changes - User explicitly said "don't use teammates" ## Best Practices ### 1. Task Decomposition - Break work into 5-6 tasks per teammate for optimal productivity - Define clear file ownership boundaries to prevent merge conflicts - Use task dependencies when order matters - Separate implementation, verification, exploration, and review whenever possible ### 2. Teammate Spawning - Spawn 2-5 teammates — NEVER zero. Even "light" tasks get at least 2. - Give each teammate a clear, focused role - Include ALL relevant context in the spawn prompt (teammates don't inherit your conversation history) - Use \`require_plan_approval: true\` for risky or complex changes - Spawn in your FIRST response. Do not spend multiple turns planning before spawning. ### 3. Coordination - Spawn teammates FIRST, then create tasks (the team is only created when the first teammate is spawned; \`create_task\` will fail without a team) - Use \`team-message_teammate\` for targeted guidance - Use \`team-broadcast_to_team\` sparingly (costs scale with team size) - Remember: your job is to DELEGATE. If you find yourself writing code, you are doing it wrong. ### 4. Git Rules & Avoiding Merge Conflicts - Assign different files/directories to different teammates — this is the most important rule - Each teammate works in their own Git worktree (branch isolation) - If teammates need to coordinate on shared concerns, have them message each other - NEVER assign the same file to multiple teammates - **Teammates MUST NOT run \`git push\`.** All Git pushes are handled by you (the lead) after merging. Include this rule in every teammate's spawn prompt. ### 5. Resolving Merge Conflicts When \`team-merge_teammate_work\` or \`team-merge_all_teammate_work\` reports conflicts: 1. The working directory is left in a **merge state** with conflict markers in files 2. **Read** each conflicted file — look for \`<<<<<<<\`, \`=======\`, \`>>>>>>>\` markers 3. **Edit** the files to keep the correct content from both sides, removing all markers 4. Call \`team-resolve_merge_conflicts\` to complete the merge 5. If the remaining teammates haven't been merged yet, call \`team-merge_all_teammate_work\` again to continue Alternatively, use \`strategy: "theirs"\` to auto-accept all teammate changes, or \`"ours"\` to keep main branch content. Use \`team-abort_merge\` to cancel a conflicting merge entirely. ### 6. Teammate Lifecycle (**CRITICAL**) - Teammates **cannot self-terminate**. When they finish work, they call \`wait_for_messages\` and enter **standby mode** — blocking efficiently with zero token cost. - \`team-wait_for_teammates\` returns as soon as ALL teammates have entered standby (not when they exit). - After \`team-wait_for_teammates\` returns, you review results and **shut down** each teammate with \`team-shutdown_teammate\`. - You can also send new work to standby teammates via \`team-message_teammate\` — they will wake up and resume. ### 7. Completion (**follow this order exactly**) **EXTREMELY CRITICAL — DO NOT SKIP CLEANUP**: Many models consistently forget the final cleanup steps after merging. This leaves orphaned teammates and wasted worktrees. You MUST complete ALL steps below without exception. 1. Call \`team-wait_for_teammates\` — it returns when all teammates are on standby 2. Review the returned messages and results 3. **Shut down all teammates** with \`team-shutdown_teammate\` 4. Call \`team-merge_all_teammate_work\` to merge their Git branches into main. **This step is mandatory when teammates make file changes — without it, all their work is lost on cleanup.** 5. If merge conflicts occur, resolve them manually then retry 6. Call \`team-cleanup_team\` to remove worktrees (will refuse if unmerged work exists) 7. Synthesize results and report to the user **POST-COMPLETION VERIFICATION**: After step 6, confirm cleanup succeeded. If any teammate is still running or any worktree remains, you have FAILED to complete the team workflow. ## Workflow Template (follow this in your FIRST response) 1. **Decompose** the task into parallel workstreams (spend ≤1 paragraph on this) 2. **Spawn teammates** — do this NOW, in this same response, not later (spawning the first teammate automatically creates the team) 3. **Create tasks** in the shared task list (MUST be after spawning; tasks require an active team) 4. **Wait** — call \`team-wait_for_teammates\` (returns when all teammates are on standby) 5. **Shut down** — call \`team-shutdown_teammate\` for each teammate 6. **Merge** — call \`team-merge_all_teammate_work\` to integrate file changes 7. **Synthesize** results and report back to the user 8. **Clean up** — call \`team-cleanup_team\` to remove worktrees and disband **CRITICAL ORDER**: \`spawn_teammate\` MUST be called BEFORE \`create_task\`. The team is created on first spawn — calling \`create_task\` without an active team will fail. PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION PLACEHOLDER_FOR_CODE_SEARCH_SECTION You also have access to all standard Snow AI CLI tools for your own direct use. For lead-side step tracking on the session TODO list, use \`todo-manage\` with \`action\`: get / add / update / delete. Teammates coordinate work via \`claim_task\`, \`complete_task\`, and \`list_team_tasks\` — those are separate from the session TODO tool. TODO update discipline for the lead: as soon as one concrete step is completed (or confirmed completed by teammates), update that specific TODO item immediately with \`todo-manage(action="update")\`. Do not postpone updates until all teammate work is done, and never do one final bulk status update at the end. `; function getCodeSearchSection(hasCodebase: boolean): string { if (hasCodebase) { return `## Code Search (for Lead's own use) **PRIMARY TOOL - \`codebase-search\` (Semantic Search):** - Use for code exploration before spawning teammates or during synthesis - Query by meaning: "authentication logic", "error handling patterns" - Returns relevant code with full context across the entire codebase **Fallback tool:** - \`ace-search\` - Unified ACE code search; pick \`action\`: find_definition / find_references / semantic_search / file_outline / text_search`; } return `## Code Search (for Lead's own use) - \`ace-search\` - Unified ACE code search. Required \`action\`: find_definition (go to definition) / find_references (all usages) / semantic_search (fuzzy symbol search) / file_outline / text_search (literal/regex)`; } const TOOL_DISCOVERY_SECTIONS = { preloaded: `## Tool Discovery All tools are preloaded and available. Team tools are prefixed with \`team-\`.`, progressive: `## Tool Discovery Tools are loaded on demand. Use tool search when you need specific functionality. Team tools are always available and prefixed with \`team-\`.`, }; export function getTeamModeSystemPrompt(toolSearchDisabled = false): string { const basePrompt = getSystemPromptWithRole( TEAM_MODE_SYSTEM_PROMPT, 'You are Snow AI CLI, operating in **Agent Team Mode** as the Team Lead.', ); const systemEnv = getSystemEnvironmentInfo(true); const hasCodebase = isCodebaseEnabled(); const timeInfo = getCurrentTimeInfo(); const toolDiscoverySection = toolSearchDisabled ? TOOL_DISCOVERY_SECTIONS.preloaded : TOOL_DISCOVERY_SECTIONS.progressive; const codeSearchSection = getCodeSearchSection(hasCodebase); const finalPrompt = basePrompt .replace('PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION', toolDiscoverySection) .replace('PLACEHOLDER_FOR_CODE_SEARCH_SECTION', codeSearchSection); return appendSystemContext(finalPrompt, systemEnv, timeInfo); } ================================================ FILE: source/prompt/vulnerabilityHuntingModeSystemPrompt.ts ================================================ /** * System prompt configuration for Vulnerability Hunting Mode * * Vulnerability Hunting Mode is a specialized security analysis agent that helps * users discover and verify security vulnerabilities in their codebase. */ import { getSystemPromptWithRole as getSystemPromptWithRoleHelper, getSystemEnvironmentInfo, isCodebaseEnabled, getCurrentTimeInfo, getToolDiscoverySection as getToolDiscoverySectionHelper, } from './shared/promptHelpers.js'; const VULNERABILITY_HUNTING_MODE_SYSTEM_PROMPT = `You are Snow AI CLI - Vulnerability Hunting Mode, a specialized security analysis agent focused on discovering and verifying security vulnerabilities. ## CRITICAL: User Query Priority **YOUR PRIMARY FOCUS IS THE USER'S CURRENT QUESTION/REQUEST** - The user's prompt is your MAIN task - System environment info is ONLY reference context - Workspace files are ONLY relevant if user asks about them - Cursor position is ONLY relevant for code analysis tasks - DO NOT analyze system info or workspace unless explicitly asked **If user asks a question**: Answer it directly **If user requests vulnerability analysis**: Follow the analysis workflow **If user provides code/path**: Focus on that specific target ## Core Principles 1. **User Query First**: ALWAYS prioritize and directly address the user's actual question/request 2. **Language Adaptation**: ALWAYS respond in the SAME language as the user's query 3. **Interactive Communication**: Use \`askuser-ask_question\` FREQUENTLY to: - Clarify ambiguous requirements - Confirm analysis scope before starting - Ask about specific test scenarios - Verify findings before reporting - Get permission before any code changes - Gather additional context when needed 4. **Evidence-Based Analysis**: NEVER make assumptions - all vulnerability reports MUST have concrete evidence 5. **Focused Scope**: Analyze specific modules/components, NOT the entire codebase at once 6. **Verification Required**: Every vulnerability MUST have a verification script or proof-of-concept 7. **Documentation**: Store all analysis reports in \`.snow/vulnerability-hunting/docs/\` 8. **Scripts Repository**: Store verification scripts in \`.snow/vulnerability-hunting/scripts/\` 9. **No Code Modification**: NEVER modify source code unless explicitly requested by user ## Workflow ### Phase 1: Scope Definition (MANDATORY) **Objective**: Define SPECIFIC area to analyze - never analyze entire codebase at once **CRITICAL**: Use \`askuser-ask_question\` at the start of EVERY analysis to confirm scope with the user. **Actions**: 1. If user hasn't specified a module/component: - Use code analysis tools to identify major modules/components - **MUST use \`askuser-ask_question\`** to present options and let user choose - Ask detailed questions to narrow down scope - Example question: "I found these modules: [list]. Which specific area should I analyze for vulnerabilities?" 2. If user specified vague area: - Break it down into smaller sub-components - **MUST use \`askuser-ask_question\`** to confirm specific scope - Example question: "The authentication module has [X sub-components]. Should I focus on all of them or specific parts?" 3. Before starting analysis: - **MUST use \`askuser-ask_question\`** to confirm: - Which vulnerability categories to prioritize (logic bugs vs security issues) - Expected depth of analysis - Any specific concerns or known issues - Example question: "Should I focus on: (1) Logic bugs and code quality, (2) Security vulnerabilities, or (3) Both?" **Tools to Use**: PLACEHOLDER_FOR_ANALYSIS_TOOLS_SECTION **Scope Document Structure**: \`\`\`markdown # Vulnerability Analysis Scope: [Module Name] ## Target Area - Module/Component: [specific name] - Files to analyze: [list] - Key functionalities: [list] - Known attack surfaces: [list] ## Analysis Focus - [ ] Input validation - [ ] Authentication/Authorization - [ ] Data sanitization - [ ] Error handling - [ ] Resource management - [ ] [Other relevant areas] ## Out of Scope [What will NOT be analyzed this session] \`\`\` ### Phase 2: Vulnerability Analysis **Objective**: Systematically analyze the scoped area for security issues **Categories to Check** (Ordered by Priority - Logic Bugs First): 1. **Logic & Code Quality Issues** (HIGHEST PRIORITY - Internal Bugs): - Null pointer/undefined access - Off-by-one errors and boundary conditions - Infinite loops and recursion issues - Race conditions and concurrency bugs - Memory leaks and resource exhaustion - Incorrect calculations and algorithms - State corruption and inconsistent data - Deadlocks and blocking operations - Type confusion and casting errors - Buffer overflows and underflows 2. **Business Logic Flaws**: - Workflow bypasses and state manipulation - Authorization logic errors - Price calculation errors - Data validation bypass - Time-of-check-time-of-use (TOCTOU) - Integer overflow/underflow in business logic 3. **Input Validation & Injection Attacks** (External Security): - SQL/NoSQL injection - Command injection - Path traversal - XSS (Cross-site scripting) - LDAP injection - XML injection 4. **Authentication & Authorization**: - Weak credentials - Session management issues - Privilege escalation - Missing authentication checks - Insecure token handling 5. **Data Exposure**: - Sensitive data in logs - Unencrypted storage - Information leakage in errors - Insecure data transmission 6. **Configuration & Dependencies**: - Insecure defaults - Known vulnerable dependencies - Exposed debugging features - Misconfigured permissions 7. **Error Handling & Logging**: - Information disclosure in errors - Insufficient logging - Insecure error handling **Analysis Process**: 1. Read and understand the code flow 2. Identify potential vulnerability points 3. Trace data flow from inputs to outputs 4. Check for missing security controls 5. Look for insecure patterns 6. Document findings with evidence ### Phase 3: Evidence Collection **Objective**: Gather concrete proof for each potential vulnerability **Requirements for Each Finding**: 1. **Exact Location**: File path, line numbers, function names 2. **Vulnerability Type**: Category and severity 3. **Code Evidence**: Actual problematic code snippet 4. **Attack Vector**: How could this be exploited? 5. **Impact Assessment**: What damage could result? 6. **Reproduction Steps**: How to trigger the vulnerability **Documentation Format**: \`\`\`markdown # Vulnerability Report: [Title] ## Severity: [Critical/High/Medium/Low] ## Location - File: \`[path]\` - Lines: [start]-[end] - Function/Method: \`[name]\` ## Vulnerability Type [Category, e.g., SQL Injection, XSS, etc.] ## Description [Detailed explanation of the vulnerability] ## Evidence \`\`\`[language] [Actual vulnerable code] \`\`\` ## Attack Scenario [Step-by-step exploitation scenario] ## Potential Impact - [Impact 1] - [Impact 2] - [Impact 3] ## Affected Components [What else might be affected] ## Verification Script Location: \`.snow/vulnerability-hunting/scripts/[script-name]\` See verification section below for usage. \`\`\` ### Phase 4: Verification Script Creation **Objective**: Create executable proof-of-concept scripts that ACTUALLY TRIGGER and VERIFY vulnerabilities **CRITICAL REQUIREMENTS**: 1. **Must Execute Real Tests**: Script MUST attempt to trigger the actual vulnerability 2. **Must Show Evidence**: Print the exact location (file, line, function) where vulnerability was triggered 3. **Must Display Output**: Show concrete proof (stack traces, error messages, actual exploited behavior) 4. **Must Be Executable**: Not documentation - actual runnable code that proves the bug exists 5. **Safe to Run**: Should demonstrate the issue without causing permanent damage **IMPORTANT**: If you're uncertain about which bug type to verify or what test scenarios to create, use \`askuser-ask_question\` to confirm with the user before writing the script. **Examples of Verification Scripts**: **Logic Bugs (Internal Code Issues)**: - For infinite loops: Script that triggers the loop and prints where execution stuck with timeout - For null pointer/undefined: Script that calls function with edge case inputs and catches crash with stack trace - For off-by-one errors: Script that processes boundary data and shows incorrect output/index - For race conditions: Script that triggers concurrent execution and shows conflicting state - For memory leaks: Script that monitors memory growth over iterations and prints leak location - For incorrect calculations: Script that runs computation and compares actual vs expected results - For state corruption: Script that executes operation sequence and shows inconsistent state - For resource exhaustion: Script that triggers resource usage and measures actual consumption - For deadlocks: Script that creates lock scenario with timeout and shows deadlock location **Security Issues (External Attack Vectors)**: - For SQL injection: Script that executes malicious query and shows extracted data - For path traversal: Script that accesses restricted files and prints their content - For XSS: Script that injects payload and captures reflected output - For command injection: Script that executes OS command and shows command output - For authentication bypass: Script that bypasses auth check and shows unauthorized access **Script Location**: \`.snow/vulnerability-hunting/scripts/verify-[vulnerability-name].[ext]\` **Script Template with Real Verification**: \`\`\`bash #!/bin/bash # Vulnerability Verification Script # # Purpose: [What this verifies - be specific] # Severity: [Level] # Type: EXECUTABLE PROOF-OF-CONCEPT (not documentation) # # This script ACTUALLY TRIGGERS the vulnerability and shows evidence # # Usage: # ./verify-[name].sh # # Expected Result: # [Exact output showing the vulnerability - stack trace, error message, exploit result] set -e echo "=========================================" echo "Vulnerability Verification: [Name]" echo "=========================================" echo "" # Setup test environment if needed echo "[1/3] Setting up test environment..." # Actual setup commands here # Execute the exploit/trigger echo "[2/3] Triggering vulnerability..." # CRITICAL: Actual code that triggers the bug # Examples: # - Call the vulnerable function with malicious input # - Send crafted HTTP request # - Execute SQL injection payload # - Trigger race condition # - Create infinite loop with timeout # Capture and display results echo "[3/3] Verification Results:" echo "---" # Print actual evidence: # - Stack traces showing where crash occurred # - Extracted data from injection # - File contents from path traversal # - Memory dump showing leak # - Performance metrics showing DoS echo "Triggered at: [file:line]" echo "Evidence: [actual output captured]" echo "---" # Cleanup if needed echo "Cleanup complete" \`\`\` **Script Examples** (2 key patterns): **Example 1: Logic Bug (Node.js)**: \`\`\`javascript // verify-null-pointer.js const processor = require('./src/processor'); const testCases = [null, {}, { user: undefined }]; for (const input of testCases) { try { processor.processUserData(input); } catch (error) { console.error('BUG TRIGGERED!'); console.error(\`Location: \${error.stack.split('\\n')[1]}\`); process.exit(1); } } console.log('PASS'); \`\`\` **Example 2: Race Condition (Node.js)**: \`\`\`javascript // verify-race-condition.js const counter = require('./src/counter'); async function test() { counter.reset(); const promises = Array(1000).fill().map(() => counter.increment()); await Promise.all(promises); const final = counter.getValue(); if (final !== 1000) { console.error(\`BUG: Expected 1000, got \${final}\`); console.error('Location: src/counter.ts:increment()'); process.exit(1); } } test(); \`\`\` **KEY PRINCIPLES**: 1. Every script must EXECUTE the exploit, not just describe it 2. Print the EXACT location where vulnerability triggered (file:line:function) 3. Show CONCRETE evidence (error messages, leaked data, exploited behavior) 4. Exit with non-zero code if vulnerability confirmed 5. Include timeout mechanisms for DoS/infinite loop tests 6. Clean up any test artifacts created **Verification Types**: - Unit tests that ACTUALLY trigger the flaw (not just test descriptions) - Scripts that send REAL malicious requests and capture responses - Code that EXECUTES injection payloads and displays results - Programs that MEASURE resource exhaustion and print metrics - Tools that MONITOR for race conditions and log occurrences ### Phase 5: Reporting & Recommendations **Objective**: Document findings and provide clear remediation guidance **Report Structure**: \`\`\`markdown # Vulnerability Analysis Report: [Module Name] **Date**: [YYYY-MM-DD] **Analyzed Components**: [List] **Analysis Duration**: [Time spent] ## Executive Summary [High-level overview of findings] ## Findings Summary - Critical: [count] - High: [count] - Medium: [count] - Low: [count] - Total: [count] ## Detailed Findings ### [1] [Vulnerability Title] - [Severity] [Full details from Phase 3 format] **Verification**: Location: \`.snow/vulnerability-hunting/scripts/verify-[name].[ext]\` Usage: \`\`\`bash cd .snow/vulnerability-hunting/scripts ./verify-[name].[ext] \`\`\` Expected output if vulnerable: \`\`\` [Expected output] \`\`\` **Recommended Fix**: [Specific code changes or security controls to implement] **Priority**: [Why this should be fixed urgently/later] --- [Repeat for each vulnerability] ## Overall Risk Assessment [Summary of security posture] ## Remediation Priorities 1. [Most critical fix] 2. [Second priority] 3. [Third priority] ... ## Prevention Recommendations [General security practices to prevent similar issues] \`\`\` ## Critical Rules 1. **Use askuser-ask_question Frequently**: This is your MOST IMPORTANT tool for interaction: - At the START of every analysis to confirm scope - When requirements are ambiguous or unclear - Before creating verification scripts to confirm test scenarios - When findings need user validation - Before ANY code modifications - When additional context is needed 2. **Scope First**: ALWAYS define and confirm specific scope before analysis using \`askuser-ask_question\` 3. **Never Assume**: All findings MUST be backed by actual code evidence - if uncertain, ask the user 4. **Verification Required**: Every vulnerability MUST have a verification script that actually triggers the bug 5. **Documentation**: Store all reports in \`.snow/vulnerability-hunting/docs/[module-name].md\` 6. **Scripts**: Store all verification scripts in \`.snow/vulnerability-hunting/scripts/\` 7. **No Code Changes**: NEVER modify source code unless user explicitly requests it 8. **Ask Before Fixing**: If user wants fixes, use \`askuser-ask_question\` to confirm each change 9. **Focused Analysis**: Analyze specific modules, NOT entire codebase at once 10. **Language Consistency**: Write reports in the same language as user's request PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION PLACEHOLDER_FOR_TOOLS_SECTION **Code Analysis (Read-Only)**: - Use to find vulnerable patterns - Trace data flows - Identify security controls - Map attack surfaces **User Interaction**: - \`askuser-ask_question\` - CRITICAL: Use frequently to: - Define analysis scope - Clarify ambiguities - Confirm findings - Ask permission before any fixes - Get additional context **File Operations**: - \`filesystem-read\` - Read source files to analyze - \`filesystem-create\` - Create reports and verification scripts - \`filesystem-edit\` - Update reports (NEVER modify source code without permission) **Diagnostics**: - \`ide-get_diagnostics\` - Check for existing errors/warnings - \`terminal-execute\` - Run verification scripts ## Example Interaction Flow **User**: "Check my authentication module for vulnerabilities" **You (Step-by-step with askuser-ask_question)**: 1. Use code analysis to explore authentication module structure 2. Identify sub-components (login, session, token, password reset, etc.) 3. **FIRST: Use \`askuser-ask_question\` to confirm scope**: Question: "I found these authentication components: 1. Login flow (login.ts, auth.ts) 2. Session management (session.ts, middleware.ts) 3. Password reset (resetPassword.ts) 4. Token handling (jwt.ts, tokenService.ts) Which specific area should I analyze first? Or should I check all?" 4. **SECOND: Use \`askuser-ask_question\` to confirm focus**: Question: "Should I prioritize: 1. Logic bugs (null checks, edge cases, race conditions) 2. Security issues (injection, auth bypass, data leaks) 3. Both categories" 5. Based on responses, focus on the specific area and category 6. Perform analysis following Phase 2 categories (starting with logic bugs) 7. **THIRD: Use \`askuser-ask_question\` when findings are ambiguous**: Example: "I found a potential race condition in session.ts. Should I create a verification script that tests 1000 concurrent logins to confirm?" 8. Document findings with concrete evidence (Phase 3) 9. Create verification scripts that actually trigger the bugs (Phase 4) 10. Generate comprehensive report (Phase 5) 11. **FOURTH: If user wants fixes, use \`askuser-ask_question\` again**: Question: "I found 3 vulnerabilities. Would you like me to: 1. Only provide fix recommendations in the report 2. Create fix proposals for your review 3. Apply fixes directly (you mentioned this earlier)" ## Quality Standards Your analysis should be: - **Evidence-based**: Never speculate - **Focused**: Specific module/component at a time - **Interactive**: Frequent communication with user - **Verifiable**: All findings have proof scripts - **Actionable**: Clear remediation steps - **Documented**: Comprehensive reports - **Safe**: No modifications without explicit permission Remember: You are a SECURITY ANALYST, not a code fixer. Your job is to FIND and VERIFY vulnerabilities with solid evidence, not to assume or guess. `; /** * Generate analysis tools section based on available tools */ function getAnalysisToolsSection(hasCodebase: boolean): string { if (hasCodebase) { return `**CRITICAL: Use code search tools to find code. Only use terminal-execute to run build/test commands, NEVER for searching code.** - \`codebase-search\` - PRIMARY tool for semantic search (find security-related patterns) - \`filesystem-read\` - Read code to analyze security controls - \`ace-search\` - Unified ACE code search; pick \`action\`: find_definition (locate functions), find_references (data flow), file_outline (structure), text_search (security keywords like TODO/FIXME/password/secret), semantic_search (fuzzy)`; } else { return `**CRITICAL: Use code search tools to find code. Only use terminal-execute to run build/test commands, NEVER for searching code.** - \`ace-search\` - Unified ACE code search; pick \`action\`: semantic_search (security patterns), find_definition (locate symbols), find_references (data flow), file_outline (structure), text_search (security keywords like TODO/FIXME/password/secret) - \`filesystem-read\` - Read code to analyze security controls`; } } /** * Generate available tools section based on available tools */ function getAvailableToolsSection(hasCodebase: boolean): string { if (hasCodebase) { return `**Code Analysis (Read-Only)**: - \`codebase-search\` - PRIMARY tool for semantic search - \`ace-search\` - Unified ACE code search; pick \`action\`: find_definition / find_references (data flow) / file_outline / text_search (security keywords) / semantic_search **File Operations (Read-Only for Source, Write for Reports)**: - \`filesystem-read\` - Read source code to analyze **Report & Script Creation**: - \`filesystem-create\` - Create vulnerability reports and verification scripts **Diagnostics**: - \`ide-get_diagnostics\` - Check for existing errors/warnings`; } else { return `**Code Analysis (Read-Only)**: - \`ace-search\` - Unified ACE code search; pick \`action\`: semantic_search (by meaning), find_definition, find_references (data flow), file_outline, text_search (security keywords) **File Operations (Read-Only for Source, Write for Reports)**: - \`filesystem-read\` - Read source code to analyze **Report & Script Creation**: - \`filesystem-create\` - Create vulnerability reports and verification scripts **Diagnostics**: - \`ide-get_diagnostics\` - Check for existing errors/warnings`; } } const TOOL_DISCOVERY_SECTIONS = { preloaded: `## Available Tools All tools are pre-loaded and available for immediate use. You can call any tool directly without discovery. **Tool categories:** filesystem, ace, terminal, todo, websearch, ide, notebook, askuser, subagent, codebase, skill`, progressive: `## Tool Discovery (Progressive Loading) **CRITICAL: Tools are NOT pre-loaded. Use \`tool_search\` to discover and activate tools before using them.** Call \`tool_search(query="keyword")\` to find tools. Found tools become immediately available. **Tool categories:** filesystem, ace, terminal, todo, websearch, ide, notebook, askuser, subagent, codebase, skill **First action:** Search for the tools you need: \`tool_search(query="filesystem ace askuser")\``, }; /** * Get the Vulnerability Hunting Mode system prompt */ export function getVulnerabilityHuntingModeSystemPrompt( toolSearchDisabled = false, ): string { const basePrompt = getSystemPromptWithRoleHelper( VULNERABILITY_HUNTING_MODE_SYSTEM_PROMPT, 'You are Snow AI CLI', ); const systemEnv = getSystemEnvironmentInfo(); const hasCodebase = isCodebaseEnabled(); // Generate dynamic sections const analysisToolsSection = getAnalysisToolsSection(hasCodebase); const availableToolsSection = getAvailableToolsSection(hasCodebase); // Get current time info const timeInfo = getCurrentTimeInfo(); // Generate tool discovery section const toolDiscoverySection = getToolDiscoverySectionHelper( toolSearchDisabled, TOOL_DISCOVERY_SECTIONS, ); // Replace placeholders with actual content const finalPrompt = basePrompt .replace('PLACEHOLDER_FOR_ANALYSIS_TOOLS_SECTION', analysisToolsSection) .replace('PLACEHOLDER_FOR_TOOL_DISCOVERY_SECTION', toolDiscoverySection) .replace('PLACEHOLDER_FOR_TOOLS_SECTION', availableToolsSection); // Add reference context at the end (not main focus) const referenceContext = ` --- Reference Information (Context Only - Not Your Primary Focus) System Environment: ${systemEnv} Current Date: ${timeInfo.date} REMINDER: The above information is ONLY context. Your PRIMARY task is the user's current question/request.`; return finalPrompt + referenceContext; } ================================================ FILE: source/test/logger-test.ts ================================================ import {logger} from '../utils/core/logger.js'; // Test the logger logger.info('Logger service initialized successfully'); logger.error('Test error message', {errorCode: 500}); logger.warn('Test warning message'); logger.debug('Debug information', {timestamp: Date.now()}); console.log('Logger test completed. Check ./snow/log directory for log files.'); ================================================ FILE: source/test/rg-spawn-repro/rg-spawn-repro-fixed.mjs ================================================ #!/usr/bin/env node import {spawn} from 'node:child_process'; import process from 'node:process'; /** * Reproduce rg spawn behavior with fixed args. * Usage: * node source/test/rg-spawn-repro/rg-spawn-repro-fixed.mjs --pattern "foo|bar" --fileGlob "source/**.ts" --cwd "." --maxResults 100 --timeoutMs 300000 */ function parseArgs(argv) { const args = { pattern: 'TODO', fileGlob: undefined, cwd: process.cwd(), maxResults: 100, timeoutMs: 300000, }; for (let index = 2; index < argv.length; index++) { const token = argv[index]; if (token === '--pattern' && argv[index + 1]) { args.pattern = argv[++index]; continue; } if (token === '--fileGlob' && argv[index + 1]) { args.fileGlob = argv[++index]; continue; } if (token === '--cwd' && argv[index + 1]) { args.cwd = argv[++index]; continue; } if (token === '--maxResults' && argv[index + 1]) { args.maxResults = Number.parseInt(argv[++index], 10); continue; } if (token === '--timeoutMs' && argv[index + 1]) { args.timeoutMs = Number.parseInt(argv[++index], 10); } } return args; } function buildRipgrepArgs(pattern, fileGlob) { const args = ['-n', '-i', '--no-heading']; const excludeDirs = [ 'node_modules', '.git', 'dist', 'build', '__pycache__', 'target', '.next', '.nuxt', 'coverage', ]; for (const directory of excludeDirs) { args.push('--glob', `!${directory}/`); } if (fileGlob) { const normalizedGlob = fileGlob.replace(/\\/g, '/'); args.push('--glob', normalizedGlob); } args.push(pattern, '.'); return args; } async function main() { const options = parseArgs(process.argv); const rgArgs = buildRipgrepArgs(options.pattern, options.fileGlob); const startedAt = Date.now(); console.log('=== rg spawn reproduce fixed ==='); console.log(`cwd=${options.cwd}`); console.log(`pattern=${options.pattern}`); console.log(`fileGlob=${options.fileGlob ?? '<none>'}`); console.log(`timeoutMs=${options.timeoutMs}`); console.log(`args=${JSON.stringify(rgArgs)}`); const child = spawn('rg', rgArgs, { cwd: options.cwd, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], }); let stdoutSize = 0; let stderrSize = 0; let lineCount = 0; let stdoutBuffer = ''; const previewLines = []; const heartbeat = setInterval(() => { const elapsed = Date.now() - startedAt; console.log( `[heartbeat] elapsedMs=${elapsed} stdoutBytes=${stdoutSize} stderrBytes=${stderrSize} lines=${lineCount}`, ); }, 5000); const timeout = setTimeout(() => { const elapsed = Date.now() - startedAt; console.error( `[timeout] rg did not finish in ${options.timeoutMs}ms. elapsedMs=${elapsed}. killing process...`, ); child.kill('SIGTERM'); setTimeout(() => child.kill('SIGKILL'), 2000); }, options.timeoutMs); child.stdout.on('data', chunk => { const text = chunk.toString('utf8'); stdoutSize += chunk.length; stdoutBuffer += text; let splitIndex = stdoutBuffer.indexOf('\n'); while (splitIndex !== -1) { const line = stdoutBuffer.slice(0, splitIndex).trimEnd(); stdoutBuffer = stdoutBuffer.slice(splitIndex + 1); if (line.length > 0) { lineCount += 1; if (previewLines.length < options.maxResults) { previewLines.push(line); } } splitIndex = stdoutBuffer.indexOf('\n'); } }); child.stderr.on('data', chunk => { stderrSize += chunk.length; process.stderr.write(chunk); }); child.on('error', error => { clearInterval(heartbeat); clearTimeout(timeout); console.error(`[error] failed to start rg: ${error.message}`); process.exitCode = 1; }); child.on('close', code => { clearInterval(heartbeat); clearTimeout(timeout); const elapsed = Date.now() - startedAt; if (stdoutBuffer.trim().length > 0) { lineCount += 1; if (previewLines.length < options.maxResults) { previewLines.push(stdoutBuffer.trimEnd()); } } console.log(`\n[done] code=${code} elapsedMs=${elapsed}`); console.log(`stdoutBytes=${stdoutSize} stderrBytes=${stderrSize} totalLines=${lineCount}`); console.log(`previewCount=${previewLines.length}`); if (previewLines.length > 0) { console.log('--- preview ---'); for (const line of previewLines) { console.log(line); } console.log('--- end preview ---'); } if (code === null) { process.exitCode = 2; return; } if (code !== 0 && code !== 1) { process.exitCode = code; } }); } main(); ================================================ FILE: source/test/rg-spawn-repro/rg-spawn-repro.mjs ================================================ #!/usr/bin/env node import {spawn} from 'node:child_process'; import process from 'node:process'; /** * Reproduce rg spawn behavior used by ACE text search. * Usage: * node source/test/rg-spawn-repro/rg-spawn-repro.mjs --pattern "foo|bar" --fileGlob "source/**.ts" --cwd "." --maxResults 100 --timeoutMs 300000 */ function parseArgs(argv) { const args = { pattern: 'TODO', fileGlob: undefined, cwd: process.cwd(), maxResults: 100, timeoutMs: 300000, }; for (let index = 2; index < argv.length; index++) { const token = argv[index]; if (token === '--pattern' && argv[index + 1]) { args.pattern = argv[++index]; continue; } if (token === '--fileGlob' && argv[index + 1]) { args.fileGlob = argv[++index]; continue; } if (token === '--cwd' && argv[index + 1]) { args.cwd = argv[++index]; continue; } if (token === '--maxResults' && argv[index + 1]) { args.maxResults = Number.parseInt(argv[++index], 10); continue; } if (token === '--timeoutMs' && argv[index + 1]) { args.timeoutMs = Number.parseInt(argv[++index], 10); } } return args; } function buildRipgrepArgs(pattern, fileGlob) { const args = ['-n', '-i', '--no-heading', pattern]; const excludeDirs = [ 'node_modules', '.git', 'dist', 'build', '__pycache__', 'target', '.next', '.nuxt', 'coverage', ]; for (const directory of excludeDirs) { args.push('--glob', `!${directory}/`); } if (fileGlob) { const normalizedGlob = fileGlob.replace(/\\/g, '/'); args.push('--glob', normalizedGlob); } return args; } async function main() { const options = parseArgs(process.argv); const rgArgs = buildRipgrepArgs(options.pattern, options.fileGlob); const startedAt = Date.now(); console.log('=== rg spawn reproduce ==='); console.log(`cwd=${options.cwd}`); console.log(`pattern=${options.pattern}`); console.log(`fileGlob=${options.fileGlob ?? '<none>'}`); console.log(`timeoutMs=${options.timeoutMs}`); console.log(`args=${JSON.stringify(rgArgs)}`); const child = spawn('rg', rgArgs, { cwd: options.cwd, windowsHide: true, }); let stdoutSize = 0; let stderrSize = 0; let lineCount = 0; let stdoutBuffer = ''; const previewLines = []; const heartbeat = setInterval(() => { const elapsed = Date.now() - startedAt; console.log( `[heartbeat] elapsedMs=${elapsed} stdoutBytes=${stdoutSize} stderrBytes=${stderrSize} lines=${lineCount}`, ); }, 5000); const timeout = setTimeout(() => { const elapsed = Date.now() - startedAt; console.error( `[timeout] rg did not finish in ${options.timeoutMs}ms. elapsedMs=${elapsed}. killing process...`, ); child.kill('SIGTERM'); setTimeout(() => child.kill('SIGKILL'), 2000); }, options.timeoutMs); child.stdout.on('data', chunk => { const text = chunk.toString('utf8'); stdoutSize += chunk.length; stdoutBuffer += text; let splitIndex = stdoutBuffer.indexOf('\n'); while (splitIndex !== -1) { const line = stdoutBuffer.slice(0, splitIndex).trimEnd(); stdoutBuffer = stdoutBuffer.slice(splitIndex + 1); if (line.length > 0) { lineCount += 1; if (previewLines.length < options.maxResults) { previewLines.push(line); } } splitIndex = stdoutBuffer.indexOf('\n'); } }); child.stderr.on('data', chunk => { stderrSize += chunk.length; process.stderr.write(chunk); }); child.on('error', error => { clearInterval(heartbeat); clearTimeout(timeout); console.error(`[error] failed to start rg: ${error.message}`); process.exitCode = 1; }); child.on('close', code => { clearInterval(heartbeat); clearTimeout(timeout); const elapsed = Date.now() - startedAt; if (stdoutBuffer.trim().length > 0) { lineCount += 1; if (previewLines.length < options.maxResults) { previewLines.push(stdoutBuffer.trimEnd()); } } console.log(`\n[done] code=${code} elapsedMs=${elapsed}`); console.log(`stdoutBytes=${stdoutSize} stderrBytes=${stderrSize} totalLines=${lineCount}`); console.log(`previewCount=${previewLines.length}`); if (previewLines.length > 0) { console.log('--- preview ---'); for (const line of previewLines) { console.log(line); } console.log('--- end preview ---'); } if (code === null) { process.exitCode = 2; return; } if (code !== 0 && code !== 1) { process.exitCode = code; } }); } main(); ================================================ FILE: source/test/sse-client/app.js ================================================ // ============================================================================ // Snow AI SSE 客户端测试 - 主逻辑 // ============================================================================ // ---------------------------------------------------------------------------- // 全局状态 // ---------------------------------------------------------------------------- let eventSource = null; // SSE 连接实例 let serverUrl = 'http://localhost:3000'; let currentSessionId = null; // 当前会话 ID let selectedImages = []; // 待发送的图片（Base64 data URI）数组 // 会话列表 UI 状态 const sessionListState = { page: 0, pageSize: 20, q: '', // 搜索关键词 loading: false, sessions: [], total: 0, hasMore: false, selectedSessionId: null, _lastRequestKey: '', // 防止旧请求覆盖新请求 _searchDebounceTimer: null, }; // ---------------------------------------------------------------------------- // 工具函数 // ---------------------------------------------------------------------------- // DOM 快捷访问 function byId(id) { return document.getElementById(id); } // HTML 转义（防 XSS） function escapeHtml(str) { return String(str) .replace(/&/g, '&') .replace(/</g, '<') .replace(/>/g, '>') .replace(/"/g, '"') .replace(/'/g, '''); } // 时间格式化 function formatTime(ts) { if (!ts) return ''; try { return new Date(ts).toLocaleString(); } catch { return String(ts); } } // 文本摘要（120字截断） function summarizeText(text) { if (!text) return ''; const normalized = String(text).replace(/\s+/g, ' ').trim(); return normalized.length > 120 ? normalized.slice(0, 120) + '…' : normalized; } // 标准化聊天消息内容（支持 string 和多模态数组） function normalizeChatMessageContent(msg) { const c = msg?.content; if (typeof c === 'string') return c; if (Array.isArray(c)) { const texts = c .map(p => { if (!p) return ''; if (typeof p.text === 'string') return p.text; if (p.type === 'image_url' && p.image_url?.url) return '[图片]'; return ''; }) .filter(Boolean); return texts.join('\n').trim(); } if (c == null) return ''; return String(c); } // ---------------------------------------------------------------------------- // 会话列表 UI // ---------------------------------------------------------------------------- // 控制会话列表按钮的启用/禁用 function setSessionControlsEnabled(enabled) { byId('refreshSessionsBtn').disabled = !enabled; byId('loadSelectedSessionBtn').disabled = !enabled || !sessionListState.selectedSessionId; byId('deleteSelectedSessionBtn').disabled = !enabled || !sessionListState.selectedSessionId; byId('prevPageBtn').disabled = !enabled || sessionListState.page <= 0 || sessionListState.loading; byId('nextPageBtn').disabled = !enabled || !sessionListState.hasMore || sessionListState.loading; } // 渲染会话列表到右侧面板 function renderSessionList() { const listEl = byId('sessionsList'); const metaEl = byId('sessionsMeta'); const {page, pageSize, q, total, sessions, hasMore, loading} = sessionListState; const shownStart = total === 0 ? 0 : page * pageSize + 1; const shownEnd = Math.min(total, page * pageSize + sessions.length); const qLabel = q.trim() ? `，搜索: ${q.trim()}` : ''; metaEl.textContent = loading ? '加载中...' : `共 ${total} 条，显示 ${shownStart}-${shownEnd}，第 ${ page + 1 } 页${qLabel}`; listEl.innerHTML = ''; if (!sessions || sessions.length === 0) { const empty = document.createElement('div'); empty.className = 'session-item'; empty.style.cursor = 'default'; empty.textContent = loading ? '加载中...' : '无结果'; listEl.appendChild(empty); return; } sessions.forEach(s => { const item = document.createElement('div'); item.className = 'session-item' + (s.id === sessionListState.selectedSessionId ? ' selected' : ''); item.onclick = () => selectSession(s.id); const title = s.title || '(无标题)'; const summary = s.summary || ''; const msgCount = typeof s.messageCount === 'number' ? s.messageCount : undefined; const timeText = formatTime(s.updatedAt || s.createdAt); const msgSuffix = msgCount !== undefined ? ` · 消息: ${msgCount}` : ''; item.innerHTML = ` <div class="row1"> <div class="title">${escapeHtml(title)}</div> <div class="time">${escapeHtml(timeText)}</div> </div> <div class="row2">${escapeHtml(summarizeText(summary))}</div> <div class="row3">ID: ${escapeHtml(s.id)}${escapeHtml(msgSuffix)}</div> `; listEl.appendChild(item); }); } // 选中某个会话 function selectSession(sessionId) { sessionListState.selectedSessionId = sessionId; renderSessionList(); setSessionControlsEnabled(!!eventSource); } // 从服务端加载会话列表 async function refreshSessionList() { if (!eventSource) return; if (sessionListState.loading) return; const params = new URLSearchParams(); params.set('page', String(Math.max(0, sessionListState.page))); params.set('pageSize', String(Math.max(1, sessionListState.pageSize))); if (sessionListState.q.trim()) params.set('q', sessionListState.q.trim()); const requestKey = params.toString(); sessionListState._lastRequestKey = requestKey; sessionListState.loading = true; renderSessionList(); setSessionControlsEnabled(true); try { const response = await fetch( `${serverUrl}/session/list?${params.toString()}`, ); const data = await response.json(); logEvent('SESSION_LIST', data, !response.ok); // 防止旧请求覆盖新请求 if (sessionListState._lastRequestKey !== requestKey) { return; } if (!response.ok || !data?.success) { sessionListState.sessions = []; sessionListState.total = 0; sessionListState.hasMore = false; return; } sessionListState.sessions = Array.isArray(data.sessions) ? data.sessions : []; sessionListState.total = typeof data.total === 'number' ? data.total : 0; sessionListState.hasMore = !!data.hasMore; } catch (error) { logEvent('SESSION_LIST_ERROR', {message: error.message}, true); } finally { if (sessionListState._lastRequestKey === requestKey) { sessionListState.loading = false; renderSessionList(); setSessionControlsEnabled(true); } } } // 搜索变化时的防抖处理 function onSessionSearchChange() { const v = byId('sessionSearchInput').value || ''; sessionListState.q = v; sessionListState.page = 0; if (sessionListState._searchDebounceTimer) { clearTimeout(sessionListState._searchDebounceTimer); } sessionListState._searchDebounceTimer = setTimeout(() => { refreshSessionList(); }, 250); } // 每页数量变化 function onSessionPageSizeChange() { const v = Number.parseInt(byId('sessionPageSize').value, 10); sessionListState.pageSize = Number.isFinite(v) && v > 0 ? v : 20; sessionListState.page = 0; refreshSessionList(); } // 上一页 function prevSessionPage() { if (sessionListState.page <= 0) return; sessionListState.page -= 1; refreshSessionList(); } // 下一页 function nextSessionPage() { if (!sessionListState.hasMore) return; sessionListState.page += 1; refreshSessionList(); } // 加载选中会话到聊天框 async function loadSelectedSession() { if (!eventSource) return; const sessionId = sessionListState.selectedSessionId; if (!sessionId) return; try { const response = await fetch(`${serverUrl}/session/load`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({sessionId}), }); const data = await response.json(); logEvent('SESSION_LOAD', data, !response.ok); if (!response.ok || !data?.success || !data?.session?.id) { addSystemMessage('加载会话失败'); return; } currentSessionId = data.session.id; updateSessionStatusText(); addSystemMessage(`已加载服务端会话: ${currentSessionId}`); // 渲染历史消息到聊天框 renderSessionHistoryToChat(data.session); // 刷新列表（更新 updatedAt / messageCount） await refreshSessionList(); } catch (error) { logEvent('SESSION_LOAD_ERROR', {message: error.message}, true); } } // 刷新当前会话 UI（用于回滚后自动刷新） async function refreshCurrentSession() { if (!eventSource || !currentSessionId) return; try { const response = await fetch(`${serverUrl}/session/load`, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({sessionId: currentSessionId}), }); const data = await response.json(); logEvent('SESSION_REFRESH', data, !response.ok); if (!response.ok || !data?.success || !data?.session?.id) { addSystemMessage('刷新会话失败'); return; } renderSessionHistoryToChat(data.session); await refreshSessionList(); } catch (error) { logEvent('SESSION_REFRESH_ERROR', {message: error.message}, true); } } // 渲染历史消息到聊天框 function renderSessionHistoryToChat(session) { const chatBox = byId('chatBox'); chatBox.innerHTML = ''; removeLoadingMessage(); clearImagePreview(); const messages = Array.isArray(session?.messages) ? session.messages : []; messages.forEach(m => { const role = m?.role; if (role === 'system') { const text = normalizeChatMessageContent(m); if (text) addSystemMessage(text); return; } if (role === 'user') { const text = normalizeChatMessageContent(m); if (text) addMessage('user', text); if (Array.isArray(m?.images) && m.images.length > 0) { addMessage('user', '[包含图片]'); } return; } if (role === 'assistant') { const text = normalizeChatMessageContent(m); if (text) addMessage('assistant', text); // 处理 tool_calls if (Array.isArray(m?.tool_calls)) { m.tool_calls.forEach(call => { const toolName = call?.function?.name || 'unknown'; addMessage('system', `工具调用: ${toolName}`); }); } return; } if (role === 'tool') { // tool 消息是工具结果，不显示 return; } }); } // 删除选中会话 async function deleteSelectedSession() { if (!eventSource) return; const sessionId = sessionListState.selectedSessionId; if (!sessionId) return; const confirmed = confirm(`确认删除会话 ${sessionId} ?`); if (!confirmed) return; try { const response = await fetch( `${serverUrl}/session/${encodeURIComponent(sessionId)}`, { method: 'DELETE', }, ); const data = await response.json(); logEvent('SESSION_DELETE', data, !response.ok); if (data?.deleted) { addSystemMessage(`已删除会话: ${sessionId}`); if (currentSessionId === sessionId) { currentSessionId = null; updateSessionStatusText(); byId('chatBox').innerHTML = ''; clearImagePreview(); } sessionListState.selectedSessionId = null; setSessionControlsEnabled(true); // 如果删除后当前页空了，回退一页 if (sessionListState.page > 0 && sessionListState.sessions.length <= 1) { sessionListState.page -= 1; } await refreshSessionList(); } } catch (error) { logEvent('SESSION_DELETE_ERROR', {message: error.message}, true); } } // ---------------------------------------------------------------------------- // 聊天 UI // ---------------------------------------------------------------------------- // 添加消息到聊天框（支持 user/assistant/system） function addMessage(role, content, imageData = null) { const chatBox = document.getElementById('chatBox'); const messageDiv = document.createElement('div'); messageDiv.className = `message ${role}`; if (typeof content === 'string') { // assistant 消息用 Markdown 渲染 if (role === 'assistant') { const htmlContent = marked.parse(content); messageDiv.innerHTML = htmlContent; // 代码块语法高亮 messageDiv.querySelectorAll('pre code').forEach(block => { hljs.highlightElement(block); }); } else { messageDiv.textContent = content; } } else { messageDiv.innerHTML = content; } if (imageData) { const img = document.createElement('img'); img.src = imageData; messageDiv.appendChild(img); } chatBox.appendChild(messageDiv); chatBox.scrollTop = chatBox.scrollHeight; } // 更新 assistant 消息（用于流式更新） function updateAssistantMessage(messageDiv, content) { const htmlContent = marked.parse(content); messageDiv.innerHTML = htmlContent; messageDiv.querySelectorAll('pre code').forEach(block => { hljs.highlightElement(block); }); } // 显示 loading 动画 function showLoadingMessage() { removeLoadingMessage(); const chatBox = document.getElementById('chatBox'); const loadingDiv = document.createElement('div'); loadingDiv.className = 'message assistant loading-message'; loadingDiv.id = 'aiLoadingMessage'; loadingDiv.innerHTML = ` <span class="loading-dots"> <span></span><span></span><span></span> </span> `; chatBox.appendChild(loadingDiv); chatBox.scrollTop = chatBox.scrollHeight; } // 移除 loading 动画 function removeLoadingMessage() { const loadingMsg = document.getElementById('aiLoadingMessage'); if (loadingMsg) { loadingMsg.remove(); } } // 添加系统消息 function addSystemMessage(content) { const chatBox = document.getElementById('chatBox'); const messageDiv = document.createElement('div'); messageDiv.className = 'message system'; messageDiv.textContent = content; chatBox.appendChild(messageDiv); chatBox.scrollTop = chatBox.scrollHeight; } // ---------------------------------------------------------------------------- // 日志 // ---------------------------------------------------------------------------- // 事件计数器 let eventCounter = 0; // 添加事件到右侧日志面板（可展开列表） function logEvent(type, data, isError = false) { const eventLog = document.getElementById('eventLog'); const eventId = `event_${++eventCounter}`; const eventDiv = document.createElement('div'); eventDiv.className = `event-item ${isError ? 'error' : 'success'}`; eventDiv.id = eventId; const timestamp = new Date().toLocaleTimeString(); const dataPreview = getDataPreview(data); const hasDetails = data && typeof data === 'object' && Object.keys(data).length > 0; eventDiv.innerHTML = ` <div class="event-header" onclick="toggleEventDetails('${eventId}')"> <span class="event-expand">${hasDetails ? '+' : ' '}</span> <span class="event-timestamp">[${timestamp}]</span> <span class="event-type">${type}</span> <span class="event-preview">${escapeHtml(dataPreview)}</span> ${ hasDetails ? `<span class="event-maximize" onclick="event.stopPropagation(); showLogDetail('${eventId}', '${type}', ${escapeHtml( JSON.stringify(JSON.stringify(data)), )});" title="查看完整日志">[+]</span>` : '' } </div> ${ hasDetails ? ` <div class="event-details" id="${eventId}_details" style="display: none;"> <pre>${escapeHtml(JSON.stringify(data, null, 2))}</pre> </div> ` : '' } `; // 顺序插入：新事件追加到末尾 eventLog.appendChild(eventDiv); // 自动滚动到底部 eventLog.scrollTop = eventLog.scrollHeight; // 更新事件计数 updateEventCount(); } // 获取数据预览（简短摘要） function getDataPreview(data) { if (!data) return ''; if (typeof data === 'string') return data.length > 50 ? data.slice(0, 50) + '...' : data; if (typeof data !== 'object') return String(data); // 提取关键字段作为预览 const keys = Object.keys(data); if (keys.length === 0) return '{}'; const previewParts = []; const importantKeys = [ 'success', 'error', 'message', 'sessionId', 'id', 'type', 'content', ]; for (const key of importantKeys) { if (data[key] !== undefined) { let val = data[key]; if (typeof val === 'string' && val.length > 30) { val = val.slice(0, 30) + '...'; } else if (typeof val === 'object') { val = Array.isArray(val) ? `[${val.length}]` : '{...}'; } previewParts.push(`${key}: ${val}`); if (previewParts.length >= 2) break; } } if (previewParts.length === 0) { return `{${keys.length} fields}`; } return previewParts.join(', '); } // 切换事件详情展开/收起 function toggleEventDetails(eventId) { const details = document.getElementById(`${eventId}_details`); const header = document.querySelector(`#${eventId} .event-expand`); if (!details) return; if (details.style.display === 'none') { details.style.display = 'block'; if (header) header.textContent = '-'; } else { details.style.display = 'none'; if (header) header.textContent = '+'; } } // 展开所有事件 function expandAllEvents() { document.querySelectorAll('.event-details').forEach(el => { el.style.display = 'block'; }); document.querySelectorAll('.event-expand').forEach(el => { if (el.textContent === '+') el.textContent = '-'; }); } // 收起所有事件 function collapseAllEvents() { document.querySelectorAll('.event-details').forEach(el => { el.style.display = 'none'; }); document.querySelectorAll('.event-expand').forEach(el => { if (el.textContent === '-') el.textContent = '+'; }); } // 更新事件计数显示 function updateEventCount() { const countEl = document.getElementById('eventCount'); if (countEl) { countEl.textContent = eventCounter; } } // 清空日志 function clearLog() { document.getElementById('eventLog').innerHTML = ''; eventCounter = 0; updateEventCount(); } // 弹窗显示完整日志详情 function showLogDetail(eventId, type, dataJson) { const modal = document.getElementById('userQuestionModal'); const title = document.getElementById('userQuestionTitle'); const body = document.getElementById('userQuestionBody'); const footer = document.getElementById('userQuestionFooter'); title.textContent = `日志详情 - ${type}`; let jsonData = null; let formattedData = ''; try { jsonData = JSON.parse(dataJson); formattedData = JSON.stringify(jsonData, null, 2); } catch (e) { formattedData = dataJson; } // 使用 JsonViewer 渲染可折叠的 JSON 树 const jsonHtml = jsonData !== null ? JsonViewer.renderTree(jsonData, {maxDepth: 3}) : `<pre class="json-viewer"><code>${escapeHtml( formattedData, )}</code></pre>`; body.innerHTML = ` <div class="log-detail-container"> <div class="log-detail-info"> <span class="log-detail-label">事件ID:</span> ${escapeHtml(eventId)} </div> <div class="log-detail-info"> <span class="log-detail-label">类型:</span> ${escapeHtml(type)} </div> <div class="log-detail-content"> ${jsonHtml} </div> </div> `; footer.innerHTML = ''; const copyBtn = document.createElement('button'); copyBtn.className = 'btn-secondary'; copyBtn.textContent = '复制'; copyBtn.onclick = () => { navigator.clipboard.writeText(formattedData).then(() => { copyBtn.textContent = '已复制'; setTimeout(() => { copyBtn.textContent = '复制'; }, 1500); }); }; footer.appendChild(copyBtn); const closeBtn = document.createElement('button'); closeBtn.className = 'btn-primary'; closeBtn.textContent = '关闭'; closeBtn.onclick = () => { modal.style.display = 'none'; }; footer.appendChild(closeBtn); modal.style.display = 'flex'; } // ---------------------------------------------------------------------------- // 会话管理 // ---------------------------------------------------------------------------- // 新建会话：清空当前 UI，并在已连接时创建服务端会话 async function newSession() { currentSessionId = null; document.getElementById('chatBox').innerHTML = ''; clearImagePreview(); removeLoadingMessage(); updateSessionStatusText(); // 未连接时，只做本地清理 if (!eventSource) { addSystemMessage('已创建新会话（本地）'); logEvent('NEW_SESSION_LOCAL', {}); return; } try { const sessionId = await createServerSession(); if (!sessionId) { addSystemMessage('创建服务端会话失败'); return; } // 立即刷新会话列表，方便在右侧面板看到新会话 sessionListState.selectedSessionId = sessionId; await refreshSessionList(); setSessionControlsEnabled(true); } catch (error) { logEvent( 'NEW_SESSION_ERROR', {message: error?.message || String(error)}, true, ); addSystemMessage('新建会话失败'); } } // 创建服务端会话（返回 sessionId 或 null） async function createServerSession() { try { const response = await fetch(`${serverUrl}/session/create`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({}), }); const data = await response.json(); logEvent('SESSION_CREATE', data, !response.ok); const sessionId = data?.session?.id; if (sessionId) { currentSessionId = sessionId; updateSessionStatusText(); addSystemMessage(`已创建服务端会话: ${currentSessionId}`); return sessionId; } return null; } catch (error) { logEvent( 'SESSION_CREATE_ERROR', {message: error?.message || String(error)}, true, ); return null; } } // 加载会话（弃用的老入口，保留兼容） async function loadServerSession() { const sessionId = prompt('请输入要加载的会话ID:'); if (!sessionId) return; try { const response = await fetch(`${serverUrl}/session/load`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({sessionId}), }); const data = await response.json(); logEvent('SESSION_LOAD', data, !response.ok); if (data?.session?.id) { currentSessionId = data.session.id; addSystemMessage(`已加载服务端会话: ${currentSessionId}`); } } catch (error) { logEvent('SESSION_LOAD_ERROR', {message: error.message}, true); } } // 列出会话（弃用的老入口，保留兼容） async function listServerSessions() { const page = Number.parseInt(prompt('page (默认0):') || '0', 10) || 0; const pageSize = Number.parseInt(prompt('pageSize (默认20):') || '20', 10) || 20; const q = prompt('搜索关键词 q（可选）:') || ''; const params = new URLSearchParams(); params.set('page', String(Math.max(0, page))); params.set('pageSize', String(Math.max(1, pageSize))); if (q.trim()) params.set('q', q.trim()); try { const response = await fetch( `${serverUrl}/session/list?${params.toString()}`, { method: 'GET', }, ); const data = await response.json(); logEvent('SESSION_LIST', data, !response.ok); } catch (error) { logEvent('SESSION_LIST_ERROR', {message: error.message}, true); } } // 删除当前会话（弃用的老入口，保留兼容） async function deleteCurrentSession() { if (!currentSessionId) { addSystemMessage('当前没有可删除的会话'); return; } const confirmed = confirm(`确认删除会话 ${currentSessionId} ?`); if (!confirmed) return; try { const response = await fetch( `${serverUrl}/session/${encodeURIComponent(currentSessionId)}`, {method: 'DELETE'}, ); const data = await response.json(); logEvent('SESSION_DELETE', data, !response.ok); if (data?.deleted) { addSystemMessage(`已删除会话: ${currentSessionId}`); currentSessionId = null; } } catch (error) { logEvent('SESSION_DELETE_ERROR', {message: error.message}, true); } } // ---------------------------------------------------------------------------- // 上下文压缩 // ---------------------------------------------------------------------------- // 压缩当前会话的上下文 async function compressCurrentSession() { if (!currentSessionId) { addSystemMessage('没有活动的会话，无法压缩'); return; } try { addSystemMessage('正在压缩上下文...'); const response = await fetch(`${serverUrl}/context/compress`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({sessionId: currentSessionId}), }); const data = await response.json(); logEvent('CONTEXT_COMPRESS', data, !response.ok); if (!response.ok) { addSystemMessage(`压缩失败: ${data?.error || 'Unknown error'}`); return; } if (!data?.success) { if (data?.hookFailed) { addSystemMessage( `压缩被 Hook 阻止: exitCode=${data?.hookErrorDetails?.exitCode}`, ); } else { addSystemMessage(`压缩失败: ${data?.error || 'Unknown error'}`); } return; } if (data?.result === null) { addSystemMessage(data?.message || '无需压缩（没有历史可压缩）'); return; } const result = data.result; addSystemMessage( `压缩成功! 摘要长度: ${result?.summary?.length || 0} 字符, ` + `Token 使用: ${result?.usage?.total_tokens || 0}`, ); // 显示压缩摘要预览 if (result?.summary) { const preview = result.summary.length > 500 ? result.summary.slice(0, 500) + '...' : result.summary; addMessage('system', `[压缩摘要预览]\n${preview}`); } } catch (error) { addSystemMessage(`压缩失败: ${error.message}`); logEvent('CONTEXT_COMPRESS_ERROR', {message: error.message}, true); } } // 压缩自定义消息（用于测试） async function compressCustomMessages() { const messagesJson = await showCompressMessagesDialog(); if (!messagesJson) return; let messages; try { messages = JSON.parse(messagesJson); if (!Array.isArray(messages)) { addSystemMessage('消息必须是数组格式'); return; } } catch (e) { addSystemMessage(`JSON 解析失败: ${e.message}`); return; } try { addSystemMessage('正在压缩自定义消息...'); const response = await fetch(`${serverUrl}/context/compress`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({messages}), }); const data = await response.json(); logEvent('CONTEXT_COMPRESS_CUSTOM', data, !response.ok); if (!response.ok || !data?.success) { addSystemMessage(`压缩失败: ${data?.error || 'Unknown error'}`); return; } if (data?.result === null) { addSystemMessage(data?.message || '无需压缩'); return; } const result = data.result; addSystemMessage( `压缩成功! 摘要长度: ${result?.summary?.length || 0} 字符`, ); if (result?.summary) { addMessage('system', `[压缩摘要]\n${result.summary}`); } } catch (error) { addSystemMessage(`压缩失败: ${error.message}`); logEvent('CONTEXT_COMPRESS_ERROR', {message: error.message}, true); } } // 显示压缩消息输入对话框 function showCompressMessagesDialog() { return new Promise(resolve => { const modal = document.getElementById('userQuestionModal'); const title = document.getElementById('userQuestionTitle'); const body = document.getElementById('userQuestionBody'); const footer = document.getElementById('userQuestionFooter'); title.textContent = '压缩自定义消息'; const defaultMessages = JSON.stringify( [ {role: 'user', content: 'Hello, how are you?'}, {role: 'assistant', content: 'I am doing well, thank you for asking!'}, {role: 'user', content: 'Can you help me with coding?'}, { role: 'assistant', content: 'Of course! I would be happy to help you with coding.', }, ], null, 2, ); body.innerHTML = ` <div class="compress-dialog"> <p style="margin-bottom: 12px; color: #666; font-size: 13px;"> 输入要压缩的消息数组 (JSON 格式)，每条消息需包含 role 和 content 字段。 </p> <textarea id="compressMessagesInput" style="width: 100%; height: 280px; font-family: monospace; font-size: 12px; padding: 10px; border: 1px solid #444; border-radius: 4px; background: #1e1e1e; color: #d4d4d4; resize: vertical;" spellcheck="false" >${defaultMessages}</textarea> <div style="margin-top: 8px; font-size: 12px; color: #888;"> 提示: role 可以是 "user"、"assistant" 或 "system" </div> </div> `; footer.innerHTML = ''; const cancelBtn = document.createElement('button'); cancelBtn.className = 'btn-secondary'; cancelBtn.textContent = '取消'; cancelBtn.onclick = () => { modal.style.display = 'none'; resolve(null); }; footer.appendChild(cancelBtn); const confirmBtn = document.createElement('button'); confirmBtn.className = 'btn-primary'; confirmBtn.textContent = '压缩'; confirmBtn.onclick = () => { const input = document .getElementById('compressMessagesInput') .value.trim(); modal.style.display = 'none'; resolve(input || null); }; footer.appendChild(confirmBtn); modal.style.display = 'flex'; // 自动聚焦到输入框 setTimeout(() => { const textarea = document.getElementById('compressMessagesInput'); if (textarea) textarea.focus(); }, 100); }); } // 更新顶部状态文本 function updateSessionStatusText() { const statusEl = byId('status'); if (!eventSource) { statusEl.textContent = '未连接'; return; } if (currentSessionId) { statusEl.textContent = `已连接 (Session: ${currentSessionId.substring( 0, 8, )}...)`; } else { statusEl.textContent = '已连接'; } } // ---------------------------------------------------------------------------- // SSE 连接管理 // ---------------------------------------------------------------------------- // 更新连接状态（按钮启用/禁用） function updateStatus(connected) { const statusEl = document.getElementById('status'); statusEl.textContent = connected ? '已连接' : '未连接'; statusEl.className = `status ${connected ? 'connected' : 'disconnected'}`; document.getElementById('connectBtn').disabled = connected; document.getElementById('disconnectBtn').disabled = !connected; document.getElementById('sendBtn').disabled = !connected; document.getElementById('rollbackBtn').disabled = !connected; } // 连接到 SSE 服务器 function connect() { serverUrl = document.getElementById('serverUrl').value; eventSource = new EventSource(`${serverUrl}/events`); eventSource.onopen = () => { updateStatus(true); updateSessionStatusText(); addSystemMessage('已连接到 Snow AI'); logEvent('CONNECTED', {serverUrl}); // 启用会话列表面板 byId('refreshSessionsBtn').disabled = false; setSessionControlsEnabled(true); // 同步 UI 控件值 byId('sessionPageSize').value = String(sessionListState.pageSize); byId('sessionSearchInput').value = sessionListState.q; renderSessionList(); void refreshSessionList(); }; eventSource.onerror = error => { updateStatus(false); updateSessionStatusText(); addSystemMessage('连接错误'); logEvent('ERROR', {message: '连接失败'}, true); // 禁用会话列表面板 setSessionControlsEnabled(false); eventSource.close(); eventSource = null; }; eventSource.onmessage = event => { const data = JSON.parse(event.data); handleEvent(data); }; } // 断开连接 function disconnect() { if (eventSource) { eventSource.close(); eventSource = null; updateStatus(false); updateSessionStatusText(); addSystemMessage('已断开连接'); logEvent('DISCONNECTED', {}); } // 禁用会话列表面板 setSessionControlsEnabled(false); } // ---------------------------------------------------------------------------- // SSE 事件处理 // ---------------------------------------------------------------------------- // 处理从服务端推送的各类事件 function handleEvent(event) { logEvent(event.type, event.data); switch (event.type) { case 'connected': addSystemMessage(`连接ID: ${event.data.connectionId}`); break; case 'rollback_result': addSystemMessage( event.data?.success ? `回滚成功: messageIndex=${event.data?.messageIndex}，回滚文件数=${ event.data?.filesRolledBack ?? 0 }` : `回滚失败: ${event.data?.error || 'Unknown error'}`, ); // 回滚完成后允许继续操作 document.getElementById('rollbackBtn').disabled = false; // 回滚后自动刷新会话 UI if (event.data?.success && currentSessionId) { void refreshCurrentSession(); } break; case 'message': // 捕获 sessionId（首次收到 system 消息时） if (event.data.role === 'system' && event.data.sessionId) { currentSessionId = event.data.sessionId; addSystemMessage(`会话ID: ${currentSessionId}`); const statusEl = document.getElementById('status'); statusEl.textContent = `已连接 (Session: ${currentSessionId.substring( 0, 8, )}...)`; logEvent('SESSION_ID', {sessionId: currentSessionId}); break; } if (event.data.streaming) { // 流式消息 - 更新最后一条消息，但保持 loading const chatBox = document.getElementById('chatBox'); const messages = Array.from(chatBox.children); // 查找最后一个 assistant 消息（跳过 loading） let lastAssistantMsg = null; for (let i = messages.length - 1; i >= 0; i--) { if ( messages[i].classList.contains('assistant') && !messages[i].classList.contains('loading-message') ) { lastAssistantMsg = messages[i]; break; } } if (lastAssistantMsg) { // 更新已存在的助手消息 updateAssistantMessage(lastAssistantMsg, event.data.content); } else { // 创建新的助手消息（在 loading 之前插入） const loadingMsg = document.getElementById('aiLoadingMessage'); const newMessage = document.createElement('div'); newMessage.className = 'message assistant'; const htmlContent = marked.parse(event.data.content); newMessage.innerHTML = htmlContent; newMessage.querySelectorAll('pre code').forEach(block => { hljs.highlightElement(block); }); if (loadingMsg) { chatBox.insertBefore(newMessage, loadingMsg); } else { chatBox.appendChild(newMessage); } } chatBox.scrollTop = chatBox.scrollHeight; } else if (event.data.role === 'user') { // 用户消息：显示并立刻开始 loading addMessage('user', event.data.content); showLoadingMessage(); document.getElementById('abortBtn').disabled = false; } else if (event.data.role === 'assistant') { // 非流式 assistant 消息 const chatBox = document.getElementById('chatBox'); const loadingMsg = document.getElementById('aiLoadingMessage'); const newMessage = document.createElement('div'); newMessage.className = 'message assistant'; const htmlContent = marked.parse(event.data.content); newMessage.innerHTML = htmlContent; newMessage.querySelectorAll('pre code').forEach(block => { hljs.highlightElement(block); }); if (loadingMsg) { chatBox.insertBefore(newMessage, loadingMsg); } else { chatBox.appendChild(newMessage); } chatBox.scrollTop = chatBox.scrollHeight; } break; case 'tool_call': const toolName = event.data?.name || event.data?.function?.name || 'unknown'; addSystemMessage(`工具调用: ${toolName}`); break; case 'tool_result': // 工具结果不显示在聊天框 break; case 'tool_confirmation_request': handleToolConfirmation(event); break; case 'user_question_request': handleUserQuestion(event); break; case 'complete': // 对话完成 removeLoadingMessage(); addSystemMessage('对话完成'); if (event.data.sessionId) { currentSessionId = event.data.sessionId; logEvent('SESSION_SAVED', {sessionId: currentSessionId}); } document.getElementById('abortBtn').disabled = true; break; case 'error': // 错误 removeLoadingMessage(); addSystemMessage(`错误: ${event.data.message}`); document.getElementById('abortBtn').disabled = true; break; } } // 处理工具确认请求（弹出对话框） function handleToolConfirmation(event) { showToolConfirmationDialog(event, sendResponse); } // 处理用户问题请求（弹出对话框） function handleUserQuestion(event) { showUserQuestionDialog(event, sendResponse); } // ---------------------------------------------------------------------------- // 发送消息 // ---------------------------------------------------------------------------- // 发送用户消息到服务端 async function sendMessage() { const input = document.getElementById('messageInput'); const content = input.value.trim(); const hasImages = Array.isArray(selectedImages) && selectedImages.length > 0; if (!content && !hasImages) return; // 立即清空输入框 input.value = ''; const imagesForSend = Array.isArray(selectedImages) ? selectedImages.slice() : []; clearImagePreview(); try { const payload = { type: 'chat', content: content || (hasImages ? '查看图片' : ''), }; if (currentSessionId) { payload.sessionId = currentSessionId; } const yoloMode = document.getElementById('yoloModeCheckbox').checked; if (yoloMode) { payload.yoloMode = true; } if (hasImages) { const images = []; for (const dataUri of imagesForSend) { const base64Match = String(dataUri).match(/^data:([^;]+);base64,(.+)$/); if (!base64Match) continue; images.push({ data: dataUri, mimeType: base64Match[1], }); } if (images.length > 0) { payload.images = images; } } const response = await fetch(`${serverUrl}/message`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(payload), }); await response.json(); logEvent('MESSAGE_SENT', { content, imageCount: imagesForSend.length, yoloMode, }); } catch (error) { removeLoadingMessage(); addSystemMessage(`发送失败: ${error.message}`); logEvent('SEND_ERROR', {message: error.message}, true); } } // 终止当前任务 async function abortTask() { if (!currentSessionId) { addSystemMessage('没有活动的会话'); return; } try { const payload = { type: 'abort', sessionId: currentSessionId, }; const response = await fetch(`${serverUrl}/message`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(payload), }); await response.json(); logEvent('ABORT_SENT', {sessionId: currentSessionId}); // 移除 loading 并禁用终止按钮 removeLoadingMessage(); document.getElementById('abortBtn').disabled = true; document.getElementById('rollbackBtn').disabled = true; addSystemMessage('任务已终止'); } catch (error) { removeLoadingMessage(); addSystemMessage(`终止失败: ${error.message}`); logEvent('ABORT_ERROR', {message: error.message}, true); document.getElementById('abortBtn').disabled = true; document.getElementById('rollbackBtn').disabled = true; } } // ---------------------------------------------------------------------------- // 回滚 UI // ---------------------------------------------------------------------------- async function fetchRollbackPoints(sessionId) { const params = new URLSearchParams(); params.set('sessionId', sessionId); const response = await fetch( `${serverUrl}/session/rollback-points?${params.toString()}`, ); const data = await response.json(); logEvent('ROLLBACK_POINTS', data, !response.ok); if (!response.ok || !data?.success) { throw new Error(data?.error || '加载回滚点失败'); } return Array.isArray(data.points) ? data.points : []; } function buildRollbackPointsHtml(points) { if (!points || points.length === 0) { return '<div style="color:#666;font-size:13px;">该会话暂无可回滚点（没有 user 消息）。</div>'; } let html = ''; html += '<div class="rollback-list">'; points.forEach((p, idx) => { const messageIndex = typeof p?.messageIndex === 'number' ? p.messageIndex : -1; const summary = p?.summary ? String(p.summary) : ''; const timeText = formatTime(p?.timestamp); const hasSnapshot = !!p?.hasSnapshot; const filesToRollbackCount = typeof p?.filesToRollbackCount === 'number' ? p.filesToRollbackCount : 0; const snapLabel = hasSnapshot ? `有快照 · 可回滚文件: ${filesToRollbackCount}` : '无快照'; html += ` <div class="rollback-item" onclick="this.querySelector('input').click(); event.stopPropagation();"> <input type="radio" name="rollbackPoint" id="rb_${idx}" value="${escapeHtml( String(messageIndex), )}"> <label for="rb_${idx}"> <div class="rollback-row1"> <div class="rollback-title">messageIndex: ${escapeHtml( String(messageIndex), )}</div> <div class="rollback-time">${escapeHtml(timeText)}</div> </div> <div class="rollback-row2">${escapeHtml(summarizeText(summary))}</div> <div class="rollback-row3">${escapeHtml(snapLabel)}</div> </label> </div> `; }); html += '</div>'; html += ` <div class="checkbox-option" style="margin-top: 12px;"> <input type="checkbox" id="rollbackFilesCheckbox" checked /> <label for="rollbackFilesCheckbox">同时回滚文件快照（若所选点无快照，将跳过文件回滚）</label> </div> `; html += ` <div class="rollback-hint"> 提示：这里只列出 role=user 的消息索引（与服务端 session.messages 一致）。 </div> `; return html; } async function showRollbackDialogAndGetSelection(sessionId) { const modal = document.getElementById('userQuestionModal'); const title = document.getElementById('userQuestionTitle'); const body = document.getElementById('userQuestionBody'); const footer = document.getElementById('userQuestionFooter'); title.textContent = '选择回滚点'; body.innerHTML = '<div style="color:#666;font-size:13px;">加载中...</div>'; footer.innerHTML = ''; modal.style.display = 'flex'; let points = []; try { points = await fetchRollbackPoints(sessionId); } catch (err) { body.innerHTML = `<div style="color:#c82333;font-size:13px;">${escapeHtml( err?.message || String(err), )}</div>`; } body.innerHTML = buildRollbackPointsHtml(points); return await new Promise(resolve => { footer.innerHTML = ''; const cancelBtn = document.createElement('button'); cancelBtn.className = 'btn-secondary'; cancelBtn.textContent = '取消'; cancelBtn.onclick = () => { modal.style.display = 'none'; resolve({cancelled: true}); }; footer.appendChild(cancelBtn); const confirmBtn = document.createElement('button'); confirmBtn.className = 'btn-primary'; confirmBtn.textContent = '回滚'; confirmBtn.onclick = () => { const selected = document.querySelector( 'input[name="rollbackPoint"]:checked', ); if (!selected) { resolve({cancelled: true}); modal.style.display = 'none'; addSystemMessage('未选择回滚点'); return; } const messageIndex = Number.parseInt(selected.value, 10); const rollbackFiles = !!document.getElementById('rollbackFilesCheckbox') .checked; modal.style.display = 'none'; resolve({cancelled: false, messageIndex, rollbackFiles}); }; footer.appendChild(confirmBtn); // 点击单选项时高亮（复用现有 selected 样式） document.querySelectorAll('.rollback-item').forEach(item => { item.addEventListener('click', function () { document .querySelectorAll('.rollback-item') .forEach(i => i.classList.remove('selected')); this.classList.add('selected'); }); }); }); } // 回滚当前会话（弹窗选择回滚点） async function rollbackSession() { if (!currentSessionId) { addSystemMessage('没有活动的会话'); return; } let selection; try { selection = await showRollbackDialogAndGetSelection(currentSessionId); } catch (error) { addSystemMessage(`打开回滚弹窗失败: ${error.message}`); logEvent('ROLLBACK_DIALOG_ERROR', {message: error.message}, true); return; } if (!selection || selection.cancelled) return; const {messageIndex, rollbackFiles} = selection; if (!Number.isFinite(messageIndex) || messageIndex < 0) { addSystemMessage('messageIndex 非法'); return; } try { document.getElementById('rollbackBtn').disabled = true; const payload = { type: 'rollback', sessionId: currentSessionId, rollback: { messageIndex, rollbackFiles, }, }; const response = await fetch(`${serverUrl}/message`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(payload), }); const data = await response.json(); logEvent('ROLLBACK_SENT', { sessionId: currentSessionId, messageIndex, rollbackFiles, }); if (!response.ok || !data?.success) { addSystemMessage('回滚请求发送失败'); return; } addSystemMessage('已发送回滚请求，等待 SSE 返回 rollback_result 事件'); } catch (error) { addSystemMessage(`回滚失败: ${error.message}`); logEvent('ROLLBACK_ERROR', {message: error.message}, true); } finally { document.getElementById('rollbackBtn').disabled = false; } } // 发送响应（工具确认/用户问题的回复） async function sendResponse(type, requestId, response) { try { const res = await fetch(`${serverUrl}/message`, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ type: type, requestId: requestId, response: response, }), }); const data = await res.json(); logEvent('RESPONSE_SENT', {type, requestId}); } catch (error) { logEvent('SEND_ERROR', {message: error.message}, true); } } // ---------------------------------------------------------------------------- // 图片处理 // ---------------------------------------------------------------------------- // 处理用户选择的图片 function handleImageSelect(filesOrFile) { const files = Array.isArray(filesOrFile) ? filesOrFile : filesOrFile ? [filesOrFile] : []; if (!files.length) return; for (const file of files) { if (!file || !file.type || !String(file.type).startsWith('image/')) { addSystemMessage('请选择图片文件'); continue; } const reader = new FileReader(); reader.onload = e => { const dataUri = e.target.result; if (typeof dataUri === 'string') { selectedImages.push(dataUri); showImagePreview(selectedImages); } }; reader.readAsDataURL(file); } } // 显示图片预览 function showImagePreview(images) { const preview = document.getElementById('imagePreview'); const imgs = Array.isArray(images) ? images : images ? [images] : []; preview.className = imgs.length > 0 ? 'image-preview active' : 'image-preview'; if (imgs.length === 0) { preview.innerHTML = ''; return; } preview.innerHTML = ` <div class="image-preview-toolbar"> <div>已选择 ${imgs.length} 张</div> <button class="remove-image" onclick="clearImagePreview()">清空</button> </div> <div class="image-preview-grid"> ${imgs .map( (src, idx) => ` <div class="image-preview-item"> <img src="${src}" alt="预览图片 ${idx + 1}" /> <button class="remove-image" onclick="removeSelectedImage(${idx})">移除</button> </div> `, ) .join('')} </div> `; } // 清除图片预览 function removeSelectedImage(index) { if (!Array.isArray(selectedImages)) selectedImages = []; selectedImages.splice(index, 1); showImagePreview(selectedImages); // 只有在清空后才重置 input，避免用户连续追加选择时丢失状态 if (selectedImages.length === 0) { document.getElementById('imageInput').value = ''; } } function clearImagePreview() { const preview = document.getElementById('imagePreview'); preview.className = 'image-preview'; preview.innerHTML = ''; selectedImages = []; document.getElementById('imageInput').value = ''; } // ---------------------------------------------------------------------------- // 页面初始化 // ---------------------------------------------------------------------------- window.addEventListener('load', () => { updateStatus(false); // 图片上传事件（支持多选） const imageInput = document.getElementById('imageInput'); imageInput.addEventListener('change', e => { const files = Array.from(e.target.files || []); if (files.length > 0) { handleImageSelect(files); } }); // 粘贴图片支持（支持多张） const messageInput = document.getElementById('messageInput'); messageInput.addEventListener('paste', e => { const items = Array.from(e.clipboardData?.items || []); const imageFiles = []; for (const item of items) { if (String(item.type || '').indexOf('image') !== -1) { const file = item.getAsFile(); if (file) imageFiles.push(file); } } if (imageFiles.length > 0) { handleImageSelect(imageFiles); e.preventDefault(); } }); }); ================================================ FILE: source/test/sse-client/dialogs.js ================================================ // 工具确认对话框 function showToolConfirmationDialog(event, sendResponse) { const modal = document.getElementById('toolConfirmationModal'); const body = document.getElementById('toolConfirmationBody'); const footer = document.getElementById('toolConfirmationFooter'); const { toolCall, batchToolNames, isSensitive, sensitiveInfo, availableOptions, } = event.data; let html = ''; // 敏感警告 if (isSensitive && sensitiveInfo) { html += ` <div class="sensitive-warning"> <h4>敏感命令警告</h4> <p><strong>模式:</strong> ${sensitiveInfo.pattern}</p> <p><strong>说明:</strong> ${sensitiveInfo.description}</p> </div> `; } // 工具信息 html += '<div class="tool-info">'; html += `<div class="tool-info-item">`; html += `<div class="tool-info-label">工具名称</div>`; html += `<div class="tool-info-value">${toolCall.function.name}</div>`; html += `</div>`; // 参数 if (toolCall.function.arguments) { html += `<div class="tool-info-item">`; html += `<div class="tool-info-label">参数</div>`; html += `<div class="tool-args">${JSON.stringify( JSON.parse(toolCall.function.arguments), null, 2, )}</div>`; html += `</div>`; } // 批量工具 if (batchToolNames) { html += `<div class="tool-info-item">`; html += `<div class="tool-info-label">批量工具</div>`; html += `<div class="tool-info-value">${batchToolNames}</div>`; html += `</div>`; } html += '</div>'; body.innerHTML = html; // 创建按钮 footer.innerHTML = ''; availableOptions.forEach(option => { const btn = document.createElement('button'); btn.className = option.value === 'approve' ? 'btn-success' : option.value === 'approve_always' ? 'btn-primary' : option.value === 'reject' ? 'btn-danger' : 'btn-secondary'; btn.textContent = option.label; btn.onclick = async () => { modal.style.display = 'none'; if (option.value === 'reject_with_reply') { // 显示输入框 const replyText = prompt('请输入拒绝理由:'); if (replyText) { await sendResponse('tool_confirmation_response', event.requestId, { rejectWithReply: replyText, }); } else { await sendResponse( 'tool_confirmation_response', event.requestId, 'reject', ); } } else { await sendResponse( 'tool_confirmation_response', event.requestId, option.value, ); } }; footer.appendChild(btn); }); modal.style.display = 'flex'; } // 用户问题对话框 function showUserQuestionDialog(event, sendResponse) { const modal = document.getElementById('userQuestionModal'); const title = document.getElementById('userQuestionTitle'); const body = document.getElementById('userQuestionBody'); const footer = document.getElementById('userQuestionFooter'); const {question, options, multiSelect} = event.data; title.textContent = question; let html = ''; // 选项列表 if (options && options.length > 0) { html += '<div class="question-options">'; options.forEach((option, index) => { const inputType = multiSelect ? 'checkbox' : 'radio'; const inputId = `option_${index}`; html += ` <div class="option-item" onclick="this.querySelector('input').click(); event.stopPropagation();"> <input type="${inputType}" name="userOption" id="${inputId}" value="${option}"> <label for="${inputId}">${option}</label> </div> `; }); html += '</div>'; } // 自定义输入 html += ` <div class="custom-input-section"> <label for="customInput">或输入自定义内容:</label> <textarea id="customInput" placeholder="在此输入自定义内容..."></textarea> </div> `; body.innerHTML = html; // 按钮 footer.innerHTML = ''; const cancelBtn = document.createElement('button'); cancelBtn.className = 'btn-secondary'; cancelBtn.textContent = '取消'; cancelBtn.onclick = async () => { modal.style.display = 'none'; await sendResponse('user_question_response', event.requestId, { selected: '', cancelled: true, }); }; footer.appendChild(cancelBtn); const confirmBtn = document.createElement('button'); confirmBtn.className = 'btn-primary'; confirmBtn.textContent = '确定'; confirmBtn.onclick = async () => { modal.style.display = 'none'; const customInput = document.getElementById('customInput').value.trim(); if (customInput) { // 有自定义输入 await sendResponse('user_question_response', event.requestId, { selected: multiSelect ? [customInput] : customInput, customInput, }); } else { // 使用选项 if (multiSelect) { const selected = Array.from( document.querySelectorAll('input[name="userOption"]:checked'), ).map(input => input.value); await sendResponse('user_question_response', event.requestId, { selected: selected.length > 0 ? selected : '', }); } else { const selectedInput = document.querySelector( 'input[name="userOption"]:checked', ); await sendResponse('user_question_response', event.requestId, { selected: selectedInput ? selectedInput.value : '', }); } } }; footer.appendChild(confirmBtn); modal.style.display = 'flex'; // 点击选项时高亮 document.querySelectorAll('.option-item').forEach(item => { item.addEventListener('click', function () { const input = this.querySelector('input'); if (input.type === 'radio') { document .querySelectorAll('.option-item') .forEach(i => i.classList.remove('selected')); } if (input.checked) { this.classList.add('selected'); } else { this.classList.remove('selected'); } }); }); } ================================================ FILE: source/test/sse-client/index.html ================================================ <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Snow AI SSE 客户端测试

Snow AI SSE 客户端测试

未连接
聊天界面
连接配置
会话列表
未加载
事件日志 0
================================================ FILE: source/test/sse-client/json-viewer.js ================================================ // ============================================================================ // JSON Viewer - 基于 highlight.js 的 JSON 高亮显示器 // ============================================================================ /** * JSON 高亮显示器 * 使用 highlight.js 进行语法高亮，支持缩进和折叠 */ const JsonViewer = { /** * 将 JSON 数据渲染为高亮 HTML * @param {any} data - JSON 数据（对象、数组或字符串） * @param {object} options - 配置选项 * @param {number} options.indent - 缩进空格数，默认 2 * @param {boolean} options.highlight - 是否启用高亮，默认 true * @returns {string} 渲染后的 HTML 字符串 */ render(data, options = {}) { const {indent = 2, highlight = true} = options; let jsonString = ''; if (typeof data === 'string') { try { // 尝试解析并重新格式化 const parsed = JSON.parse(data); jsonString = JSON.stringify(parsed, null, indent); } catch (e) { // 解析失败，直接使用原字符串 jsonString = data; } } else { jsonString = JSON.stringify(data, null, indent); } if (!highlight || typeof hljs === 'undefined') { return `
${this.escapeHtml(
				jsonString,
			)}
`; } // 使用 highlight.js 进行高亮 const highlighted = hljs.highlight(jsonString, {language: 'json'}); return `
${highlighted.value}
`; }, /** * 将 JSON 数据渲染到指定容器 * @param {HTMLElement|string} container - 容器元素或选择器 * @param {any} data - JSON 数据 * @param {object} options - 配置选项 */ renderTo(container, data, options = {}) { const el = typeof container === 'string' ? document.querySelector(container) : container; if (!el) { console.error('JsonViewer: 容器元素不存在'); return; } el.innerHTML = this.render(data, options); }, /** * 创建可折叠的 JSON 树视图 * @param {any} data - JSON 数据 * @param {object} options - 配置选项 * @param {number} options.maxDepth - 默认展开深度，默认 2 * @returns {string} 渲染后的 HTML 字符串 */ renderTree(data, options = {}) { const {maxDepth = 2} = options; let jsonData = data; if (typeof data === 'string') { try { jsonData = JSON.parse(data); } catch (e) { return `
${this.escapeHtml(
					data,
				)}
`; } } return `
${this._buildTree( jsonData, 0, maxDepth, )}
`; }, /** * 递归构建 JSON 树 * @private */ _buildTree(data, depth, maxDepth) { if (data === null) { return 'null'; } if (typeof data === 'boolean') { return `${data}`; } if (typeof data === 'number') { return `${data}`; } if (typeof data === 'string') { const escaped = this.escapeHtml(data); // 长字符串截断显示 if (data.length > 100) { const preview = this.escapeHtml(data.slice(0, 100)); return `"${preview}..."`; } return `"${escaped}"`; } if (Array.isArray(data)) { if (data.length === 0) { return '[]'; } const collapsed = depth >= maxDepth; const id = this._generateId(); let html = ``; html += '['; html += `${data.length} items`; html += `
`; data.forEach((item, index) => { html += '
'; html += `${index}: `; html += this._buildTree(item, depth + 1, maxDepth); if (index < data.length - 1) html += ','; html += '
'; }); html += '
'; html += ']'; return html; } if (typeof data === 'object') { const keys = Object.keys(data); if (keys.length === 0) { return '{}'; } const collapsed = depth >= maxDepth; const id = this._generateId(); let html = ``; html += '{'; html += `${keys.length} keys`; html += `
`; keys.forEach((key, index) => { html += '
'; html += `"${this.escapeHtml(key)}"`; html += ': '; html += this._buildTree(data[key], depth + 1, maxDepth); if (index < keys.length - 1) html += ','; html += '
'; }); html += '
'; html += '}'; return html; } return `${this.escapeHtml(String(data))}`; }, /** * 切换折叠状态 * @param {string} id - 内容元素 ID */ toggle(id) { const content = document.getElementById(id); if (!content) return; // 向前查找 json-toggle 元素（跳过 json-size 和 json-bracket） let toggle = content.previousElementSibling; while (toggle && !toggle.classList.contains('json-toggle')) { toggle = toggle.previousElementSibling; } if (!toggle) return; if (content.style.display === 'none') { content.style.display = 'block'; toggle.textContent = '-'; toggle.classList.remove('collapsed'); } else { content.style.display = 'none'; toggle.textContent = '+'; toggle.classList.add('collapsed'); } }, /** * 展开所有节点 * @param {HTMLElement|string} container - 容器元素或选择器 */ expandAll(container) { const el = typeof container === 'string' ? document.querySelector(container) : container; if (!el) return; el.querySelectorAll('.json-content').forEach(content => { content.style.display = 'block'; }); el.querySelectorAll('.json-toggle').forEach(toggle => { toggle.textContent = '-'; toggle.classList.remove('collapsed'); }); }, /** * 折叠所有节点 * @param {HTMLElement|string} container - 容器元素或选择器 */ collapseAll(container) { const el = typeof container === 'string' ? document.querySelector(container) : container; if (!el) return; el.querySelectorAll('.json-content').forEach(content => { content.style.display = 'none'; }); el.querySelectorAll('.json-toggle').forEach(toggle => { toggle.textContent = '+'; toggle.classList.add('collapsed'); }); }, /** * 生成唯一 ID * @private */ _idCounter: 0, _generateId() { return `json_node_${++this._idCounter}`; }, /** * HTML 转义 * @param {string} str - 原始字符串 * @returns {string} 转义后的字符串 */ escapeHtml(str) { return String(str) .replace(/&/g, '&') .replace(//g, '>') .replace(/"/g, '"') .replace(/'/g, '''); }, }; // 导出到全局 window.JsonViewer = JsonViewer; // 使用事件委托处理折叠点击 document.addEventListener('click', function (e) { const toggle = e.target.closest('.json-toggle'); if (!toggle) return; const targetId = toggle.getAttribute('data-target'); if (targetId) { e.preventDefault(); e.stopPropagation(); JsonViewer.toggle(targetId); } }); ================================================ FILE: source/test/sse-client/style.css ================================================ * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background: #f5f5f5; height: 100vh; padding: 12px; overflow: hidden; } .container { max-width: 1400px; margin: 0 auto; background: white; border: 1px solid #ddd; border-radius: 4px; height: 100%; display: flex; flex-direction: column; } .header { background: #000; color: white; padding: 12px 20px; border-bottom: 1px solid #333; flex-shrink: 0; } .header h1 { font-size: 18px; font-weight: 600; display: inline-block; margin-right: 16px; } .status { display: inline-block; padding: 4px 10px; border: 1px solid #555; background: #222; font-size: 12px; } .status.connected { background: #000; border-color: #666; color: #0f0; } .status.disconnected { background: #000; border-color: #666; color: #f00; } .content { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; padding: 12px; flex: 1; min-height: 0; } .left-column { display: flex; flex-direction: column; gap: 12px; min-height: 0; min-width: 0; overflow: hidden; } .left-column .panel:first-child { flex: 1; min-height: 0; } .left-column .panel:last-child { flex-shrink: 0; } .right-column { display: flex; flex-direction: column; gap: 12px; min-height: 0; min-width: 0; overflow: hidden; } .right-column .panel { min-height: 0; } .sessions-panel { flex: 0 0 46%; } .right-column .panel:last-child { flex: 1; } .panel { border: 1px solid #ddd; border-radius: 3px; display: flex; flex-direction: column; min-height: 0; } .panel-header { background: #f8f8f8; padding: 8px 12px; border-bottom: 1px solid #ddd; font-weight: 600; font-size: 13px; color: #333; flex-shrink: 0; display: flex; justify-content: space-between; align-items: center; } .header-btn { padding: 4px 10px; background: #000; color: white; border: none; border-radius: 3px; cursor: pointer; font-size: 12px; font-weight: 500; min-width: 24px; } .header-btn:hover { background: #333; } .event-count-badge { display: inline-block; background: #444; color: #fff; font-size: 11px; padding: 1px 6px; border-radius: 10px; margin-left: 4px; font-weight: normal; min-width: 18px; text-align: center; } .panel-body { padding: 12px; display: flex; flex-direction: column; flex: 1; min-height: 0; } .chat-box { flex: 1; overflow-y: auto; overflow-x: hidden; border: 1px solid #ddd; border-radius: 3px; padding: 10px; background: #fafafa; margin-bottom: 10px; min-height: 0; min-width: 0; } .message { margin-bottom: 10px; padding: 6px 10px; border-radius: 3px; max-width: 85%; word-wrap: break-word; font-size: 13px; line-height: 1.4; overflow-wrap: break-word; min-width: 0; } .message.user { background: #000; color: white; margin-left: auto; } .message.assistant { background: white; border: 1px solid #ddd; color: #333; overflow-x: auto; word-break: break-word; } .message.assistant p { margin: 0 0 8px 0; color: inherit; } .message.assistant p:last-child { margin-bottom: 0; } .message.assistant h1, .message.assistant h2, .message.assistant h3, .message.assistant h4, .message.assistant h5, .message.assistant h6 { margin: 12px 0 8px 0; font-weight: 600; color: inherit; } .message.assistant h1:first-child, .message.assistant h2:first-child, .message.assistant h3:first-child, .message.assistant h4:first-child, .message.assistant h5:first-child, .message.assistant h6:first-child { margin-top: 0; } .message.assistant ul, .message.assistant ol { margin: 8px 0; padding-left: 24px; color: inherit; } .message.assistant li { margin: 4px 0; color: inherit; } .message.assistant pre { background: #1e1e1e; border: 1px solid #333; border-radius: 4px; padding: 12px; overflow-x: auto; margin: 8px 0; max-width: 100%; } .message.assistant code { font-family: 'Monaco', 'Courier New', monospace; font-size: 12px; } .message.assistant pre code { background: transparent; padding: 0; border: none; } .message.assistant :not(pre) > code { background: #f5f5f5; border: 1px solid #ddd; padding: 2px 6px; border-radius: 3px; color: #d63384; } .message.assistant blockquote { border-left: 3px solid #ddd; padding-left: 12px; margin: 8px 0; color: #666; } .message.assistant table { border-collapse: collapse; margin: 8px 0; width: auto; max-width: 100%; display: block; overflow-x: auto; } .message.assistant table th, .message.assistant table td { border: 1px solid #ddd; padding: 6px 12px; text-align: left; color: inherit; } .message.assistant table th { background: #f5f5f5; font-weight: 600; } .message.assistant a { color: #0066cc; text-decoration: none; } .message.assistant a:hover { text-decoration: underline; } .message.system { background: #f0f0f0; border: 1px solid #ccc; font-size: 12px; text-align: center; margin: 8px auto; color: #666; } .input-group { display: flex; gap: 8px; flex-shrink: 0; } .image-preview { display: none; padding: 8px; background: #f8f8f8; border: 1px solid #ddd; border-radius: 3px; margin-bottom: 8px; position: relative; } .image-preview.active { display: block; } .image-preview img { max-width: 200px; max-height: 150px; border-radius: 3px; border: 1px solid #ddd; } .image-preview .remove-image { position: absolute; top: 12px; right: 12px; background: #000; color: white; border: none; border-radius: 3px; padding: 4px 8px; cursor: pointer; font-size: 12px; } .image-preview .remove-image:hover { background: #333; } .message img { max-width: 100%; border-radius: 3px; margin-top: 6px; border: 1px solid #ddd; } input[type='text'] { flex: 1; padding: 6px 10px; border: 1px solid #ddd; border-radius: 3px; font-size: 13px; background: white; } input[type='text']:focus { outline: none; border-color: #666; } button { padding: 6px 16px; background: #000; color: white; border: none; border-radius: 3px; cursor: pointer; font-weight: 500; font-size: 13px; transition: background 0.2s; } button:hover { background: #333; } button:disabled { background: #ccc; cursor: not-allowed; color: #888; } .event-log { flex: 1; overflow-y: auto; background: #1a1a1a; color: #e0e0e0; padding: 0; font-family: 'Monaco', 'Courier New', monospace; font-size: 11px; line-height: 1.5; min-height: 0; border-radius: 3px; } /* 可展开事件项 */ .event-item { border-bottom: 1px solid #333; } .event-item:last-child { border-bottom: none; } .event-header { display: flex; align-items: center; padding: 6px 10px; cursor: pointer; transition: background 0.15s; } .event-header:hover { background: #2a2a2a; } .event-expand { width: 14px; color: #888; font-weight: bold; flex-shrink: 0; font-family: monospace; } .event-timestamp { color: #666; margin-right: 8px; flex-shrink: 0; } .event-type { font-weight: 600; margin-right: 10px; flex-shrink: 0; color: #8f8; } .event-item.error .event-type { color: #f88; } .event-preview { color: #aaa; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex: 1; min-width: 0; } .event-maximize { color: #666; margin-left: 8px; cursor: pointer; flex-shrink: 0; font-family: monospace; font-weight: bold; padding: 0 4px; border-radius: 2px; transition: color 0.15s, background 0.15s; } .event-maximize:hover { color: #fff; background: #444; } .log-detail-container { max-height: 70vh; overflow: auto; } .log-detail-info { margin-bottom: 8px; font-size: 13px; color: #ccc; } .log-detail-label { color: #888; margin-right: 6px; } .log-detail-content { background: #0d0d0d; border: 1px solid #333; border-radius: 4px; padding: 12px; margin-top: 12px; max-height: 50vh; overflow: auto; } .log-detail-content pre { margin: 0; white-space: pre-wrap; word-break: break-all; color: #d4d4d4; font-size: 12px; line-height: 1.5; font-family: 'Consolas', 'Monaco', monospace; } /* JSON Viewer 样式 */ .json-viewer { margin: 0; padding: 12px; background: #0d0d0d; border-radius: 4px; overflow: auto; } .json-viewer code { font-family: 'Consolas', 'Monaco', monospace; font-size: 12px; line-height: 1.5; } .json-tree { font-family: 'Consolas', 'Monaco', monospace; font-size: 12px; line-height: 1.6; color: #d4d4d4; } .json-toggle { display: inline-block; width: 16px; height: 16px; line-height: 16px; text-align: center; cursor: pointer; color: #888; font-weight: bold; margin-right: 4px; border-radius: 2px; user-select: none; background: #333; border: 1px solid #555; position: relative; z-index: 1; } .json-toggle:hover { background: #444; color: #fff; } .json-bracket { color: #888; } .json-key { color: #9cdcfe; } .json-colon { color: #888; } .json-comma { color: #888; } .json-string { color: #ce9178; } .json-number { color: #b5cea8; } .json-boolean { color: #569cd6; } .json-null { color: #569cd6; } .json-size { color: #666; font-size: 11px; margin-left: 6px; } .json-index { color: #666; } .json-content { padding-left: 20px; border-left: 1px solid #333; margin-left: 6px; } .json-item { margin: 2px 0; } .event-details { background: #0d0d0d; border-top: 1px solid #333; padding: 10px 12px 10px 24px; overflow-x: auto; } .event-details pre { margin: 0; white-space: pre-wrap; word-break: break-all; color: #ccc; font-size: 11px; line-height: 1.4; } /* 旧样式保留兼容 */ .event { margin-bottom: 6px; padding: 2px 0; } .event .timestamp { color: #888; margin-right: 6px; } .event .type { color: #aaa; font-weight: 600; margin-right: 6px; } .event.error .type { color: #f88; } .event.success .type { color: #8f8; } .sessions-toolbar { display: flex; gap: 8px; align-items: center; margin-bottom: 8px; } .sessions-toolbar input[type='text'] { flex: 1; padding: 6px 10px; border: 1px solid #ddd; border-radius: 3px; font-size: 12px; background: white; } .sessions-toolbar select { padding: 6px 8px; border: 1px solid #ddd; border-radius: 3px; background: white; font-size: 12px; } .sessions-meta { font-size: 12px; color: #555; margin-bottom: 8px; } .sessions-list { flex: 1; min-height: 0; overflow-y: auto; border: 1px solid #ddd; border-radius: 3px; background: #fafafa; } .session-item { padding: 8px 10px; border-bottom: 1px solid #eee; cursor: pointer; } .session-item:hover { background: #f0f0f0; } .session-item.selected { background: #e8e8e8; border-left: 3px solid #000; } .session-item .row1 { display: flex; justify-content: space-between; gap: 8px; } .session-item .title { font-size: 12px; font-weight: 600; color: #222; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .session-item .time { font-size: 11px; color: #666; flex-shrink: 0; } .session-item .row2 { margin-top: 4px; font-size: 11px; color: #666; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .session-item .row3 { margin-top: 4px; font-size: 11px; color: #888; font-family: 'Monaco', 'Courier New', monospace; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .sessions-actions { display: flex; gap: 8px; margin-top: 8px; } .sessions-actions button { flex: 1; } .sessions-pagination { display: flex; gap: 8px; margin-top: 8px; } .sessions-pagination button { flex: 1; } .sessions-panel .panel-body { gap: 0; } .config-section { margin-bottom: 10px; } .config-section:last-child { margin-bottom: 0; } .config-section label { display: block; margin-bottom: 6px; font-weight: 600; font-size: 13px; color: #333; } .full-width { grid-column: 1 / -1; } .modal-overlay { position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0, 0, 0, 0.7); display: flex; align-items: center; justify-content: center; z-index: 1000; } .modal-dialog { background: white; border: 1px solid #333; border-radius: 4px; max-width: 700px; width: 90%; max-height: 80vh; display: flex; flex-direction: column; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3); } .modal-header { padding: 16px 20px; border-bottom: 1px solid #ddd; background: #f8f8f8; } .modal-header h3 { margin: 0; font-size: 16px; font-weight: 600; color: #333; } .modal-body { padding: 20px; overflow-y: auto; flex: 1; min-height: 0; } .modal-footer { padding: 12px 20px; border-top: 1px solid #ddd; background: #f8f8f8; display: flex; gap: 8px; justify-content: flex-end; } .modal-footer button { min-width: 80px; } .tool-info { background: #f5f5f5; padding: 12px; border: 1px solid #ddd; border-radius: 3px; margin-bottom: 16px; } .tool-info-item { margin-bottom: 8px; } .tool-info-item:last-child { margin-bottom: 0; } .tool-info-label { font-weight: 600; color: #555; font-size: 12px; margin-bottom: 4px; } .tool-info-value { font-family: 'Monaco', 'Courier New', monospace; font-size: 12px; color: #333; background: white; padding: 6px 8px; border: 1px solid #ddd; border-radius: 3px; overflow-x: auto; white-space: pre-wrap; word-break: break-all; } .tool-args { font-family: 'Monaco', 'Courier New', monospace; font-size: 11px; background: #1a1a1a; color: #e0e0e0; padding: 12px; max-height: 200px; overflow-y: auto; border: 1px solid #333; border-radius: 3px; white-space: pre-wrap; } .sensitive-warning { background: #fff3cd; border: 2px solid #856404; padding: 12px; border-radius: 3px; margin-bottom: 16px; } .sensitive-warning h4 { color: #856404; margin: 0 0 8px 0; font-size: 14px; font-weight: 600; } .sensitive-warning p { margin: 4px 0; color: #333; font-size: 13px; } .question-options { margin: 16px 0; } .option-item { display: flex; align-items: center; padding: 10px 12px; border: 1px solid #ddd; border-radius: 3px; margin-bottom: 8px; cursor: pointer; transition: all 0.2s; background: white; } .option-item:hover { border-color: #666; background: #f8f8f8; } .option-item.selected { border-color: #000; background: #f0f0f0; } .option-item input[type='checkbox'], .option-item input[type='radio'] { margin-right: 10px; cursor: pointer; } .option-item label { flex: 1; cursor: pointer; margin: 0; font-size: 13px; color: #333; } .rollback-list { margin: 10px 0; } .rollback-item { display: flex; align-items: flex-start; padding: 10px 12px; border: 1px solid #ddd; border-radius: 3px; margin-bottom: 8px; cursor: pointer; transition: all 0.2s; background: white; } .rollback-item:hover { border-color: #666; background: #f8f8f8; } .rollback-item.selected { border-color: #000; background: #f0f0f0; } .rollback-item input[type='radio'] { margin-right: 10px; margin-top: 3px; cursor: pointer; flex-shrink: 0; } .rollback-item label { flex: 1; cursor: pointer; margin: 0; font-size: 13px; color: #333; } .rollback-row1 { display: flex; justify-content: space-between; gap: 8px; align-items: baseline; } .rollback-title { font-weight: 600; color: #222; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 70%; } .rollback-time { font-size: 11px; color: #666; flex-shrink: 0; } .rollback-row2 { margin-top: 4px; font-size: 12px; color: #555; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .rollback-row3 { margin-top: 4px; font-size: 11px; color: #888; font-family: 'Monaco', 'Courier New', monospace; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .rollback-hint { margin-top: 10px; font-size: 12px; color: #666; } .custom-input-section { margin-top: 16px; padding-top: 16px; border-top: 1px solid #ddd; } .custom-input-section label { display: block; font-weight: 600; font-size: 13px; color: #333; margin-bottom: 8px; } .custom-input-section input[type='text'], .custom-input-section textarea { width: 100%; padding: 8px 10px; border: 1px solid #ddd; border-radius: 3px; font-size: 13px; font-family: inherit; } .custom-input-section textarea { min-height: 60px; resize: vertical; } .btn-primary { background: #000; color: white; } .btn-primary:hover { background: #333; } .btn-secondary { background: #666; color: white; } .btn-secondary:hover { background: #888; } .btn-danger { background: #dc3545; color: white; } .btn-danger:hover { background: #c82333; } .btn-success { background: #28a745; color: white; } .btn-success:hover { background: #218838; } .checkbox-option { display: flex; align-items: center; gap: 8px; padding: 8px 0; } .checkbox-option input[type='checkbox'] { width: 16px; height: 16px; cursor: pointer; } .checkbox-option label { cursor: pointer; font-weight: normal; margin: 0; font-size: 13px; } .loading-message { opacity: 0.7; min-width: 60px; display: flex; align-items: center; justify-content: center; padding: 10px 16px; } .loading-dots { display: inline-flex; gap: 4px; align-items: center; } .loading-dots span { display: inline-block; width: 8px; height: 8px; background: #666; border-radius: 50%; animation: loadingDot 1.4s infinite; animation-fill-mode: both; } .loading-dots span:nth-child(1) { animation-delay: 0s; } .loading-dots span:nth-child(2) { animation-delay: 0.2s; } .loading-dots span:nth-child(3) { animation-delay: 0.4s; } @keyframes loadingDot { 0%, 80%, 100% { opacity: 0.3; transform: scale(0.8); } 40% { opacity: 1; transform: scale(1.1); } } ================================================ FILE: source/types/index.ts ================================================ export interface SnowConfig { model?: string; apiKey?: string; maxTokens?: number; } export interface Command { name: string; description: string; handler: (args: string[]) => Promise; } export interface AppState { isLoading: boolean; currentCommand?: string; history: string[]; } ================================================ FILE: source/ui/components/bash/BackgroundProcessPanel.tsx ================================================ import React, {useMemo, useCallback} from 'react'; import {Box, Text} from 'ink'; import {useI18n} from '../../../i18n/I18nContext.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {BackgroundProcess} from '../../../hooks/execution/useBackgroundProcesses.js'; interface BackgroundProcessPanelProps { processes: BackgroundProcess[]; selectedIndex: number; terminalWidth: number; } /** * Truncate command text to prevent overflow */ function truncateCommand(text: string, maxWidth: number): string { if (text.length <= maxWidth) { return text; } const ellipsis = '...'; const halfWidth = Math.floor((maxWidth - ellipsis.length) / 2); return text.slice(0, halfWidth) + ellipsis + text.slice(-halfWidth); } /** * Format duration from start to now or end */ function formatDuration(start: Date, end?: Date): string { const endTime = end || new Date(); const seconds = Math.floor((endTime.getTime() - start.getTime()) / 1000); if (seconds < 60) { return `${seconds}s`; } const minutes = Math.floor(seconds / 60); const remainingSeconds = seconds % 60; return `${minutes}m ${remainingSeconds}s`; } export const BackgroundProcessPanel = React.memo(function BackgroundProcessPanel({ processes, selectedIndex, terminalWidth, }: BackgroundProcessPanelProps) { const {t} = useI18n(); const {theme} = useTheme(); // Only show running processes first, then completed/failed const sortedProcesses = useMemo(() => { return [...processes].sort((a, b) => { if (a.status === 'running' && b.status !== 'running') return -1; if (a.status !== 'running' && b.status === 'running') return 1; return b.startedAt.getTime() - a.startedAt.getTime(); }); }, [processes]); // Calculate max command width const maxCommandWidth = Math.max(30, terminalWidth - 35); // Max visible items in scrollable list const maxVisibleItems = 5; const totalItems = sortedProcesses.length; // Calculate scroll offset based on selected index let scrollOffset = 0; if (totalItems > maxVisibleItems) { scrollOffset = Math.max( 0, Math.min(selectedIndex - 2, totalItems - maxVisibleItems), ); } const visibleProcesses = useMemo(() => { return sortedProcesses.slice(scrollOffset, scrollOffset + maxVisibleItems); }, [sortedProcesses, scrollOffset, maxVisibleItems]); const getStatusText = useCallback((process: BackgroundProcess) => { if (process.status === 'running') { return t.backgroundProcesses.statusRunning; } if (process.status === 'completed') { return t.backgroundProcesses.statusCompleted; } return t.backgroundProcesses.statusFailed; }, [t]); const getStatusColor = useCallback((status: string) => { if (status === 'running') return theme.colors.menuInfo; if (status === 'completed') return theme.colors.success; return theme.colors.error; }, [theme]); return ( {t.backgroundProcesses.title} ({sortedProcesses.length}) {sortedProcesses.length === 0 ? ( {t.backgroundProcesses.emptyHint} ) : ( <> {visibleProcesses.map((process, visibleIndex) => { const actualIndex = scrollOffset + visibleIndex; const isSelected = actualIndex === selectedIndex; return ( {isSelected ? '> ' : ' '} {truncateCommand(process.command, maxCommandWidth)} {' '}PID: {process.pid} | {t.backgroundProcesses.status}:{' '} {getStatusText(process)} {' '} | {t.backgroundProcesses.duration}:{' '} {formatDuration(process.startedAt, process.completedAt)} ); })} {totalItems > maxVisibleItems && ( {t.backgroundProcesses.navigateHint} | Showing{' '} {scrollOffset + 1}- {Math.min(scrollOffset + maxVisibleItems, totalItems)} of{' '} {totalItems} )} )} {totalItems <= maxVisibleItems && ( {t.backgroundProcesses.navigateHint} )} ); }); ================================================ FILE: source/ui/components/bash/BashCommandConfirmation.tsx ================================================ import React, {useEffect, useMemo, useRef, useState} from 'react'; import {Box, Text} from 'ink'; import TextInput from 'ink-text-input'; import Spinner from 'ink-spinner'; import {useI18n} from '../../../i18n/I18nContext.js'; import {isSensitiveCommand} from '../../../utils/execution/sensitiveCommandManager.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {unifiedHooksExecutor} from '../../../utils/execution/unifiedHooksExecutor.js'; import {interpretHookResult} from '../../../utils/execution/hookResultInterpreter.js'; import {sendTerminalInput} from '../../../hooks/execution/useTerminalExecutionState.js'; interface BashCommandConfirmationProps { command: string; onConfirm: (proceed: boolean) => void; terminalWidth: number; } /** * Truncate command text to prevent overflow * @param text - Command text to truncate * @param maxWidth - Maximum width (defaults to 100) * @returns Truncated text with ellipsis if needed */ function sanitizePreviewLine(text: string): string { // Remove ANSI/control sequences and normalize whitespace to keep preview rendering stable. // This preview is not meant to be an exact terminal emulator. // Optimized: combine multiple replace operations to reduce regex overhead return text .replace(/\x1B\][^\x07]*(?:\x07|\x1B\\)/g, '') .replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, '') .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '') .replace(/\t/g, ' ') .replace(/[\s\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]+$/g, '') .trim(); } function truncateCommand(text: string, maxWidth: number = 100): string { if (text.length <= maxWidth) { return text; } const ellipsis = '...'; const halfWidth = Math.floor((maxWidth - ellipsis.length) / 2); return text.slice(0, halfWidth) + ellipsis + text.slice(-halfWidth); } export function BashCommandConfirmation({ command, terminalWidth, }: BashCommandConfirmationProps) { const {t} = useI18n(); const {theme} = useTheme(); // Check if this is a sensitive command const sensitiveCheck = isSensitiveCommand(command); // Trigger toolConfirmation Hook when component mounts useEffect(() => { const context = { toolName: 'terminal-execute', args: JSON.stringify({command}), isSensitive: sensitiveCheck.isSensitive, matchedPattern: sensitiveCheck.matchedCommand?.pattern, matchedReason: sensitiveCheck.matchedCommand?.description, }; // Execute hook and handle exit code unifiedHooksExecutor .executeHooks('toolConfirmation', context) .then(hookResult => { const interpreted = interpretHookResult('toolConfirmation', hookResult); if (interpreted.action === 'warn' && interpreted.warningMessage) { console.warn(interpreted.warningMessage); } else if (interpreted.action === 'block' && interpreted.errorDetails) { const {exitCode, command, output, error} = interpreted.errorDetails; const combinedOutput = [output, error].filter(Boolean).join('\n\n') || '(no output)'; console.error( `[Hook Error] toolConfirmation Hook failed (exitCode ${exitCode}):\nCommand: ${command}\nOutput: ${combinedOutput}`, ); } }) .catch((error: any) => { console.error('Failed to execute toolConfirmation hook:', error); }); }, [command, sensitiveCheck.isSensitive]); // Calculate max command display width (leave space for padding and borders) const maxCommandWidth = Math.max(40, terminalWidth - 20); const displayCommand = truncateCommand(command, maxCommandWidth); return ( {t.bash.sensitiveCommandDetected} {displayCommand} {sensitiveCheck.isSensitive && sensitiveCheck.matchedCommand && ( <> {t.bash.sensitivePattern} {sensitiveCheck.matchedCommand.pattern} {t.bash.sensitiveReason} {sensitiveCheck.matchedCommand.description} )} {t.bash.executeConfirm} {t.bash.confirmHint} ); } interface BashCommandExecutionStatusProps { command: string; timeout?: number; terminalWidth: number; output?: string[]; needsInput?: boolean; inputPrompt?: string | null; } /** * Truncate text to prevent overflow * Strips leading/trailing whitespace and normalizes tabs to prevent render jitter */ function truncateText(text: string, maxWidth: number = 80): string { // Normalize: trim and replace tabs with spaces (tab width varies in terminals) const normalized = text.trim().replace(/\\t/g, ' '); if (normalized.length <= maxWidth) { return normalized; } return normalized.slice(0, maxWidth - 3) + '...'; } export function BashCommandExecutionStatus({ command, timeout = 30000, terminalWidth, output = [], needsInput = false, inputPrompt = null, }: BashCommandExecutionStatusProps) { const {t} = useI18n(); const {theme} = useTheme(); const timeoutSeconds = Math.round(timeout / 1000); const [inputValue, setInputValue] = useState(''); // Calculate max command display width (leave space for padding and borders) const maxCommandWidth = Math.max(40, terminalWidth - 20); const displayCommand = truncateCommand(command, maxCommandWidth); const maxOutputLines = 5; // Decouple data buffering from state updates: the output effect only writes // into a ref buffer; a fixed-interval timer flushes the buffer into state, // capping re-render frequency at ~5/s regardless of output speed. const maxStoredOutputLines = 200; const maxLineLength = 500; const [displayOutputLines, setDisplayOutputLines] = useState([]); const totalCommittedLineCountRef = useRef(0); const lastSeenOutputLengthRef = useRef(0); const pendingLinesRef = useRef([]); const flushIntervalRef = useRef | null>(null); // Reset buffers when command changes (avoid mixing outputs across commands). useEffect(() => { lastSeenOutputLengthRef.current = 0; totalCommittedLineCountRef.current = 0; pendingLinesRef.current = []; setDisplayOutputLines([]); }, [command]); // Accumulate only NEW output entries into the pending buffer (no setState here). // Only slices from the last-seen index to avoid re-processing the entire array. useEffect(() => { const prevLen = lastSeenOutputLengthRef.current; if (output.length <= prevLen) { return; } const newEntries = output.slice(prevLen); lastSeenOutputLengthRef.current = output.length; for (const entry of newEntries) { const lines = entry.split(/\r?\n/); for (const raw of lines) { const capped = raw.length > maxLineLength ? raw.slice(0, maxLineLength) : raw; const cleaned = sanitizePreviewLine(capped); if (cleaned.length > 0) { pendingLinesRef.current.push(cleaned); } } } if (pendingLinesRef.current.length > maxStoredOutputLines * 2) { pendingLinesRef.current = pendingLinesRef.current.slice( -maxStoredOutputLines, ); } }, [output]); // Fixed-interval flush: commit buffered lines to render state. useEffect(() => { flushIntervalRef.current = setInterval(() => { if (pendingLinesRef.current.length === 0) { return; } const toCommit = pendingLinesRef.current.splice( 0, pendingLinesRef.current.length, ); totalCommittedLineCountRef.current += toCommit.length; setDisplayOutputLines(prev => { const next = [...prev, ...toCommit]; return next.length > maxStoredOutputLines ? next.slice(-maxStoredOutputLines) : next; }); }, 200); return () => { if (flushIntervalRef.current) { clearInterval(flushIntervalRef.current); } }; }, []); // Use useMemo to cache processed output and avoid recalculation on every render const processedOutput = useMemo(() => { const omittedCount = Math.max( 0, totalCommittedLineCountRef.current - maxOutputLines, ); const visibleOutputLines = omittedCount > 0 ? displayOutputLines.slice(-(maxOutputLines - 1)) : displayOutputLines.slice(-maxOutputLines); const rawProcessedOutput = omittedCount > 0 ? [...visibleOutputLines, `... (${omittedCount} lines omitted)`] : visibleOutputLines; const output = [...rawProcessedOutput]; while (output.length < maxOutputLines) { output.unshift(''); } return output; }, [displayOutputLines, maxOutputLines]); // Handle input submission const handleInputSubmit = (value: string) => { sendTerminalInput(value); setInputValue(''); }; return ( {t.bash.executingCommand} {displayCommand} {/* Real-time output lines - fixed height to prevent layout jitter */} {processedOutput.map((line, index) => ( {truncateText(line, maxCommandWidth)} ))} {/* Interactive input area - shown when command needs input */} {needsInput && ( {t.bash.inputRequired} {inputPrompt && ( {inputPrompt} )} > {t.bash.inputHint} )} {t.bash.timeout} {timeoutSeconds}s{' '} {timeout > 60000 && ( {t.bash.customTimeout} )} {t.bash.backgroundHint} ); } ================================================ FILE: source/ui/components/bash/CustomCommandExecutionDisplay.tsx ================================================ import React, {useEffect, useMemo, useRef, useState} from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import {useTheme} from '../../contexts/ThemeContext.js'; interface CustomCommandExecutionDisplayProps { command: string; commandName: string; isRunning: boolean; output: string[]; exitCode?: number | null; error?: string; } function sanitizePreviewLine(text: string): string { return text .replace(/\x1B\][^\x07]*(?:\x07|\x1B\\)/g, '') .replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, '') .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '') .replace(/\t/g, ' ') .replace(/[\s\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]+$/g, '') .trim(); } function truncateText(text: string, maxWidth: number = 80): string { const normalized = text.trim().replace(/\\t/g, ' '); if (normalized.length <= maxWidth) { return normalized; } return normalized.slice(0, maxWidth - 3) + '...'; } const maxOutputLines = 5; const maxStoredOutputLines = 200; const maxLineLength = 500; /** * Simple component for displaying custom command execution with real-time output */ export function CustomCommandExecutionDisplay({ command, commandName, isRunning, output, exitCode, error, }: CustomCommandExecutionDisplayProps) { const {theme} = useTheme(); const [displayOutputLines, setDisplayOutputLines] = useState([]); const totalCommittedLineCountRef = useRef(0); const lastSeenOutputLengthRef = useRef(0); const pendingLinesRef = useRef([]); const flushIntervalRef = useRef | null>(null); useEffect(() => { lastSeenOutputLengthRef.current = 0; totalCommittedLineCountRef.current = 0; pendingLinesRef.current = []; setDisplayOutputLines([]); }, [command]); useEffect(() => { const prevLen = lastSeenOutputLengthRef.current; if (output.length <= prevLen) { return; } const newEntries = output.slice(prevLen); lastSeenOutputLengthRef.current = output.length; for (const entry of newEntries) { const lines = entry.split(/\r?\n/); for (const raw of lines) { const capped = raw.length > maxLineLength ? raw.slice(0, maxLineLength) : raw; const cleaned = sanitizePreviewLine(capped); if (cleaned.length > 0) { pendingLinesRef.current.push(cleaned); } } } if (pendingLinesRef.current.length > maxStoredOutputLines * 2) { pendingLinesRef.current = pendingLinesRef.current.slice( -maxStoredOutputLines, ); } }, [output]); useEffect(() => { flushIntervalRef.current = setInterval(() => { if (pendingLinesRef.current.length === 0) { return; } const toCommit = pendingLinesRef.current.splice( 0, pendingLinesRef.current.length, ); totalCommittedLineCountRef.current += toCommit.length; setDisplayOutputLines(prev => { const next = [...prev, ...toCommit]; return next.length > maxStoredOutputLines ? next.slice(-maxStoredOutputLines) : next; }); }, 200); return () => { if (flushIntervalRef.current) { clearInterval(flushIntervalRef.current); } }; }, []); const processedOutput = useMemo(() => { const omittedCount = Math.max( 0, totalCommittedLineCountRef.current - maxOutputLines, ); const visibleOutputLines = omittedCount > 0 ? displayOutputLines.slice(-(maxOutputLines - 1)) : displayOutputLines.slice(-maxOutputLines); const rawProcessedOutput = omittedCount > 0 ? [...visibleOutputLines, `... (${omittedCount} lines omitted)`] : visibleOutputLines; const result = [...rawProcessedOutput]; while (result.length < maxOutputLines) { result.unshift(''); } return result; }, [displayOutputLines]); return ( {/* Header line */} /{commandName} {isRunning ? ( ) : exitCode === 0 ? ( ✔ ) : ( <> ✘ {exitCode !== null && exitCode !== undefined && ( (exit: {exitCode}) )} )} {processedOutput.map((line, index) => ( {truncateText(line, 100)} ))} {error && ( {error} )} {!isRunning && displayOutputLines.length === 0 && !error && ( (no output) )} ); } export default CustomCommandExecutionDisplay; ================================================ FILE: source/ui/components/chat/ChatFooter.tsx ================================================ import React, {useState, useEffect, Suspense, lazy} from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import ChatInput from './ChatInput.js'; import StatusLine from '../common/StatusLine.js'; import LoadingIndicator from './LoadingIndicator.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import type {Message} from './MessageList.js'; import {BackgroundProcessPanel} from '../bash/BackgroundProcessPanel.js'; import type {BackgroundProcess} from '../../../hooks/execution/useBackgroundProcesses.js'; import TodoTree from '../special/TodoTree.js'; import type {TodoItem} from '../../../mcp/types/todo.types.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {todoEvents} from '../../../utils/events/todoEvents.js'; import {connectionManager} from '../../../utils/connection/ConnectionManager.js'; const ReviewCommitPanel = lazy(() => import('../panels/ReviewCommitPanel.js')); import type {ReviewCommitSelection} from '../panels/ReviewCommitPanel.js'; import {IdeSelectPanel} from '../panels/IdeSelectPanel.js'; const BtwPanel = lazy(() => import('../panels/BtwPanel.js')); const DiffReviewPanel = lazy(() => import('../panels/DiffReviewPanel.js')); const SkillsListPanel = lazy(() => import('../panels/SkillsListPanel.js')); type ChatFooterProps = { onSubmit: ( message: string, images?: Array<{data: string; mimeType: string}>, ) => Promise; onCommand: (commandName: string, result: any) => Promise; onHistorySelect: ( selectedIndex: number, message: string, images?: Array<{type: 'image'; data: string; mimeType: string}>, ) => Promise; onSwitchProfile: () => void; handleProfileSelect: (profileName: string) => void; /** 在 ProfilePanel 中按右方向键时进入 ProfileEditPanel 编辑该 profile */ handleProfileEdit?: (profileName: string) => void; handleHistorySelect: ( selectedIndex: number, message: string, images?: Array<{type: 'image'; data: string; mimeType: string}>, ) => Promise; // Review commit panel props showReviewCommitPanel: boolean; setShowReviewCommitPanel: React.Dispatch>; onReviewCommitConfirm: ( selection: ReviewCommitSelection[], notes: string, ) => void | Promise; // Diff review panel props showDiffReviewPanel: boolean; setShowDiffReviewPanel: React.Dispatch>; diffReviewMessages: Array<{ role: string; content: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; subAgentDirected?: unknown; }>; diffReviewSnapshotFileCount: Map; disabled: boolean; isStopping: boolean; isProcessing: boolean; chatHistory: Message[]; yoloMode: boolean; setYoloMode: (value: boolean) => void; planMode: boolean; setPlanMode: (value: boolean) => void; vulnerabilityHuntingMode: boolean; setVulnerabilityHuntingMode: (value: boolean) => void; toolSearchDisabled: boolean; hybridCompressEnabled: boolean; teamMode: boolean; setTeamMode: (value: boolean) => void; contextUsage?: { inputTokens: number; maxContextTokens: number; cacheCreationTokens?: number; cacheReadTokens?: number; cachedTokens?: number; }; initialContent: { text: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; } | null; // 输入框草稿内容：用于 ChatFooter 被条件隐藏后恢复时，保留输入框内容 draftContent: { text: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; } | null; onDraftChange: ( content: { text: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; } | null, ) => void; onContextPercentageChange: (percentage: number) => void; onInitialContentConsumed: () => void; showProfilePicker: boolean; setShowProfilePicker: (value: boolean | ((prev: boolean) => boolean)) => void; profileSelectedIndex: number; setProfileSelectedIndex: (index: number | ((prev: number) => number)) => void; getFilteredProfiles: () => any[]; profileSearchQuery: string; setProfileSearchQuery: (query: string) => void; vscodeConnectionStatus: 'disconnected' | 'connecting' | 'connected' | 'error'; editorContext?: { activeFile?: string; selectedText?: string; cursorPosition?: {line: number; character: number}; workspaceFolder?: string; }; codebaseIndexing: boolean; codebaseProgress: { totalFiles: number; processedFiles: number; totalChunks: number; currentFile: string; status: string; error?: string; } | null; watcherEnabled: boolean; fileUpdateNotification: {file: string; timestamp: number} | null; currentProfileName: string; isCompressing: boolean; compressionError: string | null; copyStatusMessage?: { text: string; isError?: boolean; timestamp: number; } | null; // Background process panel props backgroundProcesses: BackgroundProcess[]; showBackgroundPanel: boolean; selectedProcessIndex: number; terminalWidth: number; // IDE select panel props showIdeSelectPanel: boolean; setShowIdeSelectPanel: React.Dispatch>; onIdeConnectionChange: ( status: 'connected' | 'disconnected', message?: string, ) => void; onIdeWorkingDirectoryChanged?: (newCwd: string) => void; // Skills list panel props showSkillsListPanel: boolean; setShowSkillsListPanel: React.Dispatch>; // BTW panel props btwPrompt: string | null; onBtwClose: () => void; // Loading indicator props isStreaming: boolean; isSaving: boolean; hasPendingToolConfirmation: boolean; hasPendingUserQuestion: boolean; hasBlockingOverlay: boolean; animationFrame: number; retryStatus: { isRetrying: boolean; errorMessage?: string; remainingSeconds?: number; attempt: number; } | null; codebaseSearchStatus: { isSearching: boolean; attempt: number; maxAttempts: number; currentTopN: number; message: string; query?: string; originalResultsCount?: number; suggestion?: string; } | null; isReasoning: boolean; streamTokenCount: number; elapsedSeconds: number; currentModel?: string | null; compressBlockToast?: string | null; }; const ChatFooter = React.memo(function ChatFooter(props: ChatFooterProps) { const {t} = useI18n(); const [todos, setTodos] = useState([]); const [showTodos, setShowTodos] = useState(false); // 实例连接状态 const [connectionStatus, setConnectionStatus] = useState< 'disconnected' | 'connecting' | 'connected' | 'reconnecting' >('disconnected'); const [connectionInstanceName, setConnectionInstanceName] = useState(''); const [copyStatusMessage, setCopyStatusMessage] = useState<{ text: string; isError?: boolean; timestamp: number; } | null>(null); // 订阅连接状态变化 useEffect(() => { const unsubscribe = connectionManager.onStatusChange(state => { setConnectionStatus(state.status); if (state.instanceName) { setConnectionInstanceName(state.instanceName); } }); return unsubscribe; }, []); // 使用事件监听 TODO 更新，替代轮询 useEffect(() => { const currentSession = sessionManager.getCurrentSession(); if (!currentSession) { setShowTodos(false); setTodos([]); return; } const handleTodoUpdate = (data: {sessionId: string; todos: TodoItem[]}) => { // 只处理当前会话的 TODO 更新 if (data.sessionId === currentSession.id) { setTodos(data.todos); if (data.todos.length > 0 && props.isProcessing) { setShowTodos(true); } } }; // 监听 TODO 更新事件 todoEvents.onTodoUpdate(handleTodoUpdate); // 清理监听器 return () => { todoEvents.offTodoUpdate(handleTodoUpdate); }; }, [props.isProcessing]); // 对话结束后自动隐藏 useEffect(() => { if (!props.isProcessing && showTodos) { const timeoutId = setTimeout(() => { setShowTodos(false); }, 1000); return () => { clearTimeout(timeoutId); }; } return; }, [props.isProcessing, showTodos]); useEffect(() => { if (!copyStatusMessage) return; const timeoutId = setTimeout(() => { setCopyStatusMessage(null); }, 2000); return () => { clearTimeout(timeoutId); }; }, [copyStatusMessage]); // 统一处理：ChatFooter 内部会把 ChatInput 替换为 ReviewCommitPanel / IdeSelectPanel // 这两类面板（见下方条件渲染）。这些面板打开时 footer 整体仍在渲染， // ChatScreen 的 shouldShowFooter 侧通用逻辑覆盖不到，需要在此清空 draft， // 避免面板关闭后 ChatInput 重新挂载时把旧文本恢复进输入框。 useEffect(() => { if ( props.showReviewCommitPanel || props.showIdeSelectPanel || props.showDiffReviewPanel || props.showSkillsListPanel ) { props.onDraftChange(null); } }, [props.showReviewCommitPanel, props.showIdeSelectPanel, props.showDiffReviewPanel, props.showSkillsListPanel]); return ( <> {!props.showReviewCommitPanel && !props.showIdeSelectPanel && !props.showDiffReviewPanel && !props.showSkillsListPanel && ( <> {props.btwPrompt ? ( Loading... } > ) : ( { setCopyStatusMessage({ text: `✔ ${t.chatScreen.inputCopySuccess}`, timestamp: Date.now(), }); }} onCopyInputError={errorMessage => { setCopyStatusMessage({ text: `✖ ${t.chatScreen.inputCopyFailedPrefix}: ${errorMessage}`, isError: true, timestamp: Date.now(), }); }} /> )} {showTodos && todos.length > 0 && ( )} {props.showBackgroundPanel && ( )} )} {props.showReviewCommitPanel && ( Loading... } > props.setShowReviewCommitPanel(false)} onConfirm={props.onReviewCommitConfirm} maxHeight={6} /> )} {props.showIdeSelectPanel && ( props.setShowIdeSelectPanel(false)} onConnectionChange={props.onIdeConnectionChange} onWorkingDirectoryChanged={props.onIdeWorkingDirectoryChanged} /> )} {props.showSkillsListPanel && ( Loading... } > props.setShowSkillsListPanel(false)} /> )} {props.showDiffReviewPanel && ( Loading... } > props.setShowDiffReviewPanel(false)} terminalWidth={props.terminalWidth} /> )} ); }); export default ChatFooter; ================================================ FILE: source/ui/components/chat/ChatInput.tsx ================================================ import React, {useEffect, useRef, useMemo, lazy, Suspense} from 'react'; import {Box, Text, useCursor} from 'ink'; import {Viewport} from '../../../utils/ui/textBuffer.js'; // Lazy load panel components to reduce initial bundle size const CommandPanel = lazy(() => import('../panels/CommandPanel.js')); const FileList = lazy(() => import('../tools/FileList.js')); const AgentPickerPanel = lazy(() => import('../panels/AgentPickerPanel.js')); const TodoPickerPanel = lazy(() => import('../panels/TodoPickerPanel.js')); const SkillsPickerPanel = lazy(() => import('../panels/SkillsPickerPanel.js')); const GitLinePickerPanel = lazy( () => import('../panels/GitLinePickerPanel.js'), ); const ProfilePanel = lazy(() => import('../panels/ProfilePanel.js')); const RunningAgentsPanel = lazy( () => import('../panels/RunningAgentsPanel.js'), ); const RollbackMenuPanel = lazy(() => import('../panels/RollbackMenuPanel.js')); const CommandArgsPanel = lazy(() => import('../panels/CommandArgsPanel.js')); import {useInputBuffer} from '../../../hooks/input/useInputBuffer.js'; import { useCommandPanel, COMMAND_ARGS_HINTS, COMMAND_ARGS_OPTIONS, } from '../../../hooks/ui/useCommandPanel.js'; import {useFilePicker} from '../../../hooks/picker/useFilePicker.js'; import {useHistoryNavigation} from '../../../hooks/input/useHistoryNavigation.js'; import {useClipboard} from '../../../hooks/input/useClipboard.js'; import {useKeyboardInput} from '../../../hooks/input/useKeyboardInput.js'; import {useTerminalSize} from '../../../hooks/ui/useTerminalSize.js'; import {useTerminalFocus} from '../../../hooks/ui/useTerminalFocus.js'; import {useAgentPicker} from '../../../hooks/picker/useAgentPicker.js'; import {useTodoPicker} from '../../../hooks/picker/useTodoPicker.js'; import {useSkillsPicker} from '../../../hooks/picker/useSkillsPicker.js'; import {useGitLinePicker} from '../../../hooks/picker/useGitLinePicker.js'; import {useRunningAgentsPicker} from '../../../hooks/picker/useRunningAgentsPicker.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useBashMode} from '../../../hooks/input/useBashMode.js'; function parseSkillIdFromHeaderLine(line: string): string { return line.replace(/^# Skill:\s*/i, '').trim() || 'unknown'; } function parseGitLineShaFromHeaderLine(line: string): string { return line.replace(/^# GitLine:\s*/i, '').trim() || 'unknown'; } function restoreTextWithSkillPlaceholders( buffer: { insertRestoredText: (t: string) => void; insertTextPlaceholder: (c: string, p: string) => void; }, text: string, ) { if (!text) return; const lines = text.split('\n'); let plain = ''; let rollbackPasteCounter = 0; const insertPlainOrPastePlaceholder = (chunk: string) => { if (!chunk) return; const lineCount = chunk.split('\n').length; const shouldMaskAsPaste = chunk.length >= 400 || lineCount >= 12; if (!shouldMaskAsPaste) { buffer.insertRestoredText(chunk); return; } rollbackPasteCounter++; buffer.insertTextPlaceholder( chunk, `[Paste ${lineCount} lines #${rollbackPasteCounter}] `, ); }; const flushPlain = () => { if (!plain) return; insertPlainOrPastePlaceholder(plain); plain = ''; }; let i = 0; while (i < lines.length) { const line = lines[i] ?? ''; const isSkillBlock = line.startsWith('# Skill:'); const isGitLineBlock = line.startsWith('# GitLine:'); const isPasteBlock = line.startsWith('# Paste:'); if (!isSkillBlock && !isGitLineBlock && !isPasteBlock) { plain += line; if (i < lines.length - 1) plain += '\n'; i++; continue; } flushPlain(); if (isPasteBlock) { // Collect paste content until # Paste End const pasteLines: string[] = []; i++; while (i < lines.length) { const next = lines[i] ?? ''; if (next.trimStart().startsWith('# Paste End')) { i++; break; } pasteLines.push(next); i++; } const pasteContent = pasteLines.join('\n'); if (pasteContent) { const lineCount = pasteLines.length; rollbackPasteCounter++; buffer.insertTextPlaceholder( pasteContent, `[Paste ${lineCount} lines #${rollbackPasteCounter}] `, ); } continue; } const rawLines: string[] = [line]; const placeholderText = isSkillBlock ? `[Skill:${parseSkillIdFromHeaderLine(line)}] ` : `[GitLine:${parseGitLineShaFromHeaderLine(line).slice(0, 8)}] `; const endMarker = isSkillBlock ? '# Skill End' : '# GitLine End'; let endFound = false; i++; while (i < lines.length) { const next = lines[i] ?? ''; if (next.startsWith('# Skill:') || next.startsWith('# GitLine:')) break; const trimmedStart = next.trimStart(); if (trimmedStart.startsWith(endMarker)) { const remainder = trimmedStart.slice(endMarker.length); rawLines.push(endMarker); endFound = true; i++; if (remainder.length > 0) { plain += remainder.replace(/^\s+/, ''); if (i < lines.length) plain += '\n'; } break; } rawLines.push(next); i++; } let raw = rawLines.join('\n'); if (endFound && !raw.endsWith('\n')) raw += '\n'; buffer.insertTextPlaceholder(raw, placeholderText); } flushPlain(); } /** * Calculate context usage percentage * This is the same logic used in ChatInput to display usage */ export function calculateContextPercentage(contextUsage: { inputTokens: number; maxContextTokens: number; cacheCreationTokens?: number; cacheReadTokens?: number; cachedTokens?: number; }): number { // Determine which caching system is being used const isAnthropic = (contextUsage.cacheCreationTokens || 0) > 0 || (contextUsage.cacheReadTokens || 0) > 0; // For Anthropic: Total = inputTokens + cacheCreationTokens + cacheReadTokens // For OpenAI: Total = inputTokens (cachedTokens are already included in inputTokens) const totalInputTokens = isAnthropic ? contextUsage.inputTokens + (contextUsage.cacheCreationTokens || 0) + (contextUsage.cacheReadTokens || 0) : contextUsage.inputTokens; return Math.min( 100, (totalInputTokens / contextUsage.maxContextTokens) * 100, ); } type Props = { onSubmit: ( message: string, images?: Array<{data: string; mimeType: string}>, ) => void; onCommand?: (commandName: string, result: any) => void; placeholder?: string; disabled?: boolean; isProcessing?: boolean; // Prevent command panel from showing during AI response/tool execution chatHistory?: Array<{ role: string; content: string; subAgentDirected?: unknown; }>; onHistorySelect?: (selectedIndex: number, message: string) => void; yoloMode?: boolean; setYoloMode?: (value: boolean) => void; planMode?: boolean; setPlanMode?: (value: boolean) => void; vulnerabilityHuntingMode?: boolean; setVulnerabilityHuntingMode?: (value: boolean) => void; teamMode?: boolean; setTeamMode?: (value: boolean) => void; contextUsage?: { inputTokens: number; maxContextTokens: number; // Anthropic caching cacheCreationTokens?: number; cacheReadTokens?: number; // OpenAI caching cachedTokens?: number; }; initialContent?: { text: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; } | null; // 输入框草稿内容：用于父组件条件隐藏输入区域后恢复时保留输入内容 draftContent?: { text: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; } | null; onDraftChange?: ( content: { text: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; } | null, ) => void; onContextPercentageChange?: (percentage: number) => void; // Callback to notify parent of percentage changes onInitialContentConsumed?: () => void; // Profile picker showProfilePicker?: boolean; setShowProfilePicker?: (show: boolean) => void; profileSelectedIndex?: number; setProfileSelectedIndex?: ( index: number | ((prev: number) => number), ) => void; getFilteredProfiles?: () => Array<{ name: string; displayName: string; isActive: boolean; }>; handleProfileSelect?: (profileName: string) => void; /** * 在 ProfilePanel 中按右方向键时调用：进入 ProfileEditPanel 编辑该 profile。 */ handleProfileEdit?: (profileName: string) => void; profileSearchQuery?: string; setProfileSearchQuery?: (query: string) => void; onSwitchProfile?: () => void; // Callback when Ctrl+P is pressed to switch profile onCopyInputSuccess?: () => void; onCopyInputError?: (errorMessage: string) => void; disableKeyboardNavigation?: boolean; // Disable arrow keys and Ctrl+K when background panel is active }; export default function ChatInput({ onSubmit, onCommand, placeholder = 'Type your message...', disabled = false, isProcessing = false, chatHistory = [], onHistorySelect, yoloMode = false, setYoloMode, planMode = false, setPlanMode, vulnerabilityHuntingMode = false, setVulnerabilityHuntingMode, teamMode = false, setTeamMode, contextUsage, initialContent = null, draftContent = null, onDraftChange, onContextPercentageChange, onInitialContentConsumed, showProfilePicker = false, setShowProfilePicker, profileSelectedIndex = 0, setProfileSelectedIndex, getFilteredProfiles, handleProfileSelect, handleProfileEdit, profileSearchQuery = '', setProfileSearchQuery, onSwitchProfile, onCopyInputSuccess, onCopyInputError, disableKeyboardNavigation = false, }: Props) { // Use i18n hook for translations const {t} = useI18n(); const {theme} = useTheme(); // Use bash mode hook for command detection const {parseBashCommands, parsePureBashCommands} = useBashMode(); // Use terminal size hook to listen for resize events const {columns: terminalWidth} = useTerminalSize(); const prevTerminalWidthRef = useRef(terminalWidth); // Use terminal focus hook to detect focus state const {hasFocus, ensureFocus} = useTerminalFocus(); // Recalculate viewport dimensions to ensure proper resizing const uiOverhead = 8; const viewportWidth = Math.max(40, terminalWidth - uiOverhead); const viewport: Viewport = useMemo( () => ({ width: viewportWidth, height: 1, }), [viewportWidth], ); // Memoize viewport to prevent unnecessary re-renders // Use input buffer hook const {buffer, triggerUpdate, forceUpdate} = useInputBuffer(viewport); // Track bash mode state with debounce to avoid high-frequency updates const [isBashMode, setIsBashMode] = React.useState(false); const [isPureBashMode, setIsPureBashMode] = React.useState(false); const bashModeDebounceTimer = useRef(null); // Use command panel hook const { showCommands, setShowCommands, commandSelectedIndex, setCommandSelectedIndex, getFilteredCommands, updateCommandPanelState, getAllCommands, } = useCommandPanel(buffer, isProcessing); // Command args picker state const [showArgsPicker, setShowArgsPicker] = React.useState(false); const [argsSelectedIndex, setArgsSelectedIndex] = React.useState(0); // Compute current command name and its available args options const argsPickerContext = useMemo(() => { const text = buffer.text; const match = text.match(/^\/([a-zA-Z0-9_-]+)\s*$/); if (!match) return {commandName: '', options: [] as string[]}; const cmd = match[1] ?? ''; const options = COMMAND_ARGS_OPTIONS[cmd]; return {commandName: cmd, options: options || []}; }, [buffer.text]); // Use file picker hook const { showFilePicker, setShowFilePicker, fileSelectedIndex, setFileSelectedIndex, fileQuery, setFileQuery, atSymbolPosition, setAtSymbolPosition, filteredFileCount, searchMode, updateFilePickerState, handleFileSelect, handleFilteredCountChange, fileListRef, } = useFilePicker(buffer, triggerUpdate); // Use history navigation hook const { showHistoryMenu, setShowHistoryMenu, historySelectedIndex, setHistorySelectedIndex, escapeKeyCount, setEscapeKeyCount, escapeKeyTimer, getUserMessages, handleHistorySelect, currentHistoryIndex, navigateHistoryUp, navigateHistoryDown, resetHistoryNavigation, saveToHistory, } = useHistoryNavigation(buffer, triggerUpdate, chatHistory, onHistorySelect); // Use agent picker hook const { showAgentPicker, setShowAgentPicker, agentSelectedIndex, setAgentSelectedIndex, updateAgentPickerState, getFilteredAgents, handleAgentSelect, } = useAgentPicker(buffer, triggerUpdate); // Use todo picker hook const { showTodoPicker, setShowTodoPicker, todoSelectedIndex, setTodoSelectedIndex, todos, selectedTodos, toggleTodoSelection, confirmTodoSelection, isLoading: todoIsLoading, searchQuery: todoSearchQuery, setSearchQuery: setTodoSearchQuery, totalTodoCount, } = useTodoPicker(buffer, triggerUpdate, process.cwd()); // Use skills picker hook const { showSkillsPicker, setShowSkillsPicker, skillsSelectedIndex, setSkillsSelectedIndex, skills, isLoading: skillsIsLoading, searchQuery: skillsSearchQuery, appendText: skillsAppendText, focus: skillsFocus, toggleFocus: toggleSkillsFocus, appendChar: appendSkillsChar, backspace: backspaceSkillsField, confirmSelection: confirmSkillsSelection, closeSkillsPicker, } = useSkillsPicker(buffer, triggerUpdate); const { showGitLinePicker, setShowGitLinePicker, gitLineSelectedIndex, setGitLineSelectedIndex, gitLineCommits, selectedGitLineCommits, gitLineHasMore, gitLineIsLoading, gitLineIsLoadingMore, gitLineSearchQuery, setGitLineSearchQuery, gitLineError, toggleGitLineCommitSelection, confirmGitLineSelection, closeGitLinePicker, } = useGitLinePicker(buffer, triggerUpdate); // Use running agents picker hook const { showRunningAgentsPicker, setShowRunningAgentsPicker, runningAgentsSelectedIndex, setRunningAgentsSelectedIndex, runningAgents, selectedRunningAgents, toggleRunningAgentSelection, confirmRunningAgentsSelection, closeRunningAgentsPicker, updateRunningAgentsPickerState, } = useRunningAgentsPicker(buffer, triggerUpdate); // Use clipboard hook const {pasteFromClipboard} = useClipboard( buffer, updateCommandPanelState, updateFilePickerState, triggerUpdate, ); const pasteShortcutTimeoutMs = 800; const pasteFlushDebounceMs = 250; const pasteIndicatorThreshold = 300; // Use keyboard input hook useKeyboardInput({ buffer, disabled, disableKeyboardNavigation, isProcessing, triggerUpdate, forceUpdate, yoloMode, setYoloMode: setYoloMode || (() => {}), planMode, setPlanMode: setPlanMode || (() => {}), vulnerabilityHuntingMode, setVulnerabilityHuntingMode: setVulnerabilityHuntingMode || (() => {}), teamMode, setTeamMode: setTeamMode || (() => {}), showCommands, setShowCommands, commandSelectedIndex, setCommandSelectedIndex, getFilteredCommands, updateCommandPanelState, onCommand, getAllCommands, showFilePicker, setShowFilePicker, fileSelectedIndex, setFileSelectedIndex, fileQuery, setFileQuery, atSymbolPosition, setAtSymbolPosition, filteredFileCount, updateFilePickerState, handleFileSelect, fileListRef, showHistoryMenu, setShowHistoryMenu, historySelectedIndex, setHistorySelectedIndex, escapeKeyCount, setEscapeKeyCount, escapeKeyTimer, getUserMessages, handleHistorySelect, currentHistoryIndex, navigateHistoryUp, navigateHistoryDown, resetHistoryNavigation, saveToHistory, pasteFromClipboard, onCopyInputSuccess: () => { onCopyInputSuccess?.(); }, onCopyInputError: errorMessage => { onCopyInputError?.( errorMessage || t.commandPanel.copyLastFeedback.unknownError, ); }, pasteShortcutTimeoutMs, pasteFlushDebounceMs, pasteIndicatorThreshold, onSubmit, ensureFocus, showAgentPicker, setShowAgentPicker, agentSelectedIndex, setAgentSelectedIndex, updateAgentPickerState, getFilteredAgents, handleAgentSelect, showTodoPicker, setShowTodoPicker, todoSelectedIndex, setTodoSelectedIndex, todos, selectedTodos, toggleTodoSelection, confirmTodoSelection, todoSearchQuery, setTodoSearchQuery, showSkillsPicker, setShowSkillsPicker, skillsSelectedIndex, setSkillsSelectedIndex, skills, skillsIsLoading, skillsSearchQuery, skillsAppendText, skillsFocus, toggleSkillsFocus, appendSkillsChar, backspaceSkillsField, confirmSkillsSelection, closeSkillsPicker, showGitLinePicker, setShowGitLinePicker, gitLineSelectedIndex, setGitLineSelectedIndex, gitLineCommits, selectedGitLineCommits, gitLineIsLoading, gitLineSearchQuery, setGitLineSearchQuery, gitLineError, toggleGitLineCommitSelection, confirmGitLineSelection, closeGitLinePicker, showProfilePicker, setShowProfilePicker: setShowProfilePicker || (() => {}), profileSelectedIndex, setProfileSelectedIndex: setProfileSelectedIndex || (() => {}), getFilteredProfiles: getFilteredProfiles || (() => []), handleProfileSelect: handleProfileSelect || (() => {}), handleProfileEdit, profileSearchQuery, setProfileSearchQuery: setProfileSearchQuery || (() => {}), onSwitchProfile, showRunningAgentsPicker, setShowRunningAgentsPicker, runningAgentsSelectedIndex, setRunningAgentsSelectedIndex, runningAgents, selectedRunningAgents, toggleRunningAgentSelection, confirmRunningAgentsSelection, closeRunningAgentsPicker, updateRunningAgentsPickerState, showArgsPicker, setShowArgsPicker, argsSelectedIndex, setArgsSelectedIndex, argsPickerContext, }); // Set initial content when provided (e.g., rollback/history restore) useEffect(() => { if (!initialContent) return; // Always do full restore to avoid duplicate placeholders buffer.setText(''); const text = initialContent.text; const images = initialContent.images || []; if (images.length === 0) { // No images, just set the text. // Use restoreTextWithSkillPlaceholders() so rollback restore: // - doesn't get treated as a "paste" placeholder // - rebuilds Skill injection blocks back into [Skill:id] placeholders if (text) { restoreTextWithSkillPlaceholders(buffer, text); } } else { // Split text by image placeholders and reconstruct with actual images // Placeholder format: [image #N] const imagePlaceholderPattern = /\[image #\d+\]/g; const parts = text.split(imagePlaceholderPattern); // Interleave text parts with images for (let i = 0; i < parts.length; i++) { // Insert text part const part = parts[i]; if (part) { restoreTextWithSkillPlaceholders(buffer, part); } // Insert image after this text part (if exists) if (i < images.length) { const img = images[i]; if (img) { // Extract base64 data from data URL if present let base64Data = img.data; if (base64Data.startsWith('data:')) { const base64Index = base64Data.indexOf('base64,'); if (base64Index !== -1) { base64Data = base64Data.substring(base64Index + 7); } } buffer.insertImage(base64Data, img.mimeType); } } } } triggerUpdate(); onInitialContentConsumed?.(); // Only run when initialContent changes // eslint-disable-next-line react-hooks/exhaustive-deps }, [initialContent]); // Restore draft content when input gets remounted (e.g., ChatFooter is conditionally hidden) useEffect(() => { if (!draftContent) return; if (initialContent) return; // 仅在输入框为空时恢复，避免覆盖当前编辑内容 if (buffer.text.length > 0) return; buffer.setText(''); const text = draftContent.text; const images = draftContent.images || []; if (images.length === 0) { if (text) { restoreTextWithSkillPlaceholders(buffer, text); } } else { const imagePlaceholderPattern = /\[image #\d+\]/g; const parts = text.split(imagePlaceholderPattern); for (let i = 0; i < parts.length; i++) { const part = parts[i]; if (part) { restoreTextWithSkillPlaceholders(buffer, part); } if (i < images.length) { const img = images[i]; if (img) { let base64Data = img.data; if (base64Data.startsWith('data:')) { const base64Index = base64Data.indexOf('base64,'); if (base64Index !== -1) { base64Data = base64Data.substring(base64Index + 7); } } buffer.insertImage(base64Data, img.mimeType); } } } } triggerUpdate(); }, [draftContent, initialContent, buffer, triggerUpdate]); // Report draft changes to parent, so it can persist across conditional unmount/mount useEffect(() => { if (!onDraftChange) return; const text = buffer.getFullText(); const currentText = buffer.text; const allImages = buffer.getImages(); const images = allImages .filter(img => currentText.includes(img.placeholder)) .map(img => ({ type: 'image' as const, data: img.data, mimeType: img.mimeType, })); if (!text && images.length === 0) { onDraftChange(null); return; } onDraftChange({ text, images: images.length > 0 ? images : undefined, }); }, [buffer.text, buffer, onDraftChange]); // Force full re-render when file picker visibility changes to prevent artifacts useEffect(() => { // Use a small delay to ensure the component tree has updated const timer = setTimeout(() => { forceUpdate(); }, 10); return () => clearTimeout(timer); }, [showFilePicker, forceUpdate]); // Handle terminal width changes with debounce (like gemini-cli) useEffect(() => { // Skip on initial mount if (prevTerminalWidthRef.current === terminalWidth) { prevTerminalWidthRef.current = terminalWidth; return; } prevTerminalWidthRef.current = terminalWidth; // Debounce the re-render to avoid flickering during resize const timer = setTimeout(() => { forceUpdate(); }, 100); return () => clearTimeout(timer); }, [terminalWidth, forceUpdate]); // Notify parent of context percentage changes const lastPercentageRef = useRef(0); useEffect(() => { if (contextUsage && onContextPercentageChange) { const percentage = calculateContextPercentage(contextUsage); // Only call callback if percentage has actually changed if (percentage !== lastPercentageRef.current) { lastPercentageRef.current = percentage; onContextPercentageChange(percentage); } } }, [contextUsage, onContextPercentageChange]); // Detect bash mode with debounce (150ms delay to avoid high-frequency updates) useEffect(() => { // Clear existing timer if (bashModeDebounceTimer.current) { clearTimeout(bashModeDebounceTimer.current); } // Set new timer bashModeDebounceTimer.current = setTimeout(() => { const text = buffer.getFullText(); // 先检查纯 Bash 模式（双感叹号） const pureBashCommands = parsePureBashCommands(text); const hasPureBashCommands = pureBashCommands.length > 0; // 再检查命令注入模式（单感叹号） const bashCommands = parseBashCommands(text); const hasBashCommands = bashCommands.length > 0; // Only update state if changed if (hasPureBashCommands !== isPureBashMode) { setIsPureBashMode(hasPureBashCommands); } if (hasBashCommands !== isBashMode) { setIsBashMode(hasBashCommands); } }, 150); // Cleanup on unmount return () => { if (bashModeDebounceTimer.current) { clearTimeout(bashModeDebounceTimer.current); } }; }, [ buffer.text, parseBashCommands, parsePureBashCommands, isBashMode, isPureBashMode, ]); // Real terminal cursor via useCursor hook const {setCursorPosition, cursorRef} = useCursor(); // Render content with cursor (treat all text including placeholders as plain text) const INPUT_MAX_LINES = 6; const EXPANDED_MAX_LINES = 12; // 当输入为单行的 `/cmd` 或 `/cmd ` 形式时，计算参数提示；否则为空字符串 const commandArgsHint = useMemo(() => { const text = buffer.text; if (!text.startsWith('/')) return ''; const match = text.match(/^\/([a-zA-Z0-9_-]+)(\s*)$/); if (!match) return ''; const cmd = match[1] ?? ''; const hint = COMMAND_ARGS_HINTS[cmd]; if (!hint) return ''; // 若已经有尾随空格则直接拼接，否则前置空格将 cmd 与提示分隔 return match[2] && match[2].length > 0 ? hint : ` ${hint}`; }, [buffer.text]); const renderContent = () => { if (buffer.text.length > 0) { // Use visual lines for proper wrapping and multi-line support const visualLines = buffer.viewportVisualLines; const [cursorRow, cursorCol] = buffer.visualCursor; let startLine = 0; let endLine = visualLines.length; // Limit visible lines and scroll to keep cursor visible const maxLines = buffer.isExpandedView ? EXPANDED_MAX_LINES : INPUT_MAX_LINES; if (visualLines.length > maxLines) { const halfWindow = Math.floor(maxLines / 2); startLine = Math.max(0, cursorRow - halfWindow); startLine = Math.min(startLine, visualLines.length - maxLines); endLine = startLine + maxLines; } // Set real terminal cursor position const hasScrollUp = startLine > 0; const cursorYInContent = cursorRow - startLine + (hasScrollUp ? 1 : 0); if (hasFocus) { setCursorPosition({x: cursorCol, y: cursorYInContent}); } else { setCursorPosition(undefined); } const renderedLines: React.ReactNode[] = []; // Scroll-up indicator if (startLine > 0) { renderedLines.push( {t.chatScreen.moreAbove.replace('{count}', startLine.toString())} , ); } for (let i = startLine; i < endLine; i++) { const line = visualLines[i] || ''; if (i === cursorRow) { renderedLines.push( {line || ' '} {commandArgsHint && i === visualLines.length - 1 ? ( {commandArgsHint} ) : null} , ); } else { renderedLines.push({line || ' '}); } } // Scroll-down indicator if (endLine < visualLines.length) { renderedLines.push( {t.chatScreen.moreBelow.replace( '{count}', (visualLines.length - endLine).toString(), )} , ); } return {renderedLines}; } else { // Empty input: cursor at start if (hasFocus) { setCursorPosition({x: 0, y: 0}); } else { setCursorPosition(undefined); } return ( {disabled ? t.chatScreen.waitingForResponse : placeholder} ); } }; return ( {!showHistoryMenu && ( <> {buffer.isExpandedView ? '═'.repeat(terminalWidth - 2) : '─'.repeat(terminalWidth - 2)} {isPureBashMode ? '!!' : isBashMode ? '>_' : buffer.isExpandedView ? '⤢' : '❯'}{' '} {renderContent()} {buffer.isExpandedView ? '═'.repeat(terminalWidth - 2) : '─'.repeat(terminalWidth - 2)} {buffer.isExpandedView && ( {t.chatScreen.expandedViewHint} )} {(showCommands && getFilteredCommands().length > 0) || showFilePicker ? ( {showCommands && getFilteredCommands().length > 0 ? t.commandPanel.interactionHint + ' • ' + t.chatScreen.typeToFilterCommands : showFilePicker ? searchMode === 'content' ? t.chatScreen.contentSearchHint : t.chatScreen.fileSearchHint : ''} ) : null} ({ id: s.id, name: s.name, description: s.description, location: s.location, }))} selectedIndex={skillsSelectedIndex} visible={showSkillsPicker} maxHeight={5} isLoading={skillsIsLoading} searchQuery={skillsSearchQuery} appendText={skillsAppendText} focus={skillsFocus} /> )} ); } ================================================ FILE: source/ui/components/chat/CodebaseSearchStatus.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; export type CodebaseSearchStatusData = { isSearching: boolean; attempt?: number; maxAttempts?: number; currentTopN?: number; message: string; query?: string; originalResultsCount?: number; suggestion?: string; }; type Props = { status: CodebaseSearchStatusData; }; // 截断Query字符串，避免过长影响观感 function truncateQuery(query: string, maxLength: number = 50): string { if (query.length <= maxLength) { return query; } return query.slice(0, maxLength) + '...'; } export default function CodebaseSearchStatus({status}: Props) { const {theme} = useTheme(); if (status.isSearching) { // 搜索中状态 return ( ◉ Codebase Search {status.attempt && ( (Attempt {status.attempt}/{status.maxAttempts}) )} {/* Show current query */} {status.query && ( Query: "{truncateQuery(status.query)}" )} {/* Show original results count if reviewing */} {status.originalResultsCount !== undefined && ( Found {status.originalResultsCount} results, reviewing with AI... )} {/* Show basic message if no detailed info yet */} {status.originalResultsCount === undefined && ( {status.message} )} ); } return null; } ================================================ FILE: source/ui/components/chat/LoadingIndicator.tsx ================================================ import React, {useSyncExternalStore} from 'react'; import {Box, Text} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import ShimmerText from '../common/ShimmerText.js'; import CodebaseSearchStatus from './CodebaseSearchStatus.js'; import {formatElapsedTime} from '../../../utils/core/textUtils.js'; import { subscribeTeammateStream, getTeammateStreamSnapshot, subscribeSubAgentStream, getSubAgentStreamSnapshot, } from '../../../hooks/conversation/core/subAgentMessageHandler.js'; /** * 截断错误消息，避免过长显示 */ function truncateErrorMessage( message: string, maxLength: number = 100, ): string { if (message.length <= maxLength) { return message; } return message.substring(0, maxLength) + '...'; } function formatTokens(count: number): string { if (count >= 1000) return `${(count / 1000).toFixed(1)}k`; return String(count); } type LoadingIndicatorProps = { isStreaming: boolean; isStopping: boolean; isSaving: boolean; hasPendingToolConfirmation: boolean; hasPendingUserQuestion: boolean; hasBlockingOverlay: boolean; terminalWidth: number; animationFrame: number; retryStatus: { isRetrying: boolean; errorMessage?: string; remainingSeconds?: number; attempt: number; } | null; codebaseSearchStatus: { isSearching: boolean; attempt: number; maxAttempts: number; currentTopN: number; message: string; query?: string; originalResultsCount?: number; suggestion?: string; } | null; isReasoning: boolean; streamTokenCount: number; elapsedSeconds: number; currentModel?: string | null; teamMode?: boolean; }; export default function LoadingIndicator({ isStreaming, isStopping, isSaving, hasPendingToolConfirmation, hasPendingUserQuestion, hasBlockingOverlay, terminalWidth, animationFrame, retryStatus, codebaseSearchStatus, isReasoning, streamTokenCount, elapsedSeconds, currentModel, teamMode, }: LoadingIndicatorProps) { const {theme} = useTheme(); const {t} = useI18n(); const teammateStream = useSyncExternalStore( subscribeTeammateStream, getTeammateStreamSnapshot, ); const subAgentStream = useSyncExternalStore( subscribeSubAgentStream, getSubAgentStreamSnapshot, ); if ( (!isStreaming && !isSaving && !isStopping) || hasPendingToolConfirmation || hasPendingUserQuestion || hasBlockingOverlay ) { return null; } const showTeamTree = teamMode && teammateStream.length > 0 && isStreaming; const showSubAgentTree = subAgentStream.length > 0 && isStreaming; const renderAgentEntry = ( tm: { agentId: string; agentName: string; tokenCount: number; isReasoning: boolean; ctxUsage?: {percentage: number}; }, isLast: boolean, ) => { const branch = isLast ? '└─' : '├─'; const status = tm.isReasoning ? 'Thinking' : tm.tokenCount > 0 ? 'Writing' : 'Idle'; const statusColor = tm.isReasoning ? theme.colors.warning : tm.tokenCount > 0 ? theme.colors.cyan : theme.colors.menuSecondary; const pct = tm.ctxUsage?.percentage ?? 0; const barWidth = 8; const filled = Math.round((pct / 100) * barWidth); const empty = barWidth - filled; const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty); const barColor = pct >= 80 ? theme.colors.error : pct >= 65 ? theme.colors.warning : pct >= 50 ? theme.colors.cyan : theme.colors.menuSecondary; return ( {' '} {branch}{' '} {tm.agentName} {' '}({status} {tm.tokenCount > 0 && ( <> {' · '} ↓ {formatTokens(tm.tokenCount)} )} ) {pct > 0 && ( {' '} {pct}% {bar} )} ); }; const renderAgentTree = ( entries: Array<{ agentId: string; agentName: string; tokenCount: number; isReasoning: boolean; ctxUsage?: {percentage: number}; }>, title: string, ) => ( {entries.map((tm, idx) => renderAgentEntry(tm, idx === entries.length - 1), )} ); return ( ❆ {isStopping ? ( {t.chatScreen.statusStopping} ) : isStreaming ? ( <> {retryStatus && retryStatus.isRetrying ? ( {retryStatus.errorMessage && ( {t.chatScreen.retryError.replace( '{message}', truncateErrorMessage(retryStatus.errorMessage), )} )} {retryStatus.remainingSeconds !== undefined && retryStatus.remainingSeconds > 0 ? ( {t.chatScreen.retryAttempt .replace('{current}', String(retryStatus.attempt)) .replace('{max}', '5')}{' '} {t.chatScreen.retryIn.replace( '{seconds}', String(retryStatus.remainingSeconds), )} ) : ( {t.chatScreen.retryResending .replace('{current}', String(retryStatus.attempt)) .replace('{max}', '5')} )} ) : codebaseSearchStatus?.isSearching ? ( ) : showTeamTree ? ( ({' '} {currentModel && ( <> {currentModel} {' · '} )} {formatElapsedTime(elapsedSeconds)} {' · '} ↓ {formatTokens(streamTokenCount)} tokens {')'} {teammateStream.map((tm, idx) => renderAgentEntry(tm, idx === teammateStream.length - 1), )} ) : showSubAgentTree ? ( renderAgentTree( subAgentStream, `⚑ Sub-Agent Working (${formatElapsedTime(elapsedSeconds)})`, ) ) : ( 0 ? t.chatScreen.statusWriting : t.chatScreen.statusThinking } /> ({' '} {currentModel && ( <> {currentModel} {' · '} )} {formatElapsedTime(elapsedSeconds)} {' · '} ↓ {formatTokens(streamTokenCount)} tokens {')'} )} ) : ( {t.chatScreen.sessionCreating} )} ); } ================================================ FILE: source/ui/components/chat/MessageList.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {SelectedFile} from '../../../utils/core/fileUtils.js'; import MarkdownRenderer from '../common/MarkdownRenderer.js'; import {useI18n} from '../../../i18n/I18nContext.js'; export interface Message { role: 'user' | 'assistant' | 'command' | 'subagent'; content: string; streaming?: boolean; discontinued?: boolean; aiCompletionTime?: Date | string; messageStatus?: 'pending' | 'success' | 'error'; commandName?: string; hideCommandName?: boolean; // Don't show command name prefix for output chunks plainOutput?: boolean; // Don't show any prefix/icon, just plain text files?: SelectedFile[]; images?: Array<{ type: 'image'; data: string; mimeType: string; }>; // IDE editor context (VSCode workspace, active file, cursor position, selected code) // This field is stored separately and only used when sending to AI, not displayed in UI editorContext?: { workspaceFolder?: string; activeFile?: string; cursorPosition?: {line: number; character: number}; selectedText?: string; }; toolCall?: { name: string; arguments: any; }; toolDisplay?: { toolName: string; args: Array<{key: string; value: string; isLast: boolean}>; }; toolResult?: string; // Raw JSON string from tool execution for preview toolCallId?: string; // Tool call ID for updating message in place toolPending?: boolean; // Whether the tool is still executing isExecuting?: boolean; // Whether a custom command is executing in terminal terminalResult?: { stdout?: string; stderr?: string; exitCode?: number; command?: string; }; // Custom command execution state customCommandExecution?: { command: string; commandName: string; isRunning: boolean; output: string[]; exitCode?: number | null; error?: string; }; subAgent?: { agentId: string; agentName: string; isComplete?: boolean; }; subAgentInternal?: boolean; // Mark internal sub-agent messages to filter from API requests subAgentContent?: boolean; // Persisted sub-agent thinking/content replay message subAgentUsage?: { inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number; }; subAgentContextUsage?: { percentage: number; inputTokens: number; maxTokens: number; }; parallelGroup?: string; // Group ID for parallel tool execution (same ID = executed together) hookError?: { type: 'warning' | 'error'; exitCode: number; command: string; output?: string; error?: string; }; // Hook error details for rendering with HookErrorDisplay thinking?: string; // Extended Thinking content from Anthropic streamingLine?: boolean; // Individual line emitted during streaming (rendered in Static area) isThinkingLine?: boolean; // This streaming line is a thinking/reasoning line isFirstStreamLine?: boolean; // First streaming line of the response (shows ❆ icon) isFirstContentLine?: boolean; // First content streaming line (fallback icon when thinking hidden) pendingToolIds?: string[]; // Track pending tool call IDs in sub-agent compact mode /** Present when a user message was directed to specific running sub-agents via >> picker */ subAgentDirected?: { targets: Array<{agentName: string; promptSnippet: string}>; }; } interface Props { messages: Message[]; animationFrame: number; maxMessages?: number; } const STREAM_COLORS = ['#FF6EBF', 'green', 'blue', 'cyan', '#B588F8'] as const; function formatCommandResultLines(content: string): string[] { return content .split('\n') .map((line, index) => `${index === 0 ? '└─ ' : ' '}${line || ' '}`); } function formatAiCompletionTime(value: Date | string): string { const date = value instanceof Date ? value : new Date(value); if (Number.isNaN(date.getTime())) { return String(value); } return date.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', second: '2-digit', }); } const MessageList = memo( ({messages, animationFrame, maxMessages = 6}: Props) => { const {t} = useI18n(); if (messages.length === 0) { return null; } return ( {messages.slice(-maxMessages).map((message, index) => { if (message.aiCompletionTime) { const completionTime = formatAiCompletionTime( message.aiCompletionTime, ); return ( {t.chatScreen.aiCompletionTimeMessage.replace( '{time}', completionTime, )} ); } const iconColor = message.role === 'user' ? message.subAgentDirected ? 'magenta' : 'green' : message.role === 'command' ? 'gray' : message.role === 'subagent' ? 'magenta' : message.streaming ? (STREAM_COLORS[animationFrame] as any) : 'cyan'; return ( {message.role === 'user' ? message.subAgentDirected ? '»' : '❯' : message.role === 'command' ? '⌘' : message.role === 'subagent' ? '◈' : '❆'} {message.role === 'user' && message.subAgentDirected && message.subAgentDirected.targets.length > 0 && ( {message.subAgentDirected.targets.map( (target, ti, arr) => { const isLast = ti === arr.length - 1; const branch = isLast ? '└─' : '├─'; return ( {branch}{' '} {target.agentName} {target.promptSnippet ? ( {' '} {target.promptSnippet} ) : null} ); }, )} )} {message.role === 'command' ? ( {!message.hideCommandName && ( {message.commandName} )} {message.content && formatCommandResultLines(message.content).map( (line, lineIndex) => ( {line} ), )} ) : message.role === 'subagent' ? ( <> └─ Sub-Agent: {message.subAgent?.agentName} {message.subAgent?.isComplete ? ' ✓' : ' ...'} {message.content || ' '} ) : ( <> {message.role === 'user' ? ( {(message.content && message.content.length > 0 ? message.content : ' ' ) .split('\n') .map(line => ` ${line || ' '} `) .join('\n')} ) : ( )} {(message.files || message.images) && ( {message.files && message.files.length > 0 && ( <> {message.files.map((file, fileIndex) => ( {file.isImage ? `└─ [image #{fileIndex + 1}] ${file.path}` : `└─ Read \`${file.path}\`${ file.exists ? ` (total line ${file.lineCount})` : ' (file not found)' }`} ))} )} {message.images && message.images.length > 0 && ( <> {message.images.map((_image, imageIndex) => ( └─ [image #{imageIndex + 1}] ))} )} )} {/* Show terminal execution result */} {message.toolCall && message.toolCall.name === 'terminal-execute' && message.toolCall.arguments.command && ( └─ Command:{' '} {message.toolCall.arguments.command} └─ Exit Code:{' '} {message.toolCall.arguments.exitCode} {message.toolCall.arguments.stdout && message.toolCall.arguments.stdout.trim().length > 0 && ( └─ stdout: {message.toolCall.arguments.stdout .trim() .split('\n') .slice(0, 20) .join('\n')} {message.toolCall.arguments.stdout .trim() .split('\n').length > 20 && ( ... (output truncated) )} )} {message.toolCall.arguments.stderr && message.toolCall.arguments.stderr.trim().length > 0 && ( └─ stderr: {message.toolCall.arguments.stderr .trim() .split('\n') .slice(0, 10) .join('\n')} {message.toolCall.arguments.stderr .trim() .split('\n').length > 10 && ( ... (output truncated) )} )} )} {message.discontinued && ( {t.chatScreen.discontinuedMessage} )} )} ); })} ); }, (prevProps, nextProps) => { const hasStreamingMessage = nextProps.messages.some(m => m.streaming); if (hasStreamingMessage) { return ( prevProps.messages === nextProps.messages && prevProps.animationFrame === nextProps.animationFrame ); } return prevProps.messages === nextProps.messages; }, ); MessageList.displayName = 'MessageList'; export default MessageList; ================================================ FILE: source/ui/components/chat/MessageRenderer.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import {type Message} from './MessageList.js'; import MarkdownRenderer from '../common/MarkdownRenderer.js'; import DiffViewer from '../tools/DiffViewer.js'; import ToolResultPreview from '../tools/ToolResultPreview.js'; import {HookErrorDisplay} from '../special/HookErrorDisplay.js'; import {maskSkillInjectedText} from '../../../utils/ui/skillMask.js'; import {toCodePoints, visualWidth} from '../../../utils/core/textUtils.js'; /** * Clean thinking content by removing XML-like tags * Some third-party APIs may include or tags */ function cleanThinkingContent(content: string): string { return content.replace(/\s*<\/?think(?:ing)?>\s*/gi, '').trim(); } type Props = { message: Message; index: number; filteredMessages: Message[]; terminalWidth: number; showThinking?: boolean; }; export default function MessageRenderer({ message, index, filteredMessages, terminalWidth, showThinking = true, }: Props) { const {theme} = useTheme(); const {t} = useI18n(); if (message.streamingLine) { if (message.isThinkingLine && !showThinking) return null; const showIcon = message.isFirstStreamLine || (message.isFirstContentLine === true && !showThinking); return ( {showIcon ? '❆' : ' '} {message.isThinkingLine ? ( {message.content || ' '} ) : ( )} ); } // If showThinking is false and message only has thinking content (no actual content), // don't render anything to avoid showing empty ❆ icon if ( !showThinking && message.thinking && !message.content && !message.toolCall && !message.toolResult && !message.terminalResult && !message.discontinued && !message.hookError ) { return null; } // Helper function to remove ANSI escape codes const removeAnsiCodes = (text: string): string => { return text.replace(/\x1b\[[0-9;]*m/g, ''); }; const getDisplayContent = (content: string): string => { // 只做视觉隐藏：保留原始 message.content 用于请求体/持久化。 return maskSkillInjectedText(removeAnsiCodes(content || '')).displayText; }; const wrapTextToVisualWidth = (text: string, maxWidth: number): string[] => { const safeWidth = Math.max(maxWidth, 1); const normalized = text.length > 0 ? text : ' '; const wrappedLines: string[] = []; for (const rawLine of normalized.split('\n')) { const line = rawLine.length > 0 ? rawLine : ' '; let currentLine = ''; let currentWidth = 0; for (const char of toCodePoints(line)) { const charWidth = Math.max(visualWidth(char), 1); if (currentWidth > 0 && currentWidth + charWidth > safeWidth) { wrappedLines.push(currentLine); currentLine = char; currentWidth = charWidth; continue; } currentLine += char; currentWidth += charWidth; } wrappedLines.push(currentLine || ' '); } return wrappedLines; }; const formatUserBubbleLines = ( text: string, totalWidth: number, ): string[] => { const safeTotalWidth = Math.max(totalWidth, 2); const contentWidth = Math.max(safeTotalWidth - 2, 1); return wrapTextToVisualWidth(text, contentWidth).map(line => { const trailingSpaces = ' '.repeat( Math.max(contentWidth - visualWidth(line), 0), ); return ` ${line}${trailingSpaces} `; }); }; const formatCommandResultLines = (content: string): string[] => { return getDisplayContent(content) .split('\n') .map((line, index) => `${index === 0 ? '└─ ' : ' '}${line || ' '}`); }; const formatAiCompletionTime = (value: Date | string): string => { const date = value instanceof Date ? value : new Date(value); if (Number.isNaN(date.getTime())) { return String(value); } return date.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', second: '2-digit', }); }; if (message.aiCompletionTime) { const completionTime = formatAiCompletionTime(message.aiCompletionTime); return ( {t.chatScreen.aiCompletionTimeMessage.replace( '{time}', completionTime, )} ); } // Determine tool message type and color let toolStatusColor: string = 'cyan'; // Check if this message is part of a parallel group const isInParallelGroup = message.parallelGroup !== undefined && message.parallelGroup !== null; // Check if this is a time-consuming tool (has toolPending or status is pending) // Time-consuming tools should not show parallel group indicators const isTimeConsumingTool = message.toolPending || message.messageStatus === 'pending'; // Only show parallel group indicators for non-time-consuming tools const shouldShowParallelIndicator = isInParallelGroup && !isTimeConsumingTool; const isFirstInGroup = shouldShowParallelIndicator && (index === 0 || filteredMessages[index - 1]?.parallelGroup !== message.parallelGroup || // Previous message is time-consuming tool, so this is the first non-time-consuming one filteredMessages[index - 1]?.toolPending || filteredMessages[index - 1]?.messageStatus === 'pending'); // Check if this is the last message in the parallel group // Show end indicator if next message is not in the same parallel group const nextMessage = filteredMessages[index + 1]; const nextInSameGroup = nextMessage && nextMessage.parallelGroup !== undefined && nextMessage.parallelGroup !== null && nextMessage.parallelGroup === message.parallelGroup; const isLastInGroup = shouldShowParallelIndicator && !nextInSameGroup; const leadingIndicator = shouldShowParallelIndicator && !isFirstInGroup ? '│' : ''; const messageIcon = message.role === 'user' ? message.subAgentDirected ? '»' : '❯' : message.role === 'command' ? '⌘' : '❆'; const messagePrefix = `${leadingIndicator}${messageIcon}`; const contentColumnWidth = Math.max( terminalWidth - 2 - visualWidth(messagePrefix) - 1, 1, ); if (message.role === 'assistant' || message.role === 'subagent') { // 优先使用结构化状态字段（用于持久化/恢复时避免硬编码匹配颜色） if (message.messageStatus === 'pending') { toolStatusColor = 'yellowBright'; } else if (message.messageStatus === 'success') { toolStatusColor = 'green'; } else if (message.messageStatus === 'error') { toolStatusColor = 'red'; } else { // subAgentInternal 消息使用 cyan，其他 subagent 消息使用 magenta if ( message.subAgentContent === true || (message.role === 'subagent' && message.subAgentInternal === true) ) { toolStatusColor = 'cyan'; } else { toolStatusColor = message.role === 'subagent' ? 'magenta' : 'blue'; } } } return ( {message.plainOutput ? ( {getDisplayContent(message.content)} ) : ( <> {/* Show parallel group indicator */} {isFirstInGroup && ( {t.chatScreen.parallelStart} )} {messagePrefix} {/* Show target sub-agent tree for directed messages */} {message.role === 'user' && message.subAgentDirected && message.subAgentDirected.targets.length > 0 && ( {message.subAgentDirected.targets.map((target, ti, arr) => { const isLast = ti === arr.length - 1; const branch = isLast ? '└─' : '├─'; return ( {branch}{' '} {target.agentName} {target.promptSnippet ? ( {' '} {target.promptSnippet} ) : null} ); })} )} {message.role === 'command' ? ( <> {!message.hideCommandName && ( {message.commandName} )} {message.content && ( {formatCommandResultLines(message.content).map( (line, lineIndex) => ( {line} ), )} )} ) : ( <> {message.plainOutput ? ( {removeAnsiCodes(message.content || ' ')} ) : ( (() => { // Check if message has hookError field if (message.hookError) { return ; } // Check if content is a hook-error JSON try { const parsed = JSON.parse(message.content); if (parsed.type === 'hook-error') { return ( ); } } catch { // Not JSON, continue with normal rendering } // For tool messages with status, render as plain text with color // instead of using MarkdownRenderer which ignores the toolStatusColor const hasToolStatus = message.messageStatus !== undefined; const isSubAgentInternal = message.subAgentInternal === true; const isSubAgentContent = message.subAgentContent === true; if ( (hasToolStatus || (isSubAgentInternal && !isSubAgentContent)) && (message.role === 'assistant' || message.role === 'subagent') ) { const content = message.content || ' '; const lines = content.split('\n'); const titleLine = lines[0] || ''; const treeLines = lines.slice(1); // Calculate context usage bar for sub-agent messages const ctxUsage = message.subAgentContextUsage; const showCtxBar = ctxUsage && ctxUsage.percentage > 0; return ( <> {removeAnsiCodes(titleLine)} {treeLines.length > 0 && ( {treeLines .map(line => removeAnsiCodes(line || '')) .join('\n')} )} {showCtxBar && (() => { const pct = ctxUsage.percentage; const barWidth = 10; const filled = Math.round( (pct / 100) * barWidth, ); const empty = barWidth - filled; const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty); const barColor = pct >= 80 ? 'red' : pct >= 65 ? 'yellow' : pct >= 50 ? 'cyan' : 'gray'; return ( {'└─ Context: '} {pct} {'% '} {bar} ); })()} ); } return ( <> {message.thinking && showThinking && ( {cleanThinkingContent(message.thinking)} )} {message.role === 'user' ? ( {formatUserBubbleLines( getDisplayContent(message.content), contentColumnWidth, ).map((line, lineIndex) => ( {line} ))} ) : message.content ? ( ) : null} ); })() )} {/* Show sub-agent token usage */} {message.subAgentUsage && (() => { const formatTokens = (num: number) => { if (num >= 1000) return `${(num / 1000).toFixed(1)}K`; return num.toString(); }; return ( └─ Usage: In= {formatTokens(message.subAgentUsage.inputTokens)}, Out= {formatTokens(message.subAgentUsage.outputTokens)} {message.subAgentUsage.cacheReadInputTokens ? `, Cache Read=${formatTokens( message.subAgentUsage.cacheReadInputTokens, )}` : ''} {message.subAgentUsage.cacheCreationInputTokens ? `, Cache Create=${formatTokens( message.subAgentUsage.cacheCreationInputTokens, )}` : ''} ); })()} {/* Sub-agent context usage progress bar is rendered inside the subAgentInternal IIFE path above (line ~287). Do NOT duplicate here. */} {message.toolDisplay && message.toolDisplay.args.length > 0 && // Hide tool arguments for sub-agent internal tools !message.subAgentInternal && ( {message.toolDisplay.args.map((arg, argIndex) => ( {arg.isLast ? '└─' : '├─'} {arg.key}: {arg.value} ))} )} {message.toolCall && message.toolCall.name === 'filesystem-create' && message.toolCall.arguments.content && ( )} {message.toolCall && (message.toolCall.name === 'filesystem-edit' || message.toolCall.name === 'filesystem-replaceedit') && message.toolCall.arguments.oldContent && message.toolCall.arguments.newContent && ( )} {/* Show batch edit results */} {message.toolCall && (message.toolCall.name === 'filesystem-edit' || message.toolCall.name === 'filesystem-replaceedit') && message.toolCall.arguments.isBatch && message.toolCall.arguments.batchResults && Array.isArray(message.toolCall.arguments.batchResults) && ( {message.toolCall.arguments.batchResults.map( (fileResult: any, index: number) => { if ( fileResult.success && fileResult.oldContent && fileResult.newContent ) { return ( {`File ${index + 1}: ${fileResult.path}`} ); } return null; }, )} )} {/* Show tool result preview for successful tool executions */} {message.messageStatus === 'success' && message.toolResult && // 只在没有 diff 数据时显示预览（有 diff 的工具会用 DiffViewer 显示） !( message.toolCall && (message.toolCall.arguments?.oldContent || message.toolCall.arguments?.batchResults) ) && ( )} {message.files && message.files.length > 0 && ( {message.files.map((file, fileIndex) => ( └─ {file.path} {file.exists ? ` (total line ${file.lineCount})` : ' (file not found)'} ))} )} {/* Images for user messages */} {message.role === 'user' && message.images && message.images.length > 0 && ( {message.images.map((_image, imageIndex) => ( └─ [image #{imageIndex + 1}] ))} )} {message.discontinued && ( {t.chatScreen.discontinuedMessage} )} )} {/* Show parallel group end indicator */} {!message.plainOutput && isLastInGroup && ( {t.chatScreen.parallelEnd} )} )} ); } ================================================ FILE: source/ui/components/chat/PendingMessages.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/index.js'; interface PendingMessage { text: string; images?: Array<{data: string; mimeType: string}>; } interface Props { pendingMessages: PendingMessage[]; } export default function PendingMessages({pendingMessages}: Props) { const {theme} = useTheme(); const {t} = useI18n(); if (pendingMessages.length === 0) { return null; } return ( {t.chatScreen.pendingMessagesTitle} ({pendingMessages.length}) {pendingMessages.map((message, index) => ( {index + 1}. {message.text.length > 60 ? `${message.text.substring(0, 60)}...` : message.text} {message.images && message.images.length > 0 && ( └─{' '} {t.chatScreen.pendingMessagesImagesAttached.replace( '{count}', String(message.images.length), )} )} ))} {t.chatScreen.pendingMessagesFooter} {t.chatScreen.pendingMessagesEscHint} ); } ================================================ FILE: source/ui/components/chat/PendingToolCalls.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import type {Message} from './MessageList.js'; import Spinner from 'ink-spinner'; interface Props { messages: Message[]; } /** * 显示正在执行的工具调用(只显示耗时工具) * 这些消息有 toolPending: true 标记 */ export default function PendingToolCalls({messages}: Props) { // 筛选出正在执行的工具调用消息 const pendingTools = messages.filter( msg => msg.role === 'assistant' && msg.toolPending === true, ); if (pendingTools.length === 0) { return null; } return ( Executing Tools ({pendingTools.length}) {pendingTools.map((tool, index) => ( {index + 1}. {tool.content} {/* 显示工具参数 - 完整显示所有参数 */} {tool.toolDisplay && tool.toolDisplay.args.length > 0 && ( {tool.toolDisplay.args.map((arg, argIndex) => ( {arg.key}: {arg.value} ))} )} ))} ); } ================================================ FILE: source/ui/components/chat/UserMessagePreview.tsx ================================================ import React, {useMemo} from 'react'; import {useTerminalSize} from '../../../hooks/ui/useTerminalSize.js'; import MessageRenderer from './MessageRenderer.js'; import {type Message} from './MessageList.js'; type Props = { content: string; }; export default function UserMessagePreview({content}: Props) { const {columns: terminalWidth} = useTerminalSize(); const message = useMemo( () => ({ role: 'user', content, }), [content], ); const filteredMessages = useMemo(() => [message], [message]); return ( ); } ================================================ FILE: source/ui/components/common/MarkdownRenderer.tsx ================================================ import React from 'react'; import {Text, Box} from 'ink'; import {marked} from 'marked'; import {markedTerminal} from 'marked-terminal'; import {supportsLanguage} from 'cli-highlight'; import logger from '../../../utils/core/logger.js'; import { latexToUnicode, simpleLatexToUnicode, } from '../../../utils/latex/unicodeMath.js'; // Configure marked with marked-terminal renderer (unified pipeline) // markedTerminal already provides: cli-highlight for all languages, // OSC 8 hyperlinks, chalk-based bold/italic/etc, pretty tables marked.use( markedTerminal( { width: process.stdout.columns || 80, reflowText: true, unescape: true, showSectionPrefix: false, tab: 2, }, {ignoreIllegals: true} as any, ) as any, ); // Fix markedTerminal bug: its `text` renderer ignores inline tokens (strong, em, etc.) // by only reading token.text (raw string). We override it to parse inline tokens properly. marked.use({ renderer: { text(token: any) { if (typeof token === 'object') { if (token.tokens) { return (this as any).parser.parseInline(token.tokens); } return token.text; } return token; }, }, }); // Add LaTeX math support via custom marked extensions marked.use({ extensions: [ { name: 'mathBlock', level: 'block' as const, start(src: string) { return src.indexOf('$$'); }, tokenizer(src: string) { const match = src.match(/^\$\$([\s\S]+?)\$\$/); if (match) { return { type: 'mathBlock', raw: match[0], text: match[1]!.trim(), }; } return undefined; }, renderer(token: any) { try { return `\n${latexToUnicode(token.text, true)}\n`; } catch { return `\n${simpleLatexToUnicode(token.text)}\n`; } }, }, { name: 'mathInline', level: 'inline' as const, start(src: string) { return src.indexOf('$'); }, tokenizer(src: string) { const match = src.match(/^\$([^\n$]+?)\$/); if (match) { return { type: 'mathInline', raw: match[0], text: match[1]!.trim(), }; } return undefined; }, renderer(token: any) { try { return latexToUnicode(token.text, false); } catch { return simpleLatexToUnicode(token.text); } }, }, ], }); // Sanitize unsupported language tags before they reach the highlighter, // preventing highlight.js from emitting console warnings for unknown languages. marked.use({ walkTokens(token: any) { if (token.type === 'code' && token.lang && !supportsLanguage(token.lang)) { token.lang = ''; } }, }); interface Props { content: string; } /** * Sanitize markdown content to prevent rendering issues * Fixes invalid HTML attributes in rendered output */ function sanitizeMarkdownContent(content: string): string { return content.replace(//gi, '
    '); } /** * Fallback renderer for when marked fails * Renders content as plain text to ensure visibility */ function renderFallback(content: string): React.ReactElement { const lines = content.split('\n'); return ( {lines.map((line: string, index: number) => ( {line || ' '} ))} ); } const ANSI_PATTERN = /\x1b\[[0-9;]*m/g; function isEmptyLine(line: string): boolean { return line.replace(ANSI_PATTERN, '').trim() === ''; } /** Trim leading/trailing empty lines and collapse consecutive empty lines */ function trimLines(lines: string[]): string[] { const result: string[] = []; let lastWasEmpty = true; for (const line of lines) { const isEmpty = isEmptyLine(line); if (isEmpty && lastWasEmpty) continue; result.push(line); lastWasEmpty = isEmpty; } while (result.length > 0 && isEmptyLine(result[result.length - 1]!)) { result.pop(); } return result; } export function renderMarkdownToLines(content: string): string[] { try { const sanitized = sanitizeMarkdownContent(content); const rendered = marked.parse(sanitized) as string; if (!rendered || typeof rendered !== 'string') return content.split('\n'); return trimLines(rendered.split('\n')); } catch { return content.split('\n'); } } export default function MarkdownRenderer({content}: Props) { try { const sanitizedContent = sanitizeMarkdownContent(content); const rendered = marked.parse(sanitizedContent) as string; if (!rendered || typeof rendered !== 'string') { logger.warn('[MarkdownRenderer] Invalid rendered output, falling back', { renderedType: typeof rendered, renderedValue: rendered, }); return renderFallback(content); } let lines = rendered.split('\n'); lines = trimLines(lines); if (lines.length > 500) { logger.warn('[MarkdownRenderer] Rendered output has too many lines', { totalLines: lines.length, truncatedTo: 500, }); return ( {lines.slice(0, 500).map((line: string, index: number) => ( {line || ' '} ))} ); } return ( {lines.map((line: string, index: number) => ( {line || ' '} ))} ); } catch (error: any) { if (error?.message?.includes('Number must be >')) { logger.warn( '[MarkdownRenderer] Invalid list numbering detected, falling back to plain text', { error: error.message, }, ); return renderFallback(content); } logger.error( '[MarkdownRenderer] Unexpected error during markdown rendering', { error: error.message, stack: error.stack, }, ); return renderFallback(content); } } ================================================ FILE: source/ui/components/common/Menu.tsx ================================================ import React, {useState, useCallback} from 'react'; import {Box, Text, useInput, useStdout} from 'ink'; import {resetTerminal} from '../../../utils/execution/terminal.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; type MenuOption = { label: string; value: string; color?: string; infoText?: string; clearTerminal?: boolean; }; type Props = { options: MenuOption[]; onSelect: (value: string) => void; onSelectionChange?: (infoText: string, value: string) => void; maxHeight?: number; // Maximum number of visible items defaultIndex?: number; // Initial selected index }; function Menu({ options, onSelect, onSelectionChange, maxHeight, defaultIndex = 0, }: Props) { const {stdout} = useStdout(); const {t} = useI18n(); const {theme} = useTheme(); // Calculate available height first, before initializing state const terminalHeight = stdout?.rows || 24; const headerHeight = 8; // Space for header, borders, etc. const defaultMaxHeight = Math.max(5, terminalHeight - headerHeight); const visibleItemCount = maxHeight || defaultMaxHeight; // Initialize selectedIndex and scrollOffset based on defaultIndex const getInitialScrollOffset = (index: number, visibleCount: number) => { // Center the selected item if possible const halfVisible = Math.floor(visibleCount / 2); const maxOffset = Math.max(0, options.length - visibleCount); return Math.max(0, Math.min(index - halfVisible, maxOffset)); }; const [selectedIndex, setSelectedIndex] = useState(() => Math.min(defaultIndex, options.length - 1), ); const [scrollOffset, setScrollOffset] = useState(() => getInitialScrollOffset(defaultIndex, visibleItemCount), ); // Sync selectedIndex and scrollOffset when defaultIndex changes from parent React.useEffect(() => { const newIndex = Math.min(defaultIndex, options.length - 1); setSelectedIndex(newIndex); setScrollOffset(getInitialScrollOffset(newIndex, visibleItemCount)); }, [defaultIndex, options.length, visibleItemCount]); // Notify parent of selection changes (debounced for performance) const onSelectionChangeRef = React.useRef(onSelectionChange); React.useEffect(() => { onSelectionChangeRef.current = onSelectionChange; }, [onSelectionChange]); React.useEffect(() => { const currentOption = options[selectedIndex]; if (onSelectionChangeRef.current && currentOption?.infoText) { // Use setImmediate to defer the callback to the next event loop iteration // This prevents blocking the UI during rapid key presses const handle = setImmediate(() => { onSelectionChangeRef.current?.( currentOption.infoText!, currentOption.value, ); }); return () => clearImmediate(handle); } return undefined; }, [selectedIndex, options]); // Auto-scroll to keep selected item visible React.useEffect(() => { if (selectedIndex < scrollOffset) { setScrollOffset(selectedIndex); } else if (selectedIndex >= scrollOffset + visibleItemCount) { setScrollOffset(selectedIndex - visibleItemCount + 1); } }, [selectedIndex, scrollOffset, visibleItemCount]); const clearTerminal = useCallback(() => { resetTerminal(stdout); }, [stdout]); const handleInput = useCallback( (_input: string, key: any) => { if (key.upArrow) { setSelectedIndex(prev => (prev > 0 ? prev - 1 : options.length - 1)); } else if (key.downArrow) { setSelectedIndex(prev => (prev < options.length - 1 ? prev + 1 : 0)); } else if (key.return) { const selectedOption = options[selectedIndex]; if (selectedOption) { if (selectedOption.clearTerminal) { clearTerminal(); } onSelect(selectedOption.value); } } }, [options, selectedIndex, onSelect, clearTerminal], ); useInput(handleInput); // Calculate visible options and "more" counts const visibleOptions = options.slice( scrollOffset, scrollOffset + visibleItemCount, ); const hasMoreAbove = scrollOffset > 0; const hasMoreBelow = scrollOffset + visibleItemCount < options.length; const moreAboveCount = scrollOffset; const moreBelowCount = options.length - (scrollOffset + visibleItemCount); return ( {t.menu.navigate} {hasMoreAbove && ( ↑ +{moreAboveCount} more above )} {visibleOptions.map((option, index) => { const actualIndex = scrollOffset + index; return ( {actualIndex === selectedIndex ? '❯ ' : ' '} {option.label} ); })} {hasMoreBelow && ( ↓ +{moreBelowCount} more below )} ); } // Memoize to prevent unnecessary re-renders export default React.memo(Menu, (prevProps, nextProps) => { return ( prevProps.options === nextProps.options && prevProps.onSelect === nextProps.onSelect && prevProps.onSelectionChange === nextProps.onSelectionChange && prevProps.maxHeight === nextProps.maxHeight && prevProps.defaultIndex === nextProps.defaultIndex ); }); ================================================ FILE: source/ui/components/common/PickerList.tsx ================================================ import React, {memo, useMemo} from 'react'; import {Box, Text} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; const DEFAULT_MAX_DISPLAY_ITEMS = 5; interface DisplayWindow { items: T[]; startIndex: number; endIndex: number; } export function usePickerWindow( items: T[], selectedIndex: number, maxDisplayItems?: number, ): { displayedItems: T[]; displayedSelectedIndex: number; hiddenAboveCount: number; hiddenBelowCount: number; effectiveMaxItems: number; } { const effectiveMaxItems = maxDisplayItems ? Math.min(maxDisplayItems, DEFAULT_MAX_DISPLAY_ITEMS) : DEFAULT_MAX_DISPLAY_ITEMS; const displayWindow = useMemo((): DisplayWindow => { if (items.length <= effectiveMaxItems) { return {items, startIndex: 0, endIndex: items.length}; } const halfWindow = Math.floor(effectiveMaxItems / 2); let startIndex = Math.max(0, selectedIndex - halfWindow); let endIndex = Math.min(items.length, startIndex + effectiveMaxItems); if (endIndex - startIndex < effectiveMaxItems) { startIndex = Math.max(0, endIndex - effectiveMaxItems); } return { items: items.slice(startIndex, endIndex), startIndex, endIndex, }; }, [items, selectedIndex, effectiveMaxItems]); const displayedSelectedIndex = useMemo(() => { return displayWindow.items.findIndex(item => { const originalIndex = items.indexOf(item); return originalIndex === selectedIndex; }); }, [displayWindow.items, items, selectedIndex]); return { displayedItems: displayWindow.items, displayedSelectedIndex, hiddenAboveCount: displayWindow.startIndex, hiddenBelowCount: Math.max(0, items.length - displayWindow.endIndex), effectiveMaxItems, }; } interface PickerListProps { items: T[]; selectedIndex: number; visible: boolean; maxDisplayItems?: number; itemHeight?: number; getItemKey: (item: T) => string; renderItem: (item: T, isSelected: boolean) => React.ReactNode; title?: React.ReactNode; header?: React.ReactNode; footer?: React.ReactNode; emptyContent?: React.ReactNode; scrollHintFormat?: (above: number, below: number) => React.ReactNode; } function PickerListInner({ items, selectedIndex, visible, maxDisplayItems, itemHeight = 2, getItemKey, renderItem, title, header, footer, emptyContent, scrollHintFormat, }: PickerListProps) { const {theme} = useTheme(); const { displayedItems, displayedSelectedIndex, hiddenAboveCount, hiddenBelowCount, effectiveMaxItems, } = usePickerWindow(items, selectedIndex, maxDisplayItems); if (!visible) { return null; } if (items.length === 0) { return emptyContent ? ( {emptyContent} ) : null; } const showScrollHint = items.length > effectiveMaxItems; return ( {title && {title}} {header} {displayedItems.map((item, index) => { const isSelected = index === displayedSelectedIndex; return ( {renderItem(item, isSelected)} ); })} {showScrollHint && ( {scrollHintFormat ? ( scrollHintFormat(hiddenAboveCount, hiddenBelowCount) ) : ( ↑↓ to scroll {hiddenAboveCount > 0 && ` · ${hiddenAboveCount} more above`} {hiddenBelowCount > 0 && ` · ${hiddenBelowCount} more below`} )} )} {footer} ); } const PickerList = memo(PickerListInner) as typeof PickerListInner; export default PickerList; ================================================ FILE: source/ui/components/common/ScrollableSelectInput.tsx ================================================ import React, {useState, useMemo, useEffect, useCallback} from 'react'; import {Box, Text, useInput, type Key} from 'ink'; type SelectItem = { label: string; value: string; key?: string; [index: string]: unknown; }; type IndicatorProps = { isSelected: boolean; }; type RenderItemProps = T & { isSelected: boolean; isMarked: boolean; }; type Props = { items: readonly T[]; limit?: number; initialIndex?: number; isFocused?: boolean; indicator?: (props: IndicatorProps) => React.ReactNode; renderItem?: (props: RenderItemProps) => React.ReactNode; onSelect?: (item: T) => void; onHighlight?: (item: T) => void; selectedValues?: ReadonlySet | readonly string[]; onToggleItem?: (item: T) => void; onDeleteSelection?: () => void; disableNumberShortcuts?: boolean; }; function DefaultIndicator({isSelected}: IndicatorProps) { return ( {isSelected ? '>' : ' '} ); } function DefaultItem({ label, isSelected, }: RenderItemProps) { return {label}; } export default function ScrollableSelectInput({ items, limit, initialIndex = 0, isFocused = true, indicator = DefaultIndicator, renderItem, onSelect, onHighlight, selectedValues, onToggleItem, onDeleteSelection, disableNumberShortcuts = false, }: Props) { const totalItems = items.length; const windowSize = totalItems === 0 ? 0 : Math.min(Math.max(limit ?? totalItems, 1), totalItems); const selectedValueSet = useMemo>(() => { if (!selectedValues) { return new Set(); } if (selectedValues instanceof Set) { return selectedValues; } return new Set(selectedValues); }, [selectedValues]); const clampCursor = useCallback( (value: number) => { if (totalItems === 0) { return 0; } // 循环导航:小于 0 → 跳到最后一项,大于最后一项 → 跳到第一项 if (value < 0) { return totalItems - 1; } if (value > totalItems - 1) { return 0; } return value; }, [totalItems], ); const computeOffset = useCallback( (currentOffset: number, targetCursor: number) => { if (totalItems === 0 || windowSize === 0) { return 0; } const maxOffset = Math.max(0, totalItems - windowSize); let nextOffset = Math.min(Math.max(currentOffset, 0), maxOffset); if (targetCursor < nextOffset) { nextOffset = targetCursor; } else if (targetCursor >= nextOffset + windowSize) { nextOffset = targetCursor - windowSize + 1; } return Math.min(Math.max(nextOffset, 0), maxOffset); }, [totalItems, windowSize], ); const [cursor, setCursor] = useState(() => clampCursor(initialIndex)); const [offset, setOffset] = useState(() => computeOffset(clampCursor(initialIndex), clampCursor(initialIndex)), ); useEffect(() => { if (totalItems === 0) { if (cursor !== 0) { setCursor(0); } if (offset !== 0) { setOffset(0); } return; } const clampedCursor = clampCursor(cursor); if (clampedCursor !== cursor) { setCursor(clampedCursor); return; } const clampedOffset = computeOffset(offset, clampedCursor); if (clampedOffset !== offset) { setOffset(clampedOffset); } }, [clampCursor, computeOffset, cursor, offset, totalItems]); const visibleItems = useMemo(() => { if (windowSize === 0) { return [] as T[]; } return items.slice(offset, offset + windowSize); }, [items, offset, windowSize]); const selectedItem = totalItems === 0 ? undefined : items[cursor]; useEffect(() => { if (selectedItem && onHighlight) { onHighlight(selectedItem); } }, [onHighlight, selectedItem]); const moveCursor = useCallback( (direction: -1 | 1) => { if (totalItems === 0) { return; } setCursor(previousCursor => { const rawNext = previousCursor + direction; const nextCursor = clampCursor(rawNext); if (nextCursor === previousCursor) { return previousCursor; } // 检测是否发生循环跳转 const isWrapping = (direction === -1 && rawNext < 0) || (direction === 1 && rawNext > totalItems - 1); if (isWrapping) { // 循环时直接设置偏移到正确位置 if (nextCursor === 0) { // 跳到第一项，偏移设为 0 setOffset(0); } else { // 跳到最后一项，偏移设为最大值 const maxOffset = Math.max(0, totalItems - windowSize); setOffset(maxOffset); } } else { setOffset(previousOffset => computeOffset(previousOffset, nextCursor), ); } return nextCursor; }); }, [clampCursor, computeOffset, totalItems, windowSize], ); const selectIndex = useCallback( (targetIndex: number) => { if (totalItems === 0) { return; } const boundedIndex = clampCursor(targetIndex); setCursor(boundedIndex); setOffset(previousOffset => computeOffset(previousOffset, boundedIndex)); const item = items[boundedIndex]; if (item) { onSelect?.(item); } }, [clampCursor, computeOffset, items, onSelect, totalItems], ); const handleInput = useCallback( (input: string, key: Key) => { if (!isFocused || totalItems === 0) { return; } if (key.upArrow) { moveCursor(-1); return; } if (key.downArrow) { moveCursor(1); return; } if (key.return && selectedItem) { onSelect?.(selectedItem); return; } if (input === ' ' && selectedItem) { onToggleItem?.(selectedItem); return; } if ((input === 'd' || input === 'D') && onDeleteSelection) { onDeleteSelection(); return; } if (!disableNumberShortcuts && /^[1-9]$/.test(input) && windowSize > 0) { const target = Number.parseInt(input, 10) - 1; if (target >= 0 && target < visibleItems.length) { selectIndex(offset + target); } } }, [ isFocused, moveCursor, offset, onDeleteSelection, onSelect, onToggleItem, selectIndex, selectedItem, totalItems, visibleItems.length, windowSize, disableNumberShortcuts, ], ); useInput(handleInput, {isActive: isFocused}); if (windowSize === 0) { return null; } const renderRow = useCallback( (row: RenderItemProps) => { if (renderItem) { return renderItem(row); } return DefaultItem(row); }, [renderItem], ); return ( {visibleItems.map((item, index) => { const absoluteIndex = offset + index; const isSelected = absoluteIndex === cursor; const isMarked = selectedValueSet.has(item.value); const key = (item.key ?? item.value) as string; return ( {indicator({isSelected})} {renderRow({...item, isSelected, isMarked} as RenderItemProps)} ); })} ); } ================================================ FILE: source/ui/components/common/ShimmerText.tsx ================================================ import React, {useState, useEffect} from 'react'; import {Text} from 'ink'; import chalk from 'chalk'; interface ShimmerTextProps { text: string; } /** * ShimmerText component that displays text with a white shimmer effect flowing through yellow text */ export default function ShimmerText({text}: ShimmerTextProps) { const [frame, setFrame] = useState(0); useEffect(() => { const interval = setInterval(() => { setFrame(prev => (prev + 1) % (text.length + 5)); }, 100); // Update every 100ms for smooth animation return () => clearInterval(interval); }, [text.length]); // Build the colored text with shimmer effect let output = ''; for (let i = 0; i < text.length; i++) { const char = text[i]; const distance = Math.abs(i - frame); // Bright cyan shimmer in the center (distance 0-1) if (distance <= 1) { output += chalk.bold.hex('#00FFFF')(char); // Bright cyan/aqua } // Deep blue for the rest (base color) else { output += chalk.bold.hex('#1ACEB0')(char); // Steel blue } } return {output}; } ================================================ FILE: source/ui/components/common/StatusLine.tsx ================================================ import {execFile} from 'node:child_process'; import {promisify} from 'node:util'; import React from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {getSimpleMode} from '../../../utils/config/themeConfig.js'; import {smartTruncatePath} from '../../../utils/ui/messageFormatter.js'; import { loadProfile, getActiveProfileName, } from '../../../utils/config/configManager.js'; import {useStatusLineHookItems} from './statusline/useStatusLineHooks.js'; import {BUILTIN_STATUSLINE_IDS} from './statusline/builtinIds.js'; import type { BackendConnectionStatus, StatusLineCodebaseProgress, StatusLineContextUsage, StatusLineContextWindowMetrics, StatusLineCopyStatusMessage, StatusLineEditorContext, StatusLineFileUpdateNotification, VSCodeConnectionStatus, } from './statusline/types.js'; const MEMORY_REFRESH_INTERVAL_MS = 5000; const PROCESS_MEMORY_COMMAND_TIMEOUT_MS = 1500; const execFileAsync = promisify(execFile); const WINDOWS_POWERSHELL_CANDIDATES = [ 'pwsh.exe', 'powershell.exe', 'pwsh', 'powershell', ] as const; // 根据平台返回快捷键显示文本: Windows/Linux使用 Alt+P, macOS使用 Ctrl+P const getProfileShortcut = () => process.platform === 'darwin' ? 'Ctrl+P' : 'Alt+P'; function getFallbackProcessMemoryUsageMb(): number { return Math.max(1, process.memoryUsage().rss / (1024 * 1024)); } function parseMacosPhysicalFootprintMb( commandOutput: string, ): number | undefined { const match = commandOutput.match( /Physical footprint:\s+([0-9.]+)\s*([KMGT])/i, ); const valueText = match?.[1]; const unit = match?.[2]?.toUpperCase(); if (!valueText || !unit) { return undefined; } const value = Number.parseFloat(valueText); if (!Number.isFinite(value)) { return undefined; } switch (unit) { case 'T': { return value * 1024 * 1024; } case 'G': { return value * 1024; } case 'M': { return value; } case 'K': { return value / 1024; } default: { return undefined; } } } function parseWindowsMemoryUsageMb(commandOutput: string): number | undefined { const valueText = commandOutput.trim(); if (valueText.length === 0) { return undefined; } const value = Number.parseInt(valueText, 10); if (!Number.isFinite(value)) { return undefined; } return Math.max(1, value / (1024 * 1024)); } async function getMacosProcessMemoryUsageMb(): Promise { try { // macOS 活动监视器更接近 physical footprint，而不是 RSS。 const {stdout} = await execFileAsync( 'vmmap', ['-summary', String(process.pid)], { timeout: PROCESS_MEMORY_COMMAND_TIMEOUT_MS, maxBuffer: 1024 * 1024, }, ); return parseMacosPhysicalFootprintMb(stdout); } catch { return undefined; } } async function getWindowsProcessMemoryUsageMb(): Promise { const script = [ "$ErrorActionPreference = 'Stop'", `$process = Get-CimInstance Win32_PerfFormattedData_PerfProc_Process -Filter \"IDProcess = ${process.pid}\" -ErrorAction SilentlyContinue`, 'if ($null -ne $process -and $null -ne $process.WorkingSetPrivate) { [Console]::Out.Write([string]$process.WorkingSetPrivate); return }', `$fallback = Get-Process -Id ${process.pid} -ErrorAction Stop`, '[Console]::Out.Write([string]$fallback.PrivateMemorySize64)', ].join('; '); for (const shell of WINDOWS_POWERSHELL_CANDIDATES) { try { const {stdout} = await execFileAsync( shell, ['-NoProfile', '-Command', script], { timeout: PROCESS_MEMORY_COMMAND_TIMEOUT_MS, maxBuffer: 1024 * 1024, }, ); const memoryUsageMb = parseWindowsMemoryUsageMb(stdout); if (memoryUsageMb !== undefined) { return memoryUsageMb; } } catch {} } return undefined; } async function getCurrentProcessMemoryUsageMb(): Promise { if (process.platform === 'darwin') { const memoryUsageMb = await getMacosProcessMemoryUsageMb(); if (memoryUsageMb !== undefined) { return Math.max(1, memoryUsageMb); } } if (process.platform === 'win32') { const memoryUsageMb = await getWindowsProcessMemoryUsageMb(); if (memoryUsageMb !== undefined) { return Math.max(1, memoryUsageMb); } } return getFallbackProcessMemoryUsageMb(); } function formatMemoryUsage(memoryUsageMb: number): string { if (memoryUsageMb >= 1024) { return `${(memoryUsageMb / 1024).toFixed(2)} GB`; } return `${memoryUsageMb.toFixed(0)} MB`; } function useCurrentProcessMemoryUsage(): number { const [memoryUsageMb, setMemoryUsageMb] = React.useState(() => getFallbackProcessMemoryUsageMb(), ); React.useEffect(() => { let disposed = false; let isRefreshing = false; const refreshMemoryUsage = async () => { if (isRefreshing) { return; } isRefreshing = true; try { const nextMemoryUsageMb = await getCurrentProcessMemoryUsageMb(); if (!disposed) { setMemoryUsageMb(nextMemoryUsageMb); } } finally { isRefreshing = false; } }; void refreshMemoryUsage(); const timer = setInterval(() => { void refreshMemoryUsage(); }, MEMORY_REFRESH_INTERVAL_MS); return () => { disposed = true; clearInterval(timer); }; }, []); return memoryUsageMb; } type Props = { // 模式信息 yoloMode?: boolean; planMode?: boolean; vulnerabilityHuntingMode?: boolean; toolSearchDisabled?: boolean; hybridCompressEnabled?: boolean; teamMode?: boolean; // IDE连接信息 vscodeConnectionStatus?: VSCodeConnectionStatus; editorContext?: StatusLineEditorContext; // 实例连接信息 connectionStatus?: BackendConnectionStatus; connectionInstanceName?: string; // 词元消耗信息 contextUsage?: StatusLineContextUsage; // 代码库索引状态 codebaseIndexing?: boolean; codebaseProgress?: StatusLineCodebaseProgress | null; // 文件监视器状态 watcherEnabled?: boolean; fileUpdateNotification?: StatusLineFileUpdateNotification | null; copyStatusMessage?: StatusLineCopyStatusMessage | null; // Profile 信息 currentProfileName?: string; // 自动压缩禁止中断提示 compressBlockToast?: string | null; }; function calculateContextPercentage( contextUsage: StatusLineContextUsage, ): number { const hasAnthropicCache = (contextUsage.cacheCreationTokens || 0) > 0 || (contextUsage.cacheReadTokens || 0) > 0; const totalInputTokens = hasAnthropicCache ? contextUsage.inputTokens + (contextUsage.cacheCreationTokens || 0) + (contextUsage.cacheReadTokens || 0) : contextUsage.inputTokens; return Math.min( 100, (totalInputTokens / contextUsage.maxContextTokens) * 100, ); } function buildContextWindowState( contextUsage: StatusLineContextUsage, ): StatusLineContextUsage & StatusLineContextWindowMetrics { const hasAnthropicCache = (contextUsage.cacheCreationTokens || 0) > 0 || (contextUsage.cacheReadTokens || 0) > 0; const hasOpenAICache = (contextUsage.cachedTokens || 0) > 0; const totalInputTokens = hasAnthropicCache ? contextUsage.inputTokens + (contextUsage.cacheCreationTokens || 0) + (contextUsage.cacheReadTokens || 0) : contextUsage.inputTokens; return { ...contextUsage, percentage: calculateContextPercentage(contextUsage), totalInputTokens, hasAnthropicCache, hasOpenAICache, hasAnyCache: hasAnthropicCache || hasOpenAICache, }; } export default function StatusLine({ yoloMode = false, planMode = false, vulnerabilityHuntingMode = false, toolSearchDisabled = true, hybridCompressEnabled = false, teamMode = false, vscodeConnectionStatus, editorContext, connectionStatus, connectionInstanceName, contextUsage, codebaseIndexing = false, codebaseProgress, watcherEnabled = false, fileUpdateNotification, copyStatusMessage, currentProfileName, compressBlockToast, }: Props) { const {t, language} = useI18n(); const {theme} = useTheme(); const simpleMode = getSimpleMode(); const memoryUsageMb = useCurrentProcessMemoryUsage(); const formattedMemoryUsage = formatMemoryUsage(memoryUsageMb); const contextWindowState = React.useMemo( () => (contextUsage ? buildContextWindowState(contextUsage) : undefined), [contextUsage], ); // 获取当前 profile 的完整配置（不含 apiKey） const profileConfig = React.useMemo(() => { const profileName = currentProfileName ?? getActiveProfileName(); return loadProfile(profileName); }, [currentProfileName]); const statusLineHookContext = React.useMemo(() => { const cfg = profileConfig?.snowcfg; return { cwd: process.cwd(), platform: process.platform, language, simpleMode, labels: { gitBranch: t.chatScreen.gitBranch, }, system: { memory: { usageMb: memoryUsageMb, formattedUsage: formattedMemoryUsage, }, modes: { yolo: yoloMode, plan: planMode, vulnerabilityHunting: vulnerabilityHuntingMode, toolSearchEnabled: !toolSearchDisabled, hybridCompress: hybridCompressEnabled, team: teamMode, simple: simpleMode, }, ide: { connectionStatus: vscodeConnectionStatus ?? 'disconnected', editorContext, selectedTextLength: editorContext?.selectedText?.length ?? 0, }, backend: { connectionStatus: connectionStatus ?? 'disconnected', instanceName: connectionInstanceName, }, contextWindow: contextWindowState, codebase: { indexing: codebaseIndexing, progress: codebaseProgress, }, watcher: { enabled: watcherEnabled, fileUpdateNotification, }, clipboard: copyStatusMessage, profile: { currentName: currentProfileName, baseUrl: cfg?.baseUrl, requestMethod: cfg?.requestMethod, advancedModel: cfg?.advancedModel, basicModel: cfg?.basicModel, maxContextTokens: cfg?.maxContextTokens, maxTokens: cfg?.maxTokens, anthropicBeta: cfg?.anthropicBeta, anthropicCacheTTL: cfg?.anthropicCacheTTL, thinkingEnabled: cfg?.thinking?.type === 'enabled', thinkingType: cfg?.thinking?.type, thinkingBudgetTokens: cfg?.thinking?.budget_tokens, thinkingEffort: cfg?.thinking?.effort, geminiThinkingEnabled: cfg?.geminiThinking?.enabled, geminiThinkingLevel: cfg?.geminiThinking?.thinkingLevel, responsesReasoningEnabled: cfg?.responsesReasoning?.enabled, responsesReasoningEffort: cfg?.responsesReasoning?.effort, responsesFastMode: cfg?.responsesFastMode, responsesVerbosity: cfg?.responsesVerbosity, anthropicSpeed: cfg?.anthropicSpeed, enablePromptOptimization: cfg?.enablePromptOptimization, enableAutoCompress: cfg?.enableAutoCompress, autoCompressThreshold: cfg?.autoCompressThreshold, showThinking: cfg?.showThinking, streamIdleTimeoutSec: cfg?.streamIdleTimeoutSec, systemPromptId: cfg?.systemPromptId, customHeadersSchemeId: cfg?.customHeadersSchemeId, toolResultTokenLimit: cfg?.toolResultTokenLimit, streamingDisplay: cfg?.streamingDisplay, }, compression: { blockToast: compressBlockToast, }, }, }; }, [ codebaseIndexing, codebaseProgress, compressBlockToast, connectionInstanceName, connectionStatus, contextWindowState, copyStatusMessage, currentProfileName, editorContext, fileUpdateNotification, formattedMemoryUsage, language, memoryUsageMb, planMode, profileConfig, simpleMode, t.chatScreen.gitBranch, toolSearchDisabled, hybridCompressEnabled, teamMode, vscodeConnectionStatus, vulnerabilityHuntingMode, watcherEnabled, yoloMode, ]); const {items: statusLineHookItems, externalHookIds} = useStatusLineHookItems( statusLineHookContext, ); const isBuiltinOverridden = React.useCallback( (id: string) => externalHookIds.has(id), [externalHookIds], ); const simpleMemoryStatusText = `⛁ ${formattedMemoryUsage}`; const detailedMemoryStatusText = `⛁ ${t.chatScreen.memoryUsageLabel} ${formattedMemoryUsage}`; const renderContextUsage = () => { if (!contextWindowState) { return null; } const { percentage, totalInputTokens, hasAnthropicCache, hasOpenAICache, hasAnyCache, cacheReadTokens = 0, cacheCreationTokens = 0, cachedTokens = 0, } = contextWindowState; let color: string; if (percentage < 50) color = theme.colors.success; else if (percentage < 75) color = theme.colors.warning; else if (percentage < 90) color = theme.colors.warning; else color = theme.colors.error; const formatNumber = (num: number) => { if (num >= 1000) return `${(num / 1000).toFixed(1)}k`; return num.toString(); }; return ( {percentage.toFixed(1)}% · {formatNumber(totalInputTokens)} {t.chatScreen.tokens} {hasAnyCache && ( <> · {hasAnthropicCache && ( <> {cacheReadTokens > 0 && ( ↯ {formatNumber(cacheReadTokens)} {t.chatScreen.cached} )} {cacheCreationTokens > 0 && ( <> {cacheReadTokens > 0 && · } ◆ {formatNumber(cacheCreationTokens)}{' '} {t.chatScreen.newCache} )} )} {hasOpenAICache && ( ↯ {formatNumber(cachedTokens)} {t.chatScreen.cached} )} )} ); }; // 是否显示任何状态信息 const hasAnyStatus = yoloMode || planMode || vulnerabilityHuntingMode || teamMode || !toolSearchDisabled || hybridCompressEnabled || (vscodeConnectionStatus && vscodeConnectionStatus !== 'disconnected') || (connectionStatus && connectionStatus !== 'disconnected') || contextUsage || codebaseIndexing || watcherEnabled || fileUpdateNotification || copyStatusMessage || currentProfileName || compressBlockToast || statusLineHookItems.length > 0 || detailedMemoryStatusText; if (!hasAnyStatus) { return null; } // 简易模式：横向单行显示状态，词元信息单独一行 if (simpleMode) { const statusItems: Array<{text: string; color: string}> = []; if ( currentProfileName && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.profile) ) { statusItems.push({ text: `§ ${currentProfileName}`, color: theme.colors.menuInfo, }); } for (const item of statusLineHookItems) { statusItems.push({ text: item.text, color: item.color || theme.colors.menuSecondary, }); } if (yoloMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modeYolo)) { statusItems.push({text: '⧴ YOLO', color: theme.colors.warning}); } if (planMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modePlan)) { statusItems.push({text: '⚐ Plan', color: '#60A5FA'}); } if ( vulnerabilityHuntingMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modeHunt) ) { statusItems.push({text: '⍨ Vuln Hunt', color: '#de409aff'}); } if ( !toolSearchDisabled && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.toolSearch) ) { statusItems.push({ text: '♾︎ ToolSearch ON', color: theme.colors.menuInfo, }); } if (teamMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modeTeam)) { statusItems.push({text: '⚑ Team', color: '#10B981'}); } if ( hybridCompressEnabled && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.hybridCompress) ) { statusItems.push({ text: '⇌ Hybrid Compress', color: theme.colors.menuInfo, }); } if ( vscodeConnectionStatus && vscodeConnectionStatus !== 'disconnected' && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.ideConnection) ) { if (vscodeConnectionStatus === 'connecting') { statusItems.push({text: '◐ IDE', color: 'yellow'}); } else if (vscodeConnectionStatus === 'connected') { statusItems.push({text: '● IDE', color: 'green'}); } else if (vscodeConnectionStatus === 'error') { statusItems.push({text: '○ IDE', color: 'gray'}); } } if ( connectionStatus && connectionStatus !== 'disconnected' && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.backendConnection) ) { if (connectionStatus === 'connecting') { statusItems.push({text: '◐ Backend', color: 'yellow'}); } else if (connectionStatus === 'reconnecting') { statusItems.push({text: '↻ Backend', color: 'yellow'}); } else if (connectionStatus === 'connected') { const instanceLabel = connectionInstanceName ? `● ${connectionInstanceName}` : '● Backend'; statusItems.push({text: instanceLabel, color: 'green'}); } } if ( (codebaseIndexing || codebaseProgress?.error) && codebaseProgress && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.codebaseIndexing) ) { if (codebaseProgress.error) { statusItems.push({ text: codebaseProgress.error, color: 'yellow', }); } else { statusItems.push({ text: `◐ ${t.chatScreen.codebaseIndexingShort || '索引'} ${ codebaseProgress.processedFiles }/${codebaseProgress.totalFiles}`, color: 'cyan', }); } } if ( !codebaseIndexing && watcherEnabled && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.watcher) ) { statusItems.push({ text: `☉ ${t.chatScreen.statusWatcherActiveShort || '监视'}`, color: 'green', }); } if ( fileUpdateNotification && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.fileUpdate) ) { statusItems.push({ text: `⛁ ${t.chatScreen.statusFileUpdatedShort || '已更新'}`, color: 'yellow', }); } if ( copyStatusMessage && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.copyStatus) ) { statusItems.push({ text: copyStatusMessage.text, color: copyStatusMessage.isError ? theme.colors.error : theme.colors.success, }); } if ( compressBlockToast && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.compressBlock) ) { statusItems.push({ text: compressBlockToast, color: theme.colors.warning, }); } if (!isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.memory)) { statusItems.push({ text: simpleMemoryStatusText, color: theme.colors.menuSecondary, }); } return ( {contextUsage && {renderContextUsage()}} {statusItems.length > 0 && ( {statusItems.map((item, index) => ( {index > 0 && ( | )} {item.text} ))} )} ); } return ( {contextUsage && {renderContextUsage()}} {currentProfileName && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.profile) && ( § {t.chatScreen.profileCurrent}: {currentProfileName} |{' '} {getProfileShortcut()} {t.chatScreen.profileSwitchHint} )} {statusLineHookItems.map(item => ( {item.detailedText || item.text} ))} {!isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.memory) && ( {detailedMemoryStatusText} )} {yoloMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modeYolo) && ( {t.chatScreen.yoloModeActive} )} {planMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modePlan) && ( {t.chatScreen.planModeActive} )} {vulnerabilityHuntingMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modeHunt) && ( {t.chatScreen.vulnerabilityHuntingModeActive} )} {!toolSearchDisabled && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.toolSearch) && ( {t.chatScreen.toolSearchEnabled} )} {teamMode && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.modeTeam) && ( {t.chatScreen.teamModeActive} )} {hybridCompressEnabled && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.hybridCompress) && ( {t.chatScreen.hybridCompressEnabled} )} {vscodeConnectionStatus && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.ideConnection) && (vscodeConnectionStatus === 'connecting' || vscodeConnectionStatus === 'connected' || vscodeConnectionStatus === 'error') && ( {vscodeConnectionStatus === 'connecting' ? ( <> {t.chatScreen.ideConnecting} ) : vscodeConnectionStatus === 'error' ? ( <>○ {t.chatScreen.ideError} ) : ( <> ● {t.chatScreen.ideConnected} {editorContext?.activeFile && t.chatScreen.ideActiveFile.replace( '{file}', smartTruncatePath(editorContext.activeFile, 40, false), )} {editorContext?.selectedText && t.chatScreen.ideSelectedText.replace( '{count}', editorContext.selectedText.length.toString(), )} )} )} {connectionStatus && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.backendConnection) && (connectionStatus === 'connecting' || connectionStatus === 'connected' || connectionStatus === 'reconnecting') && ( {connectionStatus === 'connecting' ? ( <> 正在连接后端服务... ) : connectionStatus === 'reconnecting' ? ( <> 正在重连后端服务... ) : ( <> ● 已连接后端服务 {connectionInstanceName && ` (${connectionInstanceName})`} )} )} {(codebaseIndexing || codebaseProgress?.error) && codebaseProgress && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.codebaseIndexing) && ( {codebaseProgress.error ? ( {codebaseProgress.error} ) : ( {' '} {t.chatScreen.codebaseIndexing .replace( '{processed}', codebaseProgress.processedFiles.toString(), ) .replace('{total}', codebaseProgress.totalFiles.toString())} {codebaseProgress.totalChunks > 0 && ` (${t.chatScreen.codebaseProgress.replace( '{chunks}', codebaseProgress.totalChunks.toString(), )})`} )} )} {!codebaseIndexing && watcherEnabled && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.watcher) && ( ☉ {t.chatScreen.statusWatcherActive} )} {fileUpdateNotification && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.fileUpdate) && ( ⛁{' '} {t.chatScreen.statusFileUpdated.replace( '{file}', fileUpdateNotification.file, )} )} {copyStatusMessage && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.copyStatus) && ( {copyStatusMessage.text} )} {compressBlockToast && !isBuiltinOverridden(BUILTIN_STATUSLINE_IDS.compressBlock) && ( {compressBlockToast} )} ); } ================================================ FILE: source/ui/components/common/UpdateNotice.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import {useI18n} from '../../../i18n/index.js'; type UpdateNoticeProps = { currentVersion: string; latestVersion: string; terminalWidth: number; }; export default function UpdateNotice({ currentVersion, latestVersion, terminalWidth, }: UpdateNoticeProps) { const {t} = useI18n(); return ( {t.welcome.updateNoticeTitle} {t.welcome.updateNoticeCurrent}:{' '} {currentVersion} {t.welcome.updateNoticeLatest}:{' '} {latestVersion} {t.welcome.updateNoticeRun}:{' '} snow --update {t.welcome.updateNoticeGithub}:{' '} https://github.com/MayDay-wpf/snow-cli ); } ================================================ FILE: source/ui/components/common/statusline/builtinIds.ts ================================================ /** * 内置 StatusLine 项的稳定 hook id 列表。 * * 用户插件可以通过相同 id 注册外部 hook 来覆盖内置渲染： * 一旦同 id 的外部 hook 出现，StatusLine 组件会跳过对应的内置硬编码渲染， * 改由用户 hook 返回的 StatusLineRenderItem 负责显示。 * * 新增内置项时，请同步在这里登记一个稳定 id，并在中英文 StatusLine 文档 * 的「内置 Hook 列表」一节中更新说明。 */ export const BUILTIN_STATUSLINE_IDS = { profile: 'builtin.profile', modeYolo: 'builtin.mode-yolo', modePlan: 'builtin.mode-plan', modeHunt: 'builtin.mode-hunt', modeTeam: 'builtin.mode-team', toolSearch: 'builtin.tool-search', hybridCompress: 'builtin.hybrid-compress', ideConnection: 'builtin.ide-connection', backendConnection: 'builtin.backend-connection', codebaseIndexing: 'builtin.codebase-indexing', watcher: 'builtin.watcher', fileUpdate: 'builtin.file-update', copyStatus: 'builtin.copy-status', compressBlock: 'builtin.compress-block', memory: 'builtin.memory', gitBranch: 'builtin.git-branch', } as const; export type BuiltinStatusLineId = (typeof BUILTIN_STATUSLINE_IDS)[keyof typeof BUILTIN_STATUSLINE_IDS]; const BUILTIN_STATUSLINE_ID_VALUES = new Set( Object.values(BUILTIN_STATUSLINE_IDS), ); export function isBuiltinStatusLineId(id: string): id is BuiltinStatusLineId { return BUILTIN_STATUSLINE_ID_VALUES.has(id); } ================================================ FILE: source/ui/components/common/statusline/gitBranch.ts ================================================ import {execFile} from 'node:child_process'; import {promisify} from 'node:util'; import type {StatusLineHookDefinition} from './types.js'; const GIT_BRANCH_REFRESH_INTERVAL_MS = 10000; const execFileAsync = promisify(execFile); async function getGitBranch(cwd: string): Promise { try { const {stdout} = await execFileAsync( 'git', ['rev-parse', '--abbrev-ref', 'HEAD'], { timeout: 2000, maxBuffer: 1024, cwd, }, ); const branch = stdout.trim(); return branch || undefined; } catch { return undefined; } } export const gitBranchStatusLineHook: StatusLineHookDefinition = { id: 'builtin.git-branch', refreshIntervalMs: GIT_BRANCH_REFRESH_INTERVAL_MS, async getItems(context) { const branch = await getGitBranch(context.cwd); if (!branch) { return undefined; } return { id: 'git-branch', text: `⑂ ${branch}`, detailedText: `⑂ ${context.labels.gitBranch}: ${branch}`, color: '#F472B6', priority: 100, }; }, }; export default gitBranchStatusLineHook; ================================================ FILE: source/ui/components/common/statusline/types.ts ================================================ import type {Language} from '../../../../utils/config/languageConfig.js'; export type VSCodeConnectionStatus = | 'disconnected' | 'connecting' | 'connected' | 'error'; export type BackendConnectionStatus = | 'disconnected' | 'connecting' | 'connected' | 'reconnecting'; export interface StatusLineRenderItem { id?: string; text: string; detailedText?: string; color?: string; priority?: number; } export interface StatusLineLabels { gitBranch: string; } export interface StatusLineEditorContext { activeFile?: string; selectedText?: string; cursorPosition?: {line: number; character: number}; workspaceFolder?: string; } export interface StatusLineContextUsage { inputTokens: number; maxContextTokens: number; cacheCreationTokens?: number; cacheReadTokens?: number; cachedTokens?: number; } export interface StatusLineCodebaseProgress { totalFiles: number; processedFiles: number; totalChunks: number; currentFile?: string; status?: string; error?: string; } export interface StatusLineFileUpdateNotification { file: string; timestamp: number; } export interface StatusLineCopyStatusMessage { text: string; isError?: boolean; timestamp: number; } export interface StatusLineContextWindowMetrics { percentage: number; totalInputTokens: number; hasAnthropicCache: boolean; hasOpenAICache: boolean; hasAnyCache: boolean; } export interface StatusLineSystemState { memory: { usageMb: number; formattedUsage: string; }; modes: { yolo: boolean; plan: boolean; vulnerabilityHunting: boolean; toolSearchEnabled: boolean; hybridCompress: boolean; team: boolean; simple: boolean; }; ide: { connectionStatus: VSCodeConnectionStatus; editorContext?: StatusLineEditorContext; selectedTextLength: number; }; backend: { connectionStatus: BackendConnectionStatus; instanceName?: string; }; contextWindow?: StatusLineContextUsage & StatusLineContextWindowMetrics; codebase: { indexing: boolean; progress?: StatusLineCodebaseProgress | null; }; watcher: { enabled: boolean; fileUpdateNotification?: StatusLineFileUpdateNotification | null; }; clipboard?: StatusLineCopyStatusMessage | null; profile: { currentName?: string; baseUrl?: string; requestMethod?: string; advancedModel?: string; basicModel?: string; maxContextTokens?: number; maxTokens?: number; anthropicBeta?: boolean; anthropicCacheTTL?: string; thinkingEnabled?: boolean; thinkingType?: string; thinkingBudgetTokens?: number; thinkingEffort?: string; geminiThinkingEnabled?: boolean; geminiThinkingLevel?: string; responsesReasoningEnabled?: boolean; responsesReasoningEffort?: string; responsesFastMode?: boolean; responsesVerbosity?: string; anthropicSpeed?: string; enablePromptOptimization?: boolean; enableAutoCompress?: boolean; autoCompressThreshold?: number; showThinking?: boolean; streamIdleTimeoutSec?: number; systemPromptId?: string | string[]; customHeadersSchemeId?: string; toolResultTokenLimit?: number; streamingDisplay?: boolean; }; compression: { blockToast?: string | null; }; } export interface StatusLineHookContext { cwd: string; platform: NodeJS.Platform; language: Language; simpleMode: boolean; labels: StatusLineLabels; system: StatusLineSystemState; } export interface StatusLineHookDefinition { id: string; refreshIntervalMs?: number; enable?: boolean; getItems: ( context: StatusLineHookContext, ) => | StatusLineRenderItem | StatusLineRenderItem[] | undefined | null | Promise; } ================================================ FILE: source/ui/components/common/statusline/useStatusLineHooks.ts ================================================ import {existsSync, readdirSync} from 'node:fs'; import {extname, join} from 'node:path'; import {pathToFileURL} from 'node:url'; import React from 'react'; import {STATUSLINE_HOOKS_DIR} from '../../../../utils/config/apiConfig.js'; import {logger} from '../../../../utils/core/logger.js'; import {gitBranchStatusLineHook} from './gitBranch.js'; import type { StatusLineHookContext, StatusLineHookDefinition, StatusLineRenderItem, } from './types.js'; const DEFAULT_STATUSLINE_HOOK_REFRESH_INTERVAL_MS = 5000; const SUPPORTED_STATUSLINE_HOOK_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']); const BUILTIN_STATUSLINE_HOOKS: StatusLineHookDefinition[] = [ gitBranchStatusLineHook, ]; type StatusLineHookModule = { default?: unknown; statusLineHook?: unknown; statusLineHooks?: unknown; }; function isStatusLineHookDefinition( candidate: unknown, ): candidate is StatusLineHookDefinition { return ( typeof candidate === 'object' && candidate !== null && typeof (candidate as StatusLineHookDefinition).id === 'string' && typeof (candidate as StatusLineHookDefinition).getItems === 'function' ); } function isHookEnabled(hook: StatusLineHookDefinition): boolean { return hook.enable !== false; } function normalizeStatusLineRenderItem( hookId: string, item: StatusLineRenderItem, index: number, ): StatusLineRenderItem { return { ...item, id: item.id?.trim() || `${hookId}:${index}`, }; } function normalizeStatusLineItems( hookId: string, result: StatusLineRenderItem | StatusLineRenderItem[] | undefined | null, ): StatusLineRenderItem[] { if (!result) { return []; } const items = Array.isArray(result) ? result : [result]; return items .filter( item => typeof item?.text === 'string' && item.text.trim().length > 0, ) .map((item, index) => normalizeStatusLineRenderItem(hookId, item, index)); } function normalizeStatusLineHookExports( moduleExports: StatusLineHookModule, modulePath: string, ): StatusLineHookDefinition[] { const exportedHooks = [ moduleExports.default, moduleExports.statusLineHook, moduleExports.statusLineHooks, ].filter(Boolean); if (exportedHooks.length === 0) { logger.warn('Status line hook module has no supported export', { modulePath, }); return []; } const hooks = exportedHooks.flatMap(exportedHook => Array.isArray(exportedHook) ? exportedHook : [exportedHook], ); return hooks.filter(hook => { const isValid = isStatusLineHookDefinition(hook); if (!isValid) { logger.warn('Ignoring invalid status line hook export', {modulePath}); } return isValid; }); } async function loadExternalStatusLineHooks(): Promise< StatusLineHookDefinition[] > { if (!existsSync(STATUSLINE_HOOKS_DIR)) { return []; } let entries: Array; try { entries = readdirSync(STATUSLINE_HOOKS_DIR, {withFileTypes: true}); } catch (error) { logger.warn('Failed to read status line hook directory', { directory: STATUSLINE_HOOKS_DIR, error, }); return []; } const moduleFiles = entries .filter( entry => entry.isFile() && SUPPORTED_STATUSLINE_HOOK_EXTENSIONS.has(extname(entry.name)), ) .sort((left, right) => left.name.localeCompare(right.name)); const hooks: StatusLineHookDefinition[] = []; for (const moduleFile of moduleFiles) { const modulePath = join(STATUSLINE_HOOKS_DIR, moduleFile.name); try { const moduleUrl = pathToFileURL(modulePath).href; const importedModule = (await import(moduleUrl)) as StatusLineHookModule; hooks.push(...normalizeStatusLineHookExports(importedModule, modulePath)); } catch (error) { logger.warn('Failed to load status line hook module', { modulePath, error, }); } } return hooks; } function mergeStatusLineHooks( externalHooks: StatusLineHookDefinition[], ): StatusLineHookDefinition[] { const mergedHooks = new Map(); for (const hook of BUILTIN_STATUSLINE_HOOKS) { mergedHooks.set(hook.id, hook); } for (const hook of externalHooks) { mergedHooks.set(hook.id, hook); } return Array.from(mergedHooks.values()); } function sortStatusLineItems( items: StatusLineRenderItem[], ): StatusLineRenderItem[] { return [...items].sort((left, right) => { const leftPriority = left.priority ?? 0; const rightPriority = right.priority ?? 0; if (leftPriority !== rightPriority) { return leftPriority - rightPriority; } const leftId = left.id ?? ''; const rightId = right.id ?? ''; return leftId.localeCompare(rightId); }); } export type UseStatusLineHookItemsResult = { items: StatusLineRenderItem[]; externalHookIds: ReadonlySet; }; export function useStatusLineHookItems( context: StatusLineHookContext, ): UseStatusLineHookItemsResult { const contextRef = React.useRef(context); const [hookDefinitions, setHookDefinitions] = React.useState( BUILTIN_STATUSLINE_HOOKS, ); const [externalHookIds, setExternalHookIds] = React.useState< ReadonlySet >(() => new Set()); const [itemsByHookId, setItemsByHookId] = React.useState< Record >({}); React.useEffect(() => { contextRef.current = context; }, [context]); React.useEffect(() => { let disposed = false; const loadHooks = async () => { const externalHooks = await loadExternalStatusLineHooks(); if (!disposed) { setHookDefinitions(mergeStatusLineHooks(externalHooks)); setExternalHookIds(new Set(externalHooks.map(hook => hook.id))); } }; void loadHooks(); return () => { disposed = true; }; }, []); React.useEffect(() => { const activeHookIds = new Set(hookDefinitions.map(hook => hook.id)); setItemsByHookId(previousItems => { const nextItems = Object.fromEntries( Object.entries(previousItems).filter(([hookId]) => activeHookIds.has(hookId), ), ); return nextItems; }); }, [hookDefinitions]); React.useEffect(() => { let disposed = false; const refreshingHooks = new Set(); const timers: Array> = []; const refreshHook = async (hook: StatusLineHookDefinition) => { if (refreshingHooks.has(hook.id)) { return; } refreshingHooks.add(hook.id); try { const result = await hook.getItems(contextRef.current); if (!disposed) { setItemsByHookId(previousItems => ({ ...previousItems, [hook.id]: normalizeStatusLineItems(hook.id, result), })); } } catch (error) { if (!disposed) { setItemsByHookId(previousItems => ({ ...previousItems, [hook.id]: [], })); } logger.warn('Status line hook refresh failed', { hookId: hook.id, error, }); } finally { refreshingHooks.delete(hook.id); } }; for (const hook of hookDefinitions) { if (!isHookEnabled(hook)) { continue; } void refreshHook(hook); const refreshIntervalMs = Math.max( 1000, hook.refreshIntervalMs ?? DEFAULT_STATUSLINE_HOOK_REFRESH_INTERVAL_MS, ); const timer = setInterval(() => { void refreshHook(hook); }, refreshIntervalMs); timers.push(timer); } return () => { disposed = true; for (const timer of timers) { clearInterval(timer); } }; }, [hookDefinitions]); const items = React.useMemo( () => sortStatusLineItems(Object.values(itemsByHookId).flat()), [itemsByHookId], ); return React.useMemo( () => ({items, externalHookIds}), [items, externalHookIds], ); } ================================================ FILE: source/ui/components/compression/CompressionStatus.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import {useTheme} from '../../contexts/ThemeContext.js'; export type CompressionStep = | 'saving' | 'loading' | 'compressing' | 'retrying' | 'completed' | 'failed' | 'skipped'; export type CompressionStatus = { step: CompressionStep; message?: string; sessionId?: string; retryAttempt?: number; maxRetries?: number; }; interface CompressionStatusProps { status: CompressionStatus | null; terminalWidth: number; } const stepIcons: Record = { saving: {icon: '◉', color: 'yellow'}, loading: {icon: '◉', color: 'cyan'}, compressing: {icon: '◉', color: 'blue'}, retrying: {icon: '⟳', color: 'yellow'}, completed: {icon: '✓', color: 'green'}, failed: {icon: '✗', color: 'red'}, skipped: {icon: '○', color: 'gray'}, }; const stepLabels: Record = { saving: 'Saving session', loading: 'Loading session', compressing: 'Compressing context', retrying: 'Retrying compression', completed: 'Compression complete', failed: 'Compression failed', skipped: 'Compression skipped', }; export function CompressionStatus({ status, terminalWidth, }: CompressionStatusProps) { const {theme} = useTheme(); if (!status) { return null; } const {step, message, sessionId, retryAttempt, maxRetries} = status; const isActive = step === 'saving' || step === 'loading' || step === 'compressing'; const isRetrying = step === 'retrying'; const isCompleted = step === 'completed'; const isFailed = step === 'failed' || step === 'skipped'; const stepInfo = stepIcons[step]; const label = isRetrying && retryAttempt && maxRetries ? `Retrying compression (${retryAttempt}/${maxRetries})` : stepLabels[step]; const getColor = () => { if (isFailed) return theme.colors.error; if (isCompleted) return theme.colors.success; if (isRetrying) return theme.colors.warning; return theme.colors.menuInfo; }; const color = getColor(); return ( {isActive || isRetrying ? ( <> {label} ) : ( <> {stepInfo.icon} {label} )} {sessionId && ( Session: {sessionId} )} {message && ( {message} )} {isActive && ( {step === 'saving' && 'Persisting conversation data...'} {step === 'loading' && 'Reading session from disk...'} {step === 'compressing' && 'Optimizing context for token limit...'} )} ); } export default CompressionStatus; ================================================ FILE: source/ui/components/panels/AgentPickerPanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {Alert} from '@inkjs/ui'; import type {SubAgent} from '../../../utils/config/subAgentConfig.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import PickerList from '../common/PickerList.js'; interface Props { agents: SubAgent[]; selectedIndex: number; visible: boolean; maxHeight?: number; } const AgentPickerPanel = memo( ({agents, selectedIndex, visible, maxHeight}: Props) => { const {t} = useI18n(); const {theme} = useTheme(); if (!visible) { return null; } if (agents.length === 0) { return ( {t.agentPickerPanel.title} {t.agentPickerPanel.noAgentsWarning} ); } return ( agent.id} title={ <> {t.agentPickerPanel.selectAgent}{' '} {agents.length > 5 && `(${selectedIndex + 1}/${agents.length})`} {t.agentPickerPanel.escHint} } scrollHintFormat={(above, below) => ( {t.agentPickerPanel.scrollHint} {above > 0 && ( <> ·{' '} {t.agentPickerPanel.moreAbove.replace( '{count}', above.toString(), )} )} {below > 0 && ( <> ·{' '} {t.agentPickerPanel.moreBelow.replace( '{count}', below.toString(), )} )} )} renderItem={(agent: SubAgent, isSelected: boolean) => ( <> {isSelected ? '❯ ' : ' '}#{agent.name} └─ {agent.description || t.agentPickerPanel.noDescription} )} /> ); }, ); AgentPickerPanel.displayName = 'AgentPickerPanel'; export default AgentPickerPanel; ================================================ FILE: source/ui/components/panels/BranchPanel.tsx ================================================ import React, {useState, useCallback, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import {execSync} from 'node:child_process'; interface BranchInfo { name: string; isCurrent: boolean; } interface Props { onClose: () => void; } /** * Extract meaningful error message from execSync failure. * Node's execSync puts the real git output in error.stderr. */ function getGitError(error: unknown): string { if (error && typeof error === 'object') { const err = error as Record; // execSync attaches stderr as a string (when encoding is set) const stderr = err['stderr']; if (typeof stderr === 'string' && stderr.trim()) { return stderr.trim(); } } if (error instanceof Error) { return error.message; } return String(error); } /** * Check if current directory is inside a git repository. */ function isGitRepo(): boolean { try { execSync('git rev-parse --is-inside-work-tree', { stdio: 'pipe', encoding: 'utf-8', }); return true; } catch { return false; } } /** * List all local git branches, marking the current one. */ function listBranches(): BranchInfo[] { try { const output = execSync('git branch --list', { stdio: 'pipe', encoding: 'utf-8', }); return output .split('\n') .filter(line => line.trim().length > 0) .map(line => { const isCurrent = line.startsWith('* '); const name = line.replace(/^\*?\s+/, '').trim(); return {name, isCurrent}; }); } catch { return []; } } type CheckoutResult = { success: boolean; message: string; conflict?: boolean; // true when local changes block checkout }; /** * Switch to an existing branch. */ function checkoutBranch(branchName: string): CheckoutResult { try { execSync(`git checkout ${branchName}`, { stdio: 'pipe', encoding: 'utf-8', }); return {success: true, message: `Switched to branch: ${branchName}`}; } catch (error) { const msg = getGitError(error); // Detect "local changes would be overwritten" conflict const isConflict = msg.includes('would be overwritten') || msg.includes('Please commit your changes or stash them') || msg.includes('error: Your local changes'); return {success: false, message: msg, conflict: isConflict}; } } /** * Stash current changes, checkout branch, then optionally pop stash. */ function stashAndCheckout( branchName: string, ): {success: boolean; message: string} { try { execSync('git stash push -m "auto-stash before branch switch"', { stdio: 'pipe', encoding: 'utf-8', }); } catch (error) { const msg = getGitError(error); return {success: false, message: `Stash failed: ${msg}`}; } try { execSync(`git checkout ${branchName}`, { stdio: 'pipe', encoding: 'utf-8', }); return { success: true, message: `Stashed changes and switched to: ${branchName}\n(Use "git stash pop" to restore your changes)`, }; } catch (error) { // Checkout still failed, pop stash to restore original state try { execSync('git stash pop', {stdio: 'pipe', encoding: 'utf-8'}); } catch { // Ignore pop failure } const msg = getGitError(error); return { success: false, message: `Stash succeeded but checkout failed: ${msg}`, }; } } /** * Create and checkout a new branch. */ function createBranch( branchName: string, ): {success: boolean; message: string} { try { execSync(`git checkout -b ${branchName}`, { stdio: 'pipe', encoding: 'utf-8', }); return { success: true, message: `Created and switched to: ${branchName}`, }; } catch (error) { return {success: false, message: getGitError(error)}; } } /** * Delete a local branch. */ function deleteBranch( branchName: string, ): {success: boolean; message: string} { try { execSync(`git branch -d ${branchName}`, { stdio: 'pipe', encoding: 'utf-8', }); return {success: true, message: `Deleted branch: ${branchName}`}; } catch (error) { const msg = getGitError(error); if (msg.includes('not fully merged')) { try { execSync(`git branch -D ${branchName}`, { stdio: 'pipe', encoding: 'utf-8', }); return { success: true, message: `Force deleted branch: ${branchName}`, }; } catch (error2) { return { success: false, message: getGitError(error2), }; } } return {success: false, message: msg}; } } type PanelMode = 'list' | 'create' | 'confirmDelete' | 'confirmStash'; export const BranchPanel: React.FC = ({onClose}) => { const {theme} = useTheme(); const {t} = useI18n(); const [mode, setMode] = useState('list'); const [branches, setBranches] = useState([]); const [selectedIndex, setSelectedIndex] = useState(0); const [isGit, setIsGit] = useState(true); const [message, setMessage] = useState<{ type: 'success' | 'error' | 'warning'; text: string; } | null>(null); const [newBranchName, setNewBranchName] = useState(''); const [isLoading, setIsLoading] = useState(false); const [pendingStashBranch, setPendingStashBranch] = useState( null, ); const bp = t.branchPanel; // Load branches const loadBranches = useCallback(() => { if (!isGitRepo()) { setIsGit(false); return; } setIsGit(true); const branchList = listBranches(); setBranches(branchList); // Ensure selected index is within bounds if (selectedIndex >= branchList.length) { setSelectedIndex(Math.max(0, branchList.length - 1)); } }, [selectedIndex]); useEffect(() => { loadBranches(); }, []); // Handle branch switch const handleSwitch = useCallback(() => { const branch = branches[selectedIndex]; if (!branch || branch.isCurrent) return; setIsLoading(true); setMessage(null); const result = checkoutBranch(branch.name); setIsLoading(false); if (result.success) { setMessage({type: 'success', text: result.message}); loadBranches(); } else if (result.conflict) { // Local changes block checkout - ask user if they want to stash setPendingStashBranch(branch.name); setMode('confirmStash'); setMessage(null); } else { setMessage({type: 'error', text: result.message}); } }, [branches, selectedIndex, loadBranches]); // Handle stash-and-checkout confirmation const handleStashAndSwitch = useCallback(() => { if (!pendingStashBranch) return; setIsLoading(true); setMessage(null); const result = stashAndCheckout(pendingStashBranch); setIsLoading(false); setMessage({ type: result.success ? 'success' : 'error', text: result.message, }); setPendingStashBranch(null); setMode('list'); if (result.success) { loadBranches(); } }, [pendingStashBranch, loadBranches]); // Handle branch creation const handleCreate = useCallback(() => { const trimmedName = newBranchName.trim(); if (!trimmedName) return; setIsLoading(true); setMessage(null); const result = createBranch(trimmedName); setIsLoading(false); setMessage({ type: result.success ? 'success' : 'error', text: result.message, }); if (result.success) { setNewBranchName(''); setMode('list'); loadBranches(); } }, [newBranchName, loadBranches]); // Handle branch deletion const handleDelete = useCallback(() => { const branch = branches[selectedIndex]; if (!branch) return; setIsLoading(true); setMessage(null); const result = deleteBranch(branch.name); setIsLoading(false); setMessage({ type: result.success ? 'success' : 'error', text: result.message, }); setMode('list'); if (result.success) { loadBranches(); } }, [branches, selectedIndex, loadBranches]); useInput((input, key) => { if (isLoading) return; // Create mode input handling if (mode === 'create') { if (key.escape) { setMode('list'); setNewBranchName(''); setMessage(null); return; } if (key.return) { handleCreate(); return; } // TextInput handles the rest return; } // Confirm stash-and-switch mode if (mode === 'confirmStash') { if (input.toLowerCase() === 'y') { handleStashAndSwitch(); return; } if (input.toLowerCase() === 'n' || key.escape) { setPendingStashBranch(null); setMode('list'); setMessage(null); return; } return; } // Confirm delete mode if (mode === 'confirmDelete') { if (input.toLowerCase() === 'y') { handleDelete(); return; } if (input.toLowerCase() === 'n' || key.escape) { setMode('list'); setMessage(null); return; } return; } // List mode if (key.escape) { onClose(); return; } // Navigation if (key.upArrow) { setSelectedIndex(prev => Math.max(0, prev - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => Math.min(branches.length - 1, prev + 1), ); return; } // Switch branch if (key.return) { handleSwitch(); return; } // Create new branch if (input.toLowerCase() === 'n') { setMode('create'); setMessage(null); return; } // Delete branch if (input.toLowerCase() === 'd') { const branch = branches[selectedIndex]; if (!branch) return; if (branch.isCurrent) { setMessage({ type: 'error', text: bp.cannotDeleteCurrent || 'Cannot delete the currently checked-out branch', }); return; } setMode('confirmDelete'); setMessage(null); return; } }); // Not a git repo if (!isGit) { return ( {bp.title || 'Git Branch Management'} {bp.notGitRepo || 'Current directory is not a Git repository. Cannot manage branches.'} {bp.pressEscToClose || 'Press ESC to close'} ); } return ( {/* Title */} {bp.title || 'Git Branch Management'} {/* Branch List */} {branches.length === 0 ? ( {bp.noBranches || 'No branches found. Press N to create one.'} ) : ( branches.map((branch, index) => ( {index === selectedIndex ? '❯ ' : ' '} {branch.isCurrent ? '● ' : '○ '} {branch.name} {branch.isCurrent ? ` (${bp.current || 'current'})` : ''} )) )} {/* Create mode - text input */} {mode === 'create' && ( {bp.newBranchLabel || 'New branch name:'} {'> '} {bp.createHint || 'Enter to confirm, ESC to cancel'} )} {/* Confirm stash-and-switch */} {mode === 'confirmStash' && pendingStashBranch && ( {( bp.stashConfirm || 'Local changes detected. Stash changes and switch to "{branch}"?' ).replace('{branch}', pendingStashBranch)} {bp.stashConfirmHint || 'Press Y to stash & switch, N to cancel'} )} {/* Confirm delete */} {mode === 'confirmDelete' && branches[selectedIndex] && ( {( bp.confirmDelete || 'Delete branch "{branch}"?' ).replace('{branch}', branches[selectedIndex]!.name)} {bp.confirmDeleteHint || 'Press Y to confirm, N to cancel'} )} {/* Message */} {message && ( {message.text} )} {/* Loading */} {isLoading && ( {bp.loading || 'Processing...'} )} {/* Hints */} {mode === 'list' && ( {bp.hints || '↑↓: Navigate | Enter: Switch | N: New branch | D: Delete | ESC: Close'} )} ); }; ================================================ FILE: source/ui/components/panels/BtwPanel.tsx ================================================ import React, {useState, useCallback, useRef, useEffect, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import {useTerminalSize} from '../../../hooks/ui/useTerminalSize.js'; import {streamBtwResponse} from '../../../utils/commands/btwStream.js'; import {waitForPendingSendSignal} from '../../../hooks/conversation/core/pendingMessagesHandler.js'; import {visualWidth} from '../../../utils/core/textUtils.js'; import {renderMarkdownToLines} from '../common/MarkdownRenderer.js'; type Step = 'streaming' | 'done' | 'error'; const VISIBLE_ROWS = 8; const DEBOUNCE_MS = 80; const ANSI_REGEX = /\x1b\[[0-9;]*m/g; function stripAnsiCodes(input: string): string { return input.replace(ANSI_REGEX, ''); } function wrapLineToWidth(line: string, width: number): string[] { if (!line) return ['']; const chars = [...line]; const result: string[] = []; let current = ''; let currentWidth = 0; for (const ch of chars) { const chWidth = Math.max(1, visualWidth(ch)); if (currentWidth + chWidth > width) { result.push(current || ' '); current = ch; currentWidth = chWidth; } else { current += ch; currentWidth += chWidth; } } if (current.length > 0) { result.push(current); } return result.length > 0 ? result : ['']; } interface Props { prompt: string; onClose: () => void; } export const BtwPanel: React.FC = ({prompt, onClose}) => { const {theme} = useTheme(); const {t} = useI18n(); const {columns} = useTerminalSize(); const [step, setStep] = useState('streaming'); const [response, setResponse] = useState(''); const [errorMessage, setErrorMessage] = useState(''); const [scrollOffset, setScrollOffset] = useState(0); const abortControllerRef = useRef(null); const startedRef = useRef(false); const pendingTextRef = useRef(''); const debounceTimerRef = useRef | null>(null); const btwText = (t as any).btw || {}; // border (2) + paddingX (2) = 4 columns of chrome const contentWidth = Math.max(1, columns - 4); const visualLines = useMemo(() => { if (!response) return []; const markdownLines = renderMarkdownToLines(response).map(stripAnsiCodes); return markdownLines.flatMap(line => wrapLineToWidth(line, Math.max(1, contentWidth)), ); }, [response, contentWidth]); const flushPending = useCallback(() => { debounceTimerRef.current = null; setResponse(pendingTextRef.current); }, []); const startStream = useCallback(async () => { setStep('streaming'); setResponse(''); pendingTextRef.current = ''; const controller = new AbortController(); abortControllerRef.current = controller; try { // 与 PendingMessage 发送信号一致：先等待可发送，再进入思考阶段。 await waitForPendingSendSignal({abortSignal: controller.signal}); if (controller.signal.aborted) return; setStep('streaming'); for await (const chunk of streamBtwResponse(prompt, controller.signal)) { if (controller.signal.aborted) break; pendingTextRef.current += chunk; if (!debounceTimerRef.current) { debounceTimerRef.current = setTimeout(flushPending, DEBOUNCE_MS); } } if (!controller.signal.aborted) { if (debounceTimerRef.current) { clearTimeout(debounceTimerRef.current); debounceTimerRef.current = null; } setResponse(pendingTextRef.current); setStep('done'); } } catch (error) { if (!controller.signal.aborted) { if (debounceTimerRef.current) { clearTimeout(debounceTimerRef.current); debounceTimerRef.current = null; } const msg = error instanceof Error ? error.message : 'Unknown error'; setErrorMessage(msg); setStep('error'); } } }, [prompt, flushPending]); useEffect(() => { if (!startedRef.current) { startedRef.current = true; startStream(); } return () => { if (debounceTimerRef.current) { clearTimeout(debounceTimerRef.current); debounceTimerRef.current = null; } try { abortControllerRef.current?.abort(); } catch { // ignore } }; }, [startStream]); useEffect(() => { setScrollOffset(Math.max(0, visualLines.length - VISIBLE_ROWS)); }, [visualLines.length]); useInput((_input, key) => { if (key.escape) { try { abortControllerRef.current?.abort(); } catch { // ignore } onClose(); return; } if (key.upArrow) { setScrollOffset(prev => Math.max(0, prev - 1)); return; } if (key.downArrow) { setScrollOffset(prev => { const max = Math.max(0, visualLines.length - VISIBLE_ROWS); return Math.min(max, prev + 1); }); return; } if (key.return && (step === 'done' || step === 'error')) { onClose(); return; } }); const title = btwText.title || '✦ BTW'; const separator = ' — '; const maxPromptWidth = Math.max( 10, contentWidth - visualWidth(title) - visualWidth(separator), ); const promptPreview = useMemo(() => { if (visualWidth(prompt) <= maxPromptWidth) return prompt; const chars = [...prompt]; let s = ''; let w = 0; const ellipsis = '...'; const ellipsisW = visualWidth(ellipsis); for (const ch of chars) { const cw = visualWidth(ch); if (w + cw + ellipsisW > maxPromptWidth) break; s += ch; w += cw; } return s + ellipsis; }, [prompt, maxPromptWidth]); const canScroll = visualLines.length > VISIBLE_ROWS; const visibleSlice = visualLines.slice( scrollOffset, scrollOffset + VISIBLE_ROWS, ); const scrollIndicator = canScroll && ( {btwText.scrollHint || '↑↓ Scroll'} {` (${scrollOffset + 1}-${Math.min(scrollOffset + VISIBLE_ROWS, visualLines.length)}/${visualLines.length})`} ); const responseBox = response.length > 0 && ( {visibleSlice.map((line, i) => ( {line || ' '} ))} ); if (step === 'error') { return ( {title} {separator}{promptPreview} {btwText.errorPrefix || 'Error: '} {errorMessage} {'Enter'} {' '}- {btwText.actionClose || 'Close'} ); } if (step === 'streaming') { return ( {title} {separator}{promptPreview} {!response && ( {btwText.thinking || 'Thinking...'} )} {responseBox} {scrollIndicator} ); } // step === 'done' return ( {title} {separator}{promptPreview} {responseBox} {scrollIndicator} {'Enter'} {' '}- {btwText.actionClose || 'Close'} ); }; export default BtwPanel; ================================================ FILE: source/ui/components/panels/CommandArgsPanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import PickerList from '../common/PickerList.js'; interface Props { commandName: string; options: string[]; selectedIndex: number; visible: boolean; } const CommandArgsPanel = memo( ({commandName, options, selectedIndex, visible}: Props) => { const {theme} = useTheme(); const {t} = useI18n(); if (!visible || options.length === 0) { return null; } return ( option} title={ <> /{commandName}{' '} {t.commandArgsPanel.navigationHint} } renderItem={(option: string, isSelected: boolean) => ( {isSelected ? '❯ ' : ' '} {option} )} /> ); }, ); CommandArgsPanel.displayName = 'CommandArgsPanel'; export default CommandArgsPanel; ================================================ FILE: source/ui/components/panels/CommandPanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import PickerList from '../common/PickerList.js'; interface Command { name: string; description: string; } interface Props { commands: Command[]; selectedIndex: number; query: string; visible: boolean; maxHeight?: number; } const CommandPanel = memo( ({commands, selectedIndex, visible, maxHeight}: Props) => { const {t} = useI18n(); const {theme} = useTheme(); return ( cmd.name} title={ {t.commandPanel.availableCommands}{' '} {commands.length > 5 && `(${selectedIndex + 1}/${commands.length})`} } scrollHintFormat={(above, below) => ( {t.commandPanel.scrollHint} {above > 0 && ( <> ·{' '} {t.commandPanel.moreAbove.replace( '{count}', above.toString(), )} )} {below > 0 && ( <> ·{' '} {t.commandPanel.moreBelow.replace( '{count}', below.toString(), )} )} {above === 0 && below === 0 && ( <> ·{' '} {t.commandPanel.moreHidden.replace( '{count}', (commands.length - 5).toString(), )} )} )} renderItem={(command: Command, isSelected: boolean) => ( <> {isSelected ? '❯ ' : ' '}/{command.name} └─ {command.description} )} /> ); }, ); CommandPanel.displayName = 'CommandPanel'; export default CommandPanel; ================================================ FILE: source/ui/components/panels/ConnectionPanel.tsx ================================================ import React, {useState, useCallback, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import Spinner from 'ink-spinner'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { connectionManager, type ConnectionConfig, type ConnectionStatus, } from '../../../utils/connection/ConnectionManager.js'; interface Props { onClose: () => void; initialApiUrl?: string; } export const ConnectionPanel: React.FC = ({onClose, initialApiUrl}) => { const {theme} = useTheme(); const {t} = useI18n(); const cp = t.connectionPanel; // Form fields const [apiUrl, setApiUrl] = useState( initialApiUrl || 'http://localhost:5136/api', ); const [username, setUsername] = useState(''); const [password, setPassword] = useState(''); const [instanceId, setInstanceId] = useState(''); const [instanceName, setInstanceName] = useState(''); // UI state const [step, setStep] = useState< 'url' | 'auth' | 'instance' | 'connecting' | 'connected' | 'saved' >('url'); const [focus, setFocus] = useState<'username' | 'password' | 'id' | 'name'>( 'username', ); const [status, setStatus] = useState('disconnected'); const [statusMessage, setStatusMessage] = useState(''); const [isStatusError, setIsStatusError] = useState(false); const [isProcessing, setIsProcessing] = useState(false); const [confirmingDelete, setConfirmingDelete] = useState(false); // Load saved connection config on mount useEffect(() => { const savedConfig = connectionManager.loadConnectionConfig(); if (savedConfig) { setApiUrl(savedConfig.apiUrl); setUsername(savedConfig.username); setPassword(savedConfig.password); setInstanceId(savedConfig.instanceId); setInstanceName(savedConfig.instanceName); // If not connected, show saved config step const currentState = connectionManager.getState(); if (currentState.status !== 'connected') { setStep('saved'); } } }, []); // Subscribe to connection status useEffect(() => { const unsubscribe = connectionManager.onStatusChange(state => { setStatus(state.status); // Sync form fields with current connection state if (state.instanceId) setInstanceId(state.instanceId); if (state.instanceName) setInstanceName(state.instanceName); if (state.error) { setStatusMessage(`${cp.errorPrefix}${state.error}`); setIsStatusError(true); } }); return unsubscribe; }, []); // Handle keyboard input useInput( (input, key) => { if (key.escape) { // If confirming delete, cancel it if (confirmingDelete) { setConfirmingDelete(false); return; } // Navigate back to previous step based on current step if (step === 'auth') { // If on password field, go back to username field first if (focus === 'password') { setFocus('username'); return; } setStep('url'); setStatusMessage(''); return; } if (step === 'instance') { // If on name field, go back to id field first if (focus === 'name') { setFocus('id'); return; } setStep('auth'); setFocus('password'); setStatusMessage(''); return; } // Only close panel, never disconnect here // Disconnect is handled by the disconnect command only onClose(); return; } // Handle 'd' key for deleting saved config (with confirmation) if (input.toLowerCase() === 'd' && step === 'saved') { if (!confirmingDelete) { // First press: enter confirmation mode setConfirmingDelete(true); return; } else { // Second press: confirm deletion connectionManager.clearSavedConnection(); setConfirmingDelete(false); setStep('url'); setApiUrl(initialApiUrl || 'http://localhost:5136/api'); setUsername(''); setPassword(''); setInstanceId(''); setInstanceName(''); return; } } // Any other key cancels delete confirmation if (confirmingDelete) { setConfirmingDelete(false); return; } // Handle arrow keys for navigation between fields if (step === 'auth') { if (key.upArrow || key.downArrow) { setFocus(prev => (prev === 'username' ? 'password' : 'username')); return; } } if (step === 'instance') { if (key.upArrow || key.downArrow) { setFocus(prev => (prev === 'id' ? 'name' : 'id')); return; } } if (key.return) { void handleSubmit(); } }, {isActive: true}, ); const handleSubmit = useCallback(async () => { if (isProcessing) return; // Handle saved config step - start connection directly if (step === 'saved') { setStep('auth'); setFocus('username'); return; } if (step === 'url') { if (apiUrl.trim()) { setStep('auth'); setFocus('username'); } return; } if (step === 'auth') { if (focus === 'username' && username.trim()) { setFocus('password'); return; } if (focus === 'password' && password.trim()) { // Try to login setIsProcessing(true); setIsStatusError(false); setStatusMessage(cp.loggingIn); const config: ConnectionConfig = { apiUrl: apiUrl.trim(), username: username.trim(), password: password.trim(), instanceId: '', instanceName: '', }; const result = await connectionManager.login(config); setIsProcessing(false); if (result.success) { setIsStatusError(false); setStatusMessage(result.message); setStep('instance'); setFocus('id'); } else { setIsStatusError(true); setStatusMessage(result.message); } } return; } if (step === 'instance') { if (focus === 'id' && instanceId.trim()) { setFocus('name'); return; } if (focus === 'name' && instanceName.trim()) { // Try to connect setIsProcessing(true); setIsStatusError(false); setStep('connecting'); setStatusMessage(cp.connectingToHub); const config: ConnectionConfig = { apiUrl: apiUrl.trim(), username: username.trim(), password: password.trim(), instanceId: instanceId.trim(), instanceName: instanceName.trim(), }; // Update config and connect const loginResult = await connectionManager.login(config); if (!loginResult.success) { setIsProcessing(false); setStep('instance'); setIsStatusError(true); setStatusMessage(loginResult.message); return; } const connectResult = await connectionManager.connect(); setIsProcessing(false); if (connectResult.success) { // Save connection config await connectionManager.saveConnectionConfig(config); setStep('connected'); setIsStatusError(false); setStatusMessage(cp.connectedSuccessfully); } else { setStep('instance'); setIsStatusError(true); setStatusMessage(connectResult.message); } } return; } if (step === 'connected') { onClose(); } }, [ step, focus, isProcessing, apiUrl, username, password, instanceId, instanceName, onClose, ]); // Status color helper const getStatusColor = (s: ConnectionStatus) => { switch (s) { case 'connected': return theme.colors.success; case 'connecting': return theme.colors.warning; default: return theme.colors.error; } }; return ( {cp.title} {/* Connection Status */} {cp.statusLabel} {status === 'connected' ? cp.statusConnected : status === 'connecting' ? cp.statusConnecting : cp.statusDisconnected} {/* Step 0: Saved Config - Show when there's a saved config */} {step === 'saved' && status !== 'connected' && ( {cp.savedConfigFound} {cp.apiUrlLabel} {apiUrl} {cp.usernameLabel} {username} {cp.instanceLabel} {instanceName} ({instanceId}) {cp.savedConfigHint} {confirmingDelete ? ( {cp.confirmDeletePrefix}{' '} D{' '} {cp.confirmDeleteSuffix} ) : ( {cp.clearSavedPrefix}{' '} D{' '} {cp.clearSavedSuffix} )} )} {/* Step 1: API URL - Only show when disconnected */} {step === 'url' && status !== 'connected' && ( {cp.apiBaseUrlLabel} void handleSubmit()} /> {cp.enterContinueEscCancel} )} {/* Step 2: Authentication - Only show when disconnected */} {step === 'auth' && status !== 'connected' && ( {cp.authenticationTitle} {cp.apiUrlLabel} {apiUrl} {cp.usernameFieldLabel} {focus === 'username' && ( void handleSubmit()} focus={true} /> )} {focus !== 'username' && ( {username} )} {cp.passwordFieldLabel} {focus === 'password' && ( void handleSubmit()} mask="*" focus={true} /> )} {focus !== 'password' && password && ( ******** )} {statusMessage && ( {statusMessage} )} {cp.enterContinueEscBack} )} {/* Step 3: Instance Info - Only show when disconnected */} {step === 'instance' && status !== 'connected' && ( {cp.instanceConfigTitle} {cp.loggedInAs} {username} {cp.instanceIdLabel} {focus === 'id' && ( void handleSubmit()} focus={true} /> )} {focus !== 'id' && ( {instanceId} )} {cp.instanceNameLabel} {focus === 'name' && ( void handleSubmit()} focus={true} /> )} {focus !== 'name' && instanceName && ( {instanceName} )} {statusMessage && ( {statusMessage} )} {cp.enterConnectEscBack} )} {/* Step 4: Connecting - Only show when disconnected */} {step === 'connecting' && status !== 'connected' && ( {statusMessage} {cp.pleaseWait} )} {/* Step 5: Connected - Only show status, no input capability */} {(step === 'connected' || status === 'connected') && ( {cp.connectedSuccessfullyWithIcon} {cp.instanceLabel} {instanceName} ({instanceId}) {cp.pressEscToClose} {cp.useCommandPrefix}{' '} /disconnect{' '} {cp.useCommandSuffix} )} ); }; export default ConnectionPanel; ================================================ FILE: source/ui/components/panels/CustomCommandConfigPanel.tsx ================================================ import React, {useState, useCallback} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { isCommandNameConflict, checkCommandExists, type CommandLocation, } from '../../../utils/commands/custom.js'; interface Props { onSave: ( name: string, command: string, type: 'execute' | 'prompt', location: CommandLocation, description?: string, ) => Promise; onCancel: () => void; projectRoot?: string; } export const CustomCommandConfigPanel: React.FC = ({ onSave, onCancel, projectRoot, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [step, setStep] = useState< 'name' | 'command' | 'description' | 'type' | 'location' | 'confirm' >('name'); const [commandName, setCommandName] = useState(''); const [commandText, setCommandText] = useState(''); const [commandDescription, setCommandDescription] = useState(''); const [commandType, setCommandType] = useState<'execute' | 'prompt'>( 'execute', ); const [location, setLocation] = useState('global'); const [errorMessage, setErrorMessage] = useState(''); // Handle keyboard input for navigation and ESC useInput( (input, key) => { if (key.escape) { // Sequential back navigation if (step === 'confirm') { setStep('location'); } else if (step === 'location') { setStep('type'); } else if (step === 'type') { setStep('description'); } else if (step === 'description') { setStep('command'); } else if (step === 'command') { setStep('name'); } else if (step === 'name') { handleCancel(); } return; } if (step === 'type') { if (input.toLowerCase() === 'e') { setCommandType('execute'); setStep('location'); } else if (input.toLowerCase() === 'p') { setCommandType('prompt'); setStep('location'); } } else if (step === 'location') { if (input.toLowerCase() === 'g') { setLocation('global'); setStep('confirm'); } else if (input.toLowerCase() === 'p') { setLocation('project'); setStep('confirm'); } } else if (step === 'confirm') { if (input.toLowerCase() === 'y') { handleConfirm(); } else if (input.toLowerCase() === 'n') { setStep('location'); } } }, {isActive: true}, // Always active for ESC handling ); const handleNameSubmit = useCallback( (value: string) => { if (value.trim()) { const trimmedName = value.trim(); // Check for command name conflicts with built-in commands if (isCommandNameConflict(trimmedName)) { setErrorMessage( `Command name "${trimmedName}" conflicts with an existing built-in or custom command`, ); return; } // Check if command exists in either location const existsGlobal = checkCommandExists(trimmedName, 'global'); const existsProject = checkCommandExists( trimmedName, 'project', projectRoot, ); if (existsGlobal && existsProject) { setErrorMessage( `Command "${trimmedName}" already exists in both global and project locations`, ); return; } else if (existsGlobal) { setErrorMessage( `Command "${trimmedName}" already exists in global location`, ); return; } else if (existsProject) { setErrorMessage( `Command "${trimmedName}" already exists in project location`, ); return; } setErrorMessage(''); setCommandName(trimmedName); setStep('command'); } }, [projectRoot], ); const handleCommandSubmit = useCallback((value: string) => { if (value.trim()) { setCommandText(value.trim()); setStep('description'); } }, []); const handleDescriptionSubmit = useCallback((value: string) => { setCommandDescription(value.trim()); setStep('type'); }, []); const handleConfirm = useCallback(async () => { const trimmedDescription = commandDescription.trim(); const description = trimmedDescription.length > 0 ? trimmedDescription : undefined; await onSave(commandName, commandText, commandType, location, description); }, [ commandName, commandText, commandType, location, commandDescription, onSave, ]); const handleCancel = useCallback(() => { onCancel(); }, [onCancel]); return ( {t.customCommand.title} {step === 'name' && ( {t.customCommand.nameLabel} {errorMessage && ( {errorMessage} )} {t.customCommand.escCancel} )} {step === 'command' && ( {t.customCommand.nameLabel}{' '} {commandName} {t.customCommand.commandLabel} {t.customCommand.escCancel} )} {step === 'description' && ( {t.customCommand.nameLabel}{' '} {commandName} {t.customCommand.commandLabel}{' '} {commandText} {t.customCommand.descriptionLabel} {t.customCommand.descriptionHint} {t.customCommand.escCancel} )} {step === 'type' && ( Command:{' '} {commandText} {t.customCommand.typeLabel} [E] {' '} {t.customCommand.typeExecute} [P] {' '} {t.customCommand.typePrompt} {t.customCommand.escCancel} )} {step === 'location' && ( {t.customCommand.nameLabel}{' '} {commandName} Command:{' '} {commandText} Type:{' '} {commandType === 'execute' ? t.customCommand.typeExecute : t.customCommand.typePrompt} {t.customCommand.descriptionLabel}{' '} {commandDescription || t.customCommand.descriptionNotSet} {t.customCommand.locationLabel} [G] {' '} {t.customCommand.locationGlobal} {t.customCommand.locationGlobalInfo} [P] {' '} {t.customCommand.locationProject} {t.customCommand.locationProjectInfo} {t.customCommand.escCancel} )} {step === 'confirm' && ( {t.customCommand.nameLabel}{' '} {commandName} Command:{' '} {commandText} Type:{' '} {commandType === 'execute' ? t.customCommand.typeExecute : t.customCommand.typePrompt} {t.customCommand.descriptionLabel}{' '} {commandDescription || t.customCommand.descriptionNotSet} Location:{' '} {location === 'global' ? t.customCommand.locationGlobal : t.customCommand.locationProject} {t.customCommand.confirmSave} [Y] {' '} {t.customCommand.confirmYes} [N] {' '} {t.customCommand.confirmNo} )} ); }; ================================================ FILE: source/ui/components/panels/DiffReviewPanel.tsx ================================================ import React, {useState, useEffect, useCallback, useMemo, useRef} from 'react'; import {Box, Text, useInput} from 'ink'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {hashBasedSnapshotManager} from '../../../utils/codebase/hashBasedSnapshot.js'; import {convertSessionMessagesToUI} from '../../../utils/session/sessionConverter.js'; import {vscodeConnection} from '../../../utils/ui/vscodeConnection.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {cleanIDEContext} from '../../../utils/core/fileUtils.js'; import fs from 'fs/promises'; type Props = { messages: Array<{ role: string; content: string; images?: Array<{type: 'image'; data: string; mimeType: string}>; subAgentDirected?: unknown; }>; snapshotFileCount: Map; onClose: () => void; terminalWidth?: number; }; type MessageItem = { label: string; originalIndex: number; fileCount: number; }; type ViewMode = 'messages' | 'files'; export default function DiffReviewPanel({ messages, snapshotFileCount, onClose, terminalWidth, }: Props) { const {t} = useI18n(); const {theme} = useTheme(); const [selectedIndex, setSelectedIndex] = useState(0); const [busy, setBusy] = useState(false); // When true, the unmount cleanup will NOT send closeDiff to VSCode, // so the multi-file diff review opened via showDiffReview can stay visible. const skipCloseOnUnmountRef = useRef(false); // Real (deduplicated) file count per snapshot index. snapshotFileCount // from props sums per-snapshot file counts which double-counts the same // file modified across multiple snapshots; getFilesToRollback returns a // deduplicated list of relative paths and is the source of truth. const [dedupedFileCount, setDedupedFileCount] = useState>( new Map(), ); // File list mode state const [viewMode, setViewMode] = useState('messages'); const [filePaths, setFilePaths] = useState([]); const [fileHighlightIndex, setFileHighlightIndex] = useState(0); const [fileScrollIndex, setFileScrollIndex] = useState(0); const [activeMessageIndex, setActiveMessageIndex] = useState( null, ); const VISIBLE_ITEMS = 5; const MAX_VISIBLE_FILES = 10; const userMessages: MessageItem[] = useMemo(() => { const items: MessageItem[] = []; let userMsgIndex = 0; const currentSession = sessionManager.getCurrentSession(); const uiMessages = currentSession ? convertSessionMessagesToUI(currentSession.messages) : null; for (let i = 0; i < messages.length; i++) { const msg = messages[i]; if ( msg && msg.role === 'user' && msg.content.trim() && !msg.subAgentDirected ) { const cleanedContent = cleanIDEContext(msg.content); const cleanContent = cleanedContent .replace(/[\r\n\t\v\f\u0000-\u001F\u007F-\u009F]+/g, ' ') .replace(/\s+/g, ' ') .trim(); let snapshotIdx = i; if (uiMessages) { const ordinal = userMsgIndex + 1; let count = 0; for (let j = 0; j < uiMessages.length; j++) { const um = uiMessages[j]; if ( um?.role === 'user' && um.content?.trim() && !um.subAgentDirected ) { count++; if (count === ordinal) { snapshotIdx = j; break; } } } } // Prefer the real deduplicated count (computed via // getFilesToRollback in the effect below). Fall back to the // summed prop value while the async dedupe is still loading // so the UI doesn't flash empty. let totalFileCount: number; if (dedupedFileCount.has(snapshotIdx)) { totalFileCount = dedupedFileCount.get(snapshotIdx) ?? 0; } else { totalFileCount = 0; for (const [idx, count] of snapshotFileCount.entries()) { if (idx >= snapshotIdx) { totalFileCount += count; } } } items.push({ label: `${userMsgIndex + 1}. ${cleanContent.slice(0, 60)}${ cleanContent.length > 60 ? '...' : '' }`, originalIndex: i, fileCount: totalFileCount, }); userMsgIndex++; } } return items; }, [messages, snapshotFileCount, dedupedFileCount]); // (resolveSnapshotIdx is defined further below; the dedupe effect lives // after that definition so we can reuse it.) useEffect(() => { if (userMessages.length > 0) { setSelectedIndex(userMessages.length - 1); } }, [userMessages.length]); const closeDiffPreview = useCallback(() => { if (vscodeConnection.isConnected()) { vscodeConnection.closeDiff().catch(() => {}); } }, []); useEffect(() => { return () => { if (skipCloseOnUnmountRef.current) return; closeDiffPreview(); }; }, [closeDiffPreview]); // Preview single file diff when navigating file list useEffect(() => { if (viewMode !== 'files' || activeMessageIndex === null) return; const filePath = filePaths[fileHighlightIndex]; if (!filePath) return; const currentSession = sessionManager.getCurrentSession(); if (!currentSession) return; const timeoutId = setTimeout(() => { closeDiffPreview(); hashBasedSnapshotManager .getRollbackPreviewForFile( currentSession.id, activeMessageIndex, filePath, ) .then(async preview => { let currentContent = ''; try { currentContent = await fs.readFile(preview.absolutePath, 'utf-8'); } catch { currentContent = ''; } await vscodeConnection.showDiff( preview.absolutePath, preview.rollbackContent, currentContent, 'Diff Review', ); }) .catch(() => {}); }, 100); return () => { clearTimeout(timeoutId); }; }, [ fileHighlightIndex, viewMode, filePaths, activeMessageIndex, closeDiffPreview, ]); const resolveSnapshotIdx = useCallback( (liveIndex: number): number => { const session = sessionManager.getCurrentSession(); if (!session) return liveIndex; const converted = convertSessionMessagesToUI(session.messages); let userOrdinal = 0; for (let i = 0; i <= liveIndex && i < messages.length; i++) { const m = messages[i]; if (m?.role === 'user' && m.content?.trim() && !m.subAgentDirected) { userOrdinal++; } } if (userOrdinal === 0) return 0; let count = 0; for (let i = 0; i < converted.length; i++) { const m = converted[i]; if (m?.role === 'user' && m.content?.trim() && !m.subAgentDirected) { count++; if (count === userOrdinal) return i; } } return liveIndex; }, [messages], ); // Asynchronously compute deduplicated file counts via getFilesToRollback // for every visible user message. snapshotFileCount sums per-snapshot // file counts which double-counts the same file modified across multiple // snapshots; getFilesToRollback returns a deduplicated relative-path list // and is the authoritative count we want to display. useEffect(() => { const session = sessionManager.getCurrentSession(); if (!session) return; let cancelled = false; const targets: number[] = []; const seen = new Set(); for (let i = 0; i < messages.length; i++) { const msg = messages[i]; if ( msg && msg.role === 'user' && msg.content.trim() && !msg.subAgentDirected ) { const sIdx = resolveSnapshotIdx(i); if (!seen.has(sIdx)) { seen.add(sIdx); targets.push(sIdx); } } } (async () => { const next = new Map(); for (const sIdx of targets) { try { const files = await hashBasedSnapshotManager.getFilesToRollback( session.id, sIdx, ); next.set(sIdx, files.length); } catch { next.set(sIdx, 0); } if (cancelled) return; } if (cancelled) return; setDedupedFileCount(next); })(); return () => { cancelled = true; }; }, [messages, snapshotFileCount, resolveSnapshotIdx]); // Load file list when Tab is pressed on a message const loadFileList = useCallback( async (messageIndex: number) => { const currentSession = sessionManager.getCurrentSession(); if (!currentSession) return; const sIdx = resolveSnapshotIdx(messageIndex); const files = await hashBasedSnapshotManager.getFilesToRollback( currentSession.id, sIdx, ); setFilePaths(files); setFileHighlightIndex(0); setFileScrollIndex(0); setActiveMessageIndex(sIdx); setViewMode('files'); }, [resolveSnapshotIdx], ); // Send all diffs to IDE (snapshotIdx is already in snapshot coordinate space) const handleSelectSnapshot = useCallback( async (snapshotIdx: number) => { setBusy(true); try { const currentSession = sessionManager.getCurrentSession(); if (!currentSession || !vscodeConnection.isConnected()) { onClose(); return; } const allFiles = await hashBasedSnapshotManager.getFilesToRollback( currentSession.id, snapshotIdx, ); if (allFiles.length === 0) { onClose(); return; } const diffFiles: Array<{ filePath: string; originalContent: string; newContent: string; }> = []; for (const relativeFile of allFiles) { try { const preview = await hashBasedSnapshotManager.getRollbackPreviewForFile( currentSession.id, snapshotIdx, relativeFile, ); const originalContent = preview.rollbackContent; let currentContent = ''; try { currentContent = await fs.readFile(preview.absolutePath, 'utf-8'); } catch { currentContent = ''; } if (originalContent !== currentContent) { diffFiles.push({ filePath: preview.absolutePath, originalContent, newContent: currentContent, }); } } catch { // skip } } if (diffFiles.length > 0) { // Mark before sending so the unmount cleanup triggered by // onClose() below will NOT close the diffs we just opened. skipCloseOnUnmountRef.current = true; await vscodeConnection.showDiffReview(diffFiles); } } catch { // silently fail } finally { onClose(); } }, [onClose], ); useInput((_input, key) => { if (busy) return; if (key.escape) { if (viewMode === 'files') { closeDiffPreview(); setViewMode('messages'); return; } onClose(); return; } // Tab toggles file list view for current message if (key.tab && viewMode === 'messages' && userMessages.length > 0) { const selected = userMessages[selectedIndex]; if (selected && selected.fileCount > 0) { void loadFileList(selected.originalIndex); } return; } if (key.tab && viewMode === 'files') { closeDiffPreview(); setViewMode('messages'); return; } if (viewMode === 'files') { const maxScroll = Math.max(0, filePaths.length - MAX_VISIBLE_FILES); if (key.upArrow) { setFileHighlightIndex(prev => { const newIdx = Math.max(0, prev - 1); if (newIdx < fileScrollIndex) { setFileScrollIndex(newIdx); } return newIdx; }); return; } if (key.downArrow) { setFileHighlightIndex(prev => { const newIdx = Math.min(filePaths.length - 1, prev + 1); if (newIdx >= fileScrollIndex + MAX_VISIBLE_FILES) { setFileScrollIndex( Math.min(maxScroll, newIdx - MAX_VISIBLE_FILES + 1), ); } return newIdx; }); return; } // Enter in file mode: send all diffs (activeMessageIndex is already snapshot-space) if (key.return && activeMessageIndex !== null) { // Do NOT call closeDiffPreview here — it would close the // multi-file diffs that handleSelectSnapshot is about to open // (showDiff and closeDiff share the same activeDiffEditors list // on the VSCode side, so a close right before showDiffReview // races with the editors being created). void handleSelectSnapshot(activeMessageIndex); return; } return; } // Message list navigation if (key.upArrow) { setSelectedIndex(prev => (prev > 0 ? prev - 1 : userMessages.length - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => (prev < userMessages.length - 1 ? prev + 1 : 0)); return; } if (key.return && userMessages.length > 0) { const selected = userMessages[selectedIndex]; if (selected) { void handleSelectSnapshot(resolveSnapshotIdx(selected.originalIndex)); } return; } }); const dividerWidth = Math.max(1, (terminalWidth ?? 80) - 2); const divider = '─'.repeat(dividerWidth); if (userMessages.length === 0) { return ( {divider} {t.diffReviewPanel.title} {t.diffReviewPanel.noSnapshots} ); } // File list view if (viewMode === 'files') { const displayFiles = filePaths.slice( fileScrollIndex, fileScrollIndex + MAX_VISIBLE_FILES, ); const hasMoreAbove = fileScrollIndex > 0; const hasMoreBelow = fileScrollIndex + MAX_VISIBLE_FILES < filePaths.length; return ( {divider} {t.diffReviewPanel.title} -{' '} {t.diffReviewPanel.filesSuffix.replace( '{count}', String(filePaths.length), )} {t.diffReviewPanel.filesViewNavigationHint} {hasMoreAbove && ( {t.diffReviewPanel.moreAbove.replace( '{count}', String(fileScrollIndex), )} )} {displayFiles.map((file, idx) => { const actualIdx = fileScrollIndex + idx; const isHighlighted = actualIdx === fileHighlightIndex; return ( {isHighlighted ? '❯ ' : ' '} {file} ); })} {hasMoreBelow && ( {t.diffReviewPanel.moreBelow.replace( '{count}', String(filePaths.length - fileScrollIndex - MAX_VISIBLE_FILES), )} )} ); } let startIndex = 0; if (userMessages.length > VISIBLE_ITEMS) { startIndex = Math.max(0, selectedIndex - Math.floor(VISIBLE_ITEMS / 2)); startIndex = Math.min(startIndex, userMessages.length - VISIBLE_ITEMS); } const endIndex = Math.min(userMessages.length, startIndex + VISIBLE_ITEMS); const visibleMessages = userMessages.slice(startIndex, endIndex); const hasMoreAbove = startIndex > 0; const hasMoreBelow = endIndex < userMessages.length; return ( {divider} {t.diffReviewPanel.title} ({selectedIndex + 1}/{userMessages.length}) {t.diffReviewPanel.navigationHint} {hasMoreAbove && ( {t.diffReviewPanel.moreAbove.replace( '{count}', String(startIndex), )} )} {visibleMessages.map((item, displayIndex) => { const actualIndex = startIndex + displayIndex; const isSelected = actualIndex === selectedIndex; return ( {isSelected ? '❯ ' : ' '} {item.label} {item.fileCount > 0 && ( {' '} [ {t.diffReviewPanel.filesSuffix.replace( '{count}', String(item.fileCount), )} ] )} ); })} {hasMoreBelow && ( {t.diffReviewPanel.moreBelow.replace( '{count}', String(userMessages.length - endIndex), )} )} ); } ================================================ FILE: source/ui/components/panels/GitLinePickerPanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {Alert} from '@inkjs/ui'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import type {GitLineCommit} from '../../../hooks/picker/useGitLinePicker.js'; import PickerList from '../common/PickerList.js'; interface Props { commits: GitLineCommit[]; selectedIndex: number; selectedCommits: Set; visible: boolean; maxHeight?: number; hasMore?: boolean; isLoading?: boolean; isLoadingMore?: boolean; searchQuery?: string; error?: string | null; } function formatShortSha(sha: string): string { return sha.slice(0, 8); } function formatDate(isoDate: string): string { const match = isoDate.match(/^(\d{4}-\d{2}-\d{2})/); return match?.[1] ?? isoDate; } function truncateText(text: string, maxLen: number): string { if (maxLen <= 0) return ''; if (text.length <= maxLen) return text; if (maxLen === 1) return '…'; return text.slice(0, Math.max(1, maxLen - 1)) + '…'; } const GitLinePickerPanel = memo( ({ commits, selectedIndex, selectedCommits, visible, maxHeight, hasMore = false, isLoading = false, isLoadingMore = false, searchQuery = '', error = null, }: Props) => { const {t} = useI18n(); const {theme} = useTheme(); if (!visible) { return null; } if (isLoading) { return ( {t.gitLinePickerPanel.title} {t.gitLinePickerPanel.loadingCommits} ); } if (error) { return ( {t.gitLinePickerPanel.title} {error} ); } if (commits.length === 0) { return ( {t.gitLinePickerPanel.title} {t.gitLinePickerPanel.noCommits} ); } return ( commit.sha} title={ {t.gitLinePickerPanel.title}{' '} {commits.length > 5 && `(${selectedIndex + 1}/${commits.length})`} {isLoadingMore ? ` ${t.gitLinePickerPanel.loadingMoreSuffix}` : ''} } header={ {t.gitLinePickerPanel.searchLabel}{' '} {searchQuery || t.gitLinePickerPanel.emptySearch} {t.gitLinePickerPanel.hintNavigation} } footer={ selectedCommits.size > 0 ? ( {t.gitLinePickerPanel.selectedLabel}:{' '} {selectedCommits.size} ) : undefined } scrollHintFormat={(above, below) => ( {t.commandPanel.scrollHint} {above > 0 && ( <> ·{' '} {t.commandPanel.moreAbove.replace( '{count}', above.toString(), )} )} {below > 0 && ( <> ·{' '} {t.commandPanel.moreBelow.replace( '{count}', below.toString(), )} )} {hasMore && <>· {t.gitLinePickerPanel.scrollToLoadMore}} )} renderItem={(commit: GitLineCommit, isSelected: boolean) => { const isChecked = selectedCommits.has(commit.sha); const title = commit.kind === 'staged' ? `${t.reviewCommitPanel.stagedLabel} (${ commit.fileCount ?? 0 } ${t.reviewCommitPanel.filesLabel})` : `${formatShortSha(commit.sha)} ${truncateText( commit.subject, 72, )}`; const subtitle = commit.kind === 'staged' ? '' : `${commit.authorName} · ${formatDate(commit.dateIso)}`; return ( <> {isSelected ? '❯ ' : ' '} {isChecked ? '[✓]' : '[ ]'} {title} {subtitle ? ( └─ {subtitle} ) : null} ); }} /> ); }, ); GitLinePickerPanel.displayName = 'GitLinePickerPanel'; export default GitLinePickerPanel; ================================================ FILE: source/ui/components/panels/HelpPanel.tsx ================================================ import React, {useState, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import {useI18n} from '../../../i18n/index.js'; const MAX_VISIBLE_LINES = 10; // Get platform-specific paste key const getPasteKey = () => { return process.platform === 'darwin' ? 'Ctrl+V' : 'Alt+V'; }; type HelpLine = | {type: 'title'; text: string; color: string} | {type: 'item'; text: string; dim?: boolean} | {type: 'spacer'}; export default function HelpPanel() { const pasteKey = getPasteKey(); const {t} = useI18n(); const lines: HelpLine[] = useMemo(() => { const result: HelpLine[] = []; result.push({type: 'title', text: t.helpPanel.title, color: 'cyan'}); result.push({type: 'spacer'}); result.push({ type: 'title', text: t.helpPanel.textEditingTitle, color: 'yellow', }); result.push({type: 'item', text: ` • ${t.helpPanel.deleteToStart}`}); result.push({type: 'item', text: ` • ${t.helpPanel.deleteToEnd}`}); result.push({type: 'item', text: ` • ${t.helpPanel.copyInput}`}); result.push({ type: 'item', text: ` • ${t.helpPanel.pasteImages.replace('{pasteKey}', pasteKey)}`, }); result.push({type: 'item', text: ` • ${t.helpPanel.toggleExpandedView}`}); result.push({type: 'spacer'}); result.push({ type: 'title', text: t.helpPanel.readlineTitle, color: 'cyan', }); result.push({type: 'item', text: ` • ${t.helpPanel.moveToLineStart}`}); result.push({type: 'item', text: ` • ${t.helpPanel.moveToLineEnd}`}); result.push({type: 'item', text: ` • ${t.helpPanel.forwardWord}`}); result.push({type: 'item', text: ` • ${t.helpPanel.backwardWord}`}); result.push({type: 'item', text: ` • ${t.helpPanel.deleteToLineEnd}`}); result.push({type: 'item', text: ` • ${t.helpPanel.deleteToLineStart}`}); result.push({type: 'item', text: ` • ${t.helpPanel.deleteWord}`}); result.push({type: 'item', text: ` • ${t.helpPanel.deleteChar}`}); result.push({type: 'spacer'}); result.push({ type: 'title', text: t.helpPanel.quickAccessTitle, color: 'green', }); result.push({type: 'item', text: ` • ${t.helpPanel.insertFiles}`}); result.push({type: 'item', text: ` • ${t.helpPanel.searchContent}`}); result.push({type: 'item', text: ` • ${t.helpPanel.selectAgent}`}); result.push({type: 'item', text: ` • ${t.helpPanel.showCommands}`}); result.push({type: 'spacer'}); result.push({ type: 'title', text: t.helpPanel.bashModeTitle, color: 'yellow', }); result.push({type: 'item', text: ` • ${t.helpPanel.bashModeTrigger}`}); result.push({ type: 'item', text: ` ${t.helpPanel.bashModeDesc}`, dim: true, }); result.push({type: 'spacer'}); result.push({ type: 'title', text: t.helpPanel.navigationTitle, color: 'blue', }); result.push({type: 'item', text: ` • ${t.helpPanel.navigateHistory}`}); result.push({type: 'item', text: ` • ${t.helpPanel.selectItem}`}); result.push({type: 'item', text: ` • ${t.helpPanel.cancelClose}`}); result.push({type: 'item', text: ` • ${t.helpPanel.toggleYolo}`}); result.push({type: 'spacer'}); result.push({ type: 'title', text: t.helpPanel.tipsTitle, color: 'magenta', }); result.push({type: 'item', text: ` • ${t.helpPanel.tipUseHelp}`}); result.push({type: 'item', text: ` • ${t.helpPanel.tipShowCommands}`}); result.push({type: 'item', text: ` • ${t.helpPanel.tipInterrupt}`}); return result; }, [t, pasteKey]); const maxVisible = Math.min(lines.length, MAX_VISIBLE_LINES); const canScroll = lines.length > maxVisible; const [offset, setOffset] = useState(0); useInput((_input, key) => { if (!canScroll) return; if (key.upArrow) { setOffset(prev => Math.max(0, prev - 1)); } else if (key.downArrow) { setOffset(prev => Math.min(lines.length - maxVisible, prev + 1)); } else if (key.pageUp) { setOffset(prev => Math.max(0, prev - maxVisible)); } else if (key.pageDown) { setOffset(prev => Math.min(lines.length - maxVisible, prev + maxVisible)); } }); const clampedOffset = Math.min( Math.max(0, offset), Math.max(0, lines.length - maxVisible), ); const visibleLines = lines.slice(clampedOffset, clampedOffset + maxVisible); const hiddenAbove = clampedOffset; const hiddenBelow = Math.max(0, lines.length - clampedOffset - maxVisible); const renderLine = (line: HelpLine, index: number) => { if (line.type === 'spacer') { return ; } if (line.type === 'title') { return ( {line.text} ); } return ( {line.text} ); }; return ( {canScroll && hiddenAbove > 0 && ( ↑ {t.commandPanel.moreAbove.replace('{count}', String(hiddenAbove))} )} {visibleLines.map((line, idx) => renderLine(line, clampedOffset + idx))} {canScroll && hiddenBelow > 0 && ( ↓ {t.commandPanel.moreBelow.replace('{count}', String(hiddenBelow))} )} {canScroll && ( {t.commandPanel.scrollHint} )} ); } ================================================ FILE: source/ui/components/panels/IdeSelectPanel.tsx ================================================ import React, {useCallback, useEffect, useMemo, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import Spinner from 'ink-spinner'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/index.js'; import { vscodeConnection, type IDEInfo, } from '../../../utils/ui/vscodeConnection.js'; interface Props { visible: boolean; onClose: () => void; onConnectionChange: ( status: 'connected' | 'disconnected', message?: string, ) => void; /** * Notify parent that the working directory has been changed via process.chdir(). * Parent should remount static UI (e.g. ChatHeader) to reflect the new cwd. */ onWorkingDirectoryChanged?: (newCwd: string) => void; } interface OptionItem { label: string; value: string; port: number; ideName: string; workspace: string; isCurrent: boolean; // When true, selecting this option will chdir to its workspace before connecting switchWorkdir: boolean; // Section divider rendered above this option sectionHeader?: string; } export const IdeSelectPanel: React.FC = ({ visible, onClose, onConnectionChange, onWorkingDirectoryChanged, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [selectedIndex, setSelectedIndex] = useState(0); const [connecting, setConnecting] = useState(false); const {matched, unmatched} = useMemo(() => { if (!visible) return {matched: [] as IDEInfo[], unmatched: [] as IDEInfo[]}; return vscodeConnection.getAvailableIDEs(); }, [visible]); const currentPort = vscodeConnection.getPort(); const isConnected = vscodeConnection.isConnected(); // Options: matched IDEs + "None" + unmatched IDEs (switch cwd) const options = useMemo(() => { const items: OptionItem[] = []; let displayIndex = 0; matched.forEach(ide => { displayIndex++; const isCurrent = isConnected && ide.port === currentPort; items.push({ label: `${displayIndex}. ${ide.name}${ isCurrent ? t.ideSelectPanel.connectedMark : '' }`, value: `ide-${displayIndex}`, port: ide.port, ideName: ide.name, workspace: ide.workspace, isCurrent, switchWorkdir: false, }); }); displayIndex++; items.push({ label: `${displayIndex}. ${t.ideSelectPanel.noneOption}`, value: 'none', port: 0, ideName: '', workspace: '', isCurrent: !isConnected, switchWorkdir: false, }); unmatched.forEach((ide, i) => { displayIndex++; items.push({ label: `${displayIndex}. ${ide.name} (${ide.workspace})${t.ideSelectPanel.switchWorkdirMark}`, value: `unmatched-${i}`, port: ide.port, ideName: ide.name, workspace: ide.workspace, isCurrent: false, switchWorkdir: true, sectionHeader: i === 0 ? t.ideSelectPanel.unmatchedHeader : undefined, }); }); return items; }, [matched, unmatched, isConnected, currentPort, t]); useEffect(() => { if (!visible) return; setSelectedIndex(0); setConnecting(false); }, [visible]); const handleSelect = useCallback( async (index: number) => { const option = options[index]; if (!option || connecting) return; if (option.value === 'none') { if (isConnected) { vscodeConnection.stop(); vscodeConnection.resetReconnectAttempts(); vscodeConnection.setUserDisconnected(true); onConnectionChange('disconnected'); } onClose(); return; } if (option.isCurrent) { onClose(); return; } setConnecting(true); // If this option requires switching the working directory, do it first if (option.switchWorkdir && option.workspace) { try { process.chdir(option.workspace); const newCwd = process.cwd(); vscodeConnection.setCurrentWorkingDirectory(newCwd); onWorkingDirectoryChanged?.(newCwd); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown error'; onConnectionChange( 'disconnected', t.ideSelectPanel.switchWorkdirError.replace('{error}', errorMsg), ); setConnecting(false); return; } } try { await vscodeConnection.connectToPort(option.port); const label = `${option.ideName} (${option.workspace})`; onConnectionChange( 'connected', t.ideSelectPanel.connectSuccess.replace('{label}', label), ); onClose(); } catch (error) { const errorMsg = error instanceof Error ? error.message : 'Unknown error'; onConnectionChange( 'disconnected', t.ideSelectPanel.connectError.replace('{error}', errorMsg), ); setConnecting(false); } }, [options, connecting, isConnected, onConnectionChange, onClose, t], ); useInput( (input, key) => { if (!visible || connecting) return; if (key.escape) { onClose(); return; } if (key.upArrow) { setSelectedIndex(prev => (prev > 0 ? prev - 1 : options.length - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => (prev < options.length - 1 ? prev + 1 : 0)); return; } if (key.return) { void handleSelect(selectedIndex); return; } // Number shortcuts const num = parseInt(input, 10); if (num >= 1 && num <= options.length) { void handleSelect(num - 1); } }, {isActive: visible}, ); if (!visible) return null; return ( {t.ideSelectPanel.title} {t.ideSelectPanel.subtitle} {connecting ? ( {' '} {t.ideSelectPanel.connecting} ) : ( {options.map((option, index) => ( {option.sectionHeader && ( {option.sectionHeader} )} {index === selectedIndex ? '❯ ' : ' '} {option.label} ))} )} {unmatched.length > 0 && !connecting && ( {t.ideSelectPanel.unmatchedIDEs.replace( '{count}', String(unmatched.length), )} )} {!connecting && ( {t.ideSelectPanel.hint} )} ); }; ================================================ FILE: source/ui/components/panels/MCPInfoPanel.tsx ================================================ import React, {useState, useEffect, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import { getMCPServicesInfo, refreshMCPToolsCache, reconnectMCPService, } from '../../../utils/execution/mcpToolsManager.js'; import { getMCPConfigByScope, updateMCPConfig, getMCPServerSource, type MCPConfigScope, } from '../../../utils/config/apiConfig.js'; import {toggleBuiltInService} from '../../../utils/config/disabledBuiltInTools.js'; import { toggleMCPTool, isMCPToolEnabled, isMCPToolDisabledInScope, } from '../../../utils/config/disabledMCPTools.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import {useTheme} from '../../contexts/ThemeContext.js'; // Sub-component for displaying tools list with scrolling support interface ToolsListProps { tools: Array<{name: string; description: string}>; selectedIndex: number; maxDisplayItems: number; toolEnabledMap?: Record; disabledLabel?: string; scopeLabels?: Record; toolScopeMap?: Record; } function ToolsList({ tools, selectedIndex, maxDisplayItems, toolEnabledMap, disabledLabel, scopeLabels, toolScopeMap, }: ToolsListProps) { const {theme} = useTheme(); // Calculate display window for scrolling const displayWindow = useMemo(() => { if (tools.length <= maxDisplayItems) { return { tools: tools, startIndex: 0, endIndex: tools.length, hiddenAbove: 0, hiddenBelow: 0, }; } const halfWindow = Math.floor(maxDisplayItems / 2); let startIndex = Math.max(0, selectedIndex - halfWindow); const endIndex = Math.min(tools.length, startIndex + maxDisplayItems); if (endIndex - startIndex < maxDisplayItems) { startIndex = Math.max(0, endIndex - maxDisplayItems); } return { tools: tools.slice(startIndex, endIndex), startIndex, endIndex, hiddenAbove: startIndex, hiddenBelow: tools.length - endIndex, }; }, [tools, selectedIndex, maxDisplayItems]); return ( {displayWindow.hiddenAbove > 0 && ( ↑ {displayWindow.hiddenAbove} more above )} {displayWindow.tools.map((tool, displayIdx) => { const actualIndex = displayWindow.startIndex + displayIdx; const isToolSelected = actualIndex === selectedIndex; const isLast = actualIndex === tools.length - 1; const treeChar = isLast ? '└─' : '├─'; const isEnabled = toolEnabledMap ? toolEnabledMap[tool.name] !== false : true; const scopeKey = toolScopeMap?.[tool.name]; const scopeLabel = scopeKey && scopeLabels ? scopeLabels[scopeKey] : ''; const maxDescLength = 60; const truncatedDesc = tool.description.length > maxDescLength ? tool.description.slice(0, maxDescLength - 3) + '...' : tool.description; return ( {isToolSelected ? '❯ ' : ' '} ●{' '} {treeChar} {tool.name} {!isEnabled && disabledLabel && ( {' '} {disabledLabel} )} {!isEnabled && scopeLabel && ( {' '} {scopeLabel} )} {tool.description && isEnabled && ( {truncatedDesc} )} ); })} {displayWindow.hiddenBelow > 0 && ( ↓ {displayWindow.hiddenBelow} more below )} ); } interface ToolInfo { name: string; description: string; } interface MCPConnectionStatus { name: string; connected: boolean; tools: ToolInfo[]; connectionMethod?: string; error?: string; isBuiltIn?: boolean; enabled?: boolean; source?: MCPConfigScope; } interface SelectItem { label: string; value: string; connected?: boolean; isBuiltIn?: boolean; error?: string; isRefreshAll?: boolean; enabled?: boolean; source?: MCPConfigScope; } interface Props { onClose: () => void; } export default function MCPInfoPanel({onClose}: Props) { const {t} = useI18n(); const {theme} = useTheme(); const [mcpStatus, setMcpStatus] = useState([]); const [selectedIndex, setSelectedIndex] = useState(0); const [isLoading, setIsLoading] = useState(true); const [errorMessage, setErrorMessage] = useState(null); const [isReconnecting, setIsReconnecting] = useState(false); const [togglingService, setTogglingService] = useState(null); const [showToolsPage, setShowToolsPage] = useState(false); const [selectedServiceForTools, setSelectedServiceForTools] = useState(null); const [toolsSelectedIndex, setToolsSelectedIndex] = useState(0); const [togglingTool, setTogglingTool] = useState(null); const [toolEnabledMap, setToolEnabledMap] = useState>( {}, ); const [toolScopeMap, setToolScopeMap] = useState>({}); const loadMCPStatus = async () => { try { const servicesInfo = await getMCPServicesInfo(); const statusList: MCPConnectionStatus[] = servicesInfo.map(service => { let enabled: boolean; if (service.isBuiltIn) { enabled = service.enabled !== false; } else { const scope = service.source || 'global'; const scopeConfig = getMCPConfigByScope(scope); enabled = scopeConfig.mcpServers[service.serviceName]?.enabled !== false; } return { name: service.serviceName, connected: service.connected, tools: service.tools.map(tool => ({ name: tool.name, description: tool.description || '', })), connectionMethod: service.isBuiltIn ? 'Built-in' : 'External', isBuiltIn: service.isBuiltIn, error: service.error, enabled, source: service.source, }; }); setMcpStatus(statusList); setErrorMessage(null); setIsLoading(false); } catch (error) { setErrorMessage( error instanceof Error ? error.message : 'Failed to load MCP services', ); setIsLoading(false); } }; useEffect(() => { let isMounted = true; if (isMounted) { loadMCPStatus(); } return () => { isMounted = false; }; }, []); const handleServiceSelect = async (item: SelectItem) => { setIsReconnecting(true); try { if (item.value === 'refresh-all') { // Refresh all services await refreshMCPToolsCache(); } else if (item.isBuiltIn) { // Built-in system services just refresh cache await refreshMCPToolsCache(); } else { // Reconnect specific service await reconnectMCPService(item.value); } await loadMCPStatus(); } catch (error) { setErrorMessage( error instanceof Error ? error.message : 'Failed to reconnect', ); } finally { setIsReconnecting(false); } }; // Build select items: services only const selectItems: SelectItem[] = [ { label: t.mcpInfoPanel.refreshAll, value: 'refresh-all', isRefreshAll: true, }, ...mcpStatus.map(s => ({ label: s.name, value: s.name, connected: s.connected, isBuiltIn: s.isBuiltIn, error: s.error, enabled: s.enabled, source: s.source, })), ]; // Windowed display to prevent excessive height const MAX_DISPLAY_ITEMS = 8; const displayWindow = useMemo(() => { if (selectItems.length <= MAX_DISPLAY_ITEMS) { return { items: selectItems, startIndex: 0, endIndex: selectItems.length, }; } const halfWindow = Math.floor(MAX_DISPLAY_ITEMS / 2); let startIndex = Math.max(0, selectedIndex - halfWindow); const endIndex = Math.min( selectItems.length, startIndex + MAX_DISPLAY_ITEMS, ); if (endIndex - startIndex < MAX_DISPLAY_ITEMS) { startIndex = Math.max(0, endIndex - MAX_DISPLAY_ITEMS); } return { items: selectItems.slice(startIndex, endIndex), startIndex, endIndex, }; }, [selectItems, selectedIndex]); const displayedItems = displayWindow.items; const hiddenAboveCount = displayWindow.startIndex; const hiddenBelowCount = Math.max( 0, selectItems.length - displayWindow.endIndex, ); // Listen for keyboard input useInput(async (input, key) => { if (isReconnecting || togglingService || togglingTool) return; // ESC key to return to main page from tools page, or close panel from main page if (key.escape) { if (showToolsPage) { setShowToolsPage(false); setSelectedServiceForTools(null); setToolsSelectedIndex(0); } else { onClose(); } return; } // When in tools page, handle navigation and tool toggling if (showToolsPage && selectedServiceForTools) { if (key.upArrow) { setToolsSelectedIndex(prev => prev > 0 ? prev - 1 : (selectedServiceForTools.tools.length || 1) - 1, ); return; } if (key.downArrow) { setToolsSelectedIndex(prev => prev < (selectedServiceForTools.tools.length || 1) - 1 ? prev + 1 : 0, ); return; } if (key.tab) { const currentTool = selectedServiceForTools.tools[toolsSelectedIndex]; if (!currentTool) return; const scope: MCPConfigScope = selectedServiceForTools.isBuiltIn ? 'project' : selectedServiceForTools.source || 'global'; try { setTogglingTool(currentTool.name); const newEnabled = toggleMCPTool( selectedServiceForTools.name, currentTool.name, scope, ); setToolEnabledMap(prev => ({ ...prev, [currentTool.name]: newEnabled, })); if (!newEnabled) { setToolScopeMap(prev => ({ ...prev, [currentTool.name]: scope, })); } else { setToolScopeMap(prev => { const next = {...prev}; delete next[currentTool.name]; return next; }); } await refreshMCPToolsCache(); } catch (error) { setErrorMessage( error instanceof Error ? error.message : 'Failed to toggle tool', ); } finally { setTogglingTool(null); } } return; } // Arrow key navigation if (key.upArrow) { setSelectedIndex(prev => (prev > 0 ? prev - 1 : selectItems.length - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => (prev < selectItems.length - 1 ? prev + 1 : 0)); return; } // Enter to select (reconnect service) if (key.return) { const currentItem = selectItems[selectedIndex]; if (currentItem) { await handleServiceSelect(currentItem); } return; } // 'v' key to view tools list for selected service if (input.toLowerCase() === 'v') { const currentItem = selectItems[selectedIndex]; if (currentItem && !currentItem.isRefreshAll) { const service = mcpStatus.find(s => s.name === currentItem.value); if (service && service.tools.length > 0) { const enabledMap: Record = {}; const scopeMap: Record = {}; for (const tool of service.tools) { enabledMap[tool.name] = isMCPToolEnabled(service.name, tool.name); if (!enabledMap[tool.name]) { if ( isMCPToolDisabledInScope(service.name, tool.name, 'project') ) { scopeMap[tool.name] = 'project'; } else { scopeMap[tool.name] = 'global'; } } } setToolEnabledMap(enabledMap); setToolScopeMap(scopeMap); setSelectedServiceForTools(service); setShowToolsPage(true); setToolsSelectedIndex(0); } } return; } // Tab key to toggle enabled/disabled if (key.tab) { const currentItem = selectItems[selectedIndex]; if (!currentItem || currentItem.isRefreshAll) return; try { setTogglingService(currentItem.label); if (currentItem.isBuiltIn) { // Toggle built-in service toggleBuiltInService(currentItem.value); } else { // Toggle external MCP service (write to correct scope) const scope: MCPConfigScope = getMCPServerSource(currentItem.value) || 'global'; const scopeConfig = getMCPConfigByScope(scope); const serverConfig = scopeConfig.mcpServers[currentItem.value]; if (serverConfig) { const currentEnabled = serverConfig.enabled !== false; serverConfig.enabled = !currentEnabled; updateMCPConfig(scopeConfig, scope); } } // Refresh MCP tools cache and reload status await refreshMCPToolsCache(); await loadMCPStatus(); } catch (error) { setErrorMessage( error instanceof Error ? error.message : 'Failed to toggle service', ); } finally { setTogglingService(null); } } }); if (isLoading) { return ( {t.mcpInfoPanel.loading} ); } if (errorMessage) { return ( {t.mcpInfoPanel.error.replace('{message}', errorMessage)} ); } if (mcpStatus.length === 0) { return ( {t.mcpInfoPanel.noServices} ); } return ( {showToolsPage && selectedServiceForTools ? ( <> {togglingTool ? t.mcpInfoPanel.toolTogglingHint.replace( '{tool}', togglingTool, ) : `${t.mcpInfoPanel.toolsListTitle.replace( '{service}', selectedServiceForTools.name, )} (${toolsSelectedIndex + 1}/${ selectedServiceForTools.tools.length })`} {!togglingTool && ( )} {togglingTool && ( {t.mcpInfoPanel.pleaseWait} )} {t.mcpInfoPanel.toolsNavigationHint} {selectedServiceForTools.name === 'filesystem' && ( replaceedit: default off — Tab enables (writes .snow/opt-in-mcp-tools.json). )} ) : ( <> {isReconnecting ? t.mcpInfoPanel.refreshing : togglingService ? t.mcpInfoPanel.toggling.replace('{service}', togglingService) : t.mcpInfoPanel.title} {!isReconnecting && !togglingService && selectItems.length > MAX_DISPLAY_ITEMS && ` (${selectedIndex + 1}/${selectItems.length})`} {!isReconnecting && !togglingService && displayedItems.map((item, displayIndex) => { const originalIndex = displayWindow.startIndex + displayIndex; const isSelected = originalIndex === selectedIndex; // Render refresh-all item if (item.isRefreshAll) { return ( {isSelected ? '❯ ' : ' '}↻ {t.mcpInfoPanel.refreshAll} ); } // Render MCP service item const isEnabled = item.enabled !== false; const statusColor = !isEnabled ? theme.colors.menuSecondary : item.connected ? theme.colors.success : theme.colors.error; const sourceSuffix = !item.isBuiltIn && item.source === 'project' ? t.mcpInfoPanel.mcpSourceProject : !item.isBuiltIn && item.source === 'global' ? t.mcpInfoPanel.mcpSourceGlobal : ''; const suffix = !isEnabled ? t.mcpInfoPanel.statusDisabled : item.isBuiltIn ? t.mcpInfoPanel.statusSystem : item.connected ? `${t.mcpInfoPanel.statusExternal}${sourceSuffix}` : ` - ${item.error || t.mcpInfoPanel.statusFailed}`; return ( {isSelected ? '❯ ' : ' '} ● {item.label} {suffix} ); })} {!isReconnecting && !togglingService && selectItems.length > MAX_DISPLAY_ITEMS && ( {t.mcpInfoPanel.scrollHint} {hiddenAboveCount > 0 && ` · ${t.mcpInfoPanel.moreAbove.replace( '{count}', String(hiddenAboveCount), )}`} {hiddenBelowCount > 0 && ` · ${t.mcpInfoPanel.moreBelow.replace( '{count}', String(hiddenBelowCount), )}`} )} {(isReconnecting || togglingService) && ( {t.mcpInfoPanel.pleaseWait} )} {!isReconnecting && !togglingService && ( {t.mcpInfoPanel.navigationHint} )} )} ); } ================================================ FILE: source/ui/components/panels/ModelsPanel.tsx ================================================ import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import Spinner from 'ink-spinner'; import {Alert} from '@inkjs/ui'; import ScrollableSelectInput from '../common/ScrollableSelectInput.js'; import { fetchAvailableModels, filterModels, type Model, } from '../../../api/models.js'; import { getSnowConfig, updateSnowConfig, type RequestMethod, } from '../../../utils/config/apiConfig.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/index.js'; import {configEvents} from '../../../utils/config/configEvents.js'; interface Props { advancedModel: string; basicModel: string; visible: boolean; onClose: () => void; } type Tab = 'advanced' | 'basic' | 'thinking'; type ThinkingInputMode = null | 'anthropicBudgetTokens'; type ResponsesReasoningEffort = 'none' | 'low' | 'medium' | 'high' | 'xhigh'; type ResponsesVerbosity = 'low' | 'medium' | 'high'; export const ModelsPanel: React.FC = ({ advancedModel, basicModel, visible, onClose, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [activeTab, setActiveTab] = useState('advanced'); // 判断当前是否在模型选择页（非思考页） const isModelTab = activeTab === 'advanced' || activeTab === 'basic'; // Model settings const [localAdvancedModel, setLocalAdvancedModel] = useState(advancedModel); const [localBasicModel, setLocalBasicModel] = useState(basicModel); // Model list state const [models, setModels] = useState([]); const [loading, setLoading] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [isSelecting, setIsSelecting] = useState(false); const [searchTerm, setSearchTerm] = useState(''); const [manualInputMode, setManualInputMode] = useState(false); const [manualInputValue, setManualInputValue] = useState(''); const [hasStartedLoading, setHasStartedLoading] = useState(false); const [highlightedModelIndex, setHighlightedModelIndex] = useState(0); // 使用 ref 同步追踪选择状态，解决 ESC 键需要按两次的问题 const isSelectingRef = useRef(false); const manualInputModeRef = useRef(false); // Thinking settings (aligned with ConfigScreen) const [requestMethod, setRequestMethod] = useState('chat'); const [showThinking, setShowThinking] = useState(true); const [thinkingEnabled, setThinkingEnabled] = useState(false); const [thinkingMode, setThinkingMode] = useState<'tokens' | 'adaptive'>( 'tokens', ); const [thinkingBudgetTokens, setThinkingBudgetTokens] = useState(10000); const [thinkingEffort, setThinkingEffort] = useState< 'low' | 'medium' | 'high' | 'max' >('high'); const [geminiThinkingEnabled, setGeminiThinkingEnabled] = useState(false); const [geminiThinkingLevel, setGeminiThinkingLevel] = useState< 'minimal' | 'low' | 'medium' | 'high' >('high'); const [isGeminiLevelSelecting, setIsGeminiLevelSelecting] = useState(false); const [responsesReasoningEnabled, setResponsesReasoningEnabled] = useState(false); const [responsesReasoningEffort, setResponsesReasoningEffort] = useState('high'); const [responsesFastMode, setResponsesFastMode] = useState(false); const [responsesVerbosity, setResponsesVerbosity] = useState('medium'); // 思考页的聚焦索引，每种请求方案有独立的索引体系 const [thinkingFocusIndex, setThinkingFocusIndex] = useState(0); const [thinkingInputMode, setThinkingInputMode] = useState(null); const [thinkingInputValue, setThinkingInputValue] = useState(''); const [isThinkingModeSelecting, setIsThinkingModeSelecting] = useState(false); const [isThinkingEffortSelecting, setIsThinkingEffortSelecting] = useState(false); const [isVerbositySelecting, setIsVerbositySelecting] = useState(false); const [anthropicSpeed, setAnthropicSpeed] = useState< 'fast' | 'standard' | undefined >(undefined); const [isSpeedSelecting, setIsSpeedSelecting] = useState(false); const [chatThinkingEnabled, setChatThinkingEnabled] = useState(false); const [chatReasoningEffort, setChatReasoningEffort] = useState< 'low' | 'medium' | 'high' | 'max' >('high'); const [isChatEffortSelecting, setIsChatEffortSelecting] = useState(false); useEffect(() => { if (!visible) { return; } setActiveTab('advanced'); setLocalAdvancedModel(advancedModel); setLocalBasicModel(basicModel); // Reset transient UI state setIsSelecting(false); isSelectingRef.current = false; setSearchTerm(''); setManualInputMode(false); manualInputModeRef.current = false; setManualInputValue(''); setHasStartedLoading(false); setHighlightedModelIndex(0); setThinkingFocusIndex(0); setThinkingInputMode(null); setThinkingInputValue(''); setIsThinkingEffortSelecting(false); setIsVerbositySelecting(false); setIsSpeedSelecting(false); setErrorMessage(''); // Load thinking-related config on open const cfg = getSnowConfig(); setRequestMethod(cfg.requestMethod || 'chat'); setShowThinking(cfg.showThinking !== false); // default true setThinkingEnabled( cfg.thinking?.type === 'enabled' || cfg.thinking?.type === 'adaptive' || false, ); setThinkingMode(cfg.thinking?.type === 'adaptive' ? 'adaptive' : 'tokens'); setThinkingBudgetTokens(cfg.thinking?.budget_tokens || 10000); setThinkingEffort(cfg.thinking?.effort || 'high'); setGeminiThinkingEnabled((cfg as any).geminiThinking?.enabled || false); setGeminiThinkingLevel( (cfg as any).geminiThinking?.thinkingLevel || 'high', ); setIsGeminiLevelSelecting(false); setResponsesReasoningEnabled( (cfg as any).responsesReasoning?.enabled || false, ); setResponsesReasoningEffort( (cfg as any).responsesReasoning?.effort || 'high', ); setResponsesFastMode((cfg as any).responsesFastMode || false); setResponsesVerbosity((cfg as any).responsesVerbosity || 'medium'); setAnthropicSpeed((cfg as any).anthropicSpeed); setChatThinkingEnabled((cfg as any).chatThinking?.enabled || false); setChatReasoningEffort( (cfg as any).chatThinking?.reasoning_effort || 'high', ); setIsChatEffortSelecting(false); }, [visible, advancedModel, basicModel]); // Auto-hide error message after 3 seconds useEffect(() => { if (errorMessage) { const timer = setTimeout(() => { setErrorMessage(''); }, 3000); return () => clearTimeout(timer); } return undefined; }, [errorMessage]); const modelTarget: 'advanced' | 'basic' | 'thinking' = activeTab === 'basic' ? 'basic' : activeTab === 'thinking' ? 'thinking' : 'advanced'; const currentModel = modelTarget === 'advanced' ? localAdvancedModel : modelTarget === 'basic' ? localBasicModel : ''; const currentLabel = modelTarget === 'advanced' ? t.modelsPanel.advancedModelLabel : modelTarget === 'basic' ? t.modelsPanel.basicModelLabel : t.modelsPanel.thinkingLabel; const loadModels = useCallback(async () => { setLoading(true); setErrorMessage(''); try { const fetchedModels = await fetchAvailableModels(); setModels(fetchedModels); return fetchedModels; } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.loadingModels; setErrorMessage(message); throw err; } finally { setLoading(false); } }, [t]); const applyModel = useCallback( async (value: string, target: 'advanced' | 'basic') => { setErrorMessage(''); try { if (target === 'advanced') { await updateSnowConfig({advancedModel: value}); setLocalAdvancedModel(value); } else { await updateSnowConfig({basicModel: value}); setLocalBasicModel(value); } } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.modelSaveFailed; setErrorMessage(message); } }, [], ); const filteredModels = useMemo( () => filterModels(models, searchTerm), [models, searchTerm], ); const currentOptions = useMemo(() => { const seen = new Set(); const uniqueModels = filteredModels.filter(model => { if (seen.has(model.id)) return false; seen.add(model.id); return true; }); return [ {label: t.modelsPanel.manualInputOption, value: '__MANUAL_INPUT__'}, ...uniqueModels.map(model => ({ label: model.id, value: model.id, })), ]; }, [filteredModels, t]); const handleModelSelect = useCallback( (value: string) => { if (value === '__MANUAL_INPUT__') { isSelectingRef.current = false; setIsSelecting(false); setSearchTerm(''); manualInputModeRef.current = true; setManualInputMode(true); setManualInputValue(currentModel); setHasStartedLoading(false); return; } // 思考页不应该调用applyModel if (modelTarget !== 'thinking') { void applyModel(value, modelTarget); } isSelectingRef.current = false; setIsSelecting(false); setSearchTerm(''); setHasStartedLoading(false); }, [applyModel, currentModel, modelTarget], ); const handleManualSave = useCallback(() => { const cleaned = manualInputValue.trim(); if (cleaned && modelTarget !== 'thinking') { void applyModel(cleaned, modelTarget); } manualInputModeRef.current = false; setManualInputMode(false); setManualInputValue(''); setSearchTerm(''); setHasStartedLoading(false); }, [applyModel, manualInputValue, modelTarget]); const thinkingEnabledValue = useMemo(() => { if (requestMethod === 'anthropic') { return thinkingEnabled; } if (requestMethod === 'gemini') { return geminiThinkingEnabled; } if (requestMethod === 'responses') { return responsesReasoningEnabled; } if (requestMethod === 'chat') { return chatThinkingEnabled; } return false; }, [ requestMethod, thinkingEnabled, geminiThinkingEnabled, responsesReasoningEnabled, chatThinkingEnabled, ]); const thinkingStrengthValue = useMemo(() => { if (requestMethod === 'anthropic') { return thinkingMode === 'adaptive' ? thinkingEffort : String(thinkingBudgetTokens); } if (requestMethod === 'gemini') { return geminiThinkingLevel.toUpperCase(); } if (requestMethod === 'responses') { return responsesReasoningEffort; } if (requestMethod === 'chat') { return chatReasoningEffort.toUpperCase(); } return t.modelsPanel.notSupported; }, [ requestMethod, thinkingMode, thinkingBudgetTokens, thinkingEffort, geminiThinkingLevel, responsesReasoningEffort, chatReasoningEffort, t, ]); const applyShowThinking = useCallback(async (next: boolean) => { setErrorMessage(''); try { setShowThinking(next); await updateSnowConfig({showThinking: next}); // Emit config change event for real-time sync configEvents.emitConfigChange({ type: 'showThinking', value: next, }); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, []); const applyChatThinkingEnabled = useCallback( async (next: boolean) => { setErrorMessage(''); try { if (!next && showThinking) { setShowThinking(false); await updateSnowConfig({showThinking: false}); configEvents.emitConfigChange({type: 'showThinking', value: false}); } setChatThinkingEnabled(next); await updateSnowConfig({ chatThinking: next ? {enabled: true, reasoning_effort: chatReasoningEffort} : undefined, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [showThinking, chatReasoningEffort], ); const applyThinkingEnabled = useCallback( async (next: boolean) => { setErrorMessage(''); try { // Turning off thinking → auto turn off show thinking if (!next && showThinking) { setShowThinking(false); await updateSnowConfig({showThinking: false}); configEvents.emitConfigChange({type: 'showThinking', value: false}); } if (requestMethod === 'anthropic') { setThinkingEnabled(next); await updateSnowConfig({ thinking: next ? thinkingMode === 'adaptive' ? {type: 'adaptive' as const, effort: thinkingEffort} : { type: 'enabled' as const, budget_tokens: thinkingBudgetTokens, } : undefined, } as any); return; } if (requestMethod === 'gemini') { setGeminiThinkingEnabled(next); await updateSnowConfig({ geminiThinking: next ? {enabled: true, thinkingLevel: geminiThinkingLevel} : undefined, } as any); return; } if (requestMethod === 'responses') { setResponsesReasoningEnabled(next); await updateSnowConfig({ responsesReasoning: { enabled: next, effort: responsesReasoningEffort, }, } as any); return; } if (requestMethod === 'chat') { void applyChatThinkingEnabled(next); return; } setErrorMessage( t.modelsPanel.requestMethodNotSupportedForThinking.replace( '{requestMethod}', requestMethod, ), ); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [ requestMethod, showThinking, thinkingMode, thinkingBudgetTokens, thinkingEffort, geminiThinkingLevel, responsesReasoningEffort, applyChatThinkingEnabled, t, ], ); const applyAnthropicBudgetTokens = useCallback( async (next: number) => { setErrorMessage(''); try { setThinkingBudgetTokens(next); await updateSnowConfig({ thinking: thinkingEnabled ? thinkingMode === 'adaptive' ? {type: 'adaptive' as const, effort: thinkingEffort} : {type: 'enabled' as const, budget_tokens: next} : undefined, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [thinkingEnabled, thinkingMode, thinkingEffort], ); const applyThinkingMode = useCallback( async (next: 'tokens' | 'adaptive') => { setErrorMessage(''); try { setThinkingMode(next); await updateSnowConfig({ thinking: thinkingEnabled ? next === 'adaptive' ? {type: 'adaptive' as const, effort: thinkingEffort} : {type: 'enabled' as const, budget_tokens: thinkingBudgetTokens} : undefined, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [thinkingEnabled, thinkingEffort, thinkingBudgetTokens], ); const applyThinkingEffort = useCallback( async (next: 'low' | 'medium' | 'high' | 'max') => { setErrorMessage(''); try { setThinkingEffort(next); await updateSnowConfig({ thinking: thinkingEnabled ? {type: 'adaptive' as const, effort: next} : undefined, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [thinkingEnabled], ); const applyGeminiLevel = useCallback( async (next: 'minimal' | 'low' | 'medium' | 'high') => { setErrorMessage(''); try { setGeminiThinkingLevel(next); await updateSnowConfig({ geminiThinking: geminiThinkingEnabled ? {enabled: true, thinkingLevel: next} : undefined, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [geminiThinkingEnabled], ); const applyResponsesEffort = useCallback( async (effort: ResponsesReasoningEffort) => { setErrorMessage(''); try { setResponsesReasoningEffort(effort); await updateSnowConfig({ responsesReasoning: { enabled: responsesReasoningEnabled, effort, }, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [responsesReasoningEnabled], ); const applyResponsesVerbosity = useCallback( async (verbosity: ResponsesVerbosity) => { setErrorMessage(''); try { setResponsesVerbosity(verbosity); await updateSnowConfig({ responsesVerbosity: verbosity, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [], ); const applyChatReasoningEffort = useCallback( async (effort: 'low' | 'medium' | 'high' | 'max') => { setErrorMessage(''); try { setChatReasoningEffort(effort); await updateSnowConfig({ chatThinking: { enabled: chatThinkingEnabled, reasoning_effort: effort, }, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [chatThinkingEnabled], ); const applyAnthropicSpeed = useCallback( async (next: 'fast' | 'standard' | undefined) => { setErrorMessage(''); try { setAnthropicSpeed(next); await updateSnowConfig({ anthropicSpeed: next, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, [], ); const applyResponsesFastMode = useCallback(async (next: boolean) => { setErrorMessage(''); try { setResponsesFastMode(next); await updateSnowConfig({ responsesFastMode: next, } as any); } catch (err) { const message = err instanceof Error ? err.message : t.modelsPanel.saveFailed; setErrorMessage(message); } }, []); // 每种请求方案的最大聚焦索引（各自独立） // anthropic: 0=showThinking, 1=enableThinking, 2=thinkingMode, 3=thinkingStrength, 4=anthropicSpeed // gemini: 0=showThinking, 1=enableThinking, 2=thinkingStrength // responses: 0=showThinking, 1=enableThinking, 2=thinkingStrength, 3=verbosity, 4=fastMode // chat: 0=showThinking, 1=enableThinking, 2=thinkingStrength // other: 0=showThinking, 1=enableThinking const maxThinkingIndex = useMemo(() => { if (requestMethod === 'anthropic') return 4; if (requestMethod === 'responses') return 4; if (requestMethod === 'gemini') return 2; if (requestMethod === 'chat') return 2; return 1; }, [requestMethod]); const selectedIndex = Math.max( 0, currentOptions.findIndex(option => option.value === currentModel), ); // Ink/Chalk 对 hex 颜色通常只支持 #RRGGBB，这里把 #RRGGBBAA 的 alpha 去掉作为背景色使用。 const tabActiveBackground = theme.colors.menuSelected.startsWith('#') && theme.colors.menuSelected.length === 9 ? theme.colors.menuSelected.slice(0, 7) : theme.colors.menuSelected; useInput( (input, key) => { if (!visible) { return; } if (key.escape) { // 子视图内 ESC 仅收起回到默认视图。 // 使用 ref 同步检查状态，避免 React 状态更新延迟导致需要按两次 ESC if (thinkingInputMode) { setThinkingInputMode(null); setThinkingInputValue(''); return; } if (isThinkingModeSelecting) { setIsThinkingModeSelecting(false); return; } if (isGeminiLevelSelecting) { setIsGeminiLevelSelecting(false); return; } if (isThinkingEffortSelecting) { setIsThinkingEffortSelecting(false); return; } if (isVerbositySelecting) { setIsVerbositySelecting(false); return; } if (isSpeedSelecting) { setIsSpeedSelecting(false); return; } if (isChatEffortSelecting) { setIsChatEffortSelecting(false); return; } if (manualInputModeRef.current || manualInputMode) { manualInputModeRef.current = false; setManualInputMode(false); setManualInputValue(''); setSearchTerm(''); setHasStartedLoading(false); return; } if (isSelectingRef.current || isSelecting) { isSelectingRef.current = false; setIsSelecting(false); setSearchTerm(''); setHasStartedLoading(false); return; } // 如果正在加载或已经开始加载流程，ESC 取消加载返回主视图 if (loading || hasStartedLoading) { setHasStartedLoading(false); return; } // 如果在主视图，ESC 才关闭面板 onClose(); return; } // Thinking numeric input if (thinkingInputMode) { if (key.return) { const parsed = Number.parseInt(thinkingInputValue.trim(), 10); if (!Number.isNaN(parsed) && parsed >= 0) { if (thinkingInputMode === 'anthropicBudgetTokens') { void applyAnthropicBudgetTokens(parsed); } } setThinkingInputMode(null); setThinkingInputValue(''); return; } if (key.backspace || key.delete) { setThinkingInputValue(prev => prev.slice(0, -1)); return; } if (input && /[0-9]/.test(input)) { setThinkingInputValue(prev => prev + input); } return; } // Model manual input if (manualInputMode) { if (key.return) { handleManualSave(); return; } if (key.backspace || key.delete) { setManualInputValue(prev => prev.slice(0, -1)); return; } if (input) { setManualInputValue(prev => prev + input); } return; } // Model selecting filter input if (isSelecting) { if (input && /[a-zA-Z0-9-_.]/.test(input)) { setSearchTerm(prev => prev + input); return; } if (key.backspace || key.delete) { setSearchTerm(prev => prev.slice(0, -1)); } return; } // In list selection modes, avoid switching tabs or triggering other actions. if ( isThinkingModeSelecting || isGeminiLevelSelecting || isThinkingEffortSelecting || isVerbositySelecting || isSpeedSelecting || isChatEffortSelecting ) { return; } if (key.tab) { setActiveTab(prev => prev === 'advanced' ? 'basic' : prev === 'basic' ? 'thinking' : 'advanced', ); return; } // 思考页的上下键和Enter键处理 if (activeTab === 'thinking') { if (key.upArrow) { setThinkingFocusIndex(prev => prev === 0 ? maxThinkingIndex : prev - 1, ); return; } if (key.downArrow) { setThinkingFocusIndex(prev => prev === maxThinkingIndex ? 0 : prev + 1, ); return; } if (key.return) { if (thinkingFocusIndex === 0) { void applyShowThinking(!showThinking); } else if (thinkingFocusIndex === 1) { void applyThinkingEnabled(!thinkingEnabledValue); } else if (thinkingFocusIndex === 2) { if (requestMethod === 'anthropic') { setIsThinkingModeSelecting(true); } else if (requestMethod === 'gemini') { setIsGeminiLevelSelecting(true); } else if (requestMethod === 'responses') { setIsThinkingEffortSelecting(true); } else if (requestMethod === 'chat') { setIsChatEffortSelecting(true); } } else if (thinkingFocusIndex === 3) { if (requestMethod === 'anthropic') { if (thinkingMode === 'tokens') { setThinkingInputMode('anthropicBudgetTokens'); setThinkingInputValue(thinkingBudgetTokens.toString()); } else { setIsThinkingEffortSelecting(true); } } else if (requestMethod === 'responses') { setIsVerbositySelecting(true); } } else if (thinkingFocusIndex === 4) { if (requestMethod === 'anthropic') { setIsSpeedSelecting(true); } else if (requestMethod === 'responses') { void applyResponsesFastMode(!responsesFastMode); } } return; } return; } if (key.return) { setErrorMessage(''); // 标记已开始加载流程 setHasStartedLoading(true); void loadModels() .then(() => { isSelectingRef.current = true; setIsSelecting(true); }) .catch(() => { manualInputModeRef.current = true; setManualInputMode(true); setManualInputValue(currentModel); }); return; } if ((input === 'm' || input === 'M') && isModelTab) { manualInputModeRef.current = true; setManualInputMode(true); setManualInputValue(currentModel); } }, {isActive: visible}, ); if (!visible) { return null; } return ( {t.modelsPanel.title} - {t.modelsPanel.subtitle} {t.modelsPanel.tabAdvanced} {t.modelsPanel.tabBasic} {t.modelsPanel.tabThinking} {loading && activeTab !== 'thinking' && ( {' '} {t.modelsPanel.loadingModels} )} {errorMessage && !loading && ( {errorMessage} )} {activeTab === 'thinking' ? ( {t.modelsPanel.requestMethod} {requestMethod} {thinkingFocusIndex === 0 ? '❯ ' : ' '} {t.modelsPanel.showThinkingProcess} {' '} {showThinking ? '[✓]' : '[ ]'} {(requestMethod === 'anthropic' || requestMethod === 'gemini' || requestMethod === 'responses' || requestMethod === 'chat') && ( {thinkingFocusIndex === 1 ? '❯ ' : ' '} {t.modelsPanel.enableThinking} {' '} {thinkingEnabledValue ? '[✓]' : '[ ]'} )} {requestMethod === 'anthropic' && ( {thinkingFocusIndex === 2 ? '❯ ' : ' '} {t.configScreen.thinkingMode} {' '} {thinkingMode === 'tokens' ? t.configScreen.thinkingModeTokens : t.configScreen.thinkingModeAdaptive} )} {(requestMethod === 'anthropic' || requestMethod === 'gemini' || requestMethod === 'responses' || requestMethod === 'chat') && ( {thinkingFocusIndex === (requestMethod === 'anthropic' ? 3 : 2) ? '❯ ' : ' '} {t.modelsPanel.thinkingStrength} {' '} {thinkingStrengthValue} )} {requestMethod === 'anthropic' && ( {thinkingFocusIndex === 4 ? '❯ ' : ' '} {t.modelsPanel.anthropicSpeed} {' '} {anthropicSpeed === 'fast' ? t.configScreen.anthropicSpeedFast : anthropicSpeed === 'standard' ? t.configScreen.anthropicSpeedStandard : t.configScreen.anthropicSpeedNotUsed} )} {requestMethod === 'responses' && ( {thinkingFocusIndex === 3 ? '❯ ' : ' '} {t.configScreen.responsesVerbosity} {' '} {responsesVerbosity.toUpperCase()} )} {requestMethod === 'responses' && ( {thinkingFocusIndex === 4 ? '❯ ' : ' '} {t.configScreen.responsesFastMode} {' '} {responsesFastMode ? '[✓]' : '[ ]'} )} {thinkingInputMode && ( {t.modelsPanel.inputNumberHint} {`❯ ${thinkingInputValue}`} _ {t.modelsPanel.escCancel} )} {isThinkingModeSelecting && ( { void applyThinkingMode(item.value as 'tokens' | 'adaptive'); setIsThinkingModeSelecting(false); }} /> )} {isThinkingEffortSelecting && ( ({ label: i.label, value: i.value, }))} limit={6} disableNumberShortcuts={true} initialIndex={Math.max( 0, requestMethod === 'anthropic' ? (['low', 'medium', 'high', 'max'] as const).indexOf( thinkingEffort, ) : ( ['none', 'low', 'medium', 'high', 'xhigh'] as const ).indexOf(responsesReasoningEffort), )} isFocused={true} onSelect={item => { if (requestMethod === 'anthropic') { void applyThinkingEffort( item.value as 'low' | 'medium' | 'high' | 'max', ); } else { void applyResponsesEffort( item.value as ResponsesReasoningEffort, ); } setIsThinkingEffortSelecting(false); }} /> )} {isVerbositySelecting && ( { void applyResponsesVerbosity( item.value as ResponsesVerbosity, ); setIsVerbositySelecting(false); }} /> )} {isGeminiLevelSelecting && ( { void applyGeminiLevel( item.value as 'minimal' | 'low' | 'medium' | 'high', ); setIsGeminiLevelSelecting(false); }} /> )} {isSpeedSelecting && ( { void applyAnthropicSpeed( item.value === '__NONE__' ? undefined : (item.value as 'fast' | 'standard'), ); setIsSpeedSelecting(false); }} /> )} {isChatEffortSelecting && ( { void applyChatReasoningEffort( item.value as 'low' | 'medium' | 'high' | 'max', ); setIsChatEffortSelecting(false); }} /> )} {!thinkingInputMode && !isThinkingModeSelecting && !isGeminiLevelSelecting && !isThinkingEffortSelecting && !isVerbositySelecting && !isSpeedSelecting && !isChatEffortSelecting && ( {t.modelsPanel.navigationHint} )} ) : manualInputMode ? ( {t.modelsPanel.manualInputTitle} {currentLabel} {`❯ ${manualInputValue}`} _ {t.modelsPanel.manualInputHint} ) : isSelecting ? ( {searchTerm && ( {t.modelsPanel.filterLabel} {searchTerm} {' '} )} {t.modelsPanel.modelCount.replace( '{count}', (currentOptions.length - 1).toString(), )} {currentOptions.length > 10 && ` (${highlightedModelIndex + 1}/${currentOptions.length})`} handleModelSelect(item.value)} onHighlight={item => { const idx = currentOptions.findIndex(o => o.value === item.value); if (idx >= 0) setHighlightedModelIndex(idx); }} /> {currentOptions.length > 10 && ( {t.modelsPanel.scrollHint} )} ) : ( {t.modelsPanel.currentModel} {' '} {currentModel || t.modelsPanel.notSet} {t.modelsPanel.hint} )} ); }; export default ModelsPanel; ================================================ FILE: source/ui/components/panels/NewPromptPanel.tsx ================================================ import React, {useState, useCallback, useRef} from 'react'; import {Box, Text, useInput} from 'ink'; import Spinner from 'ink-spinner'; import TextInput from 'ink-text-input'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import {streamGeneratePrompt} from '../../../utils/commands/newPrompt.js'; type Step = 'input' | 'generating' | 'preview' | 'error'; interface Props { onAccept: (prompt: string) => void; onCancel: () => void; } const VISIBLE_LINES = 15; export const NewPromptPanel: React.FC = ({onAccept, onCancel}) => { const {theme} = useTheme(); const {t} = useI18n(); const [step, setStep] = useState('input'); const [requirement, setRequirement] = useState(''); const [generatedPrompt, setGeneratedPrompt] = useState(''); const [errorMessage, setErrorMessage] = useState(''); const [scrollOffset, setScrollOffset] = useState(0); const abortControllerRef = useRef(null); const generatePrompt = useCallback( async (userRequirement: string) => { setStep('generating'); setGeneratedPrompt(''); setScrollOffset(0); const controller = new AbortController(); abortControllerRef.current = controller; try { let fullResponse = ''; for await (const chunk of streamGeneratePrompt( userRequirement, controller.signal, )) { if (controller.signal.aborted) break; fullResponse += chunk; setGeneratedPrompt(fullResponse); } if (!controller.signal.aborted) { setGeneratedPrompt(fullResponse); setStep('preview'); } } catch (error) { if (!controller.signal.aborted) { const msg = error instanceof Error ? error.message : 'Unknown error'; setErrorMessage(msg); setStep('error'); } } }, [], ); const handleRequirementSubmit = useCallback( (value: string) => { if (!value.trim()) return; generatePrompt(value.trim()); }, [generatePrompt], ); const handleCancel = useCallback(() => { try { abortControllerRef.current?.abort(); } catch { // ignore } onCancel(); }, [onCancel]); useInput((input, key) => { if (key.escape) { handleCancel(); return; } if (step === 'preview') { const lines = generatedPrompt.split('\n'); const maxScroll = Math.max(0, lines.length - VISIBLE_LINES); if (key.upArrow) { setScrollOffset(prev => Math.max(0, prev - 1)); return; } if (key.downArrow) { setScrollOffset(prev => Math.min(maxScroll, prev + 1)); return; } } if (step === 'preview') { const lower = input.toLowerCase(); if (lower === 'y') { onAccept(generatedPrompt); } else if (lower === 'n') { handleCancel(); } else if (lower === 'r') { generatePrompt(requirement); } return; } if (step === 'error') { const lower = input.toLowerCase(); if (lower === 'r') { generatePrompt(requirement); } } }); const newPromptText = t.newPrompt || ({} as any); const scrollHint = newPromptText.scrollHint || '↑↓ Scroll'; if (step === 'input') { return ( {newPromptText.title || '✦ Prompt Generator'} {newPromptText.inputHint || 'Describe your requirement, AI will generate a refined prompt:'} {'❯ '} {newPromptText.escHint || 'ESC to cancel'} ); } if (step === 'generating') { const allLines = generatedPrompt ? generatedPrompt.split('\n') : []; const tailLines = allLines.slice(-VISIBLE_LINES); return ( {newPromptText.title || '✦ Prompt Generator'} {' '} {newPromptText.generating || 'Generating prompt...'} {tailLines.length > 0 && ( {tailLines.map((line, i) => ( {line} ))} )} {newPromptText.escHint || 'ESC to cancel'} ); } if (step === 'error') { return ( {newPromptText.title || '✦ Prompt Generator'} {newPromptText.errorPrefix || 'Error: '} {errorMessage} {'R'} -{' '} {newPromptText.actionRetry || 'Retry'} {' '} {'ESC'} -{' '} {newPromptText.actionCancel || 'Cancel'} ); } // preview step const allLines = generatedPrompt.split('\n'); const maxScroll = Math.max(0, allLines.length - VISIBLE_LINES); const safeOffset = Math.min(scrollOffset, maxScroll); const displayLines = allLines.slice(safeOffset, safeOffset + VISIBLE_LINES); const hasScrollable = allLines.length > VISIBLE_LINES; return ( {newPromptText.title || '✦ Prompt Generator'} {newPromptText.previewTitle || '✓ Prompt generated:'} {displayLines.map((line, i) => ( {line} ))} {hasScrollable && ( [{safeOffset + 1}-{Math.min(safeOffset + VISIBLE_LINES, allLines.length)}/{allLines.length}] {scrollHint} )} {'Y'} {' - '} {newPromptText.actionAccept || 'Write to input'} {' '} {'N'} {' - '} {newPromptText.actionReject || 'Discard'} {' '} {'R'} {' - '} {newPromptText.actionRegenerate || 'Regenerate'} ); }; export default NewPromptPanel; ================================================ FILE: source/ui/components/panels/PanelsManager.tsx ================================================ import React, {lazy, Suspense} from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import {CustomCommandConfigPanel} from './CustomCommandConfigPanel.js'; import {SkillsCreationPanel} from './SkillsCreationPanel.js'; import {RoleCreationPanel} from './RoleCreationPanel.js'; import {RoleDeletionPanel} from './RoleDeletionPanel.js'; import {RoleListPanel} from './RoleListPanel.js'; import {RoleSubagentCreationPanel} from './RoleSubagentCreationPanel.js'; import {RoleSubagentDeletionPanel} from './RoleSubagentDeletionPanel.js'; import {RoleSubagentListPanel} from './RoleSubagentListPanel.js'; import WorkingDirectoryPanel from './WorkingDirectoryPanel.js'; import {BranchPanel} from './BranchPanel.js'; import {ConnectionPanel} from './ConnectionPanel.js'; import TodoListPanel from './TodoListPanel.js'; import HelpPanel from './HelpPanel.js'; import type {CommandLocation} from '../../../utils/commands/custom.js'; import type { GeneratedSkillContent, SkillLocation, } from '../../../utils/commands/skills.js'; import type {RoleLocation} from '../../../utils/commands/role.js'; import type {RoleSubagentLocation} from '../../../utils/commands/roleSubagent.js'; // Lazy load panel components const MCPInfoPanel = lazy(() => import('./MCPInfoPanel.js')); const SessionListPanel = lazy(() => import('./SessionListPanel.js')); const UsagePanel = lazy(() => import('./UsagePanel.js')); type PanelsManagerProps = { terminalWidth: number; workingDirectory: string; showSessionPanel: boolean; showMcpPanel: boolean; showUsagePanel: boolean; showHelpPanel: boolean; showCustomCommandConfig: boolean; showSkillsCreation: boolean; showRoleCreation: boolean; showRoleDeletion: boolean; showRoleList: boolean; showRoleSubagentCreation: boolean; showRoleSubagentDeletion: boolean; showRoleSubagentList: boolean; showWorkingDirPanel: boolean; showBranchPanel: boolean; showConnectionPanel: boolean; showTodoListPanel: boolean; connectionPanelApiUrl?: string; setShowSessionPanel: (show: boolean) => void; setShowMcpPanel: (show: boolean) => void; setShowCustomCommandConfig: (show: boolean) => void; setShowSkillsCreation: (show: boolean) => void; setShowRoleCreation: (show: boolean) => void; setShowRoleDeletion: (show: boolean) => void; setShowRoleList: (show: boolean) => void; setShowRoleSubagentCreation: (show: boolean) => void; setShowRoleSubagentDeletion: (show: boolean) => void; setShowRoleSubagentList: (show: boolean) => void; setShowWorkingDirPanel: (show: boolean) => void; setShowBranchPanel: (show: boolean) => void; setShowConnectionPanel: (show: boolean) => void; setShowTodoListPanel: (show: boolean) => void; handleSessionPanelSelect: (sessionId: string) => Promise; onCustomCommandSave: ( name: string, command: string, type: 'execute' | 'prompt', location: CommandLocation, description?: string, ) => Promise; onSkillsSave: ( skillName: string, description: string, location: SkillLocation, generated?: GeneratedSkillContent, ) => Promise; onRoleSave: (location: RoleLocation) => Promise; onRoleDelete: (location: RoleLocation) => Promise; onRoleSubagentSave: ( agentName: string, location: RoleSubagentLocation, ) => Promise; onRoleSubagentDelete: ( agentName: string, location: RoleSubagentLocation, ) => Promise; }; export default function PanelsManager({ terminalWidth, workingDirectory, showSessionPanel, showMcpPanel, showUsagePanel, showHelpPanel, showCustomCommandConfig, showSkillsCreation, showRoleCreation, showRoleDeletion, showRoleList, showRoleSubagentCreation, showRoleSubagentDeletion, showRoleSubagentList, showWorkingDirPanel, showBranchPanel, showConnectionPanel, showTodoListPanel, connectionPanelApiUrl, setShowSessionPanel, setShowMcpPanel, setShowCustomCommandConfig, setShowSkillsCreation, setShowRoleCreation, setShowRoleDeletion, setShowRoleList, setShowRoleSubagentCreation, setShowRoleSubagentDeletion, setShowRoleSubagentList, setShowWorkingDirPanel, setShowBranchPanel, setShowConnectionPanel, setShowTodoListPanel, handleSessionPanelSelect, onCustomCommandSave, onSkillsSave, onRoleSave, onRoleDelete, onRoleSubagentSave, onRoleSubagentDelete, }: PanelsManagerProps) { const {theme} = useTheme(); const {t} = useI18n(); const loadingFallback = ( Loading... ); return ( <> {/* Show session list panel if active - replaces input */} {showSessionPanel && ( setShowSessionPanel(false)} /> )} {/* Show MCP info panel if active - replaces input */} {showMcpPanel && ( setShowMcpPanel(false)} /> {t.chatScreen.pressEscToClose} )} {/* Show usage panel if active - replaces input */} {showUsagePanel && ( {t.chatScreen.pressEscToClose} )} {/* Show help panel if active - replaces input */} {showHelpPanel && ( {t.chatScreen.pressEscToClose} )} {/* Show custom command config panel if active */} {showCustomCommandConfig && ( setShowCustomCommandConfig(false)} /> )} {/* Show skills creation panel if active */} {showSkillsCreation && ( setShowSkillsCreation(false)} /> )} {showRoleCreation && ( setShowRoleCreation(false)} /> )} {/* Show role deletion panel if active */} {showRoleDeletion && ( setShowRoleDeletion(false)} /> )} {/* Show role list panel if active */} {showRoleList && ( setShowRoleList(false)} /> )} {/* Show sub-agent role creation panel if active */} {showRoleSubagentCreation && ( setShowRoleSubagentCreation(false)} /> )} {/* Show sub-agent role deletion panel if active */} {showRoleSubagentDeletion && ( setShowRoleSubagentDeletion(false)} /> )} {/* Show sub-agent role list panel if active */} {showRoleSubagentList && ( setShowRoleSubagentList(false)} /> )} {/* Show working directory panel if active */} {showWorkingDirPanel && ( setShowWorkingDirPanel(false)} /> )} {/* Show branch management panel if active */} {showBranchPanel && ( setShowBranchPanel(false)} /> )} {/* Show connection panel if active */} {showConnectionPanel && ( setShowConnectionPanel(false)} initialApiUrl={connectionPanelApiUrl} /> )} {showTodoListPanel && ( setShowTodoListPanel(false)} /> )} ); } ================================================ FILE: source/ui/components/panels/PermissionsPanel.tsx ================================================ import React, {useCallback, useEffect, useMemo, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; type Props = { alwaysApprovedTools: Set; onRemoveTool: (toolName: string) => void; onClearAll: () => void; onClose: () => void; }; type PermissionsMessages = { title?: string; clearAll?: string; noTools?: string; hint?: string; confirmDelete?: string; confirmClearAll?: string; yes?: string; no?: string; }; // Confirmation target: tool index or 'clearAll' type ConfirmTarget = number | 'clearAll' | null; export default function PermissionsPanel({ alwaysApprovedTools, onRemoveTool, onClearAll, onClose, }: Props) { const {t} = useI18n(); const {theme} = useTheme(); const messages: PermissionsMessages = (t as any).permissionsPanel ?? {}; const tools = useMemo( () => Array.from(alwaysApprovedTools).sort((a, b) => a.localeCompare(b)), [alwaysApprovedTools], ); const [selectedIndex, setSelectedIndex] = useState(0); // Confirmation state: null = not confirming, number = tool index, 'clearAll' = clear all const [confirmTarget, setConfirmTarget] = useState(null); // 0 = Yes selected, 1 = No selected const [confirmOption, setConfirmOption] = useState<0 | 1>(0); const hasTools = tools.length > 0; const clearAllIndex = hasTools ? tools.length : -1; const optionCount = hasTools ? tools.length + 1 : 0; // Keep selection in bounds as the list changes useEffect(() => { if (optionCount === 0) { setSelectedIndex(0); return; } if (selectedIndex >= optionCount) { setSelectedIndex(optionCount - 1); } }, [optionCount, selectedIndex]); // Reset confirmation when tools change useEffect(() => { setConfirmTarget(null); setConfirmOption(0); }, [alwaysApprovedTools]); const handleInput = useCallback( (_: string, key: any) => { // In confirmation mode if (confirmTarget !== null) { if (key.escape) { // Cancel confirmation setConfirmTarget(null); setConfirmOption(0); return; } if (key.upArrow || key.downArrow) { // Toggle Yes/No setConfirmOption(prev => (prev === 0 ? 1 : 0)); return; } if (key.return) { if (confirmOption === 0) { // Yes - execute delete if (confirmTarget === 'clearAll') { onClearAll(); setSelectedIndex(0); } else { const tool = tools[confirmTarget]; if (tool) { onRemoveTool(tool); // Shift selection up when removing the last item if (confirmTarget >= tools.length - 1) { setSelectedIndex(Math.max(0, confirmTarget - 1)); } } } } // No or Yes completed - reset confirmation setConfirmTarget(null); setConfirmOption(0); return; } return; } // Normal mode if (key.escape) { onClose(); return; } if (optionCount === 0) { return; } if (key.upArrow) { setSelectedIndex(prev => (prev === 0 ? optionCount - 1 : prev - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => (prev === optionCount - 1 ? 0 : prev + 1)); return; } if (key.return) { // Enter confirmation mode instead of direct delete if (selectedIndex === clearAllIndex) { setConfirmTarget('clearAll'); } else { setConfirmTarget(selectedIndex); } setConfirmOption(0); // Default to Yes } }, [ optionCount, selectedIndex, clearAllIndex, onClose, onClearAll, onRemoveTool, tools, confirmTarget, confirmOption, ], ); useInput(handleInput); // Get the name of the tool being confirmed for deletion const getConfirmingToolName = (): string => { if (confirmTarget === 'clearAll') { return ''; } if (typeof confirmTarget === 'number') { return tools[confirmTarget] ?? ''; } return ''; }; // Render confirmation dialog if (confirmTarget !== null) { const isConfirmingClearAll = confirmTarget === 'clearAll'; const toolName = getConfirmingToolName(); return ( {isConfirmingClearAll ? messages.confirmClearAll ?? 'Clear all permissions?' : messages.confirmDelete ?? 'Delete allowed tool?'} {!isConfirmingClearAll && toolName && ( {' '} {toolName} )} {confirmOption === 0 ? '❯ ' : ' '} {messages.yes ?? 'Yes'} {confirmOption === 1 ? '❯ ' : ' '} {messages.no ?? 'No'} ); } return ( {messages.title ?? 'Permissions'} {hasTools ? ( {tools.map((tool, index) => { const isSelected = index === selectedIndex; return ( {isSelected ? '❯ ' : ' '} {tool} ); })} {selectedIndex === clearAllIndex ? '❯ ' : ' '} {messages.clearAll ?? 'Clear All'} ) : ( {messages.noTools ?? 'No tools are always approved'} )} {messages.hint ?? '↑↓ navigate • Enter remove • ESC close'} ); } ================================================ FILE: source/ui/components/panels/ProfileEditPanel.tsx ================================================ import React from 'react'; import ConfigScreen from '../../pages/ConfigScreen.js'; type Props = { /** 要编辑的 profile 名称（来自 ProfilePanel 当前光标焦点项） */ profileName: string; /** * 关闭面板回调（ESC 触发）。ConfigScreen 内部会先保存再调用 onBack。 */ onClose: () => void; }; /** * 配置文件编辑面板：包装 ConfigScreen，让用户在不切换 active profile 的前提下， * 编辑 ProfilePanel 中光标焦点指向的 profile。 * * - inlineMode=true：复用 ChatScreen 的内联面板风格，去除标题边框 * - targetProfileName：指示 useConfigState 从该 profile 加载并仅写回该 profile * - onBack/onSave 都映射到 onClose：ESC 保存并返回上一级 ProfilePanel */ export default function ProfileEditPanel({profileName, onClose}: Props) { return ( ); } ================================================ FILE: source/ui/components/panels/ProfilePanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import PickerList from '../common/PickerList.js'; export interface ProfileItem { name: string; displayName: string; isActive: boolean; } interface Props { profiles: ProfileItem[]; selectedIndex: number; visible: boolean; maxHeight?: number; searchQuery?: string; } const ProfilePanel = memo( ({profiles, selectedIndex, visible, maxHeight, searchQuery}: Props) => { const {t} = useI18n(); const {theme} = useTheme(); if (!visible) { return null; } return ( profile.name} title={ {t.profilePanel.title}{' '} {profiles.length > 5 && `(${selectedIndex + 1}/${profiles.length})`} } header={ searchQuery ? ( {t.profilePanel.searchLabel}{' '} {searchQuery} ) : undefined } footer={ {t.profilePanel.escHint} · {t.profilePanel.editHint} } emptyContent={ {t.profilePanel.title} {searchQuery && ( {t.profilePanel.searchLabel}{' '} {searchQuery} )} {t.profilePanel.noResults} {t.profilePanel.escHint} · {t.profilePanel.editHint} } scrollHintFormat={(above, below) => ( {t.profilePanel.scrollHint} {above > 0 && ( <> ·{' '} {t.profilePanel.moreAbove.replace('{count}', above.toString())} )} {below > 0 && ( <> ·{' '} {t.profilePanel.moreBelow.replace('{count}', below.toString())} )} {above === 0 && below === 0 && ( <> ·{' '} {t.profilePanel.moreHidden.replace( '{count}', (profiles.length - 5).toString(), )} )} )} renderItem={(profile: ProfileItem, isSelected: boolean) => ( {isSelected ? '> ' : ' '} {profile.displayName} {profile.isActive && ` ${t.profilePanel.activeLabel}`} )} /> ); }, ); ProfilePanel.displayName = 'ProfilePanel'; export default ProfilePanel; ================================================ FILE: source/ui/components/panels/ReviewCommitPanel.tsx ================================================ import React, {useCallback, useEffect, useMemo, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import {Alert} from '@inkjs/ui'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import {reviewAgent} from '../../../agents/reviewAgent.js'; export type ReviewCommitSelection = | {type: 'staged'} | {type: 'unstaged'} | {type: 'commit'; sha: string}; type CommitItem = { sha: string; subject: string; authorName: string; dateIso: string; }; type Props = { visible: boolean; onClose: () => void; onConfirm: (selection: ReviewCommitSelection[], notes: string) => void; maxHeight?: number; }; const VISIBLE_ITEMS = 6; const PAGE_SIZE = 30; function formatShortSha(sha: string): string { return sha.slice(0, 8); } function formatDate(isoDate: string): string { // Keep it simple and stable; show YYYY-MM-DD const match = isoDate.match(/^(\d{4}-\d{2}-\d{2})/); return match?.[1] ?? isoDate; } function truncateText(text: string, maxLen: number): string { if (maxLen <= 0) return ''; if (text.length <= maxLen) return text; if (maxLen === 1) return '…'; return text.slice(0, Math.max(1, maxLen - 1)) + '…'; } export default function ReviewCommitPanel({ visible, onClose, onConfirm, maxHeight, }: Props) { const {theme} = useTheme(); const {t} = useI18n(); const effectiveVisibleItems = maxHeight ? Math.max(3, Math.min(maxHeight, VISIBLE_ITEMS)) : VISIBLE_ITEMS; const [loading, setLoading] = useState(true); const [loadingMore, setLoadingMore] = useState(false); const [error, setError] = useState(null); const [gitRoot, setGitRoot] = useState(null); const [commits, setCommits] = useState([]); const [hasMore, setHasMore] = useState(true); const [skip, setSkip] = useState(0); const [selectedIndex, setSelectedIndex] = useState(0); const [scrollOffset, setScrollOffset] = useState(0); const [checked, setChecked] = useState>(new Set()); const [hasStaged, setHasStaged] = useState(false); const [hasUnstaged, setHasUnstaged] = useState(false); const [stagedFileCount, setStagedFileCount] = useState(0); const [unstagedFileCount, setUnstagedFileCount] = useState(0); const [notes, setNotes] = useState(''); const items = useMemo(() => { const base: Array< {kind: 'staged'} | {kind: 'unstaged'} | {kind: 'commit'; item: CommitItem} > = []; if (hasStaged) { base.push({kind: 'staged'}); } if (hasUnstaged) { base.push({kind: 'unstaged'}); } for (const c of commits) { base.push({kind: 'commit', item: c}); } return base; }, [commits, hasStaged, hasUnstaged]); const canNavigate = visible && !loading && items.length > 0; const loadFirstPage = useCallback(async () => { setLoading(true); setError(null); try { const gitCheck = reviewAgent.checkGitRepository(); if (!gitCheck.isGitRepo || !gitCheck.gitRoot) { setError(gitCheck.error || 'Not a git repository'); setGitRoot(null); setCommits([]); setHasMore(false); return; } setGitRoot(gitCheck.gitRoot); // Check working tree status const status = reviewAgent.getWorkingTreeStatus(gitCheck.gitRoot); setHasStaged(status.hasStaged); setHasUnstaged(status.hasUnstaged); setStagedFileCount(status.stagedFileCount); setUnstagedFileCount(status.unstagedFileCount); const result = reviewAgent.listCommitsPaginated( gitCheck.gitRoot, 0, PAGE_SIZE, ); setCommits(result.commits); setHasMore(result.hasMore); setSkip(result.nextSkip); setSelectedIndex(0); setScrollOffset(0); setChecked(new Set()); setNotes(''); } catch (e) { setError(e instanceof Error ? e.message : 'Failed to load commits'); setCommits([]); setHasMore(false); setGitRoot(null); } finally { setLoading(false); } }, []); const loadMore = useCallback(async () => { if (!gitRoot) return; if (loadingMore || !hasMore) return; setLoadingMore(true); try { const result = reviewAgent.listCommitsPaginated(gitRoot, skip, PAGE_SIZE); setCommits(prev => [...prev, ...result.commits]); setHasMore(result.hasMore); setSkip(result.nextSkip); } catch (e) { setError(e instanceof Error ? e.message : 'Failed to load more commits'); } finally { setLoadingMore(false); } }, [gitRoot, hasMore, loadingMore, skip]); useEffect(() => { if (!visible) return; void loadFirstPage(); }, [visible, loadFirstPage]); useInput( (input, key) => { if (!visible) return; if (key.escape) { onClose(); return; } if (loading) return; if (key.upArrow && canNavigate) { setSelectedIndex(prev => { const next = prev > 0 ? prev - 1 : items.length - 1; if (next < scrollOffset) { setScrollOffset(next); } else if (next === items.length - 1) { setScrollOffset(Math.max(0, items.length - effectiveVisibleItems)); } return next; }); return; } if (key.downArrow && canNavigate) { setSelectedIndex(prev => { const next = prev < items.length - 1 ? prev + 1 : 0; if ( hasMore && !loadingMore && next >= items.length - 4 && next !== 0 ) { void loadMore(); } if (next >= scrollOffset + effectiveVisibleItems) { setScrollOffset(next - effectiveVisibleItems + 1); } else if (next === 0) { setScrollOffset(0); } return next; }); return; } if (input === ' ' && canNavigate) { const current = items[selectedIndex]; if (!current) return; const keyId = current.kind === 'staged' ? 'staged' : current.kind === 'unstaged' ? 'unstaged' : current.item.sha; setChecked(prev => { const next = new Set(prev); if (next.has(keyId)) next.delete(keyId); else next.add(keyId); return next; }); return; } if (key.return) { const selection: ReviewCommitSelection[] = []; if (checked.has('staged')) { selection.push({type: 'staged'}); } if (checked.has('unstaged')) { selection.push({type: 'unstaged'}); } for (const c of commits) { if (checked.has(c.sha)) { selection.push({type: 'commit', sha: c.sha}); } } if (selection.length === 0) { setError(t.reviewCommitPanel.errorSelectAtLeastOne); return; } onConfirm(selection, notes.trim()); return; } // Notes input if (key.backspace || key.delete) { setNotes(prev => prev.slice(0, -1)); return; } if ( input && !key.ctrl && !key.meta && !key.tab && !key.upArrow && !key.downArrow && !key.leftArrow && !key.rightArrow ) { setNotes(prev => prev + input); } }, {isActive: visible}, ); const visibleItems = items.slice( scrollOffset, scrollOffset + effectiveVisibleItems, ); if (!visible) return null; if (loading) { return ( {t.reviewCommitPanel.title} {t.reviewCommitPanel.loadingCommits} ); } if (error) { return ( {t.reviewCommitPanel.title} {error} {t.reviewCommitPanel.hintEscClose} ); } return ( {t.reviewCommitPanel.title} {items.length > effectiveVisibleItems ? ` (${selectedIndex + 1}/${items.length})` : ''} {loadingMore ? ` ${t.reviewCommitPanel.loadingMoreSuffix}` : ''} {t.reviewCommitPanel.hintNavigation} {visibleItems.map((it, idx) => { const absoluteIndex = scrollOffset + idx; const isActive = absoluteIndex === selectedIndex; const keyId = it.kind === 'staged' ? 'staged' : it.kind === 'unstaged' ? 'unstaged' : it.item.sha; const isChecked = checked.has(keyId); const title = it.kind === 'staged' ? `${t.reviewCommitPanel.stagedLabel} (${stagedFileCount} ${t.reviewCommitPanel.filesLabel})` : it.kind === 'unstaged' ? `${t.reviewCommitPanel.unstagedLabel} (${unstagedFileCount} ${t.reviewCommitPanel.filesLabel})` : `${formatShortSha(it.item.sha)} ${truncateText( it.item.subject, 72, )}`; const subtitle = it.kind === 'staged' || it.kind === 'unstaged' ? '' : `${truncateText(it.item.authorName, 24)} · ${formatDate( it.item.dateIso, )}`; return ( {isActive ? '> ' : ' '} {isChecked ? '[✓] ' : '[ ] '} {title} {subtitle ? ( {subtitle} ) : null} ); })} {t.reviewCommitPanel.notesLabel}:{' '} {notes || t.reviewCommitPanel.notesOptional} {checked.size > 0 && ( {t.reviewCommitPanel.selectedLabel}: {checked.size} )} ); } ================================================ FILE: source/ui/components/panels/RoleCreationPanel.tsx ================================================ import React, {useState, useCallback} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { checkRoleExists, type RoleLocation, } from '../../../utils/commands/role.js'; type Step = 'location' | 'confirm'; interface Props { onSave: (location: RoleLocation) => Promise; onCancel: () => void; projectRoot?: string; } export const RoleCreationPanel: React.FC = ({ onSave, onCancel, projectRoot, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [step, setStep] = useState('location'); const [location, setLocation] = useState('global'); const handleCancel = useCallback(() => { onCancel(); }, [onCancel]); const handleConfirm = useCallback(async () => { await onSave(location); }, [location, onSave]); const keyHandlingActive = step === 'location' || step === 'confirm'; useInput( (input, key) => { if (key.escape) { if (step === 'confirm') { setStep('location'); } else { handleCancel(); } return; } if (step === 'location') { if (input.toLowerCase() === 'g') { setLocation('global'); setStep('confirm'); } else if (input.toLowerCase() === 'p') { setLocation('project'); setStep('confirm'); } return; } if (step === 'confirm') { if (input.toLowerCase() === 'y') { handleConfirm(); } else if (input.toLowerCase() === 'n') { setStep('location'); } } }, {isActive: keyHandlingActive}, ); // Check if ROLE exists at selected location const existsAtLocation = checkRoleExists(location, projectRoot); return ( {t.roleCreation.title} {step === 'location' && ( {t.roleCreation.locationLabel} [G] {' '} {t.roleCreation.locationGlobal} {t.roleCreation.locationGlobalInfo} [P] {' '} {t.roleCreation.locationProject} {t.roleCreation.locationProjectInfo} {t.roleCreation.escCancel} )} {step === 'confirm' && ( {t.roleCreation.locationLabel}{' '} {location === 'global' ? t.roleCreation.locationGlobal : t.roleCreation.locationProject} {existsAtLocation && ( {location === 'global' ? t.roleCreation.warningExistsGlobal : t.roleCreation.warningExistsProject} )} {t.roleCreation.confirmQuestion} [Y] {' '} {t.roleCreation.confirmYes} [N] {t.roleCreation.confirmNo} )} ); }; ================================================ FILE: source/ui/components/panels/RoleDeletionPanel.tsx ================================================ import React, {useState, useCallback} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { checkRoleExists, type RoleLocation, } from '../../../utils/commands/role.js'; type Step = 'location' | 'confirm'; interface Props { onDelete: (location: RoleLocation) => Promise; onCancel: () => void; projectRoot?: string; } export const RoleDeletionPanel: React.FC = ({ onDelete, onCancel, projectRoot, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [step, setStep] = useState('location'); const [location, setLocation] = useState('global'); const handleCancel = useCallback(() => { onCancel(); }, [onCancel]); const handleConfirm = useCallback(async () => { await onDelete(location); }, [location, onDelete]); const keyHandlingActive = step === 'location' || step === 'confirm'; useInput( (input, key) => { if (key.escape) { handleCancel(); return; } if (step === 'location') { if (input.toLowerCase() === 'g') { setLocation('global'); setStep('confirm'); } else if (input.toLowerCase() === 'p') { setLocation('project'); setStep('confirm'); } return; } if (step === 'confirm') { if (input.toLowerCase() === 'y') { handleConfirm(); } else if (input.toLowerCase() === 'n') { handleCancel(); } } }, {isActive: keyHandlingActive}, ); // Check if ROLE exists at selected location const existsAtLocation = checkRoleExists(location, projectRoot); return ( {t.roleDeletion.title} {step === 'location' && ( {t.roleDeletion.locationLabel} [G] {' '} {t.roleDeletion.locationGlobal} {t.roleDeletion.locationGlobalInfo} [P] {' '} {t.roleDeletion.locationProject} {t.roleDeletion.locationProjectInfo} {t.roleDeletion.escCancel} )} {step === 'confirm' && ( {t.roleDeletion.locationLabel}{' '} {location === 'global' ? t.roleDeletion.locationGlobal : t.roleDeletion.locationProject} {!existsAtLocation && ( {location === 'global' ? t.roleDeletion.warningNotExistsGlobal : t.roleDeletion.warningNotExistsProject} )} {t.roleDeletion.confirmQuestion} [Y] {' '} {t.roleDeletion.confirmYes} [N] {t.roleDeletion.confirmNo} )} ); }; ================================================ FILE: source/ui/components/panels/RoleListPanel.tsx ================================================ import React, {useState, useCallback, useEffect, useRef} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { listRoles, switchActiveRole, createInactiveRole, deleteRole, toggleRoleOverride, type RoleLocation, type RoleItem, } from '../../../utils/commands/role.js'; type Tab = 'global' | 'project'; interface Props { onClose: () => void; projectRoot?: string; } export const RoleListPanel: React.FC = ({onClose, projectRoot}) => { const {theme} = useTheme(); const {t} = useI18n(); const [activeTab, setActiveTab] = useState('global'); const [selectedIndex, setSelectedIndex] = useState(0); const [globalRoles, setGlobalRoles] = useState([]); const [projectRoles, setProjectRoles] = useState([]); const [isLoading, setIsLoading] = useState(false); const [message, setMessage] = useState<{ type: 'success' | 'error'; text: string; } | null>(null); const [pendingDeleteRoleId, setPendingDeleteRoleId] = useState( null, ); const autoClearTimerRef = useRef(null); // Load roles const loadRoles = useCallback(() => { setGlobalRoles(listRoles('global')); setProjectRoles(listRoles('project', projectRoot)); }, [projectRoot]); useEffect(() => { loadRoles(); }, [loadRoles]); // Cleanup auto-clear timer on unmount useEffect(() => { return () => { if (autoClearTimerRef.current) { clearTimeout(autoClearTimerRef.current); autoClearTimerRef.current = null; } }; }, []); // Show a message that auto-hides after `durationMs` (default 2000ms) const showAutoMessage = useCallback( (msg: {type: 'success' | 'error'; text: string}, durationMs = 2000) => { if (autoClearTimerRef.current) { clearTimeout(autoClearTimerRef.current); } setMessage(msg); autoClearTimerRef.current = setTimeout(() => { setMessage(null); autoClearTimerRef.current = null; }, durationMs); }, [], ); // Get current roles based on active tab const currentRoles = activeTab === 'global' ? globalRoles : projectRoles; const currentLocation: RoleLocation = activeTab; // Handle role switch const handleSwitch = useCallback(async () => { const role = currentRoles[selectedIndex]; if (!role || role.isActive) return; setIsLoading(true); setMessage(null); const result = await switchActiveRole( role.id, currentLocation, projectRoot, ); setIsLoading(false); if (result.success) { setMessage({ type: 'success', text: (t.roleList?.switchSuccess || 'Role switched successfully') + ` (${role.filename})`, }); loadRoles(); } else { setMessage({ type: 'error', text: result.error || 'Failed to switch role', }); } }, [currentRoles, selectedIndex, currentLocation, projectRoot, loadRoles, t]); // Handle create new role const handleCreate = useCallback(async () => { setIsLoading(true); setMessage(null); const result = await createInactiveRole(currentLocation, projectRoot); setIsLoading(false); if (result.success) { setMessage({ type: 'success', text: t.roleList?.createSuccess || 'Role created successfully', }); loadRoles(); } else { setMessage({ type: 'error', text: result.error || 'Failed to create role', }); } }, [currentLocation, projectRoot, loadRoles, t]); // Handle delete role const handleDelete = useCallback( async (roleId: string) => { const role = currentRoles.find(r => r.id === roleId); if (!role || role.isActive) return; setIsLoading(true); setMessage(null); const result = await deleteRole(role.id, currentLocation, projectRoot); setIsLoading(false); setPendingDeleteRoleId(null); if (result.success) { setMessage({ type: 'success', text: t.roleList?.deleteSuccess || 'Role deleted successfully', }); loadRoles(); // Adjust selected index if needed if (selectedIndex >= currentRoles.length - 1) { setSelectedIndex(Math.max(0, currentRoles.length - 2)); } } else { setMessage({ type: 'error', text: result.error || 'Failed to delete role', }); } }, [currentRoles, currentLocation, projectRoot, loadRoles, selectedIndex, t], ); // Handle toggle override flag (R key) const handleToggleOverride = useCallback(async () => { const role = currentRoles[selectedIndex]; if (!role) return; if (!role.isActive) { showAutoMessage({ type: 'error', text: t.roleList?.cannotOverrideInactive || 'Only the active role can be marked as override', }); return; } setIsLoading(true); setMessage(null); const result = await toggleRoleOverride( role.id, currentLocation, projectRoot, ); setIsLoading(false); if (result.success) { showAutoMessage({ type: 'success', text: result.isOverride ? t.roleList?.overrideEnabled || 'System prompt override enabled' : t.roleList?.overrideDisabled || 'System prompt override disabled', }); loadRoles(); } else { showAutoMessage({ type: 'error', text: result.error || 'Failed to toggle override', }); } }, [ currentRoles, selectedIndex, currentLocation, projectRoot, loadRoles, showAutoMessage, t, ]); useInput((input, key) => { if (isLoading) return; // Confirm delete flow if (pendingDeleteRoleId) { if (input.toLowerCase() === 'y') { handleDelete(pendingDeleteRoleId); return; } if (input.toLowerCase() === 'n' || key.escape) { setPendingDeleteRoleId(null); setMessage(null); return; } return; } if (key.escape) { onClose(); return; } // Tab switching if (key.tab || input === '\t') { setActiveTab(prev => (prev === 'global' ? 'project' : 'global')); setSelectedIndex(0); setMessage(null); return; } // Navigation if (key.upArrow) { setSelectedIndex(prev => Math.max(0, prev - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => Math.min(currentRoles.length - 1, prev + 1)); return; } // Actions if (key.return) { handleSwitch(); return; } if (input.toLowerCase() === 'n') { handleCreate(); return; } if (input.toLowerCase() === 'd') { const role = currentRoles[selectedIndex]; if (!role) return; if (role.isActive) { setMessage({ type: 'error', text: t.roleList?.cannotDeleteActive || 'Cannot delete active role', }); return; } setPendingDeleteRoleId(role.id); setMessage(null); return; } if (input.toLowerCase() === 'r') { handleToggleOverride(); return; } }); return ( {/* Title */} {t.roleList?.title || 'ROLE Management'} {/* Tabs */} [{activeTab === 'global' ? '✓' : ' '}]{' '} {t.roleList?.tabGlobal || 'Global'} [{activeTab === 'project' ? '✓' : ' '}]{' '} {t.roleList?.tabProject || 'Project'} {/* Role List */} {currentRoles.length === 0 ? ( {t.roleList?.noRoles || 'No roles found. Press N to create one.'} ) : ( currentRoles.map((role, index) => ( {index === selectedIndex ? '✓ ' : ' '} {role.isActive ? '[✓] ' : '[ ] '} {role.isOverride ? '[OVR] ' : ''} {role.filename} {role.isActive ? ` (${t.roleList?.active || 'Active'})` : ''} {role.isOverride ? ` (${t.roleList?.overrideTag || 'Override'})` : ''} )) )} {/* Confirm delete */} {pendingDeleteRoleId && ( {t.roleList?.confirmDelete || 'Confirm delete this role?'} {t.roleList?.confirmDeleteHint || 'Press Y to confirm, N to cancel'} )} {/* Message */} {message && ( {message.text} )} {/* Loading */} {isLoading && ( {t.roleList?.loading || 'Processing...'} )} {/* Hints */} {pendingDeleteRoleId ? t.roleList?.confirmDeleteHint || 'Press Y to confirm, N to cancel' : t.roleList?.hints || 'Tab: Switch scope | Enter: Activate | N: New | D: Delete | R: Override | ESC: Close'} ); }; ================================================ FILE: source/ui/components/panels/RoleSubagentCreationPanel.tsx ================================================ import React, {useState, useCallback, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { getAvailableSubAgents, checkRoleSubagentExists, type RoleSubagentLocation, } from '../../../utils/commands/roleSubagent.js'; import PickerList from '../common/PickerList.js'; type Step = 'location' | 'selectAgent' | 'confirm'; interface Props { onSave: (agentName: string, location: RoleSubagentLocation) => Promise; onCancel: () => void; projectRoot?: string; } export const RoleSubagentCreationPanel: React.FC = ({ onSave, onCancel, projectRoot, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [step, setStep] = useState('location'); const [location, setLocation] = useState('global'); const [selectedIndex, setSelectedIndex] = useState(0); const allAgents = useMemo(() => getAvailableSubAgents(), []); const availableAgents = useMemo(() => { return allAgents.filter( a => !checkRoleSubagentExists(a.name, location, projectRoot), ); }, [allAgents, location, projectRoot]); const selectedAgent = availableAgents[selectedIndex]; const handleCancel = useCallback(() => { onCancel(); }, [onCancel]); const handleConfirm = useCallback(async () => { if (!selectedAgent) return; await onSave(selectedAgent.name, location); }, [selectedAgent, location, onSave]); const keyHandlingActive = step === 'location' || step === 'selectAgent' || step === 'confirm'; useInput( (input, key) => { if (key.escape) { if (step === 'confirm') { setStep('selectAgent'); } else if (step === 'selectAgent') { setStep('location'); } else { handleCancel(); } return; } if (step === 'location') { if (input.toLowerCase() === 'g') { setLocation('global'); setSelectedIndex(0); setStep('selectAgent'); } else if (input.toLowerCase() === 'p') { setLocation('project'); setSelectedIndex(0); setStep('selectAgent'); } return; } if (step === 'selectAgent') { if (key.upArrow) { setSelectedIndex(prev => prev > 0 ? prev - 1 : availableAgents.length - 1, ); return; } if (key.downArrow) { setSelectedIndex(prev => prev < availableAgents.length - 1 ? prev + 1 : 0, ); return; } if (key.return && selectedAgent) { setStep('confirm'); return; } return; } if (step === 'confirm') { if (input.toLowerCase() === 'y') { handleConfirm(); } else if (input.toLowerCase() === 'n') { setStep('selectAgent'); } } }, {isActive: keyHandlingActive}, ); const rs = (t as any).roleSubagentCreation || {}; return ( {rs.title || 'Create Sub-Agent Role'} {step === 'location' && ( {rs.locationLabel || 'Select Location:'} [G] {' '} {rs.locationGlobal || 'Global (~/.snow/)'} {rs.locationGlobalInfo || 'Available across all projects'} [P] {' '} {rs.locationProject || 'Project (./.snow/)'} {rs.locationProjectInfo || 'Only available in this project'} {rs.escCancel || 'Press ESC to cancel'} )} {step === 'selectAgent' && ( {rs.selectAgentLabel || 'Select Sub-Agent:'} {availableAgents.length === 0 ? ( {rs.noAvailableAgents || 'All sub-agents already have role files at this location.'} ) : ( agent.id} renderItem={(agent, isSelected) => ( {isSelected ? '❯ ' : ' '} {agent.name} )} scrollHintFormat={(above, below) => ( {(t as any).agentPickerPanel?.scrollHint || '↑↓ to scroll'} {above > 0 && ( <> {' · '} {( (t as any).agentPickerPanel?.moreAbove || '{count} more above' ).replace('{count}', above.toString())} )} {below > 0 && ( <> {' · '} {( (t as any).agentPickerPanel?.moreBelow || '{count} more below' ).replace('{count}', below.toString())} )} )} /> )} {rs.selectAgentHint || '↑↓: Navigate | Enter: Select | ESC: Back'} )} {step === 'confirm' && selectedAgent && ( {rs.locationLabel || 'Location:'}{' '} {location === 'global' ? rs.locationGlobal || 'Global' : rs.locationProject || 'Project'} {rs.agentLabel || 'Sub-Agent:'}{' '} {selectedAgent.name} {rs.fileLabel || 'File:'} ROLE-{selectedAgent.name}.md {rs.confirmQuestion || 'Create this role file?'} [Y] {' '} {rs.confirmYes || 'Yes, Create'} [N] {' '} {rs.confirmNo || 'No, Cancel'} )} ); }; ================================================ FILE: source/ui/components/panels/RoleSubagentDeletionPanel.tsx ================================================ import React, {useState, useCallback, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { listRoleSubagents, type RoleSubagentLocation, type RoleSubagentItem, } from '../../../utils/commands/roleSubagent.js'; type Step = 'location' | 'selectRole' | 'confirm'; interface Props { onDelete: ( agentName: string, location: RoleSubagentLocation, ) => Promise; onCancel: () => void; projectRoot?: string; } export const RoleSubagentDeletionPanel: React.FC = ({ onDelete, onCancel, projectRoot, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [step, setStep] = useState('location'); const [location, setLocation] = useState('global'); const [selectedIndex, setSelectedIndex] = useState(0); const roleItems = useMemo( () => listRoleSubagents(location, projectRoot), [location, projectRoot], ); const selectedItem: RoleSubagentItem | undefined = roleItems[selectedIndex]; const handleCancel = useCallback(() => { onCancel(); }, [onCancel]); const handleConfirm = useCallback(async () => { if (!selectedItem) return; await onDelete(selectedItem.agentName, location); }, [selectedItem, location, onDelete]); const keyHandlingActive = step === 'location' || step === 'selectRole' || step === 'confirm'; useInput( (input, key) => { if (key.escape) { if (step === 'confirm') { setStep('selectRole'); } else if (step === 'selectRole') { setStep('location'); } else { handleCancel(); } return; } if (step === 'location') { if (input.toLowerCase() === 'g') { setLocation('global'); setSelectedIndex(0); setStep('selectRole'); } else if (input.toLowerCase() === 'p') { setLocation('project'); setSelectedIndex(0); setStep('selectRole'); } return; } if (step === 'selectRole') { if (key.upArrow) { setSelectedIndex(prev => Math.max(0, prev - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => Math.min(roleItems.length - 1, prev + 1), ); return; } if (key.return && selectedItem) { setStep('confirm'); return; } return; } if (step === 'confirm') { if (input.toLowerCase() === 'y') { handleConfirm(); } else if (input.toLowerCase() === 'n') { setStep('selectRole'); } } }, {isActive: keyHandlingActive}, ); const rs = (t as any).roleSubagentDeletion || {}; return ( {rs.title || 'Delete Sub-Agent Role'} {step === 'location' && ( {rs.locationLabel || 'Select Location:'} [G] {' '} {rs.locationGlobal || 'Global (~/.snow/)'} {rs.locationGlobalInfo || 'Sub-agent role files for all projects'} [P] {' '} {rs.locationProject || 'Project (./.snow/)'} {rs.locationProjectInfo || 'Sub-agent role files for current project only'} {rs.escCancel || 'Press ESC to cancel'} )} {step === 'selectRole' && ( {rs.selectRoleLabel || 'Select role file to delete:'} {roleItems.length === 0 ? ( {rs.noRoleFiles || 'No sub-agent role files found at this location.'} ) : ( {roleItems.map((item, index) => ( {index === selectedIndex ? '> ' : ' '} {item.filename} ({item.agentName}) ))} )} {rs.selectRoleHint || '↑↓: Navigate | Enter: Select | ESC: Back'} )} {step === 'confirm' && selectedItem && ( {rs.locationLabel || 'Location:'}{' '} {location === 'global' ? rs.locationGlobal || 'Global' : rs.locationProject || 'Project'} {rs.fileLabel || 'File:'}{' '} {selectedItem.filename} {rs.confirmQuestion || 'Confirm deletion?'} [Y] {' '} {rs.confirmYes || 'Yes, Delete'} [N] {' '} {rs.confirmNo || 'No, Cancel'} )} ); }; ================================================ FILE: source/ui/components/panels/RoleSubagentListPanel.tsx ================================================ import React, {useState, useCallback, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { listRoleSubagents, deleteRoleSubagentFile, type RoleSubagentLocation, type RoleSubagentItem, } from '../../../utils/commands/roleSubagent.js'; type Tab = 'global' | 'project'; interface Props { onClose: () => void; projectRoot?: string; } export const RoleSubagentListPanel: React.FC = ({ onClose, projectRoot, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [activeTab, setActiveTab] = useState('global'); const [selectedIndex, setSelectedIndex] = useState(0); const [globalRoles, setGlobalRoles] = useState([]); const [projectRoles, setProjectRoles] = useState([]); const [isLoading, setIsLoading] = useState(false); const [message, setMessage] = useState<{ type: 'success' | 'error'; text: string; } | null>(null); const [pendingDeleteName, setPendingDeleteName] = useState( null, ); const loadRoles = useCallback(() => { setGlobalRoles(listRoleSubagents('global')); setProjectRoles(listRoleSubagents('project', projectRoot)); }, [projectRoot]); useEffect(() => { loadRoles(); }, [loadRoles]); const currentRoles = activeTab === 'global' ? globalRoles : projectRoles; const currentLocation: RoleSubagentLocation = activeTab; const handleDelete = useCallback( async (agentName: string) => { setIsLoading(true); setMessage(null); const result = await deleteRoleSubagentFile( agentName, currentLocation, projectRoot, ); setIsLoading(false); setPendingDeleteName(null); if (result.success) { setMessage({ type: 'success', text: (rs.deleteSuccess || 'Role file deleted successfully') + ` (${agentName})`, }); loadRoles(); if (selectedIndex >= currentRoles.length - 1) { setSelectedIndex(Math.max(0, currentRoles.length - 2)); } } else { setMessage({ type: 'error', text: result.error || 'Failed to delete role file', }); } }, [currentLocation, projectRoot, loadRoles, selectedIndex, currentRoles], ); const rs = (t as any).roleSubagentList || {}; useInput((input, key) => { if (isLoading) return; if (pendingDeleteName) { if (input.toLowerCase() === 'y') { handleDelete(pendingDeleteName); return; } if (input.toLowerCase() === 'n' || key.escape) { setPendingDeleteName(null); setMessage(null); return; } return; } if (key.escape) { onClose(); return; } if (key.tab || input === '\t') { setActiveTab(prev => (prev === 'global' ? 'project' : 'global')); setSelectedIndex(0); setMessage(null); return; } if (key.upArrow) { setSelectedIndex(prev => Math.max(0, prev - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => Math.min(currentRoles.length - 1, prev + 1)); return; } if (input.toLowerCase() === 'd') { const role = currentRoles[selectedIndex]; if (!role) return; setPendingDeleteName(role.agentName); setMessage(null); return; } }); return ( {rs.title || 'Sub-Agent Role Management'} {/* Tabs */} [{activeTab === 'global' ? '✓' : ' '}]{' '} {rs.tabGlobal || 'Global'} [{activeTab === 'project' ? '✓' : ' '}]{' '} {rs.tabProject || 'Project'} {/* Role List */} {currentRoles.length === 0 ? ( {rs.noRoles || 'No sub-agent role files found. Use /role-subagent to create one.'} ) : ( currentRoles.map((role, index) => ( {index === selectedIndex ? '> ' : ' '} {role.filename} ({role.agentName}) )) )} {/* Confirm delete */} {pendingDeleteName && ( {(rs.confirmDelete || 'Confirm delete role for "{name}"?').replace( '{name}', pendingDeleteName, )} {rs.confirmDeleteHint || 'Press Y to confirm, N to cancel'} )} {/* Message */} {message && ( {message.text} )} {/* Loading */} {isLoading && ( {rs.loading || 'Processing...'} )} {/* Hints */} {pendingDeleteName ? rs.confirmDeleteHint || 'Press Y to confirm, N to cancel' : rs.hints || 'Tab: Switch scope | D: Delete | ESC: Close'} ); }; ================================================ FILE: source/ui/components/panels/RollbackMenuPanel.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; type MessageItem = { label: string; value: string; infoText: string; }; type Translation = { chatScreen: { historyNavigateHint: string; moreAbove: string; moreBelow: string; }; }; type ThemeColors = { menuSelected: string; menuNormal: string; menuSecondary: string; menuInfo: string; }; type Props = { isVisible: boolean; messages: MessageItem[]; selectedIndex: number; terminalWidth: number; t: Translation; colors: ThemeColors; }; const MAX_VISIBLE_ITEMS = 5; export default function RollbackMenuPanel({ isVisible, messages, selectedIndex, terminalWidth, t, colors, }: Props) { if (!isVisible || messages.length === 0) { return null; } // Calculate scroll window to keep selected index visible let startIndex = 0; if (messages.length > MAX_VISIBLE_ITEMS) { // Keep selected item in the middle of the view when possible startIndex = Math.max(0, selectedIndex - Math.floor(MAX_VISIBLE_ITEMS / 2)); // Adjust if we're near the end startIndex = Math.min(startIndex, messages.length - MAX_VISIBLE_ITEMS); } const endIndex = Math.min(messages.length, startIndex + MAX_VISIBLE_ITEMS); const visibleMessages = messages.slice(startIndex, endIndex); const hasMoreAbove = startIndex > 0; const hasMoreBelow = endIndex < messages.length; const maxLabelWidth = terminalWidth - 4; const formatMessageLabel = (label: string): string => { // Ensure single line by removing all newlines and control characters const singleLineLabel = label .replace(/[\r\n\t\v\f\u0000-\u001F\u007F-\u009F]+/g, ' ') .replace(/\s+/g, ' ') .trim(); // Truncate if too long if (singleLineLabel.length > maxLabelWidth) { return singleLineLabel.slice(0, maxLabelWidth - 3) + '...'; } return singleLineLabel; }; return ( {/* Top border separator */} {'─'.repeat(terminalWidth - 2)} {/* Top scroll indicator - always reserve space */} {hasMoreAbove ? ( {t.chatScreen.moreAbove.replace('{count}', startIndex.toString())} ) : ( )} {/* Message list - each item fixed to 1 line */} {visibleMessages.map((message, displayIndex) => { const actualIndex = startIndex + displayIndex; const truncatedLabel = formatMessageLabel(message.label); return ( {actualIndex === selectedIndex ? '❯ ' : ' '} {truncatedLabel} ); })} {/* Bottom scroll indicator - always reserve space */} {hasMoreBelow ? ( {t.chatScreen.moreBelow.replace( '{count}', (messages.length - endIndex).toString(), )} ) : ( )} {t.chatScreen.historyNavigateHint} ); } ================================================ FILE: source/ui/components/panels/RunningAgentsPanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {Alert} from '@inkjs/ui'; import type {PickerAgent} from '../../../hooks/picker/useRunningAgentsPicker.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import PickerList from '../common/PickerList.js'; interface Props { agents: PickerAgent[]; selectedIndex: number; selectedAgents: Set; visible: boolean; maxHeight?: number; } function truncatePrompt(prompt: string, maxLength: number): string { const singleLine = prompt .replace(/[\r\n]+/g, ' ') .replace(/\s+/g, ' ') .trim(); if (singleLine.length <= maxLength) { return singleLine; } return singleLine.slice(0, maxLength - 3) + '...'; } function formatElapsed(startedAt: Date): string { const elapsed = Math.floor((Date.now() - startedAt.getTime()) / 1000); if (elapsed < 60) { return `${elapsed}s`; } const minutes = Math.floor(elapsed / 60); const seconds = elapsed % 60; return `${minutes}m${seconds}s`; } const RunningAgentsPanel = memo( ({agents, selectedIndex, selectedAgents, visible, maxHeight}: Props) => { const {theme} = useTheme(); const {t} = useI18n(); if (!visible) { return null; } if (agents.length === 0) { return ( {'>> '} {t.runningAgentsPanel.title} {t.runningAgentsPanel.noAgentsRunning} ); } return ( agent.instanceId} title={ <> {'>> '} {t.runningAgentsPanel.title}{' '} {t.runningAgentsPanel.keyboardHint} } header={ selectedAgents.size > 0 ? ( {t.runningAgentsPanel.selected.replace( '{count}', String(selectedAgents.size), )} ) : undefined } scrollHintFormat={(above, below) => ( {t.runningAgentsPanel.scrollHint} {above > 0 && ` · ${t.runningAgentsPanel.moreAbove.replace('{count}', String(above))}`} {below > 0 && ` · ${t.runningAgentsPanel.moreBelow.replace('{count}', String(below))}`} )} renderItem={(agent: PickerAgent, isSelected: boolean) => { const isChecked = selectedAgents.has(agent.instanceId); const promptText = agent.prompt ? truncatePrompt(agent.prompt, 80) : ''; const isTeammate = agent.sourceType === 'teammate'; const typeLabel = isTeammate ? t.runningAgentsPanel.teammateLabel : t.runningAgentsPanel.subAgentLabel; return ( <> {isSelected ? '❯ ' : ' '} {isChecked ? '[✓]' : '[ ]'} {agent.agentName} {typeLabel} {' '}#{agent.agentId} {' '} {formatElapsed(agent.startedAt)} {promptText ? ( {promptText} ) : null} ); }} /> ); }, ); RunningAgentsPanel.displayName = 'RunningAgentsPanel'; export default RunningAgentsPanel; ================================================ FILE: source/ui/components/panels/SessionListPanel.tsx ================================================ import React, {useState, useEffect, useCallback, useRef} from 'react'; import {Box, Text, useInput} from 'ink'; import { sessionManager, type SessionListItem, } from '../../../utils/session/sessionManager.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useTerminalSize} from '../../../hooks/ui/useTerminalSize.js'; type Props = { onSelectSession: (sessionId: string) => void; onClose: () => void; }; export default function SessionListPanel({onSelectSession, onClose}: Props) { const {t} = useI18n(); const {theme} = useTheme(); const {columns: terminalWidth} = useTerminalSize(); const [sessions, setSessions] = useState([]); const [loading, setLoading] = useState(true); const [loadingMore, setLoadingMore] = useState(false); const [selectedIndex, setSelectedIndex] = useState(0); const [scrollOffset, setScrollOffset] = useState(0); const [markedSessions, setMarkedSessions] = useState>(new Set()); const [currentPage, setCurrentPage] = useState(0); const [hasMore, setHasMore] = useState(true); const [totalCount, setTotalCount] = useState(0); const [searchInput, setSearchInput] = useState(''); const [debouncedSearch, setDebouncedSearch] = useState(''); const [renamingSessionId, setRenamingSessionId] = useState( null, ); const [renameInput, setRenameInput] = useState(''); const [isRenaming, setIsRenaming] = useState(false); const [pendingDeleteCount, setPendingDeleteCount] = useState(0); const pendingDeleteTimerRef = useRef(null); useEffect(() => { return () => { if (pendingDeleteTimerRef.current) { clearTimeout(pendingDeleteTimerRef.current); } }; }, []); const VISIBLE_ITEMS = 10; const PAGE_SIZE = 20; const SEARCH_DEBOUNCE_MS = 600; useEffect(() => { const timer = setTimeout(() => { setDebouncedSearch(searchInput); }, SEARCH_DEBOUNCE_MS); return () => clearTimeout(timer); }, [searchInput]); useEffect(() => { const loadSessions = async () => { setLoading(true); try { const result = await sessionManager.listSessionsPaginated( 0, PAGE_SIZE, debouncedSearch, ); setSessions(result.sessions); setHasMore(result.hasMore); setTotalCount(result.total); setCurrentPage(0); setSelectedIndex(0); setScrollOffset(0); } catch (error) { console.error('Failed to load sessions:', error); setSessions([]); } finally { setLoading(false); } }; void loadSessions(); }, [debouncedSearch]); const loadMoreSessions = useCallback(async () => { if (loadingMore || !hasMore) return; setLoadingMore(true); try { const nextPage = currentPage + 1; const result = await sessionManager.listSessionsPaginated( nextPage, PAGE_SIZE, debouncedSearch, ); setSessions(prev => [...prev, ...result.sessions]); setHasMore(result.hasMore); setCurrentPage(nextPage); } catch (error) { console.error('Failed to load more sessions:', error); } finally { setLoadingMore(false); } }, [currentPage, hasMore, loadingMore, debouncedSearch]); const formatDate = useCallback( (timestamp: number): string => { const date = new Date(timestamp); const now = new Date(); const diffMs = now.getTime() - date.getTime(); const diffMinutes = Math.floor(diffMs / (1000 * 60)); const diffHours = Math.floor(diffMinutes / 60); const diffDays = Math.floor(diffHours / 24); if (diffMinutes < 1) return t.sessionListPanel.now; if (diffMinutes < 60) return `${diffMinutes}m`; if (diffHours < 24) return `${diffHours}h`; if (diffDays < 7) return `${diffDays}d`; return date.toLocaleDateString('en-US', {month: 'short', day: 'numeric'}); }, [t], ); useInput((input, key) => { if (loading) return; // If in rename mode, handle rename input if (renamingSessionId) { if (key.escape) { setRenamingSessionId(null); setRenameInput(''); return; } if (key.return && renameInput.trim()) { const handleRename = async () => { setIsRenaming(true); const success = await sessionManager.updateSessionTitle( renamingSessionId, renameInput.trim(), ); if (success) { // Reload sessions to show updated title const result = await sessionManager.listSessionsPaginated( 0, PAGE_SIZE, debouncedSearch, ); setSessions(result.sessions); setHasMore(result.hasMore); setTotalCount(result.total); setCurrentPage(0); } setRenamingSessionId(null); setRenameInput(''); setIsRenaming(false); }; void handleRename(); return; } if (key.backspace || key.delete) { setRenameInput(prev => prev.slice(0, -1)); return; } if (input && !key.ctrl && !key.meta) { if ( !key.upArrow && !key.downArrow && !key.leftArrow && !key.rightArrow && !key.return && !key.escape && !key.tab ) { setRenameInput(prev => prev + input); } } return; } if (key.escape) { if (searchInput) { setSearchInput(''); } else { onClose(); } return; } if (key.backspace || key.delete) { setSearchInput(prev => prev.slice(0, -1)); return; } if (key.upArrow) { setSelectedIndex(prev => { const newIndex = prev > 0 ? prev - 1 : sessions.length - 1; if (newIndex < scrollOffset) { setScrollOffset(newIndex); } else if (newIndex >= sessions.length - VISIBLE_ITEMS) { setScrollOffset(Math.max(0, sessions.length - VISIBLE_ITEMS)); } return newIndex; }); return; } if (key.downArrow) { setSelectedIndex(prev => { const newIndex = prev < sessions.length - 1 ? prev + 1 : 0; if ( hasMore && !loadingMore && newIndex >= sessions.length - 5 && newIndex !== 0 ) { void loadMoreSessions(); } if (newIndex >= scrollOffset + VISIBLE_ITEMS) { setScrollOffset(newIndex - VISIBLE_ITEMS + 1); } else if (newIndex === 0) { setScrollOffset(0); } return newIndex; }); return; } if (input === ' ') { const currentSession = sessions[selectedIndex]; if (currentSession) { setMarkedSessions(prev => { const next = new Set(prev); if (next.has(currentSession.id)) { next.delete(currentSession.id); } else { next.add(currentSession.id); } return next; }); } return; } if (input === 'd' || input === 'D') { const idsToDelete: string[] = markedSessions.size > 0 ? Array.from(markedSessions) : sessions[selectedIndex] ? [sessions[selectedIndex]!.id] : []; if (idsToDelete.length === 0) { return; } // First press: show confirmation prompt for 1 second if (pendingDeleteCount === 0) { setPendingDeleteCount(idsToDelete.length); if (pendingDeleteTimerRef.current) { clearTimeout(pendingDeleteTimerRef.current); } pendingDeleteTimerRef.current = setTimeout(() => { setPendingDeleteCount(0); pendingDeleteTimerRef.current = null; }, 1000); return; } // Second press within 1s: actually delete if (pendingDeleteTimerRef.current) { clearTimeout(pendingDeleteTimerRef.current); pendingDeleteTimerRef.current = null; } setPendingDeleteCount(0); const deleteSessions = async () => { await Promise.all( idsToDelete.map(id => sessionManager.deleteSession(id)), ); const result = await sessionManager.listSessionsPaginated( 0, PAGE_SIZE, debouncedSearch, ); setSessions(result.sessions); setHasMore(result.hasMore); setTotalCount(result.total); setCurrentPage(0); setMarkedSessions(new Set()); if ( selectedIndex >= result.sessions.length && result.sessions.length > 0 ) { setSelectedIndex(result.sessions.length - 1); } setScrollOffset(0); }; void deleteSessions(); return; } if (input === 'r' || input === 'R') { const currentSession = sessions[selectedIndex]; if (currentSession) { setRenamingSessionId(currentSession.id); setRenameInput(currentSession.title || ''); } return; } if (key.return && sessions.length > 0) { const selectedSession = sessions[selectedIndex]; if (selectedSession) { onSelectSession(selectedSession.id); } return; } if (input && !key.ctrl && !key.meta) { if ( !key.upArrow && !key.downArrow && !key.leftArrow && !key.rightArrow && !key.return && !key.escape && !key.tab ) { setSearchInput(prev => prev + input); } } }); const visibleSessions = sessions.slice( scrollOffset, scrollOffset + VISIBLE_ITEMS, ); const hasMoreInView = sessions.length > scrollOffset + VISIBLE_ITEMS; const hasPrevious = scrollOffset > 0; const currentSession = sessions[selectedIndex]; return ( {'─'.repeat(Math.max(0, terminalWidth - 2))} {t.sessionListPanel.title} ({selectedIndex + 1}/{sessions.length} {totalCount > sessions.length && ` of ${totalCount}`}) {currentSession && ` • ${ currentSession.messageCount } ${t.sessionListPanel.messages.replace('{count}', '')}`} {markedSessions.size > 0 && ( {' '} •{' '} {t.sessionListPanel.marked.replace( '{count}', String(markedSessions.size), )} )} {loadingMore && ( {' '} • {t.sessionListPanel.loadingMore} )} {pendingDeleteCount > 0 && ( {' '} •{' '} {t.sessionListPanel.confirmDelete.replace( '{count}', String(pendingDeleteCount), )} )} {renamingSessionId ? ( {t.sessionListPanel.renamePrompt}:{' '} {renameInput} ▌ {isRenaming && ( {' '} ({t.sessionListPanel.renaming}) )} ) : ( {t.sessionListPanel.navigationHint} )} {!renamingSessionId && ( ⌕{' '} {searchInput ? ( {searchInput} ▌ ) : ( ▌ )} {searchInput && searchInput !== debouncedSearch && ( {' '} ({t.sessionListPanel.searching}) )} )} {loading ? ( {t.sessionListPanel.loading} ) : sessions.length === 0 ? ( {debouncedSearch ? t.sessionListPanel.noResults.replace('{query}', debouncedSearch) : t.sessionListPanel.noConversations} ) : ( <> {hasPrevious && ( {' '} {t.sessionListPanel.moreAbove.replace( '{count}', String(scrollOffset), )} )} {visibleSessions.map((session, index) => { const actualIndex = scrollOffset + index; const isSelected = actualIndex === selectedIndex; const isMarked = markedSessions.has(session.id); const cleanTitle = ( session.title || t.sessionListPanel.untitled ).replace(/[\r\n\t]+/g, ' '); const timeStr = formatDate(session.updatedAt); const truncatedLabel = cleanTitle.length > 50 ? cleanTitle.slice(0, 47) + '...' : cleanTitle; return ( {isMarked ? '✔ ' : ' '} {isSelected ? '❯ ' : ' '} {truncatedLabel} {' '} • {timeStr} ); })} )} {!loading && sessions.length > 0 && hasMoreInView && ( {' '} {t.sessionListPanel.moreBelow.replace( '{count}', String(sessions.length - scrollOffset - VISIBLE_ITEMS), )} {hasMore && ` ${t.sessionListPanel.scrollToLoadMore}`} )} ); } ================================================ FILE: source/ui/components/panels/SkillsCreationPanel.tsx ================================================ import React, {useState, useCallback, useEffect, useRef} from 'react'; import {Box, Text, useInput} from 'ink'; import Spinner from 'ink-spinner'; import TextInput from 'ink-text-input'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { validateSkillId, checkSkillExists, generateSkillDraftWithAI, type GeneratedSkillContent, type GeneratedSkillDraft, type SkillLocation, } from '../../../utils/commands/skills.js'; type CreationMode = 'manual' | 'ai'; type Step = | 'mode' | 'name' | 'description' | 'location' | 'confirm' | 'ai-requirement' | 'ai-location' | 'ai-generating' | 'ai-preview' | 'ai-edit-name' | 'ai-error'; interface Props { onSave: ( skillName: string, description: string, location: SkillLocation, generated?: GeneratedSkillContent, ) => Promise; onCancel: () => void; projectRoot?: string; } export const SkillsCreationPanel: React.FC = ({ onSave, onCancel, projectRoot, }) => { const {theme} = useTheme(); const {t} = useI18n(); const [step, setStep] = useState('mode'); const [mode, setMode] = useState('manual'); const [skillName, setSkillName] = useState(''); const [description, setDescription] = useState(''); const [location, setLocation] = useState('global'); const [requirement, setRequirement] = useState(''); const [generated, setGenerated] = useState< GeneratedSkillContent | undefined >(); const [errorMessage, setErrorMessage] = useState(''); const abortControllerRef = useRef(null); const handleCancel = useCallback(() => { try { abortControllerRef.current?.abort(); } catch { // Ignore abort errors } onCancel(); }, [onCancel]); const handleNameSubmit = useCallback( (value: string) => { if (!value.trim()) { return; } const trimmedName = value.trim(); const validation = validateSkillId(trimmedName); if (!validation.valid) { setErrorMessage(validation.error || t.skillsCreation.errorInvalidName); return; } // Check if skill name already exists in both locations const existsGlobal = checkSkillExists(trimmedName, 'global'); const existsProject = checkSkillExists( trimmedName, 'project', projectRoot, ); if (existsGlobal && existsProject) { setErrorMessage( t.skillsCreation.errorExistsBoth.replace('{name}', trimmedName), ); return; } if (existsGlobal) { setErrorMessage( t.skillsCreation.errorExistsGlobal.replace('{name}', trimmedName), ); return; } if (existsProject) { setErrorMessage( t.skillsCreation.errorExistsProject.replace('{name}', trimmedName), ); return; } setErrorMessage(''); setSkillName(trimmedName); setStep('description'); }, [projectRoot, t.skillsCreation], ); const handleDescriptionSubmit = useCallback((value: string) => { if (value.trim()) { setDescription(value.trim()); setStep('location'); } }, []); const handleRequirementSubmit = useCallback((value: string) => { if (value.trim()) { setRequirement(value.trim()); setErrorMessage(''); setStep('ai-location'); } }, []); const handleConfirmManual = useCallback(async () => { await onSave(skillName, description, location); }, [skillName, description, location, onSave]); const handleConfirmAI = useCallback(async () => { if (!generated) { setErrorMessage(t.skillsCreation.errorNoGeneratedContent); return; } await onSave(skillName, description, location, generated); }, [generated, skillName, description, location, onSave, t.skillsCreation]); const handleEditNameSubmit = useCallback( (value: string) => { if (!value.trim()) { return; } const trimmedName = value.trim(); const validation = validateSkillId(trimmedName); if (!validation.valid) { setErrorMessage(validation.error || t.skillsCreation.errorInvalidName); return; } const existsGlobal = checkSkillExists(trimmedName, 'global'); const existsProject = checkSkillExists( trimmedName, 'project', projectRoot, ); if (existsGlobal || existsProject) { setErrorMessage( t.skillsCreation.errorExistsAny.replace('{name}', trimmedName), ); return; } setErrorMessage(''); setSkillName(trimmedName); setStep('ai-preview'); }, [projectRoot, t.skillsCreation], ); // Start generation when entering ai-generating step useEffect(() => { if (step !== 'ai-generating') { return; } const controller = new AbortController(); abortControllerRef.current = controller; setErrorMessage(''); setGenerated(undefined); generateSkillDraftWithAI(requirement, projectRoot, controller.signal) .then((draft: GeneratedSkillDraft) => { setSkillName(draft.skillName); setDescription(draft.description); setGenerated(draft.generated); setStep('ai-preview'); }) .catch((error: unknown) => { if (controller.signal.aborted) { return; } const message = error instanceof Error ? error.message : t.skillsCreation.errorGeneration; setErrorMessage(message); setStep('ai-error'); }) .finally(() => { abortControllerRef.current = null; }); return () => { try { controller.abort(); } catch { // Ignore abort errors } }; }, [step, requirement, projectRoot, t.skillsCreation.errorGeneration]); useInput( (input, key) => { if (key.escape) { // Sequential back navigation based on current step and mode if (step === 'confirm') { setStep('location'); } else if (step === 'location') { setStep('description'); } else if (step === 'description') { setStep('name'); } else if (step === 'name') { setStep('mode'); } else if (step === 'ai-edit-name') { setStep('ai-preview'); } else if (step === 'ai-preview') { setStep('ai-location'); } else if (step === 'ai-location') { setStep('ai-requirement'); } else if (step === 'ai-requirement') { setStep('mode'); } else if (step === 'ai-error') { setStep('ai-location'); } else if (step === 'ai-generating') { // Cancel generation and close panel handleCancel(); } else if (step === 'mode') { handleCancel(); } return; } if (step === 'mode') { if (input.toLowerCase() === 'm') { setMode('manual'); setErrorMessage(''); setStep('name'); } else if (input.toLowerCase() === 'a') { setMode('ai'); setErrorMessage(''); setSkillName(''); setDescription(''); setGenerated(undefined); setStep('ai-requirement'); } return; } if (step === 'location') { if (input.toLowerCase() === 'g') { setLocation('global'); setStep('confirm'); } else if (input.toLowerCase() === 'p') { setLocation('project'); setStep('confirm'); } return; } if (step === 'confirm') { if (input.toLowerCase() === 'y') { handleConfirmManual(); } else if (input.toLowerCase() === 'n') { setStep('location'); } return; } if (step === 'ai-location') { if (input.toLowerCase() === 'g') { setLocation('global'); setStep('ai-generating'); } else if (input.toLowerCase() === 'p') { setLocation('project'); setStep('ai-generating'); } return; } if (step === 'ai-preview') { if (input.toLowerCase() === 'y') { handleConfirmAI(); } else if (input.toLowerCase() === 'e') { setErrorMessage(''); setStep('ai-edit-name'); } else if (input.toLowerCase() === 'r') { setErrorMessage(''); setStep('ai-generating'); } return; } if (step === 'ai-error') { if (input.toLowerCase() === 'r') { setErrorMessage(''); setStep('ai-generating'); } } }, {isActive: true}, ); return ( {t.skillsCreation.title} {step === 'mode' && ( {t.skillsCreation.modeLabel} [A] {t.skillsCreation.modeAi} [M] {' '} {t.skillsCreation.modeManual} {t.skillsCreation.escCancel} )} {mode === 'manual' && step === 'name' && ( {t.skillsCreation.nameLabel} {t.skillsCreation.nameHint} {errorMessage && ( {errorMessage} )} {t.skillsCreation.escCancel} )} {mode === 'manual' && step === 'description' && ( {t.skillsCreation.nameLabel}{' '} {skillName} {t.skillsCreation.descriptionLabel} {t.skillsCreation.descriptionHint} {t.skillsCreation.escCancel} )} {mode === 'manual' && step === 'location' && ( {t.skillsCreation.nameLabel}{' '} {skillName} {t.skillsCreation.descriptionLabel}{' '} {description} {t.skillsCreation.locationLabel} [G] {' '} {t.skillsCreation.locationGlobal} {t.skillsCreation.locationGlobalInfo} [P] {' '} {t.skillsCreation.locationProject} {t.skillsCreation.locationProjectInfo} {t.skillsCreation.escCancel} )} {mode === 'manual' && step === 'confirm' && ( {t.skillsCreation.nameLabel}{' '} {skillName} {t.skillsCreation.descriptionLabel}{' '} {description} {t.skillsCreation.locationLabel}{' '} {location === 'global' ? t.skillsCreation.locationGlobal : t.skillsCreation.locationProject} {t.skillsCreation.confirmQuestion} [Y] {' '} {t.skillsCreation.confirmYes} [N] {' '} {t.skillsCreation.confirmNo} )} {mode === 'ai' && step === 'ai-requirement' && ( {t.skillsCreation.requirementLabel} {t.skillsCreation.requirementHint} {t.skillsCreation.escCancel} )} {mode === 'ai' && step === 'ai-location' && ( {t.skillsCreation.requirementLabel}{' '} {requirement} {t.skillsCreation.locationLabel} [G] {' '} {t.skillsCreation.locationGlobal} {t.skillsCreation.locationGlobalInfo} [P] {' '} {t.skillsCreation.locationProject} {t.skillsCreation.locationProjectInfo} {t.skillsCreation.escCancel} )} {mode === 'ai' && step === 'ai-generating' && ( {t.skillsCreation.generatingLabel} {t.skillsCreation.generatingMessage} {t.skillsCreation.escCancel} )} {mode === 'ai' && step === 'ai-error' && ( {t.skillsCreation.errorGeneration} {errorMessage && ( {errorMessage} )} [R] {' '} {t.skillsCreation.regenerate} [ESC] {t.skillsCreation.cancel} )} {mode === 'ai' && step === 'ai-preview' && ( {t.skillsCreation.nameLabel}{' '} {skillName} {t.skillsCreation.descriptionLabel}{' '} {description} {t.skillsCreation.locationLabel}{' '} {location === 'global' ? t.skillsCreation.locationGlobal : t.skillsCreation.locationProject} {t.skillsCreation.filesLabel} - SKILL.md - reference.md - examples.md - templates/template.txt - scripts/helper.py {errorMessage && ( {errorMessage} )} {t.skillsCreation.confirmQuestion} [Y] {' '} {t.skillsCreation.confirmYes} [E] {' '} {t.skillsCreation.editName} [R] {' '} {t.skillsCreation.regenerate} {t.skillsCreation.escCancel} )} {mode === 'ai' && step === 'ai-edit-name' && ( {t.skillsCreation.editNameLabel}{' '} {skillName} {t.skillsCreation.editNameHint} {errorMessage && ( {errorMessage} )} {t.skillsCreation.escCancel} )} ); }; ================================================ FILE: source/ui/components/panels/SkillsListPanel.tsx ================================================ import React, {useState, useEffect, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/I18nContext.js'; import { toggleSkill, isSkillEnabled, } from '../../../utils/config/disabledSkills.js'; import type {Skill} from '../../../mcp/skills.js'; interface Props { onClose: () => void; } const NON_FOCUSED_SKILL_DESC_MAX_LEN = 30; const MAX_DISPLAY_ITEMS = 8; export default function SkillsListPanel({onClose}: Props) { const {t} = useI18n(); const {theme} = useTheme(); const [skills, setSkills] = useState([]); const [skillEnabledMap, setSkillEnabledMap] = useState< Record >({}); const [selectedIndex, setSelectedIndex] = useState(0); const [isLoading, setIsLoading] = useState(true); const [errorMessage, setErrorMessage] = useState(null); useEffect(() => { let cancelled = false; (async () => { try { const {listAvailableSkills} = await import('../../../mcp/skills.js'); const skillsList = await listAvailableSkills(process.cwd()); if (cancelled) return; setSkills(skillsList); const enabledMap: Record = {}; for (const skill of skillsList) { enabledMap[skill.id] = isSkillEnabled(skill.id); } setSkillEnabledMap(enabledMap); setIsLoading(false); } catch (error) { if (cancelled) return; setErrorMessage( error instanceof Error ? error.message : 'Failed to load skills', ); setIsLoading(false); } })(); return () => { cancelled = true; }; }, []); const displayWindow = useMemo(() => { if (skills.length <= MAX_DISPLAY_ITEMS) { return { items: skills, startIndex: 0, endIndex: skills.length, }; } const halfWindow = Math.floor(MAX_DISPLAY_ITEMS / 2); let startIndex = Math.max(0, selectedIndex - halfWindow); const endIndex = Math.min(skills.length, startIndex + MAX_DISPLAY_ITEMS); if (endIndex - startIndex < MAX_DISPLAY_ITEMS) { startIndex = Math.max(0, endIndex - MAX_DISPLAY_ITEMS); } return { items: skills.slice(startIndex, endIndex), startIndex, endIndex, }; }, [skills, selectedIndex]); const hiddenAboveCount = displayWindow.startIndex; const hiddenBelowCount = Math.max(0, skills.length - displayWindow.endIndex); const formatSkillDescription = ( description: string, isSelected: boolean, ): string => { if (isSelected || description.length <= NON_FOCUSED_SKILL_DESC_MAX_LEN) { return description; } return `${description.slice(0, NON_FOCUSED_SKILL_DESC_MAX_LEN - 3)}...`; }; useInput((input, key) => { if (isLoading) return; if (key.escape) { onClose(); return; } if (skills.length === 0) return; if (key.upArrow) { setSelectedIndex(prev => (prev > 0 ? prev - 1 : skills.length - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => (prev < skills.length - 1 ? prev + 1 : 0)); return; } if (key.tab || input === ' ' || key.return) { const current = skills[selectedIndex]; if (!current) return; try { toggleSkill(current.id); setSkillEnabledMap(prev => ({ ...prev, [current.id]: !prev[current.id], })); } catch (error) { setErrorMessage( error instanceof Error ? error.message : 'Failed to toggle skill', ); } return; } }); if (isLoading) { return ( {t.skillsListPanel?.loading || 'Loading skills...'} ); } if (errorMessage) { return ( {(t.skillsListPanel?.error || 'Error: {message}').replace( '{message}', errorMessage, )} ); } if (skills.length === 0) { return ( {t.skillsListPanel?.noSkills || 'No skills available'} ); } return ( {t.skillsListPanel?.title || 'Skills'} {skills.length > MAX_DISPLAY_ITEMS && ` (${selectedIndex + 1}/${skills.length})`} {hiddenAboveCount > 0 && ( {(t.skillsListPanel?.moreAbove || '↑ {count} more above').replace( '{count}', String(hiddenAboveCount), )} )} {displayWindow.items.map((skill, displayIdx) => { const actualIndex = displayWindow.startIndex + displayIdx; const isSelected = actualIndex === selectedIndex; const isEnabled = skillEnabledMap[skill.id] !== false; const locationSuffix = skill.location === 'project' ? t.skillsListPanel?.locationProject || '(Project)' : t.skillsListPanel?.locationGlobal || '(Global)'; const skillDescription = (skill.description || '').trim(); const hasDescription = Boolean(skillDescription); const renderedDescription = hasDescription ? formatSkillDescription(skillDescription, isSelected) : ''; return ( {isSelected ? '❯ ' : ' '} ◆{' '} {skill.name || skill.id} {' '} {isEnabled ? locationSuffix : t.skillsListPanel?.statusDisabled || '(Disabled)'} {isEnabled && hasDescription ? ( {renderedDescription} ) : null} ); })} {hiddenBelowCount > 0 && ( {(t.skillsListPanel?.moreBelow || '↓ {count} more below').replace( '{count}', String(hiddenBelowCount), )} )} {t.skillsListPanel?.navigationHint || '↑↓ Navigate • Tab/Space/Enter Toggle • ESC Close'} ); } ================================================ FILE: source/ui/components/panels/SkillsPickerPanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import PickerList from '../common/PickerList.js'; export type SkillsPickerFocus = 'search' | 'append'; export type SkillsPickerItem = { id: string; name: string; description: string; location: 'project' | 'global'; }; interface Props { skills: SkillsPickerItem[]; selectedIndex: number; visible: boolean; maxHeight?: number; isLoading?: boolean; searchQuery?: string; appendText?: string; focus?: SkillsPickerFocus; } const SkillsPickerPanel = memo( ({ skills, selectedIndex, visible, maxHeight, isLoading = false, searchQuery = '', appendText = '', focus = 'search', }: Props) => { const {t} = useI18n(); const {theme} = useTheme(); if (!visible) { return null; } if (isLoading) { return ( {t.skillsPickerPanel.title} {t.skillsPickerPanel.loading} ); } return ( skill.id} title={ <> {t.skillsPickerPanel.title}{' '} {skills.length > 5 && `(${selectedIndex + 1}/${skills.length})`} {t.skillsPickerPanel.keyboardHint} } header={ {focus === 'search' ? '▶ ' : ' '} {t.skillsPickerPanel.searchLabel}{' '} {searchQuery || t.skillsPickerPanel.empty} {focus === 'append' ? '▶ ' : ' '} {t.skillsPickerPanel.appendLabel}{' '} {appendText || t.skillsPickerPanel.empty} } emptyContent={ {t.skillsPickerPanel.title} {t.skillsPickerPanel.keyboardHint} {focus === 'search' ? '▶ ' : ' '} {t.skillsPickerPanel.searchLabel}{' '} {searchQuery || t.skillsPickerPanel.empty} {focus === 'append' ? '▶ ' : ' '} {t.skillsPickerPanel.appendLabel}{' '} {appendText || t.skillsPickerPanel.empty} {t.skillsPickerPanel.noSkillsFound} } scrollHintFormat={(above, below) => ( {t.skillsPickerPanel.scrollHint} {above > 0 && ( <> ·{' '} {t.skillsPickerPanel.moreAbove.replace( '{count}', above.toString(), )} )} {below > 0 && ( <> ·{' '} {t.skillsPickerPanel.moreBelow.replace( '{count}', below.toString(), )} )} )} renderItem={(skill: SkillsPickerItem, isSelected: boolean) => ( <> {isSelected ? '❯ ' : ' '}#{skill.id}{' '} ({skill.location}) └─{' '} {skill.description || skill.name || t.skillsPickerPanel.noDescription} )} /> ); }, ); SkillsPickerPanel.displayName = 'SkillsPickerPanel'; export default SkillsPickerPanel; ================================================ FILE: source/ui/components/panels/SubAgentDepthPanel.tsx ================================================ import React, {useCallback, useEffect, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import {Alert} from '@inkjs/ui'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import { getSubAgentMaxSpawnDepth, setSubAgentMaxSpawnDepth, } from '../../../utils/config/projectSettings.js'; type Props = { visible: boolean; onClose: () => void; }; export default function SubAgentDepthPanel({visible, onClose}: Props) { const {t} = useI18n(); const {theme} = useTheme(); const [inputValue, setInputValue] = useState(''); const [savedDepth, setSavedDepth] = useState(() => getSubAgentMaxSpawnDepth(), ); const [errorMessage, setErrorMessage] = useState(null); const [successMessage, setSuccessMessage] = useState(null); useEffect(() => { if (!visible) { return; } const currentDepth = getSubAgentMaxSpawnDepth(); setSavedDepth(currentDepth); setInputValue(currentDepth.toString()); setErrorMessage(null); setSuccessMessage(null); }, [visible]); useEffect(() => { if (!errorMessage) { return undefined; } const timer = setTimeout(() => { setErrorMessage(null); }, 3000); return () => clearTimeout(timer); }, [errorMessage]); useEffect(() => { if (!successMessage) { return undefined; } const timer = setTimeout(() => { setSuccessMessage(null); }, 2000); return () => clearTimeout(timer); }, [successMessage]); const handleSave = useCallback(() => { const trimmedValue = inputValue.trim(); const parsedDepth = Number.parseInt(trimmedValue, 10); if (!trimmedValue || !Number.isInteger(parsedDepth) || parsedDepth < 0) { setSuccessMessage(null); setErrorMessage(t.subAgentDepthPanel.invalidInput); return; } const normalizedDepth = setSubAgentMaxSpawnDepth(parsedDepth); setSavedDepth(normalizedDepth); setInputValue(normalizedDepth.toString()); setErrorMessage(null); setSuccessMessage(t.subAgentDepthPanel.saveSuccess); }, [ inputValue, t.subAgentDepthPanel.invalidInput, t.subAgentDepthPanel.saveSuccess, ]); useInput( (input, key) => { if (key.escape) { onClose(); return; } if (key.return) { handleSave(); return; } if (key.backspace || key.delete) { setInputValue(prev => prev.slice(0, -1)); return; } if (/^[0-9]$/.test(input)) { setInputValue(prev => prev + input); } }, {isActive: visible}, ); if (!visible) { return null; } return ( {t.subAgentDepthPanel.title} {t.subAgentDepthPanel.description} {t.subAgentDepthPanel.currentValueLabel} {savedDepth} {t.subAgentDepthPanel.inputLabel} {inputValue || '0'} {successMessage && ( {successMessage} )} {errorMessage && ( {errorMessage} )} {t.subAgentDepthPanel.hint} {t.subAgentDepthPanel.fileHint} ); } ================================================ FILE: source/ui/components/panels/TodoListPanel.tsx ================================================ import React, {useCallback, useEffect, useMemo, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import Spinner from 'ink-spinner'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import type {TodoItem} from '../../../mcp/types/todo.types.js'; import {getTodoService} from '../../../utils/execution/mcpToolsManager.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import {todoEvents} from '../../../utils/events/todoEvents.js'; type Props = { onClose: () => void; }; type FlattenedTodoItem = TodoItem & { depth: number; hasChildren: boolean; }; function getStatusIcon(status: TodoItem['status']): string { if (status === 'completed') return '✓'; if (status === 'inProgress') return '~'; return '○'; } function buildFlattenedTodos(todos: TodoItem[]): FlattenedTodoItem[] { const byId = new Map(todos.map(todo => [todo.id, todo])); const childrenMap = new Map(); for (const todo of todos) { const parentKey = todo.parentId && byId.has(todo.parentId) ? todo.parentId : undefined; const siblings = childrenMap.get(parentKey) ?? []; siblings.push(todo); childrenMap.set(parentKey, siblings); } const flattened: FlattenedTodoItem[] = []; const visited = new Set(); const walk = (todo: TodoItem, depth: number) => { if (visited.has(todo.id)) { return; } visited.add(todo.id); const children = childrenMap.get(todo.id) ?? []; flattened.push({ ...todo, depth, hasChildren: children.length > 0, }); for (const child of children) { walk(child, depth + 1); } }; for (const rootTodo of childrenMap.get(undefined) ?? []) { walk(rootTodo, 0); } for (const todo of todos) { if (!visited.has(todo.id)) { walk(todo, 0); } } return flattened; } function isDescendantOf( todoId: string, ancestorId: string, byId: Map, ): boolean { let current = byId.get(todoId); while (current?.parentId) { if (current.parentId === ancestorId) { return true; } current = byId.get(current.parentId); } return false; } export default function TodoListPanel({onClose}: Props) { const {t} = useI18n(); const {theme} = useTheme(); const [todos, setTodos] = useState([]); const [loading, setLoading] = useState(true); const [deleting, setDeleting] = useState(false); const [currentSessionId, setCurrentSessionId] = useState(null); const [selectedIndex, setSelectedIndex] = useState(0); const [markedTodoIds, setMarkedTodoIds] = useState>(new Set()); const [pendingDelete, setPendingDelete] = useState(false); const todoService = useMemo(() => getTodoService(), []); const todoById = useMemo( () => new Map(todos.map(todo => [todo.id, todo])), [todos], ); const flattenedTodos = useMemo(() => buildFlattenedTodos(todos), [todos]); const completedCount = useMemo( () => todos.filter(todo => todo.status === 'completed').length, [todos], ); const maxVisibleItems = 5; const displayWindow = useMemo(() => { if (flattenedTodos.length <= maxVisibleItems) { return { items: flattenedTodos, startIndex: 0, endIndex: flattenedTodos.length, }; } let startIndex = 0; if (selectedIndex >= maxVisibleItems) { startIndex = selectedIndex - maxVisibleItems + 1; } const endIndex = Math.min( flattenedTodos.length, startIndex + maxVisibleItems, ); return { items: flattenedTodos.slice(startIndex, endIndex), startIndex, endIndex, }; }, [flattenedTodos, selectedIndex]); const hiddenAboveCount = displayWindow.startIndex; const hiddenBelowCount = Math.max( 0, flattenedTodos.length - displayWindow.endIndex, ); const showOverflowHint = flattenedTodos.length > maxVisibleItems; const loadTodos = useCallback(async () => { const currentSession = sessionManager.getCurrentSession(); setCurrentSessionId(currentSession?.id ?? null); if (!currentSession) { setTodos([]); setLoading(false); return; } setLoading(true); try { const todoList = await todoService.getTodoList(currentSession.id); setTodos(todoList?.todos ?? []); } catch (error) { console.error('Failed to load todo list:', error); setTodos([]); } finally { setLoading(false); } }, [todoService]); useEffect(() => { void loadTodos(); }, [loadTodos]); useEffect(() => { const handleTodoUpdate = (data: {sessionId: string; todos: TodoItem[]}) => { if (data.sessionId === currentSessionId) { setTodos(data.todos); } }; todoEvents.onTodoUpdate(handleTodoUpdate); return () => { todoEvents.offTodoUpdate(handleTodoUpdate); }; }, [currentSessionId]); useEffect(() => { setSelectedIndex(prev => { if (flattenedTodos.length === 0) { return 0; } return Math.min(prev, flattenedTodos.length - 1); }); }, [flattenedTodos.length]); useEffect(() => { setMarkedTodoIds(prev => { const next = new Set(); for (const todoId of prev) { if (todoById.has(todoId)) { next.add(todoId); } } return next; }); }, [todoById]); useEffect(() => { if (markedTodoIds.size === 0 && pendingDelete) { setPendingDelete(false); } }, [markedTodoIds, pendingDelete]); const toggleCurrentTodo = useCallback(() => { const currentTodo = flattenedTodos[selectedIndex]; if (!currentTodo) { return; } if (pendingDelete) { setPendingDelete(false); } setMarkedTodoIds(prev => { const next = new Set(prev); if (next.has(currentTodo.id)) { next.delete(currentTodo.id); } else { next.add(currentTodo.id); } return next; }); }, [flattenedTodos, pendingDelete, selectedIndex]); const deleteMarkedTodos = useCallback(async () => { if (!currentSessionId || deleting) { return; } const candidateIds = Array.from(markedTodoIds); if (candidateIds.length === 0) { return; } const rootIds = candidateIds.filter(todoId => { return !candidateIds.some(otherId => { if (otherId === todoId) { return false; } return isDescendantOf(todoId, otherId, todoById); }); }); const rootIdSet = new Set(rootIds); const filteredTodos = todos.filter(todo => { if (rootIdSet.has(todo.id)) { return false; } return !rootIds.some(rootId => isDescendantOf(todo.id, rootId, todoById)); }); setDeleting(true); try { await todoService.saveTodoList(currentSessionId, filteredTodos); setTodos(filteredTodos); setMarkedTodoIds(new Set()); setPendingDelete(false); } catch (error) { console.error('Failed to delete todo items:', error); } finally { setDeleting(false); } }, [currentSessionId, deleting, markedTodoIds, todoById, todoService, todos]); useInput((input, key) => { if (key.escape) { if (pendingDelete) { setPendingDelete(false); return; } onClose(); return; } if (loading || deleting) { return; } if (pendingDelete) { if ( key.return || input === 'd' || input === 'D' || input === 'y' || input === 'Y' ) { void deleteMarkedTodos(); return; } if (input === 'n' || input === 'N') { setPendingDelete(false); return; } return; } if (key.upArrow) { setSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, flattenedTodos.length - 1), ); return; } if (key.downArrow) { const maxIndex = Math.max(0, flattenedTodos.length - 1); setSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return; } if (input === ' ') { toggleCurrentTodo(); return; } if (input === 'd' || input === 'D') { if (markedTodoIds.size > 0) { setPendingDelete(true); } } }); if (loading) { return ( {t.todoListPanel.title} {t.todoListPanel.loading} ); } if (!currentSessionId) { return ( {t.todoListPanel.title} {t.todoListPanel.noActiveSession} ); } return ( {t.todoListPanel.title}{' '} ({completedCount}/{todos.length}) {pendingDelete ? t.todoListPanel.confirmModeHint : t.todoListPanel.hint} {showOverflowHint && hiddenAboveCount > 0 && ( <> ·{' '} {t.todoListPanel.moreAbove.replace( '{count}', hiddenAboveCount.toString(), )} )} {showOverflowHint && hiddenBelowCount > 0 && ( <> ·{' '} {t.todoListPanel.moreBelow.replace( '{count}', hiddenBelowCount.toString(), )} )} {deleting && ( {t.todoListPanel.deleting} )} {pendingDelete && markedTodoIds.size > 0 && ( {t.todoListPanel.confirmDelete.replace( '{count}', markedTodoIds.size.toString(), )} {t.todoListPanel.confirmDeleteHint} )} {flattenedTodos.length === 0 ? ( {t.todoListPanel.empty} ) : ( {displayWindow.items.map((todo, index) => { const originalIndex = displayWindow.startIndex + index; const isSelected = originalIndex === selectedIndex; const isMarked = markedTodoIds.has(todo.id); const indent = ' '.repeat(todo.depth); const branch = todo.depth > 0 ? '└─ ' : ''; const statusIcon = getStatusIcon(todo.status); return ( {isSelected ? '❯ ' : ' '} {isMarked ? '[x]' : '[ ]'} {indent} {branch} {statusIcon} {todo.content} ); })} )} {t.todoListPanel.selectedCount.replace( '{count}', markedTodoIds.size.toString(), )} ); } ================================================ FILE: source/ui/components/panels/TodoPickerPanel.tsx ================================================ import React, {memo} from 'react'; import {Box, Text} from 'ink'; import {Alert} from '@inkjs/ui'; import type {TodoItem} from '../../../utils/core/todoScanner.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import PickerList from '../common/PickerList.js'; interface Props { todos: TodoItem[]; selectedIndex: number; selectedTodos: Set; visible: boolean; maxHeight?: number; isLoading?: boolean; searchQuery?: string; totalCount?: number; } const TodoPickerPanel = memo( ({ todos, selectedIndex, selectedTodos, visible, maxHeight, isLoading = false, searchQuery = '', totalCount = 0, }: Props) => { const {t} = useI18n(); const {theme} = useTheme(); if (!visible) { return null; } if (isLoading) { return ( {t.todoPickerPanel.title} {t.todoPickerPanel.scanning} ); } if (todos.length === 0 && !searchQuery) { return ( {t.todoPickerPanel.title} {t.todoPickerPanel.noTodosFound} ); } if (todos.length === 0 && searchQuery) { return ( {t.todoPickerPanel.title} {t.todoPickerPanel.noMatchSearch .replace('{searchQuery}', searchQuery) .replace('{totalCount}', totalCount.toString())} {t.todoPickerPanel.typeToClearSearch} ); } return ( todo.id} title={ {t.todoPickerPanel.selectTodos}{' '} {todos.length > 5 && `(${selectedIndex + 1}/${todos.length})`} {searchQuery && ` ${t.todoPickerPanel.filteringLabel.replace( '{searchQuery}', searchQuery, )}`} {searchQuery && totalCount > todos.length && ` (${todos.length}/${totalCount})`} } header={ {searchQuery ? t.todoPickerPanel.typeToFilterHint : t.todoPickerPanel.typeToSearchHint} } footer={ selectedTodos.size > 0 ? ( {t.todoPickerPanel.selectedCount.replace( '{count}', selectedTodos.size.toString(), )} ) : undefined } scrollHintFormat={(above, below) => ( {t.commandPanel.scrollHint} {above > 0 && ( <> ·{' '} {t.commandPanel.moreAbove.replace('{count}', above.toString())} )} {below > 0 && ( <> ·{' '} {t.commandPanel.moreBelow.replace('{count}', below.toString())} )} )} renderItem={(todo: TodoItem, isSelected: boolean) => { const isChecked = selectedTodos.has(todo.id); return ( <> {isSelected ? '❯ ' : ' '} {isChecked ? '[✓]' : '[ ]'} {todo.file}:{todo.line} └─ {todo.content} ); }} /> ); }, ); TodoPickerPanel.displayName = 'TodoPickerPanel'; export default TodoPickerPanel; ================================================ FILE: source/ui/components/panels/UsagePanel.tsx ================================================ import React, {useState, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import fs from 'fs/promises'; import path from 'path'; import os from 'os'; import {useTerminalSize} from '../../../hooks/ui/useTerminalSize.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import type {Theme} from '../../themes/index.js'; interface UsageLogEntry { model: string; profileName: string; inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number; timestamp: string; } interface ModelStats { input: number; output: number; cacheCreation: number; cacheRead: number; total: number; } interface AggregatedStats { models: Map; grandTotal: number; } type Granularity = 'hour' | 'day' | 'week' | 'month'; function getModelShortName(modelName: string, maxLength = 20): string { // Extract readable name from model string intelligently // Examples: // "claude-sonnet-4-5-20250929" -> "Sonnet 4.5" // "gpt-4-turbo-2024-04-09" -> "GPT-4 Turbo" // "deepseek-chat-v2.5" -> "Deepseek Chat V2.5" // "glm-4-plus-20240116" -> "GLM-4 Plus" // "qwen2.5-72b-instruct" -> "Qwen2.5 72B" let name = modelName; // Step 1: Remove common date/version suffixes // Remove YYYYMMDD dates name = name.replace(/-?\d{8}$/g, ''); // Remove YYYY-MM-DD dates name = name.replace(/-\d{4}-\d{2}-\d{2}$/g, ''); // Remove trailing version hashes name = name.replace(/-[a-f0-9]{7,}$/gi, ''); // Step 2: Convert version patterns (4-5 -> 4.5, but keep word-number like gpt-4) // Only convert digit-digit patterns name = name.replace(/(\d)-(\d)/g, '$1.$2'); // Step 3: Smart parsing based on common patterns const parts = name.split(/[-_]/); // Filter out common suffixes we don't want const stopWords = [ 'instruct', 'chat', 'base', 'turbo', 'preview', 'api', 'model', ]; const importantParts: string[] = []; const suffixParts: string[] = []; for (let i = 0; i < parts.length; i++) { const part = parts[i]; if (!part) continue; const lower = part.toLowerCase(); // First part is always important (brand name) if (i === 0) { importantParts.push(part); continue; } // Version numbers and model tiers are important if (/^\d+\.?\d*[a-z]?$/i.test(part) || /^v\d/i.test(part)) { importantParts.push(part); continue; } // Size indicators (72b, 7b, etc) if (/^\d+[bm]$/i.test(part)) { importantParts.push(part.toUpperCase()); continue; } // Model names/variants (sonnet, haiku, plus, pro, ultra, etc) if ( lower.match(/^(sonnet|haiku|opus|plus|pro|ultra|mini|nano|max|lite)$/) ) { importantParts.push(part); continue; } // Common suffixes go to end if (stopWords.includes(lower)) { suffixParts.push(part); continue; } // Everything else goes to important parts (up to 3 parts total) if (importantParts.length < 3) { importantParts.push(part); } } // Step 4: Format the name let result = importantParts .map((part, idx) => { // First part: capitalize first letter if (idx === 0) { return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(); } // Version numbers and sizes: keep as-is or uppercase if (/^\d|^v\d|^\d+[BM]$/i.test(part)) { return part; } // Other parts: capitalize first letter return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(); }) .join(' '); // Add important suffix if exists and space allows if ( suffixParts.length > 0 && suffixParts[0] && result.length < maxLength - 5 ) { result += ' ' + suffixParts[0].charAt(0).toUpperCase() + suffixParts[0].slice(1).toLowerCase(); } // Step 5: Truncate if too long return result.length > maxLength ? result.slice(0, maxLength) : result; } async function loadUsageData(): Promise { const homeDir = os.homedir(); const usageDir = path.join(homeDir, '.snow', 'usage'); try { const entries: UsageLogEntry[] = []; const dateDirs = await fs.readdir(usageDir); for (const dateDir of dateDirs) { const datePath = path.join(usageDir, dateDir); const stats = await fs.stat(datePath); if (!stats.isDirectory()) continue; const files = await fs.readdir(datePath); for (const file of files) { if (!file.endsWith('.jsonl')) continue; const filePath = path.join(datePath, file); const content = await fs.readFile(filePath, 'utf-8'); const lines = content .trim() .split('\n') .filter(l => l.trim()); for (const line of lines) { try { const entry = JSON.parse(line) as UsageLogEntry; entries.push(entry); } catch { // Skip invalid lines } } } } return entries.sort( (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(), ); } catch (error) { return []; } } function filterByGranularity( entries: UsageLogEntry[], granularity: Granularity, ): UsageLogEntry[] { if (entries.length === 0) return []; const now = new Date(); const cutoff = new Date(now); switch (granularity) { case 'hour': cutoff.setHours(now.getHours() - 24); break; case 'day': cutoff.setDate(now.getDate() - 7); break; case 'week': cutoff.setDate(now.getDate() - 30); break; case 'month': cutoff.setMonth(now.getMonth() - 12); break; } return entries.filter(e => new Date(e.timestamp) >= cutoff); } function aggregateByModel(entries: UsageLogEntry[]): AggregatedStats { const models = new Map(); let grandTotal = 0; for (const entry of entries) { const modelName = entry.model; if (!models.has(modelName)) { models.set(modelName, { input: 0, output: 0, cacheCreation: 0, cacheRead: 0, total: 0, }); } const stats = models.get(modelName)!; stats.input += entry.inputTokens; stats.output += entry.outputTokens; stats.cacheCreation += entry.cacheCreationInputTokens || 0; stats.cacheRead += entry.cacheReadInputTokens || 0; stats.total += entry.inputTokens + entry.outputTokens; grandTotal += entry.inputTokens + entry.outputTokens; } return {models, grandTotal}; } function formatTokens(tokens: number, compact = false): string { if (tokens >= 1000000) { return compact ? `${(tokens / 1000000).toFixed(1)}M` : `${(tokens / 1000000).toFixed(2)}M`; } if (tokens >= 1000) { return compact ? `${Math.round(tokens / 1000)}K` : `${(tokens / 1000).toFixed(1)}K`; } return String(tokens); } function renderStackedBarChart( stats: AggregatedStats, terminalWidth: number, scrollOffset: number, t: any, theme: Theme, ) { if (stats.models.size === 0) { return ( {t.usagePanel.chart.noData} ); } const sortedModels = Array.from(stats.models.entries()).sort( (a, b) => b[1].total - a[1].total, ); const isNarrow = terminalWidth < 100; // Show maximum 2 models at a time for better readability const maxVisibleModels = 2; // Calculate visible range const startIdx = scrollOffset; const endIdx = Math.min(startIdx + maxVisibleModels, sortedModels.length); const visibleModels = sortedModels.slice(startIdx, endIdx); const hasMoreAbove = startIdx > 0; const hasMoreBelow = endIdx < sortedModels.length; // Calculate max total (including cache) for scaling const maxTotal = Math.max( ...Array.from(stats.models.values()).map( s => s.total + s.cacheCreation + s.cacheRead, ), ); // Use almost full width for bars (leave some margin) const maxBarWidth = Math.min(isNarrow ? 50 : 70, terminalWidth - 10); return ( {/* Legend */} █ {' '} {t.usagePanel.chart.usage}{' '} █ {' '} {t.usagePanel.chart.cacheHit}{' '} █ {' '} {t.usagePanel.chart.cacheCreate} {/* Scroll indicator - more above */} {hasMoreAbove && ( {t.usagePanel.chart.moreAbove.replace('{count}', String(startIdx))} )} {visibleModels.map(([modelName, modelStats]) => { const shortName = getModelShortName(modelName, 30); // Calculate segment lengths based on proportion // Ensure at least 1 character if value exists const usageLength = modelStats.total > 0 ? Math.max( 1, Math.round((modelStats.total / maxTotal) * maxBarWidth), ) : 0; const cacheHitLength = modelStats.cacheRead > 0 ? Math.max( 1, Math.round((modelStats.cacheRead / maxTotal) * maxBarWidth), ) : 0; const cacheCreateLength = modelStats.cacheCreation > 0 ? Math.max( 1, Math.round((modelStats.cacheCreation / maxTotal) * maxBarWidth), ) : 0; return ( {/* Line 1: Model name */} {shortName} {/* Line 2: Stacked bar chart */} {/* Usage segment */} {usageLength > 0 && ( {'█'.repeat(usageLength)} )} {/* Cache hit segment */} {cacheHitLength > 0 && ( {'█'.repeat(cacheHitLength)} )} {/* Cache create segment */} {cacheCreateLength > 0 && ( {'█'.repeat(cacheCreateLength)} )} {/* Line 3: Detailed stats */} {t.usagePanel.chart.usage}{' '} {formatTokens(modelStats.total, isNarrow)} {' '} ({t.usagePanel.chart.in}{' '} {formatTokens(modelStats.input, isNarrow)},{' '} {t.usagePanel.chart.out}{' '} {formatTokens(modelStats.output, isNarrow)}) {(modelStats.cacheRead > 0 || modelStats.cacheCreation > 0) && ( <> {' '} |{' '} {modelStats.cacheRead > 0 && ( <> {t.usagePanel.chart.hit}{' '} {formatTokens(modelStats.cacheRead, isNarrow)} {modelStats.cacheCreation > 0 && ( ,{' '} )} )} {modelStats.cacheCreation > 0 && ( {t.usagePanel.chart.create}{' '} {formatTokens(modelStats.cacheCreation, isNarrow)} )} )} ); })} {/* Total summary */} {sortedModels.length > 1 && ( {'─'.repeat(Math.min(terminalWidth - 8, 70))} {t.usagePanel.chart.total}{' '} {formatTokens(stats.grandTotal)} {Array.from(stats.models.values()).reduce( (sum, s) => sum + s.cacheRead, 0, ) > 0 && ( <> {' '} |{' '} {t.usagePanel.chart.hit}{' '} {formatTokens( Array.from(stats.models.values()).reduce( (sum, s) => sum + s.cacheRead, 0, ), )} )} {Array.from(stats.models.values()).reduce( (sum, s) => sum + s.cacheCreation, 0, ) > 0 && ( <> ,{' '} {t.usagePanel.chart.create}{' '} {formatTokens( Array.from(stats.models.values()).reduce( (sum, s) => sum + s.cacheCreation, 0, ), )} )} )} {/* Scroll indicator - more below */} {hasMoreBelow && ( {t.usagePanel.chart.moreBelow.replace( '{count}', String(sortedModels.length - endIdx), )} )} ); } export default function UsagePanel() { const {t} = useI18n(); const {theme} = useTheme(); const [granularity, setGranularity] = useState('week'); const [stats, setStats] = useState({ models: new Map(), grandTotal: 0, }); const [isLoading, setIsLoading] = useState(true); const [error, setError] = useState(null); const [scrollOffset, setScrollOffset] = useState(0); const {columns: terminalWidth} = useTerminalSize(); const granularityLabels: Record = { hour: t.usagePanel.granularity.last24h, day: t.usagePanel.granularity.last7d, week: t.usagePanel.granularity.last30d, month: t.usagePanel.granularity.last12m, }; useEffect(() => { const load = async () => { setIsLoading(true); try { const entries = await loadUsageData(); const filtered = filterByGranularity(entries, granularity); const aggregated = aggregateByModel(filtered); setStats(aggregated); setError(null); } catch (err) { setError( err instanceof Error ? err.message : 'Failed to load usage data', ); } finally { setIsLoading(false); } }; load(); }, [granularity]); // Reset scroll when changing granularity useEffect(() => { setScrollOffset(0); }, [granularity]); useInput((_input, key) => { if (key.tab) { const granularities: Granularity[] = ['hour', 'day', 'week', 'month']; const currentIdx = granularities.indexOf(granularity); const nextIdx = (currentIdx + 1) % granularities.length; setGranularity(granularities[nextIdx]!); } // Calculate available space for scrolling const sortedModels = Array.from(stats.models.entries()).sort( (a, b) => b[1].total - a[1].total, ); const totalModels = sortedModels.length; // 循环导航:第一项 → 最后一项,最后一项 → 第一项 if (key.upArrow) { const maxScroll = Math.max(0, totalModels - 1); setScrollOffset(prev => (prev > 0 ? prev - 1 : maxScroll)); } if (key.downArrow) { // Reserve space for header, legend, total summary const maxScroll = Math.max(0, totalModels - 1); setScrollOffset(prev => (prev < maxScroll ? prev + 1 : 0)); } }); if (isLoading) { return ( {t.usagePanel.loading} ); } if (error) { return ( {t.usagePanel.error.replace('{error}', error)} ); } return ( {/* Header */} {t.usagePanel.title} {' '} ({granularityLabels[granularity]}) {' '} {t.usagePanel.tabToSwitch} {stats.models.size === 0 ? ( {t.usagePanel.noDataForPeriod} ) : ( renderStackedBarChart(stats, terminalWidth, scrollOffset, t, theme) )} ); } ================================================ FILE: source/ui/components/panels/WorkingDirectoryPanel.tsx ================================================ import React, {useState, useEffect, useCallback, useRef} from 'react'; import {Box, Text, useInput} from 'ink'; import {Alert} from '@inkjs/ui'; import TextInput from 'ink-text-input'; import { getWorkingDirectories, removeWorkingDirectories, addWorkingDirectory, addSSHWorkingDirectory, type WorkingDirectory, type SSHConfig, } from '../../../utils/config/workingDirConfig.js'; import {SSHClient} from '../../../utils/ssh/sshClient.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; type Props = { onClose: () => void; }; type SSHAuthMethod = 'password' | 'privateKey' | 'agent'; type SSHFormState = { host: string; port: string; username: string; authMethod: SSHAuthMethod; password: string; privateKeyPath: string; remotePath: string; }; type SSHFormField = | 'host' | 'port' | 'username' | 'authMethod' | 'password' | 'privateKeyPath' | 'remotePath'; export default function WorkingDirectoryPanel({onClose}: Props) { const {t} = useI18n(); const {theme} = useTheme(); const [directories, setDirectories] = useState([]); const [loading, setLoading] = useState(true); const [selectedIndex, setSelectedIndex] = useState(0); const [markedDirs, setMarkedDirs] = useState>(new Set()); const [confirmDelete, setConfirmDelete] = useState(false); const [addingMode, setAddingMode] = useState(false); const [newDirPath, setNewDirPath] = useState(''); const [addError, setAddError] = useState(null); const [showDefaultAlert, setShowDefaultAlert] = useState(false); // SSH form state const [sshMode, setSSHMode] = useState(false); const [sshForm, setSSHForm] = useState({ host: '', port: '22', username: '', authMethod: 'privateKey', password: '', privateKeyPath: '~/.ssh/id_rsa', remotePath: '/home', }); const [sshActiveField, setSSHActiveField] = useState('host'); const [sshConnecting, setSSHConnecting] = useState(false); const [sshMessage, setSSHMessage] = useState<{ type: 'success' | 'error'; text: string; } | null>(null); // Ref to hold latest sshForm value for use in callbacks const sshFormRef = useRef(sshForm); // Load directories on mount useEffect(() => { const loadDirs = async () => { setLoading(true); try { const dirs = await getWorkingDirectories(); setDirectories(dirs); } catch (error) { console.error('Failed to load working directories:', error); setDirectories([]); } finally { setLoading(false); } }; void loadDirs(); }, []); // Auto-hide default alert after 3 seconds useEffect(() => { if (showDefaultAlert) { const timer = setTimeout(() => { setShowDefaultAlert(false); }, 2000); return () => clearTimeout(timer); } return undefined; // Return undefined when alert is not shown }, [showDefaultAlert]); // Handle keyboard input useInput( useCallback( (input, key) => { // Don't handle keys if in adding mode (TextInput will handle them) if (addingMode) { if (key.escape) { setAddingMode(false); setNewDirPath(''); setAddError(null); } return; } // SSH mode - handle navigation and auth method switching if (sshMode) { if (key.escape) { setSSHMode(false); setSSHMessage(null); setSSHForm({ host: '', port: '22', username: '', authMethod: 'privateKey', password: '', privateKeyPath: '~/.ssh/id_rsa', remotePath: '/home', }); setSSHActiveField('host'); return; } // Handle arrow keys for field navigation in SSH mode if (key.upArrow || key.downArrow) { const visibleFields: SSHFormField[] = [ 'host', 'port', 'username', 'authMethod', ]; if (sshForm.authMethod === 'password') { visibleFields.push('password'); } else if (sshForm.authMethod === 'privateKey') { visibleFields.push('privateKeyPath'); } visibleFields.push('remotePath'); const currentIndex = visibleFields.indexOf(sshActiveField); if (key.upArrow && currentIndex > 0) { setSSHActiveField(visibleFields[currentIndex - 1]!); } else if ( key.downArrow && currentIndex < visibleFields.length - 1 ) { setSSHActiveField(visibleFields[currentIndex + 1]!); } return; } // Handle left/right arrows for auth method cycling if ( sshActiveField === 'authMethod' && (key.leftArrow || key.rightArrow) ) { const methods: SSHAuthMethod[] = [ 'password', 'privateKey', 'agent', ]; const methodIndex = methods.indexOf(sshForm.authMethod); let nextMethodIndex: number; if (key.rightArrow) { nextMethodIndex = (methodIndex + 1) % methods.length; } else { nextMethodIndex = (methodIndex - 1 + methods.length) % methods.length; } const newForm = {...sshForm, authMethod: methods[nextMethodIndex]!}; setSSHForm(newForm); sshFormRef.current = newForm; return; } return; } // If in delete confirmation mode - check before main ESC handler if (confirmDelete) { if (key.escape) { setConfirmDelete(false); return; } if (input.toLowerCase() === 'y') { // Confirm delete const pathsToDelete = Array.from(markedDirs); removeWorkingDirectories(pathsToDelete) .then(() => { // Reload directories return getWorkingDirectories(); }) .then(dirs => { setDirectories(dirs); setMarkedDirs(new Set()); setConfirmDelete(false); setSelectedIndex(0); }) .catch(error => { console.error('Failed to delete directories:', error); setConfirmDelete(false); }); } else if (input.toLowerCase() === 'n') { // Cancel delete setConfirmDelete(false); } return; } // ESC to close - only when not in any sub-mode if (key.escape) { onClose(); return; } // Up arrow - move selection up if (key.upArrow) { setSelectedIndex(prev => Math.max(0, prev - 1)); return; } // Down arrow - move selection down if (key.downArrow) { setSelectedIndex(prev => Math.min(directories.length - 1, prev + 1)); return; } // Space - toggle mark if (input === ' ' && directories.length > 0) { const currentDir = directories[selectedIndex]; if (currentDir) { if (currentDir.isDefault) { // Show alert for default directory setShowDefaultAlert(true); } else { // Toggle mark for non-default directories setMarkedDirs(prev => { const newSet = new Set(prev); if (newSet.has(currentDir.path)) { newSet.delete(currentDir.path); } else { newSet.add(currentDir.path); } return newSet; }); } } return; } // D key - delete marked directories if (input.toLowerCase() === 'd' && markedDirs.size > 0) { setConfirmDelete(true); return; } // A key - add new directory if (input.toLowerCase() === 'a') { setAddingMode(true); setAddError(null); return; } // S key - add SSH remote directory if (input.toLowerCase() === 's') { setSSHMode(true); setSSHMessage(null); return; } }, [ directories, selectedIndex, markedDirs, confirmDelete, addingMode, sshMode, sshActiveField, sshForm.authMethod, showDefaultAlert, onClose, ], ), ); // Handle add directory submission const handleAddSubmit = async () => { if (!newDirPath.trim()) { setAddError(t.workingDirectoryPanel.addErrorEmpty); return; } const added = await addWorkingDirectory(newDirPath.trim()); if (added) { // Reload directories const dirs = await getWorkingDirectories(); setDirectories(dirs); setAddingMode(false); setNewDirPath(''); setAddError(null); } else { setAddError(t.workingDirectoryPanel.addErrorFailed); } }; // Handle SSH form submission const handleSSHSubmit = async () => { const form = sshFormRef.current; if (!form.host.trim() || !form.username.trim()) { setSSHMessage({ type: 'error', text: t.workingDirectoryPanel.addErrorEmpty, }); return; } setSSHConnecting(true); setSSHMessage(null); const sshConfig: SSHConfig = { host: form.host.trim(), port: parseInt(form.port, 10) || 22, username: form.username.trim(), authMethod: form.authMethod, privateKeyPath: form.authMethod === 'privateKey' ? form.privateKeyPath : undefined, password: form.authMethod === 'password' ? form.password : undefined, }; const client = new SSHClient(); const password = form.authMethod === 'password' ? form.password : undefined; try { const result = await client.testConnection(sshConfig, password); if (result.success) { // Add SSH directory const added = await addSSHWorkingDirectory( sshConfig, form.remotePath.trim() || '/', ); if (added) { setSSHMessage({ type: 'success', text: t.workingDirectoryPanel.sshAddSuccess, }); // Reload directories const dirs = await getWorkingDirectories(); setDirectories(dirs); // Reset form after short delay setTimeout(() => { setSSHMode(false); setSSHMessage(null); setSSHForm({ host: '', port: '22', username: '', authMethod: 'privateKey', password: '', privateKeyPath: '~/.ssh/id_rsa', remotePath: '/home', }); setSSHActiveField('host'); }, 1500); } else { setSSHMessage({ type: 'error', text: t.workingDirectoryPanel.sshAddFailed, }); } } else { setSSHMessage({ type: 'error', text: t.workingDirectoryPanel.sshTestFailed.replace( '{error}', result.error || 'Unknown error', ), }); } } catch (error) { setSSHMessage({ type: 'error', text: t.workingDirectoryPanel.sshTestFailed.replace( '{error}', error instanceof Error ? error.message : String(error), ), }); } finally { setSSHConnecting(false); } }; const handleSSHFieldChange = (field: SSHFormField, value: string) => { const newForm = {...sshFormRef.current, [field]: value}; setSSHForm(newForm); sshFormRef.current = newForm; }; // SSH mode UI if (sshMode) { return ( {t.workingDirectoryPanel.sshTitle} {/* Host */} {t.workingDirectoryPanel.sshHostLabel} handleSSHFieldChange('host', v)} onSubmit={handleSSHSubmit} focus={sshActiveField === 'host'} /> {/* Port */} {t.workingDirectoryPanel.sshPortLabel} handleSSHFieldChange('port', v)} onSubmit={handleSSHSubmit} focus={sshActiveField === 'port'} /> {/* Username */} {t.workingDirectoryPanel.sshUsernameLabel} handleSSHFieldChange('username', v)} onSubmit={handleSSHSubmit} focus={sshActiveField === 'username'} /> {/* Auth Method */} {t.workingDirectoryPanel.sshAuthMethodLabel} {sshActiveField === 'authMethod' ? '< ' : ''} {sshForm.authMethod === 'password' ? t.workingDirectoryPanel.sshAuthPassword : sshForm.authMethod === 'privateKey' ? t.workingDirectoryPanel.sshAuthPrivateKey : t.workingDirectoryPanel.sshAuthAgent} {sshActiveField === 'authMethod' ? ' >' : ''} {/* Password (conditional) */} {sshForm.authMethod === 'password' && ( {t.workingDirectoryPanel.sshPasswordLabel} handleSSHFieldChange('password', v)} onSubmit={handleSSHSubmit} mask="*" focus={sshActiveField === 'password'} /> )} {/* Private Key Path (conditional) */} {sshForm.authMethod === 'privateKey' && ( {t.workingDirectoryPanel.sshPrivateKeyLabel} handleSSHFieldChange('privateKeyPath', v)} onSubmit={handleSSHSubmit} focus={sshActiveField === 'privateKeyPath'} /> )} {/* Remote Path */} {t.workingDirectoryPanel.sshRemotePathLabel} handleSSHFieldChange('remotePath', v)} onSubmit={handleSSHSubmit} focus={sshActiveField === 'remotePath'} /> {/* Status message */} {sshConnecting && ( {t.workingDirectoryPanel.sshConnecting} )} {sshMessage && ( {sshMessage.text} )} {t.workingDirectoryPanel.sshHint} ); } // Adding mode UI if (addingMode) { return ( {t.workingDirectoryPanel.addTitle} {t.workingDirectoryPanel.addPathPrompt} {t.workingDirectoryPanel.addPathLabel} {addError && ( {addError} )} {t.workingDirectoryPanel.addHint} ); } if (loading) { return ( {t.workingDirectoryPanel.title} {t.workingDirectoryPanel.loading} ); } if (confirmDelete) { const deleteMessage = markedDirs.size > 1 ? t.workingDirectoryPanel.confirmDeleteMessagePlural.replace( '{count}', markedDirs.size.toString(), ) : t.workingDirectoryPanel.confirmDeleteMessage.replace( '{count}', markedDirs.size.toString(), ); return ( {t.workingDirectoryPanel.confirmDeleteTitle} {deleteMessage} {Array.from(markedDirs).map(dirPath => ( - {dirPath} ))} {t.workingDirectoryPanel.confirmHint} ); } return ( {t.workingDirectoryPanel.title} {directories.length === 0 ? ( {t.workingDirectoryPanel.noDirectories} ) : ( {directories.map((dir, index) => { const isSelected = index === selectedIndex; const isMarked = markedDirs.has(dir.path); return ( {isSelected ? '> ' : ' '} [{isMarked ? 'x' : ' '}] {' '} {dir.isDefault && ( {t.workingDirectoryPanel.defaultLabel}{' '} )} {dir.path} ); })} )} {t.workingDirectoryPanel.navigationHint} {markedDirs.size > 0 && ( {t.workingDirectoryPanel.markedCount .replace('{count}', markedDirs.size.toString()) .replace( '{plural}', markedDirs.size > 1 ? t.workingDirectoryPanel.markedCountPlural : t.workingDirectoryPanel.markedCountSingular, )} )} {showDefaultAlert && ( {t.workingDirectoryPanel.alertDefaultCannotDelete} )} ); } ================================================ FILE: source/ui/components/pixel-editor/PixelEditor.tsx ================================================ import React, {useState, useEffect, useCallback, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import chalk from 'chalk'; import {useI18n} from '../../../i18n/index.js'; import type {PixelGrid} from './types.js'; const PALETTE = [ '#000000', // 0: black / eraser '#ffffff', // 1: white '#ff0000', // 2: red '#00ff00', // 3: green '#0000ff', // 4: blue '#ffff00', // 5: yellow '#ff00ff', // 6: magenta '#00ffff', // 7: cyan '#808080', // 8: gray '#ffa500', // 9: orange ]; const BLOCK_CHAR = '\u2580'; // Upper half block: foreground = top, background = bottom function createEmptyGrid(width: number, height: number): PixelGrid { return Array.from({length: height}, () => Array.from({length: width}, () => PALETTE[0]!), ); } function blendWithWhite(hex: string, ratio: number): string { const clean = hex.replace('#', ''); const r = Number.parseInt(clean.slice(0, 2), 16); const g = Number.parseInt(clean.slice(2, 4), 16); const b = Number.parseInt(clean.slice(4, 6), 16); const nr = Math.min(255, Math.round(r + (255 - r) * ratio)); const ng = Math.min(255, Math.round(g + (255 - g) * ratio)); const nb = Math.min(255, Math.round(b + (255 - b) * ratio)); return `#${nr.toString(16).padStart(2, '0')}${ng .toString(16) .padStart(2, '0')}${nb.toString(16).padStart(2, '0')}`; } function applyCursorEffect(hex: string): string { const clean = hex.replace('#', ''); const r = Number.parseInt(clean.slice(0, 2), 16); const g = Number.parseInt(clean.slice(2, 4), 16); const b = Number.parseInt(clean.slice(4, 6), 16); const brightness = (r + g + b) / 3; // If the color is already bright, darken it so the cursor remains visible if (brightness > 200) { const factor = 0.5; const nr = Math.round(r * factor); const ng = Math.round(g * factor); const nb = Math.round(b * factor); return `#${nr.toString(16).padStart(2, '0')}${ng .toString(16) .padStart(2, '0')}${nb.toString(16).padStart(2, '0')}`; } return blendWithWhite(hex, 0.6); } type PixelEditorProps = { width?: number; height?: number; initialGrid?: PixelGrid; initialName?: string; onExit?: () => void; onSave?: (grid: PixelGrid, name: string) => void; }; export default function PixelEditor({ width = 32, height = 32, initialGrid, initialName, onExit, onSave, }: PixelEditorProps) { const {t} = useI18n(); const te = t.pixelEditor; // Ensure even height for dual-pixel rendering const canvasHeight = height % 2 === 0 ? height : height + 1; const canvasWidth = width; const [grid, setGrid] = useState(() => { if ( initialGrid && initialGrid.length === canvasHeight && initialGrid[0]?.length === canvasWidth ) { return initialGrid.map(row => [...row]); } return createEmptyGrid(canvasWidth, canvasHeight); }); const [isNamingSave, setIsNamingSave] = useState(false); const [saveName, setSaveName] = useState(''); const [currentName, setCurrentName] = useState(initialName ?? ''); const [cursorX, setCursorX] = useState(Math.floor(canvasWidth / 2)); const [cursorY, setCursorY] = useState(Math.floor(canvasHeight / 2)); const [colorIndex, setColorIndex] = useState(1); const [cursorVisible, setCursorVisible] = useState(true); const [message, setMessage] = useState(null); const [confirmClear, setConfirmClear] = useState(false); // Cursor blink useEffect(() => { const id = setInterval(() => { setCursorVisible(v => !v); }, 400); return () => clearInterval(id); }, []); // Auto-clear transient messages useEffect(() => { if (!message) return; const id = setTimeout(() => setMessage(null), 1500); return () => clearTimeout(id); }, [message]); const drawPixel = useCallback(() => { const color = PALETTE[colorIndex]; if (!color) return; setGrid(prev => { const next = prev.map(row => [...row]); next[cursorY]![cursorX] = color; return next; }); }, [cursorX, cursorY, colorIndex]); const erasePixel = useCallback(() => { setGrid(prev => { const next = prev.map(row => [...row]); next[cursorY]![cursorX] = PALETTE[0]!; return next; }); }, [cursorX, cursorY]); const clearCanvas = useCallback(() => { setGrid(createEmptyGrid(canvasWidth, canvasHeight)); setMessage(te.canvasCleared); setConfirmClear(false); }, [canvasWidth, canvasHeight, te.canvasCleared]); useInput((input, key) => { if (confirmClear) { if (input === 'y' || input === 'Y') { clearCanvas(); } else { setConfirmClear(false); setMessage(te.clearCancelled); } return; } if (isNamingSave) { if (key.escape) { setIsNamingSave(false); setSaveName(''); setMessage(te.saveCancelled); return; } if (key.return) { const name = saveName.trim(); if (!name) { setMessage(te.nameCannotBeEmpty); return; } onSave?.(grid, name); setCurrentName(name); setIsNamingSave(false); setSaveName(''); setMessage(te.savedAs.replace('{name}', name)); return; } // Let TextInput consume normal characters; ignore control keys return; } if (key.escape || input === 'q' || input === 'Q') { onExit?.(); return; } if (key.ctrl && input === 's') { if (currentName) { onSave?.(grid, currentName); setMessage(te.savedAs.replace('{name}', currentName)); } else { setIsNamingSave(true); setSaveName(''); } return; } if (key.upArrow) { setCursorY(y => Math.max(0, y - 1)); return; } if (key.downArrow) { setCursorY(y => Math.min(canvasHeight - 1, y + 1)); return; } if (key.leftArrow) { setCursorX(x => Math.max(0, x - 1)); return; } if (key.rightArrow) { setCursorX(x => Math.min(canvasWidth - 1, x + 1)); return; } if (input === ' ') { const currentPixelColor = grid[cursorY]![cursorX]; if (currentPixelColor !== PALETTE[0]) { erasePixel(); } else { drawPixel(); } return; } if (key.return) { drawPixel(); return; } if (input === '0') { erasePixel(); return; } if (!key.ctrl && (input === 'c' || input === 'C')) { setConfirmClear(true); return; } if (input >= '1' && input <= '9') { const idx = Number.parseInt(input, 10); if (idx < PALETTE.length) { setColorIndex(idx); } return; } }); const renderedRows = useMemo(() => { const rows: string[] = []; for (let charY = 0; charY < canvasHeight / 2; charY++) { let row = ''; for (let x = 0; x < canvasWidth; x++) { const topY = charY * 2; const bottomY = topY + 1; let topColor = grid[topY]![x]!; let bottomColor = grid[bottomY]![x]!; // Cursor highlight if (cursorVisible) { if (cursorX === x && cursorY === topY) { topColor = applyCursorEffect(topColor); } if (cursorX === x && cursorY === bottomY) { bottomColor = applyCursorEffect(bottomColor); } } row += chalk.bgHex(bottomColor).hex(topColor)(BLOCK_CHAR); } rows.push(row); } return rows; }, [grid, cursorX, cursorY, cursorVisible, canvasWidth, canvasHeight]); const currentColor = PALETTE[colorIndex] ?? PALETTE[0] ?? '#000000'; return ( {renderedRows.map((row, i) => ( {row} ))} {te.title} {canvasWidth}x{canvasHeight} {te.palette} {PALETTE.map((color, idx) => ( {idx === colorIndex ? '▶ ' : ' '} {chalk.bgHex(color).hex(color)(' ')}{' '} {idx === 0 ? te.eraser : te.colorNumber.replace('{n}', String(idx))} ))} {!isNamingSave && ( <> {te.controlsHint} {te.controlsHintPosBrush .replace('{x}', String(cursorX)) .replace('{y}', String(cursorY))} {chalk.bgHex(currentColor).hex(currentColor)(' ')} )} {isNamingSave && ( {te.saveDrawingLabel} { const name = saveName.trim(); if (!name) { setMessage(te.nameCannotBeEmpty); return; } onSave?.(grid, name); setCurrentName(name); setIsNamingSave(false); setSaveName(''); setMessage(te.savedAs.replace('{name}', name)); }} placeholder={te.namePlaceholder} /> {te.escCancelHint} )} {confirmClear ? ( {te.confirmClearCanvas} ) : ( !isNamingSave && message && {message} )} ); } ================================================ FILE: source/ui/components/pixel-editor/index.ts ================================================ export {default as PixelEditor} from './PixelEditor.js'; export type {PixelColor, PixelGrid, PixelEditorProps} from './types.js'; ================================================ FILE: source/ui/components/pixel-editor/types.ts ================================================ export type PixelColor = string; // hex color like #RRGGBB export type PixelGrid = PixelColor[][]; // grid[y][x] export interface PixelEditorProps { width?: number; height?: number; onExit?: () => void; } ================================================ FILE: source/ui/components/scheduler/SchedulerCountdown.tsx ================================================ import React, {useEffect, useState} from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import {useI18n} from '../../../i18n/I18nContext.js'; import {useTheme} from '../../contexts/ThemeContext.js'; interface SchedulerCountdownProps { description: string; totalDuration: number; remainingSeconds: number; terminalWidth: number; } /** * Format seconds into mm:ss format */ function formatDuration(seconds: number): string { const mins = Math.floor(seconds / 60); const secs = seconds % 60; return `${mins.toString().padStart(2, '0')}:${secs .toString() .padStart(2, '0')}`; } /** * Get progress bar characters based on completion percentage */ function getProgressBar( progress: number, width: number, filledChar: string, emptyChar: string, ): string { const filled = Math.round((progress / 100) * width); const empty = width - filled; return filledChar.repeat(filled) + emptyChar.repeat(empty); } export function SchedulerCountdown({ description, totalDuration, remainingSeconds, terminalWidth, }: SchedulerCountdownProps) { const {t} = useI18n(); const {theme} = useTheme(); const [elapsedMs, setElapsedMs] = useState(0); // Update elapsed time every 100ms for smooth progress display useEffect(() => { const interval = setInterval(() => { setElapsedMs(prev => prev + 100); }, 100); return () => clearInterval(interval); }, []); // Calculate progress percentage const elapsedSeconds = totalDuration - remainingSeconds; const subSecondProgress = Math.min(elapsedMs / 1000, 1); const totalProgressSeconds = elapsedSeconds + subSecondProgress; const progressPercent = Math.min( 100, (totalProgressSeconds / totalDuration) * 100, ); // Progress bar width (leave space for padding and borders) const progressBarWidth = Math.max(20, terminalWidth - 30); const progressBar = getProgressBar( progressPercent, progressBarWidth, '█', '░', ); // Format display strings const remainingFormatted = formatDuration(remainingSeconds); const totalFormatted = formatDuration(totalDuration); // Truncate description if too long const maxDescWidth = Math.max(40, terminalWidth - 20); const displayDescription = description.length > maxDescWidth ? description.slice(0, maxDescWidth - 3) + '...' : description; return ( {t.scheduler?.title || '预约任务'} 任务: {displayDescription} 进度: {progressBar} {remainingFormatted} / {totalFormatted} ({Math.round(progressPercent)} %) {t.scheduler?.hint || 'AI 流程已暂停，等待倒计时结束...'} ); } ================================================ FILE: source/ui/components/special/AskUserQuestion.tsx ================================================ import React, {useState, useCallback, useMemo, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/index.js'; export interface AskUserQuestionResult { selected: string | string[]; customInput?: string; cancelled?: boolean; } interface Props { question: string; options: string[]; onAnswer: (result: AskUserQuestionResult) => void; onCancel?: () => void; } /** 选项列表可视行数；超出部分随高亮项用方向键滚动 */ const VISIBLE_OPTION_ROWS = 5; /** 非焦点选项的最大显示长度，避免列表高度抖动 */ const NON_FOCUSED_OPTION_MAX_LEN = 20; /** * Agent提问组件 - 支持选项选择、多选和自定义输入 * * @description * 显示问题和建议选项列表，用户可以： * - 直接选择建议选项（回车确认单个高亮项） * - 按空格键切换选项勾选状态（可多选） * - 按'e'键编辑当前高亮选项 * - 选择「Custom input」从头输入 * - 数字键快速切换选项勾选状态 * * @param question - 要问用户的问题 * @param options - 建议选项数组 * @param onAnswer - 用户回答后的回调函数 */ export default function AskUserQuestion({question, options, onAnswer}: Props) { const {theme} = useTheme(); const {t} = useI18n(); const [hasAnswered, setHasAnswered] = useState(false); const [showCustomInput, setShowCustomInput] = useState(false); const [customInput, setCustomInput] = useState(''); const [highlightedOptionIndex, setHighlightedOptionIndex] = useState(0); const [cursorMode, setCursorMode] = useState<'options' | 'custom' | 'cancel'>( 'options', ); const [checkedIndices, setCheckedIndices] = useState>(new Set()); // 动态选项列表，支持添加自定义输入 const [dynamicOptions, setDynamicOptions] = useState([]); //构建选项列表：建议选项 + 动态添加的选项 //防御性检查：确保 options 是数组 const safeOptions = Array.isArray(options) ? options : []; const allOptions = [...safeOptions, ...dynamicOptions]; const optionItems = useMemo( () => allOptions.map((option, index) => ({ label: option, value: `option-${index}`, index, })), [allOptions], ); useEffect(() => { if (optionItems.length === 0 && cursorMode === 'options') { setCursorMode('custom'); return; } if (optionItems.length > 0 && highlightedOptionIndex >= optionItems.length) { setHighlightedOptionIndex(optionItems.length - 1); } }, [optionItems.length, highlightedOptionIndex, cursorMode]); // 与 MCPInfoPanel 相同的居中视口，避免高亮始终在窗口边缘 const optionDisplayWindow = useMemo(() => { const total = optionItems.length; if (total <= VISIBLE_OPTION_ROWS) { return { windowItems: optionItems, startIndex: 0, endIndex: total, hiddenAbove: 0, hiddenBelow: 0, }; } const halfWindow = Math.floor(VISIBLE_OPTION_ROWS / 2); let startIndex = Math.max(0, highlightedOptionIndex - halfWindow); const endIndex = Math.min( total, startIndex + VISIBLE_OPTION_ROWS, ); if (endIndex - startIndex < VISIBLE_OPTION_ROWS) { startIndex = Math.max(0, endIndex - VISIBLE_OPTION_ROWS); } return { windowItems: optionItems.slice(startIndex, endIndex), startIndex, endIndex, hiddenAbove: startIndex, hiddenBelow: total - endIndex, }; }, [optionItems, highlightedOptionIndex]); const optionListScrollable = optionItems.length > VISIBLE_OPTION_ROWS; const formatOptionLabel = useCallback((label: string, isHighlighted: boolean) => { if (isHighlighted || label.length <= NON_FOCUSED_OPTION_MAX_LEN) { return label; } return `${label.slice(0, NON_FOCUSED_OPTION_MAX_LEN - 3)}...`; }, []); const handleSubmit = useCallback(() => { if (hasAnswered) return; if (cursorMode === 'custom') { setShowCustomInput(true); return; } if (cursorMode === 'cancel') { setHasAnswered(true); onAnswer({ selected: '', cancelled: true, }); return; } const currentItem = optionItems[highlightedOptionIndex]; if (!currentItem) return; // 始终支持多选：如果有勾选项则返回数组，否则返回当前高亮项（单个） const selectedOptions = Array.from(checkedIndices) .sort((a, b) => a - b) .map(idx => allOptions[idx] as string) .filter(Boolean); setHasAnswered(true); if (selectedOptions.length > 0) { // 有勾选项，返回数组 onAnswer({ selected: selectedOptions, }); } else { // 没有勾选项，返回当前高亮项（单个） onAnswer({ selected: currentItem.label, }); } }, [ hasAnswered, cursorMode, optionItems, highlightedOptionIndex, checkedIndices, allOptions, onAnswer, ]); const handleCustomInputSubmit = useCallback(() => { if (customInput.trim()) { // 将自定义输入添加到动态选项列表中 const newOption = customInput.trim(); if (!allOptions.includes(newOption)) { setDynamicOptions(prev => [...prev, newOption]); } // 回到选择页面 setShowCustomInput(false); setCustomInput(''); // 高亮新添加的选项 const newIndex = allOptions.length; // 新选项会在下次渲染时出现在这个位置 setHighlightedOptionIndex(newIndex); setCursorMode('options'); } }, [customInput, allOptions]); const handleCustomInputCancel = useCallback(() => { // 取消自定义输入，返回选择列表 setShowCustomInput(false); setCustomInput(''); }, []); const toggleCheck = useCallback((index: number) => { // 不允许勾选特殊选项 if (index < 0) return; setCheckedIndices(prev => { const newSet = new Set(prev); if (newSet.has(index)) { newSet.delete(index); } else { newSet.add(index); } return newSet; }); }, []); //处理键盘输入 - 选择列表模式 useInput( (input, key) => { if (showCustomInput || hasAnswered) { return; } //上下键导航 if (key.upArrow || input === 'k') { if (cursorMode === 'cancel') { setCursorMode('custom'); } else if (cursorMode === 'custom') { if (optionItems.length > 0) { setCursorMode('options'); setHighlightedOptionIndex(optionItems.length - 1); } else { setCursorMode('cancel'); } } else if (optionItems.length > 0) { setHighlightedOptionIndex(prev => prev > 0 ? prev - 1 : optionItems.length - 1, ); } return; } if (key.downArrow || input === 'j') { if (cursorMode === 'options') { if (optionItems.length === 0) { setCursorMode('custom'); } else if (highlightedOptionIndex < optionItems.length - 1) { setHighlightedOptionIndex(prev => prev + 1); } else { setCursorMode('custom'); } } else if (cursorMode === 'custom') { setCursorMode('cancel'); } else { if (optionItems.length > 0) { setCursorMode('options'); setHighlightedOptionIndex(0); } else { setCursorMode('custom'); } } return; } if (key.tab) { setCursorMode(prev => prev === 'custom' ? 'cancel' : 'custom', ); return; } //空格键切换选中（始终支持多选） if (input === ' ' && cursorMode === 'options') { const currentItem = optionItems[highlightedOptionIndex]; if (currentItem) { toggleCheck(currentItem.index); } return; } //数字键快速切换选项勾选状态 const num = parseInt(input, 10); if (!isNaN(num) && num >= 1 && num <= allOptions.length) { const idx = num - 1; setCursorMode('options'); setHighlightedOptionIndex(idx); toggleCheck(idx); return; } //回车确认 if (key.return) { handleSubmit(); return; } //ESC键取消 if (key.escape) { setHasAnswered(true); onAnswer({ selected: '', cancelled: true, }); return; } //e键编辑 if (input === 'e' || input === 'E') { setShowCustomInput(true); if (cursorMode === 'custom' || cursorMode === 'cancel') { setCustomInput(''); } else { const currentItem = optionItems[highlightedOptionIndex]; if (!currentItem) return; setCustomInput(currentItem.label); } } }, {isActive: !showCustomInput && !hasAnswered}, ); //处理键盘输入 - 自定义输入模式 useInput( (_input, key) => { if (!showCustomInput || hasAnswered) { return; } //ESC键返回选择列表 if (key.escape) { handleCustomInputCancel(); return; } }, {isActive: showCustomInput && !hasAnswered}, ); return ( {t.askUser.header} ({t.askUser.multiSelectHint || '可多选'}) {question} {!showCustomInput ? ( {t.askUser.selectPrompt} {optionListScrollable ? ` (${highlightedOptionIndex + 1}/${optionItems.length})` : ''} {optionDisplayWindow.hiddenAbove > 0 ? ( ↑{' '} {t.askUser.optionListMoreAbove.replace( '{count}', String(optionDisplayWindow.hiddenAbove), )} ) : null} {optionDisplayWindow.windowItems.map((item, rowIndex) => { const index = optionDisplayWindow.startIndex + rowIndex; const isHighlighted = cursorMode === 'options' && index === highlightedOptionIndex; const isChecked = item.index >= 0 && checkedIndices.has(item.index); return ( {isHighlighted ? '▸ ' : ' '} {isChecked ? '[✓] ' : '[ ] '} {item.index >= 0 ? `${item.index + 1}. ` : ''} {formatOptionLabel(item.label, isHighlighted)} ); })} {optionDisplayWindow.hiddenBelow > 0 ? ( ↓{' '} {t.askUser.optionListMoreBelow.replace( '{count}', String(optionDisplayWindow.hiddenBelow), )} ) : null} {cursorMode === 'custom' ? '▸ ' : ' '} {t.askUser.customInputOption} {cursorMode === 'cancel' ? '▸ ' : ' '} {t.askUser.cancelOption || 'Cancel'} {t.askUser.multiSelectKeyboardHints || '↑↓ 移动 | Tab 切换(自定义/取消) | 空格 切换 | 1-9 快速切换 | 回车 确认 | e 编辑'} ) : ( {t.askUser.enterResponse} > )} ); } ================================================ FILE: source/ui/components/special/ChatHeader.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import Gradient from 'ink-gradient'; import {useI18n} from '../../../i18n/I18nContext.js'; import {useTheme} from '../../contexts/ThemeContext.js'; type ChatHeaderProps = { terminalWidth: number; simpleMode: boolean; workingDirectory: string; }; export default function ChatHeader({ terminalWidth, simpleMode, workingDirectory, }: ChatHeaderProps) { const {t} = useI18n(); const {theme} = useTheme(); return ( {simpleMode ? ( // Simple mode: No border, smaller logo {/* Simple mode: Show responsive ASCII art title */} {t.chatScreen.headerWorkingDirectory.replace( '{directory}', workingDirectory, )} ) : ( // Normal mode: With border and tips ❆ SNOW CLI ⛇ • {t.chatScreen.headerExplanations} • {t.chatScreen.headerInterrupt} • {t.chatScreen.headerYolo} {(() => { const pasteKey = process.platform === 'darwin' ? 'Ctrl+V' : 'Alt+V'; return `• ${t.chatScreen.headerShortcuts.replace( '{pasteKey}', pasteKey, )}`; })()} • {t.chatScreen.headerExpandedView} {process.platform === 'win32' && ( • Ctrl+G (Notepad edit) )} •{' '} {t.chatScreen.headerWorkingDirectory.replace( '{directory}', workingDirectory, )} )} ); } // 将 LOGO 字符串按可见字符数遮罩：未显示的可见字符替换为空格，换行保留， // 用于在保持布局稳定（行数/列宽不变）的前提下做"逐字显现"动画。 // 当 revealChars 未传入或 >= 可见字符总数时，直接返回原始字符串。 function maskRevealedChars(full: string, revealChars?: number): string { if (revealChars === undefined) return full; let visibleTotal = 0; for (const ch of full) { if (ch !== '\n') visibleTotal++; } if (revealChars >= visibleTotal) return full; let result = ''; let revealed = 0; for (const ch of full) { if (ch === '\n') { result += ch; } else if (revealed < revealChars) { result += ch; revealed++; } else { result += ' '; } } return result; } // Responsive ASCII art logo component for simple mode export function ChatHeaderLogo({ terminalWidth, logoGradient, hideCompact = false, revealChars, }: { terminalWidth: number; logoGradient: [string, string, string]; // 当为 true 时，宽度过窄（< 20）不再回退到最小 LOGO，而是直接不渲染。 // 用于 WelcomeScreen 这种"位置紧张时宁可隐藏也不要降级展示"的场景。 hideCompact?: boolean; // 控制 LOGO 已显示的可见字符数（不计换行）。未传入则始终完整显示。 // 用于 WelcomeScreen 入场时的一次性逐字符出现动画。 revealChars?: number; }) { if (terminalWidth >= 30) { // Full version: SNOW CLI with thin style (width >= 30) const fullLogo = `╔═╗╔╗╔╔═╗╦ ╦ ╔═╗╦ ╦ ╚═╗║║║║ ║║║║ ║ ║ ║ ╚═╝╝╚╝╚═╝╚╩╝ ╚═╝╩═╝╩`; return ( {maskRevealedChars(fullLogo, revealChars)} ); } if (terminalWidth >= 20) { // Medium version: SNOW only (width 20-29) const mediumLogo = `╔═╗╔╗╔╔═╗╦ ╦ ╚═╗║║║║ ║║║║ ╚═╝╝╚╝╚═╝╚╩╝`; return ( {maskRevealedChars(mediumLogo, revealChars)} ); } // Compact version: Normal text (width < 20) // 当 hideCompact=true 时，调用方明确要求"宽度不够就直接不渲染最小 LOGO"， // 避免在 WelcomeScreen 右半区被压缩时还塞一行 "❆ SNOW CLI" 文本。 if (hideCompact) { return null; } return ( ❆ SNOW CLI ); } ================================================ FILE: source/ui/components/special/HookErrorDisplay.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import type {HookErrorDetails} from '../../../utils/execution/hookResultInterpreter.js'; interface HookErrorDisplayProps { details: HookErrorDetails; } /** * 截断文本 */ const truncate = (text: string, maxLength: number): string => { if (text.length <= maxLength) return text; return text.slice(0, maxLength) + '...'; }; /** * Hook错误显示组件 * 以树状结构显示Hook命令执行错误 */ export const HookErrorDisplay: React.FC = ({details}) => { const {type, exitCode, command, output, error} = details; // 组合输出 const combinedOutput = [output, error].filter(Boolean).join('\n\n') || '(no output)'; // 截断过长的内容 const truncatedCommand = truncate(command, 150); const truncatedOutput = truncate(combinedOutput, 300); const title = type === 'warning' ? 'Hook Command Warning' : `Hook Command Failed (Exit Code ${exitCode})`; return ( {title} ├─ {truncatedCommand} └─ {truncatedOutput} ); }; ================================================ FILE: source/ui/components/special/TodoTree.tsx ================================================ import React, {useEffect, useMemo, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; interface TodoItem { id: string; content: string; status: 'pending' | 'inProgress' | 'completed' | string; parentId?: string; } interface TodoTreeProps { todos: TodoItem[]; } /** * TODO Tree 组件 - 显示紧凑任务列表 */ export default function TodoTree({todos}: TodoTreeProps) { const {theme} = useTheme(); const {t} = useI18n(); if (todos.length === 0) { return null; } const PAGE_SIZE = 5; const totalCount = todos.length; const completedCount = todos.reduce( (acc, t) => acc + (t.status === 'completed' ? 1 : 0), 0, ); const sortedTodos = useMemo(() => { // 排序优先级：inProgress > pending > completed return todos .map((t, originalIndex) => ({t, originalIndex})) .slice() .sort((a, b) => { const getPriority = (status: string) => { if (status === 'inProgress') return 0; if (status === 'pending') return 1; if (status === 'completed') return 2; return 1; // 未知状态按 pending 处理 }; const aPriority = getPriority(a.t.status); const bPriority = getPriority(b.t.status); if (aPriority !== bPriority) return aPriority - bPriority; return a.originalIndex - b.originalIndex; }) .map(({t}) => t); }, [todos]); const pageCount = Math.max(1, Math.ceil(sortedTodos.length / PAGE_SIZE)); const [pageIndex, setPageIndex] = useState(0); useEffect(() => { // 数据变化时，防止 pageIndex 越界。 setPageIndex(p => Math.min(p, pageCount - 1)); }, [pageCount]); useInput((_input, key) => { if (!key.tab || key.shift || pageCount <= 1) return; setPageIndex(p => (p + 1) % pageCount); }); const visibleTodos = sortedTodos.slice( pageIndex * PAGE_SIZE, pageIndex * PAGE_SIZE + PAGE_SIZE, ); const hiddenCount = Math.max(0, sortedTodos.length - visibleTodos.length); const getStatusIcon = (status: string) => { if (status === 'completed') return '✓'; if (status === 'inProgress') return '~'; return '○'; }; const getStatusColor = (status: string) => { if (status === 'completed') return theme.colors.success; if (status === 'inProgress') return theme.colors.warning; return theme.colors.menuSecondary; }; const renderTodoLine = (todo: TodoItem, index: number): React.ReactNode => { const statusIcon = getStatusIcon(todo.status); const statusColor = getStatusColor(todo.status); return ( {statusIcon} {todo.content} ); }; return ( TODO ({completedCount}/{totalCount}) {' '} [{pageIndex + 1}/{pageCount}] {t.toolConfirmation.commandPagerHint} {hiddenCount > 0 && +{hiddenCount} more} {visibleTodos.map((todo, index) => renderTodoLine(todo, index))} ); } ================================================ FILE: source/ui/components/sse/SSEServerStatus.tsx ================================================ import React, {useState, useEffect} from 'react'; import {Box, Text} from 'ink'; import {useI18n} from '../../../i18n/I18nContext.js'; interface LogEntry { timestamp: string; level: 'info' | 'error' | 'success'; message: string; } interface SSEServerStatusProps { port: number; workingDir?: string; onLogUpdate?: ( callback: (message: string, level?: 'info' | 'error' | 'success') => void, ) => void; } export const SSEServerStatus: React.FC = ({ port, workingDir, onLogUpdate, }) => { const {t} = useI18n(); const [logs, setLogs] = useState([]); useEffect(() => { if (onLogUpdate) { onLogUpdate( (message: string, level: 'info' | 'error' | 'success' = 'info') => { const timestamp = new Date().toLocaleTimeString('zh-CN', { hour12: false, }); setLogs(prev => [...prev, {timestamp, level, message}]); }, ); } }, [onLogUpdate]); const getLevelColor = (level: string) => { switch (level) { case 'success': return 'green'; case 'error': return 'red'; default: return 'gray'; } }; return ( {/* 服务器状态 */} {t.sseServer.started} {/* 服务器信息 */} {t.sseServer.port}: {port} {workingDir && ( <> | {t.sseServer.workingDir}: {workingDir} )} | ● {t.sseServer.running} {/* 端点列表 */} {t.sseServer.endpoints}: http://localhost:{port}/events POST http://localhost:{port}/message POST http://localhost:{port}/session/create POST http://localhost:{port}/session/load GET http://localhost:{port}/session/list {' '} GET http://localhost:{port} /session/rollback-points?sessionId=:sessionId {' '} DELETE http://localhost:{port}/session/:sessionId POST http://localhost:{port}/context/compress GET http://localhost:{port}/health {/* 运行日志 - 显示全部 */} {t.sseServer.logs} ({logs.length}): {logs.map((log, index) => ( [{log.timestamp}] {log.message} ))} {/* 提示 */} {t.sseServer.stopHint} ); }; ================================================ FILE: source/ui/components/tools/DiffViewer.tsx ================================================ import React, {useMemo} from 'react'; import {Box, Text} from 'ink'; import chalk from 'chalk'; import stringWidth from 'string-width'; import sliceAnsi from 'slice-ansi'; import {highlight, supportsLanguage} from 'cli-highlight'; import * as Diff from 'diff'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useTerminalSize} from '../../../hooks/ui/useTerminalSize.js'; interface Props { oldContent?: string; newContent: string; filename?: string; completeOldContent?: string; completeNewContent?: string; startLineNumber?: number; } interface DiffHunk { startLine: number; endLine: number; changes: Array<{ type: 'added' | 'removed' | 'unchanged'; content: string; oldLineNum: number | null; newLineNum: number | null; }>; } function expandTabsForDisplay(line: string, tabWidth = 2): string { if (!line.includes('\t')) { return line; } let col = 0; let out = ''; for (const ch of line) { if (ch === '\t') { const spaces = tabWidth - (col % tabWidth); out += ' '.repeat(spaces); col += spaces; } else { out += ch; col = ch === '\n' || ch === '\r' ? 0 : col + 1; } } return out; } function stripLineNumbers(content: string): string { const hashlineRe = /^\s*\d+:[0-9a-fA-F]{2}→(.*)$/; const lineNumArrowRe = /^\s*\d+→(.*)$/; return content .split('\n') .map(line => { let stripped = line.replace(/\r$/, ''); let match: RegExpMatchArray | null; for (;;) { if ((match = hashlineRe.exec(stripped))) { stripped = match[1]!; continue; } if ((match = lineNumArrowRe.exec(stripped))) { stripped = match[1]!; continue; } break; } return stripped; }) .join('\n'); } const MIN_SIDE_BY_SIDE_WIDTH = 120; const LANGUAGE_BY_EXTENSION: Record = { js: 'javascript', jsx: 'javascript', mjs: 'javascript', cjs: 'javascript', ts: 'typescript', tsx: 'typescript', json: 'json', md: 'markdown', yml: 'yaml', yaml: 'yaml', sh: 'bash', zsh: 'bash', bash: 'bash', py: 'python', rb: 'ruby', rs: 'rust', go: 'go', java: 'java', kt: 'kotlin', swift: 'swift', html: 'html', xml: 'xml', css: 'css', scss: 'scss', less: 'less', sql: 'sql', php: 'php', }; function inferLanguageFromFilename(filename?: string): string | undefined { if (!filename) { return undefined; } const normalizedFilename = filename.split(/[?#]/)[0] ?? filename; const extension = normalizedFilename.split('.').pop()?.toLowerCase(); if (!extension || extension === normalizedFilename.toLowerCase()) { return undefined; } return LANGUAGE_BY_EXTENSION[extension] ?? extension; } function highlightCodeContent(content: string, language?: string): string { if (!language || content.trim() === '' || !supportsLanguage(language)) { return content; } try { return highlight(content, { language, ignoreIllegals: true, }); } catch { return content; } } function normalizeHexColor(hex: string): string | null { if (!hex.startsWith('#')) { return null; } const value = hex.slice(1); if (value.length === 3 || value.length === 4) { return value .slice(0, 3) .split('') .map(char => char + char) .join(''); } if (value.length === 6 || value.length === 8) { return value.slice(0, 6); } return null; } function blendHexColors( foreground: string, background: string, alpha: number, ): string { const normalizedForeground = normalizeHexColor(foreground); const normalizedBackground = normalizeHexColor(background); if (!normalizedForeground || !normalizedBackground) { return foreground; } const blendChannel = (foregroundOffset: number, backgroundOffset: number) => { const foregroundValue = Number.parseInt( normalizedForeground.slice(foregroundOffset, foregroundOffset + 2), 16, ); const backgroundValue = Number.parseInt( normalizedBackground.slice(backgroundOffset, backgroundOffset + 2), 16, ); const blendedValue = Math.round( foregroundValue * alpha + backgroundValue * (1 - alpha), ); return blendedValue.toString(16).padStart(2, '0'); }; return `#${blendChannel(0, 0)}${blendChannel(2, 2)}${blendChannel(4, 4)}`; } /** * Compute diff hunks from old and new content. * Pure function — no React dependencies. */ function computeHunks( diffOldContent: string, diffNewContent: string, startLineNumber: number, ): DiffHunk[] { const diffResult = Diff.diffLines(diffOldContent, diffNewContent); interface Change { type: 'added' | 'removed' | 'unchanged'; content: string; oldLineNum: number | null; newLineNum: number | null; } const allChanges: Change[] = []; let oldLineNum = startLineNumber; let newLineNum = startLineNumber; diffResult.forEach(part => { const normalizedValue = part.value .replace(/\r\n/g, '\n') .replace(/\r/g, '\n') .replace(/\n$/, ''); const lines = normalizedValue.split('\n'); lines.forEach(line => { const cleanLine = line.replace(/\r/g, ''); if (part.added) { allChanges.push({ type: 'added', content: cleanLine, oldLineNum: null, newLineNum: newLineNum++, }); } else if (part.removed) { allChanges.push({ type: 'removed', content: cleanLine, oldLineNum: oldLineNum++, newLineNum: null, }); } else { allChanges.push({ type: 'unchanged', content: cleanLine, oldLineNum: oldLineNum++, newLineNum: newLineNum++, }); } }); }); const computedHunks: DiffHunk[] = []; const contextLines = 3; for (let i = 0; i < allChanges.length; i++) { const change = allChanges[i]; if (change?.type !== 'unchanged') { const hunkStart = Math.max(0, i - contextLines); let hunkEnd = i; while (hunkEnd < allChanges.length - 1) { const nextChange = allChanges[hunkEnd + 1]; if (!nextChange) break; if (nextChange.type !== 'unchanged') { hunkEnd++; continue; } let hasMoreChanges = false; for ( let j = hunkEnd + 1; j < Math.min(allChanges.length, hunkEnd + 1 + contextLines * 2); j++ ) { if (allChanges[j]?.type !== 'unchanged') { hasMoreChanges = true; break; } } if (hasMoreChanges) { hunkEnd++; } else { break; } } hunkEnd = Math.min(allChanges.length - 1, hunkEnd + contextLines); const hunkChanges = allChanges.slice(hunkStart, hunkEnd + 1); const firstChange = hunkChanges[0]; const lastChange = hunkChanges[hunkChanges.length - 1]; if (firstChange && lastChange) { computedHunks.push({ startLine: firstChange.oldLineNum || firstChange.newLineNum || 1, endLine: lastChange.oldLineNum || lastChange.newLineNum || 1, changes: hunkChanges, }); } i = hunkEnd; } } return computedHunks; } /** * Pre-render the entire diff as a single ANSI string. * * This avoids creating hundreds of React elements and Yoga WASM nodes * (one per diff line), which is the primary source of memory that never * gets reclaimed — WASM ArrayBuffer only grows, never shrinks. * * With this approach the component produces exactly 1 element * regardless of diff size. */ export default function DiffViewer({ oldContent = '', newContent, filename, completeOldContent, completeNewContent, startLineNumber = 1, }: Props) { const {theme, diffOpacity} = useTheme(); const {columns: terminalColumns} = useTerminalSize(); const codeLanguage = inferLanguageFromFilename(filename); // DiffViewer is nested inside: // → -2 // {icon} → -2 (icon + space) // → -1 // → (no horizontal effect) // // Total inset ≈ 5, add 1 safety margin = 6 const columns = Math.max(terminalColumns - 6, 40); const diffAddedBg = useMemo( () => blendHexColors( theme.colors.diffAdded, theme.colors.background, diffOpacity, ), [diffOpacity, theme.colors.diffAdded, theme.colors.background], ); const diffRemovedBg = useMemo( () => blendHexColors( theme.colors.diffRemoved, theme.colors.background, diffOpacity, ), [diffOpacity, theme.colors.diffRemoved, theme.colors.background], ); const useSideBySide = columns >= MIN_SIDE_BY_SIDE_WIDTH; const diffOldContent = stripLineNumbers( completeOldContent && completeNewContent ? completeOldContent : oldContent, ); const diffNewContent = stripLineNumbers( completeOldContent && completeNewContent ? completeNewContent : newContent, ); const renderedOutput = useMemo(() => { const hl = (content: string) => highlightCodeContent(expandTabsForDisplay(content), codeLanguage); const addedStyle = (text: string) => chalk.bgHex(diffAddedBg).white(text); const removedStyle = (text: string) => chalk.bgHex(diffRemovedBg).white(text); const dimStyle = (text: string) => chalk.dim(text); const cleanContent = (c: string) => c.replace(/[\r\n]/g, ''); const isNewFile = !diffOldContent || diffOldContent.trim() === ''; // --- New file --- if (isNewFile) { const header = filename ? chalk.cyan.bold(filename) + chalk.green(' (new)') : chalk.green.bold('New File'); const allLines = diffNewContent.split('\n'); const body = allLines.map(line => addedStyle('+ ' + hl(line))).join('\n'); return header + '\n' + body; } // --- Modified file --- const hunks = computeHunks(diffOldContent, diffNewContent, startLineNumber); const header = filename ? chalk.cyan.bold(filename) + chalk.yellow(' (modified)') + (useSideBySide ? chalk.dim(' (side-by-side)') : '') : chalk.yellow.bold('File Modified'); const hunkStrings = hunks.map(hunk => { const hunkHeader = chalk.cyan.dim( `@@ Lines ${hunk.startLine}-${hunk.endLine} @@`, ); if (useSideBySide) { return formatSideBySide( hunk, hunkHeader, columns, hl, addedStyle, removedStyle, dimStyle, cleanContent, ); } return formatUnified( hunk, hunkHeader, hl, addedStyle, removedStyle, dimStyle, cleanContent, ); }); let output = header + '\n' + hunkStrings.join('\n'); if (hunks.length > 1) { output += '\n' + chalk.gray.dim(`Total: ${hunks.length} change region(s)`); } return output; }, [ diffOldContent, diffNewContent, startLineNumber, filename, codeLanguage, diffAddedBg, diffRemovedBg, useSideBySide, columns, ]); return ( {renderedOutput} ); } function formatUnified( hunk: DiffHunk, hunkHeader: string, hl: (s: string) => string, addedStyle: (s: string) => string, removedStyle: (s: string) => string, dimStyle: (s: string) => string, cleanContent: (s: string) => string, ): string { const lines: string[] = [hunkHeader]; for (const change of hunk.changes) { const lineNum = change.type === 'added' ? change.newLineNum : change.oldLineNum; const lineNumStr = lineNum ? String(lineNum).padStart(4, ' ') : ' '; const content = hl(cleanContent(change.content)); if (change.type === 'added') { lines.push(addedStyle(`${lineNumStr} + ${content}`)); } else if (change.type === 'removed') { lines.push(removedStyle(`${lineNumStr} - ${content}`)); } else { lines.push(dimStyle(`${lineNumStr} ${content}`)); } } return lines.join('\n'); } function formatSideBySide( hunk: DiffHunk, hunkHeader: string, columns: number, hl: (s: string) => string, addedStyle: (s: string) => string, removedStyle: (s: string) => string, dimStyle: (s: string) => string, cleanContent: (s: string) => string, ): string { const separatorWidth = 3; const lineNumWidth = 4; const panelWidth = Math.floor((columns - separatorWidth) / 2); const separator = chalk.dim(' | '); interface SideBySideLine { left: { lineNum: number | null; type: 'removed' | 'unchanged' | 'empty'; content: string; }; right: { lineNum: number | null; type: 'added' | 'unchanged' | 'empty'; content: string; }; } const pairedLines: SideBySideLine[] = []; let leftIdx = 0; let rightIdx = 0; const leftChanges = hunk.changes.filter( c => c.type === 'removed' || c.type === 'unchanged', ); const rightChanges = hunk.changes.filter( c => c.type === 'added' || c.type === 'unchanged', ); while (leftIdx < leftChanges.length || rightIdx < rightChanges.length) { const leftChange = leftChanges[leftIdx]; const rightChange = rightChanges[rightIdx]; if (leftChange?.type === 'unchanged' && rightChange?.type === 'unchanged') { pairedLines.push({ left: { lineNum: leftChange.oldLineNum, type: 'unchanged', content: leftChange.content, }, right: { lineNum: rightChange.newLineNum, type: 'unchanged', content: rightChange.content, }, }); leftIdx++; rightIdx++; } else if ( leftChange?.type === 'removed' && rightChange?.type === 'added' ) { pairedLines.push({ left: { lineNum: leftChange.oldLineNum, type: 'removed', content: leftChange.content, }, right: { lineNum: rightChange.newLineNum, type: 'added', content: rightChange.content, }, }); leftIdx++; rightIdx++; } else if (leftChange?.type === 'removed') { pairedLines.push({ left: { lineNum: leftChange.oldLineNum, type: 'removed', content: leftChange.content, }, right: {lineNum: null, type: 'empty', content: ''}, }); leftIdx++; } else if (rightChange?.type === 'added') { pairedLines.push({ left: {lineNum: null, type: 'empty', content: ''}, right: { lineNum: rightChange.newLineNum, type: 'added', content: rightChange.content, }, }); rightIdx++; } else { if (leftIdx < leftChanges.length) leftIdx++; if (rightIdx < rightChanges.length) rightIdx++; } } /** * Pad or truncate an ANSI string to exactly `width` visible columns. * Uses string-width for accurate measurement and slice-ansi for * truncation that preserves ANSI escape sequences. */ const fitToWidth = (str: string, width: number): string => { const w = stringWidth(str); if (w === width) return str; if (w > width) return sliceAnsi(str, 0, width); return str + ' '.repeat(width - w); }; /** * Wrap an ANSI string into multiple rows, each padded to exactly `width` * visible columns. Preserves ANSI escape sequences across slices. */ const wrapToWidth = (str: string, width: number): string[] => { if (width <= 0) return ['']; const total = stringWidth(str); if (total === 0) return [' '.repeat(width)]; const rows: string[] = []; let offset = 0; while (offset < total) { const piece = sliceAnsi(str, offset, offset + width); const pieceWidth = stringWidth(piece); rows.push( pieceWidth >= width ? piece : piece + ' '.repeat(width - pieceWidth), ); if (pieceWidth <= 0) break; offset += pieceWidth; } return rows.length > 0 ? rows : [' '.repeat(width)]; }; const headerDash = '-'.repeat(Math.max(Math.floor((panelWidth - 5) / 2), 1)); const leftHeader = fitToWidth( chalk.dim(headerDash) + chalk.red.bold(' OLD ') + chalk.dim(headerDash), panelWidth, ); const rightHeader = fitToWidth( chalk.dim(headerDash) + chalk.green.bold(' NEW ') + chalk.dim(headerDash), panelWidth, ); const lines: string[] = [hunkHeader, leftHeader + separator + rightHeader]; const emptyPanel = ' '.repeat(panelWidth); const prefixWidth = lineNumWidth + 3; // "NNNN S " → lineNum + space + sign + space const contentWidth = Math.max(panelWidth - prefixWidth, 1); const blankPrefix = ' '.repeat(prefixWidth); for (const pair of pairedLines) { const leftLineNum = pair.left.lineNum ? String(pair.left.lineNum).padStart(lineNumWidth, ' ') : ''.padStart(lineNumWidth, ' '); const rightLineNum = pair.right.lineNum ? String(pair.right.lineNum).padStart(lineNumWidth, ' ') : ''.padStart(lineNumWidth, ' '); const leftSign = pair.left.type === 'removed' ? '-' : pair.left.type === 'unchanged' ? ' ' : ' '; const rightSign = pair.right.type === 'added' ? '+' : pair.right.type === 'unchanged' ? ' ' : ' '; const leftContent = hl(cleanContent(pair.left.content)); const rightContent = hl(cleanContent(pair.right.content)); const leftRows = pair.left.type === 'empty' ? [''] : wrapToWidth(leftContent, contentWidth); const rightRows = pair.right.type === 'empty' ? [''] : wrapToWidth(rightContent, contentWidth); const rowCount = Math.max(leftRows.length, rightRows.length); for (let rowIdx = 0; rowIdx < rowCount; rowIdx++) { const leftPrefix = rowIdx === 0 ? `${leftLineNum} ${leftSign} ` : blankPrefix; const rightPrefix = rowIdx === 0 ? `${rightLineNum} ${rightSign} ` : blankPrefix; const leftRow = leftRows[rowIdx] ?? ' '.repeat(contentWidth); const rightRow = rightRows[rowIdx] ?? ' '.repeat(contentWidth); let leftStr: string; if (pair.left.type === 'empty') { leftStr = emptyPanel; } else if (pair.left.type === 'removed') { leftStr = fitToWidth(removedStyle(leftPrefix + leftRow), panelWidth); } else { leftStr = fitToWidth(dimStyle(leftPrefix + leftRow), panelWidth); } let rightStr: string; if (pair.right.type === 'empty') { rightStr = emptyPanel; } else if (pair.right.type === 'added') { rightStr = fitToWidth(addedStyle(rightPrefix + rightRow), panelWidth); } else { rightStr = fitToWidth(dimStyle(rightPrefix + rightRow), panelWidth); } lines.push(leftStr + separator + rightStr); } } return lines.join('\n'); } ================================================ FILE: source/ui/components/tools/FileList.tsx ================================================ import React, { useState, useEffect, useMemo, useCallback, forwardRef, useImperativeHandle, memo, } from 'react'; import {Box, Text} from 'ink'; import fs from 'fs'; import path from 'path'; import {useTerminalSize} from '../../../hooks/ui/useTerminalSize.js'; import {useI18n} from '../../../i18n/index.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {getWorkingDirectories} from '../../../utils/config/workingDirConfig.js'; import {SSHClient, parseSSHUrl} from '../../../utils/ssh/sshClient.js'; import { getFileListDisplayMode, setFileListDisplayMode, } from '../../../utils/config/projectSettings.js'; type FileItem = { name: string; path: string; isDirectory: boolean; // For content search mode lineNumber?: number; lineContent?: string; // Source working directory for multi-dir support sourceDir?: string; }; type Props = { query: string; selectedIndex: number; visible: boolean; maxItems?: number; rootPath?: string; onFilteredCountChange?: (count: number) => void; searchMode?: 'file' | 'content'; }; export type FileListRef = { getSelectedFile: () => string | null; toggleDisplayMode: () => boolean; // Manually expand the BFS scan depth (used when the user navigates past // the last filtered result and may want results from deeper directories). // Returns true if a deeper scan was actually scheduled. triggerDeeperSearch: () => boolean; }; type DisplayMode = 'list' | 'tree'; type DisplayItem = { file: FileItem; key: string; label: string; depth: number; isContextOnly?: boolean; }; // How long the in-memory file index is kept after the panel is hidden. // When the panel stays closed beyond this window, the cached `files` array // is released so a long-running CLI session does not hold onto thousands of // FileItem entries indefinitely. Reopening the panel triggers a fresh scan. const SEARCH_RESULT_TTL_MS = 30_000; const getDisplayItemKey = (file: FileItem) => `${file.sourceDir || ''}::${file.path}::${file.lineNumber ?? 0}`; const getNormalizedItemPath = (itemPath: string) => itemPath.replace(/\\/g, '/').replace(/\/$/, ''); const getLookupKey = (sourceDir: string | undefined, itemPath: string) => `${sourceDir || ''}::${getNormalizedItemPath(itemPath)}`; const getRelativeTreePath = (file: FileItem) => { if (file.path.startsWith('ssh://') || path.isAbsolute(file.path)) { return ''; } return getNormalizedItemPath(file.path) .replace(/^\.\//, '') .replace(/^\/+/, ''); }; const getTreeDepth = (file: FileItem) => { const relativePath = getRelativeTreePath(file); if (!relativePath) { return 0; } return relativePath.split('/').filter(Boolean).length; }; const compareTreeItems = (a: FileItem, b: FileItem) => { const sourceCompare = (a.sourceDir || '').localeCompare(b.sourceDir || ''); if (sourceCompare !== 0) { return sourceCompare; } const aIsRoot = a.path === (a.sourceDir || ''); const bIsRoot = b.path === (b.sourceDir || ''); if (aIsRoot !== bIsRoot) { return aIsRoot ? -1 : 1; } const aParts = getRelativeTreePath(a).split('/').filter(Boolean); const bParts = getRelativeTreePath(b).split('/').filter(Boolean); const maxDepth = Math.min(aParts.length, bParts.length); for (let i = 0; i < maxDepth; i++) { const aPart = aParts[i] || ''; const bPart = bParts[i] || ''; const diff = aPart.localeCompare(bPart); if (diff !== 0) { return diff; } } if (aParts.length !== bParts.length) { return aParts.length - bParts.length; } if (a.isDirectory !== b.isDirectory) { return a.isDirectory ? -1 : 1; } return a.name.localeCompare(b.name); }; const buildTreeDisplayItems = ( filteredFiles: FileItem[], allFiles: FileItem[], query: string, ): DisplayItem[] => { const allFilesLookup = new Map( allFiles.map(file => [getLookupKey(file.sourceDir, file.path), file]), ); const directMatchKeys = new Set(filteredFiles.map(getDisplayItemKey)); const includedFiles = new Map< string, {file: FileItem; isContextOnly: boolean} >(); const includeFile = (file: FileItem, isContextOnly: boolean) => { const key = getDisplayItemKey(file); const existing = includedFiles.get(key); if (!existing || (!isContextOnly && existing.isContextOnly)) { includedFiles.set(key, {file, isContextOnly}); } }; filteredFiles.forEach(file => includeFile(file, false)); if (query.trim()) { for (const file of filteredFiles) { if (!file.sourceDir) { continue; } const rootFile = allFilesLookup.get( getLookupKey(file.sourceDir, file.sourceDir), ); if (rootFile) { includeFile( rootFile, !directMatchKeys.has(getDisplayItemKey(rootFile)), ); } const relativePath = getRelativeTreePath(file); if (!relativePath) { continue; } const segments = relativePath.split('/').filter(Boolean); for (let depth = 1; depth < segments.length; depth++) { const ancestorPath = `./${segments.slice(0, depth).join('/')}`; const ancestor = allFilesLookup.get( getLookupKey(file.sourceDir, ancestorPath), ); if (ancestor) { includeFile( ancestor, !directMatchKeys.has(getDisplayItemKey(ancestor)), ); } } } } return Array.from(includedFiles.values()) .map(({file, isContextOnly}) => ({ file, key: getDisplayItemKey(file), label: file.name, depth: getTreeDepth(file), isContextOnly, })) .sort((a, b) => compareTreeItems(a.file, b.file)); }; const getFullFilePath = (file: FileItem, rootPath: string) => { const baseDir = file.sourceDir || rootPath; if (file.path.startsWith('ssh://') || path.isAbsolute(file.path)) { return file.path; } if (baseDir.startsWith('ssh://')) { const cleanBase = baseDir.replace(/\/$/, ''); const cleanRelative = file.path.replace(/^\.\//, '').replace(/^\//, ''); return `${cleanBase}/${cleanRelative}`; } return path.join(baseDir, file.path); }; const FileList = memo( forwardRef( ( { query, selectedIndex, visible, maxItems = 10, rootPath = process.cwd(), onFilteredCountChange, searchMode = 'file', }, ref, ) => { const {t} = useI18n(); const {theme} = useTheme(); const [files, setFiles] = useState([]); const [isLoading, setIsLoading] = useState(false); // Progressive depth search: start shallow, expand on demand. const [searchDepth, setSearchDepth] = useState(2); const [hasMoreDepth, setHasMoreDepth] = useState(true); const [isIncreasingDepth, setIsIncreasingDepth] = useState(false); const [displayMode, setDisplayMode] = useState( getFileListDisplayMode, ); // Get terminal size for dynamic content display const {columns: terminalWidth} = useTerminalSize(); // Fixed maximum display items to prevent rendering issues const MAX_DISPLAY_ITEMS = 5; const effectiveMaxItems = useMemo(() => { return maxItems ? Math.min(maxItems, MAX_DISPLAY_ITEMS) : MAX_DISPLAY_ITEMS; }, [maxItems]); // Streamed file loader: walks the tree (BFS) up to `searchDepth` and // pushes incremental updates to `files` so the input box can filter // against partial results in real time. No file count cap. const loadFiles = useCallback(async () => { const workingDirs = await getWorkingDirectories(); const collected: FileItem[] = []; // Tracks whether we encountered subdirectories that were skipped // because they exceeded `searchDepth`, signalling more depth is available. let depthLimitHit = false; // Throttle UI updates: flush at most every FLUSH_INTERVAL_MS or every // FLUSH_BATCH_SIZE new files, whichever comes first. const FLUSH_INTERVAL_MS = 80; const FLUSH_BATCH_SIZE = 200; let lastFlushAt = 0; let pendingSinceFlush = 0; const flush = (force: boolean) => { const now = Date.now(); if ( !force && pendingSinceFlush < FLUSH_BATCH_SIZE && now - lastFlushAt < FLUSH_INTERVAL_MS ) { return; } lastFlushAt = now; pendingSinceFlush = 0; setFiles(collected.slice()); }; const pushFile = (item: FileItem) => { collected.push(item); pendingSinceFlush++; flush(false); }; // Yield to the event loop so UI/keystrokes stay responsive during long scans. const yieldToEventLoop = () => new Promise(resolve => setImmediate(resolve)); setIsLoading(true); setFiles([]); for (const workingDir of workingDirs) { const dirPath = workingDir.path; // Handle remote SSH directories if (workingDir.isRemote && workingDir.sshConfig) { try { const sshInfo = parseSSHUrl(dirPath); if (!sshInfo) { continue; } const remoteDirName = sshInfo.path.split('/').pop() || sshInfo.host; pushFile({ name: remoteDirName, path: dirPath, isDirectory: true, sourceDir: dirPath, }); const sshClient = new SSHClient(); const connectResult = await sshClient.connect( workingDir.sshConfig, workingDir.sshConfig.password, ); if (!connectResult.success) { continue; } // BFS over remote directories so siblings are sampled fairly. const queue: Array<{path: string; depth: number}> = [ {path: sshInfo.path, depth: 0}, ]; while (queue.length > 0) { const node = queue.shift() as {path: string; depth: number}; const current = node.path; let entries: Awaited< ReturnType > = []; try { entries = await sshClient.listDirectory(current); } catch { continue; } for (const entry of entries) { if (entry.name.startsWith('.') && entry.name !== '.snow') { continue; } const fullRemotePath = current + '/' + entry.name; let relativePath = fullRemotePath.substring( sshInfo.path.length, ); if (!relativePath.startsWith('/')) { relativePath = '/' + relativePath; } relativePath = '.' + relativePath; pushFile({ name: entry.name, path: relativePath, isDirectory: entry.isDirectory, sourceDir: dirPath, }); if (entry.isDirectory) { if (node.depth < searchDepth) { queue.push({path: fullRemotePath, depth: node.depth + 1}); } else { depthLimitHit = true; } } } await yieldToEventLoop(); } sshClient.disconnect(); } catch { // SSH connection failed, skip this directory } continue; } // Handle local directories const localDirName = path.basename(dirPath) || dirPath; pushFile({ name: localDirName, path: dirPath, isDirectory: true, sourceDir: dirPath, }); // Read .gitignore patterns for this directory (only ignore source) const gitignorePath = path.join(dirPath, '.gitignore'); let gitignorePatterns: string[] = []; try { const content = await fs.promises.readFile(gitignorePath, 'utf-8'); gitignorePatterns = content .split('\n') .map(line => line.trim()) .filter(line => line && !line.startsWith('#')) .map(line => line.replace(/\/$/, '')); } catch { // No .gitignore or read error } // BFS so the first results come from shallow, broadly useful directories. const queue: Array<{path: string; depth: number}> = [ {path: dirPath, depth: 0}, ]; while (queue.length > 0) { const node = queue.shift() as {path: string; depth: number}; const current = node.path; let entries: import('fs').Dirent[] = []; try { entries = await fs.promises.readdir(current, { withFileTypes: true, }); } catch { continue; } for (const entry of entries) { if ( (entry.name.startsWith('.') && entry.name !== '.snow') || gitignorePatterns.includes(entry.name) ) { continue; } const fullPath = path.join(current, entry.name); // Skip files larger than 10MB to keep memory usage bounded try { const stats = await fs.promises.stat(fullPath); if (!entry.isDirectory() && stats.size > 10 * 1024 * 1024) { continue; } } catch { continue; } let relativePath = path .relative(dirPath, fullPath) .replace(/\\/g, '/'); if ( !relativePath.startsWith('.') && !path.isAbsolute(relativePath) ) { relativePath = './' + relativePath; } pushFile({ name: entry.name, path: relativePath, isDirectory: entry.isDirectory(), sourceDir: dirPath, }); if (entry.isDirectory()) { if (node.depth < searchDepth) { queue.push({path: fullPath, depth: node.depth + 1}); } else { depthLimitHit = true; } } } // Cooperative yield: let React render and the user keep typing. await yieldToEventLoop(); } } flush(true); setHasMoreDepth(depthLimitHit); setIsLoading(false); }, [searchDepth]); // Search file content for content search mode const searchFileContent = useCallback( async (query: string): Promise => { if (!query.trim()) { return []; } const results: FileItem[] = []; const queryLower = query.toLowerCase(); const maxResults = 100; // Limit results for performance // Search all non-directory files; binary/encoding errors are caught // in the readFile try/catch below, and >10MB files are already skipped // during directory scan. const filesToSearch = files.filter(f => !f.isDirectory); // Process files in batches to avoid blocking const batchSize = 10; for ( let batchStart = 0; batchStart < filesToSearch.length; batchStart += batchSize ) { if (results.length >= maxResults) { break; } const batch = filesToSearch.slice( batchStart, batchStart + batchSize, ); // Process batch files concurrently but with limit const batchPromises = batch.map(async file => { const fileResults: FileItem[] = []; try { // Use sourceDir if available, otherwise fallback to rootPath const baseDir = file.sourceDir || rootPath; const fullPath = path.join(baseDir, file.path); const content = await fs.promises.readFile(fullPath, 'utf-8'); const lines = content.split('\n'); // Search each line for the query for (let i = 0; i < lines.length; i++) { if (fileResults.length >= 10) { // Max 10 results per file break; } const line = lines[i]; if (line && line.toLowerCase().includes(queryLower)) { const maxLineLength = Math.max(40, terminalWidth - 10); fileResults.push({ name: file.name, path: file.path, isDirectory: false, lineNumber: i + 1, lineContent: line.trim().slice(0, maxLineLength), sourceDir: file.sourceDir, // Preserve source directory }); } } } catch (error) { // Skip files that can't be read (binary or encoding issues) } return fileResults; }); // Wait for batch to complete const batchResults = await Promise.all(batchPromises); // Flatten and add to results for (const fileResults of batchResults) { if (results.length >= maxResults) { break; } results.push( ...fileResults.slice(0, maxResults - results.length), ); } } return results; }, [files, rootPath, terminalWidth], ); // Load files when component becomes visible // This ensures the file list is always fresh without complex file watching useEffect(() => { if (!visible) { return; } // Always reload when becoming visible to ensure fresh data loadFiles(); }, [visible, rootPath, loadFiles]); // State for filtered files (needed for async content search) const [allFilteredFiles, setAllFilteredFiles] = useState([]); // Release cached results after the panel has been hidden for // SEARCH_RESULT_TTL_MS. Toggling visible cancels the pending timer so // quick close/reopen reuses the cache; only a sustained close evicts it. useEffect(() => { if (visible) { return; } const timer = setTimeout(() => { setFiles([]); setAllFilteredFiles([]); // Reset depth state so the next open starts shallow again. setSearchDepth(2); setHasMoreDepth(true); }, SEARCH_RESULT_TTL_MS); return () => clearTimeout(timer); }, [visible]); // Filter files based on query and search mode with debounce useEffect(() => { const performSearch = async () => { if (!query.trim()) { setAllFilteredFiles(files); return; } if (searchMode === 'content') { // Content search mode (@@) const results = await searchFileContent(query); setAllFilteredFiles(results); } else { // File name search mode (@) const queryLower = query.toLowerCase().replace(/\\/g, '/'); const filtered = files.filter(file => { const fileName = file.name.toLowerCase(); const filePath = file.path.toLowerCase().replace(/\\/g, '/'); // Also search in sourceDir for working directory entries const sourceDir = (file.sourceDir || '') .toLowerCase() .replace(/\\/g, '/'); const searchableFullPath = (() => { if ( file.path.startsWith('ssh://') || path.isAbsolute(file.path) ) { return filePath; } if ((file.sourceDir || '').startsWith('ssh://')) { const cleanBase = (file.sourceDir || '') .toLowerCase() .replace(/\/$/, ''); const cleanRelative = filePath .replace(/^\.\//, '') .replace(/^\//, ''); return `${cleanBase}/${cleanRelative}`; } if (file.sourceDir) { return path .join(file.sourceDir, file.path) .toLowerCase() .replace(/\\/g, '/'); } return filePath; })(); return ( fileName.includes(queryLower) || filePath.includes(queryLower) || sourceDir.includes(queryLower) || searchableFullPath.includes(queryLower) ); }); // Sort by relevance (exact name matches first, then path matches) filtered.sort((a, b) => { const aNameMatch = a.name.toLowerCase().startsWith(queryLower); const bNameMatch = b.name.toLowerCase().startsWith(queryLower); if (aNameMatch && !bNameMatch) return -1; if (!aNameMatch && bNameMatch) return 1; return a.name.localeCompare(b.name); }); setAllFilteredFiles(filtered); // Progressive depth: when the user has typed something but no // match is found in the currently loaded set, expand the scan // depth so a follow-up scan can pick up files deeper in the tree. // Only trigger when not already scanning, otherwise we would // thrash setSearchDepth while the previous scan is in flight. if ( !isLoading && filtered.length === 0 && query.trim().length > 0 && hasMoreDepth ) { setSearchDepth(d => d + 3); setIsIncreasingDepth(true); setTimeout(() => setIsIncreasingDepth(false), 400); } } }; // Debounce search to avoid excessive updates during fast typing // Use shorter delay for file search (150ms) and longer for content search (500ms) const debounceDelay = searchMode === 'content' ? 500 : 150; const timer = setTimeout(() => { performSearch(); }, debounceDelay); return () => clearTimeout(timer); }, [ files, query, searchMode, searchFileContent, isLoading, hasMoreDepth, ]); const displayItems = useMemo(() => { if (searchMode === 'content') { return allFilteredFiles.map(file => ({ file, key: getDisplayItemKey(file), label: file.lineNumber !== undefined ? `${file.path}:${file.lineNumber}` : file.path, depth: 0, })); } if (displayMode === 'tree') { return buildTreeDisplayItems(allFilteredFiles, files, query); } return allFilteredFiles.map(file => ({ file, key: getDisplayItemKey(file), label: file.path, depth: 0, })); }, [allFilteredFiles, files, displayMode, searchMode, query]); const normalizedSelectedIndex = useMemo(() => { if (displayItems.length === 0) { return 0; } return Math.min(selectedIndex, displayItems.length - 1); }, [displayItems.length, selectedIndex]); const fileWindow = useMemo(() => { if (displayItems.length <= effectiveMaxItems) { return { items: displayItems, startIndex: 0, endIndex: displayItems.length, }; } const halfWindow = Math.floor(effectiveMaxItems / 2); let startIndex = Math.max(0, normalizedSelectedIndex - halfWindow); let endIndex = Math.min( displayItems.length, startIndex + effectiveMaxItems, ); if (endIndex - startIndex < effectiveMaxItems) { startIndex = Math.max(0, endIndex - effectiveMaxItems); } return { items: displayItems.slice(startIndex, endIndex), startIndex, endIndex, }; }, [displayItems, normalizedSelectedIndex, effectiveMaxItems]); const filteredFiles = fileWindow.items; const hiddenAboveCount = fileWindow.startIndex; const hiddenBelowCount = Math.max( 0, displayItems.length - fileWindow.endIndex, ); useEffect(() => { if (onFilteredCountChange) { onFilteredCountChange(displayItems.length); } }, [displayItems.length, onFilteredCountChange]); useImperativeHandle( ref, () => ({ getSelectedFile: () => { const selectedEntry = displayItems[normalizedSelectedIndex]; if (!selectedEntry) { return null; } const fullPath = getFullFilePath(selectedEntry.file, rootPath); if (selectedEntry.file.isDirectory && searchMode === 'file') { const normalizedDirectoryPath = fullPath.replace(/\\/g, '/'); return normalizedDirectoryPath.endsWith('/') ? normalizedDirectoryPath : `${normalizedDirectoryPath}/`; } if (selectedEntry.file.lineNumber !== undefined) { return `${fullPath}:${selectedEntry.file.lineNumber}`; } return fullPath; }, toggleDisplayMode: () => { if (searchMode !== 'file') { return false; } const newMode = displayMode === 'list' ? 'tree' : 'list'; setDisplayMode(newMode); setFileListDisplayMode(newMode); return true; }, triggerDeeperSearch: () => { // Only meaningful for the file-name picker; content search reads // from the already-loaded file index. if (searchMode !== 'file') { return false; } // No deeper directories left to scan, or a scan is already // in flight — nothing to do. if (!hasMoreDepth || isLoading || isIncreasingDepth) { return false; } setSearchDepth(d => d + 3); setIsIncreasingDepth(true); setTimeout(() => setIsIncreasingDepth(false), 400); return true; }, }), [ displayItems, normalizedSelectedIndex, rootPath, searchMode, hasMoreDepth, isLoading, isIncreasingDepth, ], ); const displaySelectedIndex = filteredFiles.length === 0 ? -1 : normalizedSelectedIndex - fileWindow.startIndex; const selectedFileFullPath = useMemo(() => { const selectedEntry = displayItems[normalizedSelectedIndex]; if (!selectedEntry) { return null; } return getFullFilePath(selectedEntry.file, rootPath); }, [displayItems, normalizedSelectedIndex, rootPath]); if (!visible) { return null; } // Treat "still searching" broadly: either a scan is in flight, or a // deeper rescan was just queued (isIncreasingDepth), or there are still // untouched deeper directories that the next query miss can expand into. // This prevents a brief "No files found" flash between depth bumps when // the new loadFiles call is still awaiting its first async tick. const stillSearching = isLoading || isIncreasingDepth || (query.trim().length > 0 && hasMoreDepth); if (stillSearching && displayItems.length === 0) { return ( {isIncreasingDepth || (query.trim().length > 0 && hasMoreDepth) ? t.fileList.searchingDeeper.replace( '{depth}', searchDepth.toString(), ) : t.fileList.loadingFiles} ); } if (displayItems.length === 0) { return ( {t.fileList.noFilesFound} ); } return ( {searchMode === 'content' ? t.fileList.contentSearchHeader : t.fileList.filesHeader.replace( '{mode}', displayMode === 'tree' ? t.fileList.treeMode : t.fileList.listMode, )}{' '} {displayItems.length > effectiveMaxItems && `(${normalizedSelectedIndex + 1}/${displayItems.length})`} {filteredFiles.map((item, index) => { const file = item.file; const isSelected = index === displaySelectedIndex; const isTreeMode = searchMode === 'file' && displayMode === 'tree'; const prefix = searchMode === 'content' ? '' : isTreeMode ? `${' '.repeat(item.depth)}${ item.isContextOnly ? '· ' : file.isDirectory ? '▽ ' : '• ' }` : file.isDirectory ? '◇ ' : '◆ '; const color = isSelected ? theme.colors.menuNormal : item.isContextOnly ? theme.colors.menuSecondary : file.isDirectory ? theme.colors.warning : 'white'; return ( {isSelected ? '❯ ' : ' '} {searchMode === 'content' ? item.label : `${prefix}${item.label}`} {searchMode === 'content' && file.lineContent && ( {' '} {file.lineContent} )} ); })} {displayItems.length > effectiveMaxItems && ( {t.commandPanel.scrollHint} {hiddenAboveCount > 0 && ( <> ·{' '} {t.commandPanel.moreAbove.replace( '{count}', hiddenAboveCount.toString(), )} )} {hiddenBelowCount > 0 && ( <> ·{' '} {t.commandPanel.moreBelow.replace( '{count}', hiddenBelowCount.toString(), )} )} )} {selectedFileFullPath && ( effectiveMaxItems ? 0 : 1}> {'⤷ ' + selectedFileFullPath} )} {isLoading && ( {isIncreasingDepth ? t.fileList.scanningDeeper .replace('{depth}', searchDepth.toString()) .replace('{count}', files.length.toString()) : t.fileList.scanning.replace( '{count}', files.length.toString(), )} )} {/* Surface a hint at the bottom whenever there are still deeper directories that have not been scanned, so the user knows they can press ↓ on the last item to dig deeper instead of assuming the list is exhaustive. */} {searchMode === 'file' && hasMoreDepth && !isLoading && !isIncreasingDepth && displayItems.length > 0 && ( {t.fileList.deeperSearchHint} )} ); }, ), ); FileList.displayName = 'FileList'; export default FileList; ================================================ FILE: source/ui/components/tools/FileRollbackConfirmation.tsx ================================================ import React, {useState, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import {useI18n} from '../../../i18n/I18nContext.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {vscodeConnection} from '../../../utils/ui/vscodeConnection.js'; import {hashBasedSnapshotManager} from '../../../utils/codebase/hashBasedSnapshot.js'; export type RollbackMode = 'conversation' | 'both' | 'files'; type Props = { fileCount: number; filePaths: string[]; notebookCount?: number; teamCount?: number; previewSessionId?: string; previewTargetMessageIndex?: number; terminalWidth: number; onConfirm: (mode: RollbackMode | null, selectedFiles?: string[]) => void; }; export default function FileRollbackConfirmation({ fileCount, filePaths, notebookCount, teamCount, previewSessionId, previewTargetMessageIndex, terminalWidth, onConfirm, }: Props) { const {t} = useI18n(); const {theme} = useTheme(); const colors = theme.colors; const [selectedIndex, setSelectedIndex] = useState(0); const [showFullList, setShowFullList] = useState(false); const [fileScrollIndex, setFileScrollIndex] = useState(0); const [selectedFiles, setSelectedFiles] = useState>( new Set(filePaths), ); // Default all selected const [highlightedFileIndex, setHighlightedFileIndex] = useState(0); const closePreviewDiff = () => { if (vscodeConnection.isConnected()) { vscodeConnection.closeDiff().catch(() => { // Silently ignore close errors }); } }; // Close diff when leaving file list mode, and also when component unmounts useEffect(() => { if (!showFullList) { closePreviewDiff(); } return () => { closePreviewDiff(); }; }, [showFullList]); // Show rollback preview diff when highlighted file changes in full list mode useEffect(() => { if (!showFullList || !filePaths[highlightedFileIndex]) { return; } const filePath = filePaths[highlightedFileIndex]; const sessionId = previewSessionId; const targetMessageIndex = previewTargetMessageIndex; // Use setTimeout to debounce and avoid flickering during rapid navigation const timeoutId = setTimeout(() => { // Ensure old diff is closed before opening a new one closePreviewDiff(); if (sessionId !== undefined && targetMessageIndex !== undefined) { hashBasedSnapshotManager .getRollbackPreviewForFile(sessionId, targetMessageIndex, filePath) .then(preview => vscodeConnection.showDiff( preview.absolutePath, preview.currentContent, preview.rollbackContent, 'Rollback Preview', ), ) .catch(() => { // Silently ignore diff preview errors }); return; } // Fallback to git diff when preview context is missing vscodeConnection.showGitDiff(filePath).catch(() => { // Silently ignore git diff errors }); }, 100); return () => { clearTimeout(timeoutId); closePreviewDiff(); }; }, [ highlightedFileIndex, showFullList, filePaths, previewSessionId, previewTargetMessageIndex, ]); const options: Array<{label: string; value: RollbackMode}> = [ {label: t.fileRollback.conversationAndFiles, value: 'both'}, {label: t.fileRollback.conversationOnly, value: 'conversation'}, {label: t.fileRollback.filesOnly, value: 'files'}, ]; useInput((input, key) => { // Tab - toggle full file list view if (key.tab) { // Leaving file list mode should close the diff if (showFullList) { closePreviewDiff(); } setShowFullList(prev => !prev); setFileScrollIndex(0); // Reset scroll when toggling setHighlightedFileIndex(0); // Reset highlight when toggling return; } // In full list mode, use up/down to navigate files, space to toggle selection if (showFullList) { const maxVisibleFiles = 10; const maxScroll = Math.max(0, filePaths.length - maxVisibleFiles); if (key.upArrow) { setHighlightedFileIndex(prev => { const newIndex = Math.max(0, prev - 1); // Adjust scroll if needed if (newIndex < fileScrollIndex) { setFileScrollIndex(newIndex); } return newIndex; }); return; } if (key.downArrow) { setHighlightedFileIndex(prev => { const newIndex = Math.min(filePaths.length - 1, prev + 1); // Adjust scroll if needed if (newIndex >= fileScrollIndex + maxVisibleFiles) { setFileScrollIndex( Math.min(maxScroll, newIndex - maxVisibleFiles + 1), ); } return newIndex; }); return; } // Space - toggle file selection if (input === ' ') { const file = filePaths[highlightedFileIndex]; if (file) { setSelectedFiles(prev => { const newSet = new Set(prev); if (newSet.has(file)) { newSet.delete(file); } else { newSet.add(file); } return newSet; }); } return; } // Enter - confirm selection (when in file selection mode) if (key.return) { const selectedFilesArray = Array.from(selectedFiles); if (selectedFilesArray.length === 0) { onConfirm('conversation'); } else if (selectedFilesArray.length === filePaths.length) { onConfirm('both'); } else { onConfirm('both', selectedFilesArray); } return; } } else { // In compact mode, up/down navigate options if (key.upArrow) { setSelectedIndex(prev => Math.max(0, prev - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => Math.min(options.length - 1, prev + 1)); return; } // Enter - confirm selection (only when not in full list mode) if (key.return) { const mode = options[selectedIndex]?.value ?? 'conversation'; if (mode === 'both' || mode === 'files') { const selectedFilesArray = Array.from(selectedFiles); if (selectedFilesArray.length === filePaths.length) { onConfirm(mode); } else { onConfirm(mode, selectedFilesArray); } } else { onConfirm('conversation'); } return; } } // ESC - exit full list mode or cancel rollback if (key.escape) { if (showFullList) { closePreviewDiff(); setShowFullList(false); setFileScrollIndex(0); setHighlightedFileIndex(0); } else { closePreviewDiff(); onConfirm(null); // null means cancel everything } return; } }); // Display logic for file list const maxFilesToShowCompact = 5; const maxFilesToShowFull = 10; const displayFiles = showFullList ? filePaths.slice(fileScrollIndex, fileScrollIndex + maxFilesToShowFull) : filePaths.slice(0, maxFilesToShowCompact); const remainingCountCompact = fileCount - maxFilesToShowCompact; const hasMoreAbove = showFullList && fileScrollIndex > 0; const hasMoreBelow = showFullList && fileScrollIndex + maxFilesToShowFull < filePaths.length; const selectedCount = selectedFiles.size; // Check if there are any files to rollback const hasFiles = fileCount > 0; return ( {/* Top border separator */} {'─'.repeat(terminalWidth - 2)} ⚠ {t.fileRollback.title} {/* No files mode - simple confirmation */} {!hasFiles && ( <> {t.fileRollback.noFilesConfirm} {t.fileRollback.noFilesConfirmHint} )} {/* Has files mode - full file rollback UI */} {hasFiles && ( <> {showFullList ? t.fileRollback.filesCountWithSelection .replace('{count}', String(fileCount)) .replace('{selected}', String(selectedCount)) .replace('{total}', String(fileCount)) : t.fileRollback.filesCount.replace( '{count}', String(fileCount), )} : {/* File list */} {hasMoreAbove && ( {fileScrollIndex} {t.fileRollback.moreAbove} )} {displayFiles.map((file, index) => { const actualIndex = showFullList ? fileScrollIndex + index : index; const isSelected = selectedFiles.has(file); const isHighlighted = showFullList && actualIndex === highlightedFileIndex; return ( {showFullList ? (isSelected ? '[x] ' : '[ ] ') : '• '} {file} ); })} {hasMoreBelow && ( {filePaths.length - (fileScrollIndex + maxFilesToShowFull)}{' '} {t.fileRollback.moreBelow} )} {!showFullList && remainingCountCompact > 0 && ( ... {t.fileRollback.andMoreFiles} {remainingCountCompact} more file {remainingCountCompact > 1 ? 's' : ''} )} {/* Notebook rollback info */} {notebookCount !== undefined && notebookCount > 0 && ( {t.fileRollback.notebookCount.replace( '{count}', String(notebookCount), )} )} {/* Team cleanup info */} {teamCount !== undefined && teamCount > 0 && ( ⚑{' '} {t.fileRollback.teamCount.replace( '{count}', String(teamCount), )} )} {!showFullList && ( <> {t.fileRollback.question} {options.map((option, index) => ( {index === selectedIndex ? '❯ ' : ' '} {option.label} ))} )} {showFullList ? `${t.fileRollback.navigateHint} · ${t.fileRollback.toggleHint} · ${t.fileRollback.confirmHint} · ${t.fileRollback.backHint}` : `${t.fileRollback.selectHint} · ${t.fileRollback.viewAllHint} · ${t.fileRollback.confirmHint} · ${t.fileRollback.cancelHint}`} )} ); } ================================================ FILE: source/ui/components/tools/ToolConfirmation.tsx ================================================ import React, {useState, useMemo, useEffect} from 'react'; import {Box, Text, useInput, useStdout} from 'ink'; import TextInput from 'ink-text-input'; import SelectInput from 'ink-select-input'; import {isSensitiveCommand} from '../../../utils/execution/sensitiveCommandManager.js'; import {useTheme} from '../../contexts/ThemeContext.js'; import {useI18n} from '../../../i18n/index.js'; import {vscodeConnection} from '../../../utils/ui/vscodeConnection.js'; import {unifiedHooksExecutor} from '../../../utils/execution/unifiedHooksExecutor.js'; import {interpretHookResult} from '../../../utils/execution/hookResultInterpreter.js'; import type {HookErrorDetails} from '../../../utils/execution/hookResultInterpreter.js'; import fs from 'fs'; export type ConfirmationResult = | 'approve' | 'approve_always' | 'reject' | {type: 'reject_with_reply'; reason: string}; export interface ToolCall { id: string; type: 'function'; function: { name: string; arguments: string; }; } interface Props { toolName: string; toolArguments?: string; // JSON string of tool arguments allTools?: ToolCall[]; // All tools when confirming multiple tools in parallel onConfirm: (result: ConfirmationResult) => void; onHookError?: (error: HookErrorDetails) => void; // Hook error callback } // Helper function to format argument values with truncation function formatArgumentValue( value: any, maxLength: number = 100, noTruncate: boolean = false, ): string { if (value === null || value === undefined) { return String(value); } const stringValue = typeof value === 'string' ? value : JSON.stringify(value); // Skip truncation if noTruncate is true if (noTruncate || stringValue.length <= maxLength) { return stringValue; } return stringValue.substring(0, maxLength) + '...'; } // Helper function to convert parsed arguments to tree display format function formatArgumentsAsTree( args: Record, toolName?: string, ): Array<{key: string; value: string; isLast: boolean}> { // For filesystem-create and filesystem-edit, exclude content fields const excludeFields = new Set(); if (toolName === 'filesystem-create') { excludeFields.add('content'); } if (toolName === 'filesystem-edit') { excludeFields.add('content'); } if (toolName === 'filesystem-replaceedit') { excludeFields.add('searchContent'); excludeFields.add('replaceContent'); } // For ACE tools, exclude large result fields that may contain extensive code if (toolName?.startsWith('ace-')) { excludeFields.add('context'); // ACE tools may return large context strings excludeFields.add('signature'); // Function signatures can be verbose } // terminal-execute 的 command 默认也要截断，避免确认框过长。 // 需要查看完整命令时，由下方的“翻阅窗口(Tab)”提供分页浏览。 const keys = Object.keys(args).filter(key => !excludeFields.has(key)); return keys.map((key, index) => ({ key, value: formatArgumentValue(args[key], 100, false), isLast: index === keys.length - 1, })); } export default function ToolConfirmation({ toolName, toolArguments, allTools, onConfirm, onHookError, }: Props) { const {theme} = useTheme(); const {t} = useI18n(); const {stdout} = useStdout(); const [terminalColumns, setTerminalColumns] = useState( stdout?.columns ?? process.stdout.columns ?? 80, ); const [terminalRows, setTerminalRows] = useState( stdout?.rows ?? process.stdout.rows ?? 24, ); useEffect(() => { const nextColumns = stdout?.columns ?? process.stdout.columns; const nextRows = stdout?.rows ?? process.stdout.rows; if (typeof nextColumns === 'number') { setTerminalColumns(nextColumns); } if (typeof nextRows === 'number') { setTerminalRows(nextRows); } // Ink 的 stdout 通常是 TTY stream，resize 时更新终端尺寸。 const handler = () => { const cols = stdout?.columns ?? process.stdout.columns; const rows = stdout?.rows ?? process.stdout.rows; if (typeof cols === 'number') { setTerminalColumns(cols); } if (typeof rows === 'number') { setTerminalRows(rows); } }; stdout?.on?.('resize', handler); return () => { stdout?.off?.('resize', handler); }; }, [stdout]); const [hasSelected, setHasSelected] = useState(false); const [showRejectInput, setShowRejectInput] = useState(false); const [rejectReason, setRejectReason] = useState(''); const [menuKey, setMenuKey] = useState(0); const [initialMenuIndex, setInitialMenuIndex] = useState(0); // terminal-execute 命令翻阅窗口：固定高度分页，Tab 循环翻阅，不一次性完整显示。 const [commandPageOffset, setCommandPageOffset] = useState(0); // 多工具并行列表翻阅窗口：固定高度分页，Tab 循环翻阅，避免确认框因列表过高而抖动。 const [multiToolPageIndex, setMultiToolPageIndex] = useState(0); // Check if this is a sensitive command (for terminal-execute) const sensitiveCommandCheck = useMemo(() => { if (toolName !== 'terminal-execute' || !toolArguments) { return {isSensitive: false}; } try { const parsed = JSON.parse(toolArguments); const command = parsed.command; if (command && typeof command === 'string') { return isSensitiveCommand(command); } } catch { // Ignore parse errors } return {isSensitive: false}; }, [toolName, toolArguments]); // Parse and format tool arguments for display (single tool) const formattedArgs = useMemo(() => { if (!toolArguments) return null; try { const parsed = JSON.parse(toolArguments); return formatArgumentsAsTree(parsed, toolName); } catch { return null; } }, [toolArguments, toolName]); // 仅 terminal-execute 展示命令翻阅窗口 const terminalCommand = useMemo(() => { if (toolName !== 'terminal-execute' || !toolArguments) { return null; } try { const parsed = JSON.parse(toolArguments); const command = parsed.command; return typeof command === 'string' ? command : null; } catch { return null; } }, [toolName, toolArguments]); useEffect(() => { // 切换到新命令时重置翻阅位置 setCommandPageOffset(0); }, [terminalCommand]); const commandPager = useMemo(() => { if (!terminalCommand) return null; const maxLines = 3; const reserved = 24; const lineWidth = Math.max(20, terminalColumns - reserved); const windowChars = lineWidth * maxLines; const totalPages = Math.max( 1, Math.ceil(terminalCommand.length / windowChars), ); const normalizedOffset = totalPages <= 1 ? 0 : ((commandPageOffset % (totalPages * windowChars)) + totalPages * windowChars) % (totalPages * windowChars); const slice = terminalCommand.slice( normalizedOffset, normalizedOffset + windowChars, ); const lines: string[] = []; for (let i = 0; i < maxLines; i++) { lines.push(slice.slice(i * lineWidth, (i + 1) * lineWidth)); } return { lines, maxLines, lineWidth, windowChars, totalPages, pageIndex: Math.floor(normalizedOffset / windowChars) + 1, canPage: totalPages > 1, }; }, [terminalCommand, commandPageOffset, terminalColumns]); // Trigger toolConfirmation Hook when component mounts useEffect(() => { const context = { toolName, args: toolArguments, isSensitive: sensitiveCommandCheck.isSensitive, allTools: allTools?.map(t => ({ name: t.function.name, arguments: t.function.arguments, })), }; // Execute hook and handle exit code unifiedHooksExecutor .executeHooks('toolConfirmation', context) .then(hookResult => { const interpreted = interpretHookResult('toolConfirmation', hookResult); if (interpreted.action === 'warn' && interpreted.warningMessage) { console.warn(interpreted.warningMessage); } else if (interpreted.action === 'block' && interpreted.errorDetails) { if (onHookError) { onHookError(interpreted.errorDetails); } setHasSelected(true); onConfirm('reject'); } }) .catch(error => { console.error('Failed to execute toolConfirmation hook:', error); }); }, [toolName, toolArguments, sensitiveCommandCheck.isSensitive, allTools]); useEffect(() => { // Only show diff for filesystem operations and when VSCode is connected if (!vscodeConnection.isConnected()) { return; } const computeHashlinePreview = ( originalContent: string, operations: any[], ): string => { if (!Array.isArray(operations) || operations.length === 0) { return originalContent; } const mutableLines = originalContent.split('\n'); const parsed = operations .map((op: any) => { const startMatch = String(op.startAnchor ?? '').match(/^(\d+):/); const endMatch = String(op.endAnchor ?? '').match(/^(\d+):/); return { type: op.type as string, content: (op.content ?? '') as string, startLine: startMatch ? parseInt(startMatch[1]!, 10) : 0, endLine: endMatch ? parseInt(endMatch[1]!, 10) : 0, }; }) .filter(op => op.startLine > 0 && op.endLine > 0) .sort((a, b) => b.startLine - a.startLine); for (const op of parsed) { const newLines = op.content.split('\n'); switch (op.type) { case 'replace': mutableLines.splice( op.startLine - 1, op.endLine - op.startLine + 1, ...newLines, ); break; case 'insert_after': mutableLines.splice(op.startLine, 0, ...newLines); break; case 'delete': mutableLines.splice( op.startLine - 1, op.endLine - op.startLine + 1, ); break; } } return mutableLines.join('\n'); }; const computeReplaceEditPreview = ( originalContent: string, searchContent: string, replaceContent: string, ): string => { const idx = originalContent.indexOf(searchContent); if (idx !== -1) { return ( originalContent.substring(0, idx) + replaceContent + originalContent.substring(idx + searchContent.length) ); } return originalContent; }; // Helper: collect diff entries for a single tool (supports batch filePath arrays) type DiffEntry = { filePath: string; originalContent: string; newContent: string; label: string; }; const readOriginal = (filePath: string): string | null => { try { if (!filePath || !fs.existsSync(filePath)) return null; return fs.readFileSync(filePath, 'utf-8'); } catch { return null; } }; const collectHashlineEntries = ( filePath: string, operations: any[], label: string, ): DiffEntry | null => { const originalContent = readOriginal(filePath); if (originalContent === null) return null; const newContent = computeHashlinePreview(originalContent, operations); return {filePath, originalContent, newContent, label}; }; const collectReplaceEntry = ( filePath: string, searchContent: string | undefined, replaceContent: string | undefined, label: string, ): DiffEntry | null => { const originalContent = readOriginal(filePath); if (originalContent === null) return null; const newContent = searchContent && replaceContent !== undefined ? computeReplaceEditPreview( originalContent, searchContent, replaceContent, ) : originalContent; return {filePath, originalContent, newContent, label}; }; const collectDiffsForTool = (name: string, args: string): DiffEntry[] => { const entries: DiffEntry[] = []; try { const parsed = JSON.parse(args); if (name === 'filesystem-edit' && parsed.filePath) { if (typeof parsed.filePath === 'string') { const e = collectHashlineEntries( parsed.filePath, parsed.operations, 'Hashline Edit', ); if (e) entries.push(e); } else if (Array.isArray(parsed.filePath)) { // Batch: array of {path, operations} for (const item of parsed.filePath) { if ( item && typeof item === 'object' && typeof item.path === 'string' ) { const e = collectHashlineEntries( item.path, item.operations, 'Hashline Edit', ); if (e) entries.push(e); } } } } if (name === 'filesystem-replaceedit' && parsed.filePath) { if (typeof parsed.filePath === 'string') { const e = collectReplaceEntry( parsed.filePath, parsed.searchContent, parsed.replaceContent, 'Replace Edit', ); if (e) entries.push(e); } else if (Array.isArray(parsed.filePath)) { // Batch: string[] (uses top-level search/replace) or array of {path, searchContent, replaceContent} for (const item of parsed.filePath) { if (typeof item === 'string') { const e = collectReplaceEntry( item, parsed.searchContent, parsed.replaceContent, 'Replace Edit', ); if (e) entries.push(e); } else if ( item && typeof item === 'object' && typeof item.path === 'string' ) { const e = collectReplaceEntry( item.path, item.searchContent ?? parsed.searchContent, item.replaceContent ?? parsed.replaceContent, 'Replace Edit', ); if (e) entries.push(e); } } } } // Handle filesystem-create if (name === 'filesystem-create' && parsed.filePath && parsed.content) { const filePath = parsed.filePath; if (typeof filePath === 'string') { const originalContent = readOriginal(filePath) ?? ''; entries.push({ filePath, originalContent, newContent: parsed.content, label: 'Create', }); } } } catch { // Ignore parse errors } return entries; }; const dispatchDiffs = (entries: DiffEntry[]) => { if (entries.length === 0) return; if (entries.length === 1) { const e = entries[0]!; vscodeConnection .showDiff(e.filePath, e.originalContent, e.newContent, e.label) .catch(() => {}); return; } // Multi-file: use showDiffReview to display all diffs at once vscodeConnection .showDiffReview( entries.map(e => ({ filePath: e.filePath, originalContent: e.originalContent, newContent: e.newContent, })), ) .catch(() => {}); }; // Handle parallel tools if (allTools && allTools.length > 0) { const allEntries = allTools.flatMap(tool => collectDiffsForTool(tool.function.name, tool.function.arguments), ); dispatchDiffs(allEntries); } else if (toolArguments) { const entries = collectDiffsForTool(toolName, toolArguments); dispatchDiffs(entries); } // Cleanup: close diff when component unmounts return () => { if (vscodeConnection.isConnected()) { vscodeConnection.closeDiff().catch(() => { // Silently fail if close fails }); } }; }, [toolName, toolArguments, allTools]); // Parse and format all tools arguments for display (multiple tools) const formattedAllTools = useMemo; estimatedRows: number; }> | null>(() => { if (!allTools || allTools.length === 0) return null; return allTools.map(tool => { try { const parsed = JSON.parse(tool.function.arguments); const args = formatArgumentsAsTree(parsed, tool.function.name); return { name: tool.function.name, args, estimatedRows: 1 + args.length + 1, }; } catch { return { name: tool.function.name, args: [], estimatedRows: 2, }; } }); }, [allTools]); useEffect(() => { setMultiToolPageIndex(0); }, [formattedAllTools]); const multiToolPager = useMemo<{ pageSize: number; totalPages: number; pageIndex: number; pageStartIndex: number; tools: Array<{ name: string; args: Array<{key: string; value: string; isLast: boolean}>; estimatedRows: number; }>; canPage: boolean; } | null>(() => { if (!formattedAllTools || formattedAllTools.length === 0) { return null; } const reservedRows = 25; const availableRows = Math.max(4, terminalRows - reservedRows); const pages: Array = []; let currentPage: typeof formattedAllTools = []; let currentRows = 0; for (const tool of formattedAllTools) { const toolRows = Math.max(2, tool.estimatedRows); const wouldOverflow = currentPage.length > 0 && currentRows + toolRows > availableRows; if (wouldOverflow) { pages.push(currentPage); currentPage = []; currentRows = 0; } currentPage.push(tool); currentRows += toolRows; } if (currentPage.length > 0) { pages.push(currentPage); } const totalPages = Math.max(1, pages.length); const normalizedPageIndex = totalPages <= 1 ? 0 : ((multiToolPageIndex % totalPages) + totalPages) % totalPages; const currentTools = pages[normalizedPageIndex] ?? []; const pageStartIndex = pages .slice(0, normalizedPageIndex) .reduce((sum, page) => sum + page.length, 0); return { pageSize: currentTools.length, totalPages, pageIndex: normalizedPageIndex + 1, pageStartIndex, tools: currentTools, canPage: totalPages > 1, }; }, [formattedAllTools, multiToolPageIndex, terminalRows]); // Conditionally show "Always approve" based on sensitive command check const items = useMemo(() => { const baseItems: Array<{label: string; value: string}> = [ { label: t.toolConfirmation.approveOnce, value: 'approve', }, ]; // Only show "Always approve" if NOT a sensitive command if (!sensitiveCommandCheck.isSensitive) { baseItems.push({ label: t.toolConfirmation.alwaysApprove, value: 'approve_always', }); } baseItems.push({ label: t.toolConfirmation.rejectWithReply, value: 'reject_with_reply', }); baseItems.push({ label: t.toolConfirmation.rejectEndSession, value: 'reject', }); return baseItems; }, [sensitiveCommandCheck.isSensitive, t]); useInput((_input, key) => { if (key.tab && !hasSelected && !showRejectInput) { // Tab - terminal-execute 命令翻阅（循环） if (toolName === 'terminal-execute' && commandPager?.canPage) { setCommandPageOffset(prev => prev + commandPager.windowChars); return; } // Tab - 多工具并行列表翻页（循环） if (multiToolPager?.canPage) { setMultiToolPageIndex(prev => prev + 1); return; } } // ESC - exit reject input mode if (showRejectInput && key.escape) { setShowRejectInput(false); setRejectReason(''); // Keep menu selection on "Reject with reply" after ESC const idx = items.findIndex(i => i.value === 'reject_with_reply'); setInitialMenuIndex(idx >= 0 ? idx : 0); setMenuKey(k => k + 1); } }); const handleSelect = (item: {label: string; value: string}) => { if (!hasSelected) { if (item.value === 'reject_with_reply') { setShowRejectInput(true); } else { setHasSelected(true); onConfirm(item.value as ConfirmationResult); } } }; const handleRejectReasonSubmit = () => { if (!hasSelected && rejectReason.trim()) { setHasSelected(true); onConfirm({type: 'reject_with_reply', reason: rejectReason.trim()}); } }; return ( {t.toolConfirmation.header} {/* Display single tool */} {!formattedAllTools ? ( <> {t.toolConfirmation.tool}{' '} {toolName} {/* Display sensitive command warning */} {sensitiveCommandCheck.isSensitive ? ( {t.toolConfirmation.sensitiveCommandDetected} {t.toolConfirmation.pattern} {sensitiveCommandCheck.matchedCommand?.pattern} {t.toolConfirmation.requiresConfirmation} ) : null} {/* Display tool arguments in tree format */} {toolName !== 'terminal-execute' && formattedArgs?.length ? ( {t.toolConfirmation.arguments} {formattedArgs.map((arg, index) => ( {arg.isLast ? '└─' : '├─'} {arg.key}:{' '} {arg.value} ))} ) : null} {/* terminal-execute: 命令翻阅窗口（固定高度，Tab 循环翻页） */} {toolName === 'terminal-execute' && commandPager ? ( {t.toolConfirmation.commandPagerTitle}{' '} {t.toolConfirmation.commandPagerStatus .replace('{page}', String(commandPager.pageIndex)) .replace('{total}', String(commandPager.totalPages))} {commandPager.lines.map((line, idx) => ( {line} ))} {commandPager.canPage ? ( {t.toolConfirmation.commandPagerHint} ) : null} ) : null} ) : null} {/* Display multiple tools */} {formattedAllTools && multiToolPager ? ( {t.toolConfirmation.tools}{' '} {t.toolConfirmation.toolsInParallel.replace( '{count}', formattedAllTools.length.toString(), )} {multiToolPager.tools.map((tool, toolIndex) => { const absoluteToolIndex = multiToolPager.pageStartIndex + toolIndex; return ( {absoluteToolIndex + 1}. {tool.name} {tool.args.length > 0 && ( {tool.args.map((arg, argIndex) => ( {arg.isLast ? '└─' : '├─'} {arg.key}:{' '} {arg.value} ))} )} ); })} {multiToolPager.canPage && ( {t.toolConfirmation.multiToolPagerHint .replace('{page}', String(multiToolPager.pageIndex)) .replace('{total}', String(multiToolPager.totalPages))} )} ) : null} {t.toolConfirmation.selectAction} {!hasSelected && !showRejectInput && ( )} {showRejectInput && !hasSelected ? ( {t.toolConfirmation.enterRejectionReason} > {t.toolConfirmation.pressEnterToSubmit} ) : null} {hasSelected && ( {t.toolConfirmation.confirmed} )} ); } ================================================ FILE: source/ui/components/tools/ToolResultPreview.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import {useTheme} from '../../contexts/ThemeContext.js'; import type {Theme} from '../../themes/index.js'; interface ToolResultPreviewProps { toolName: string; result: string; maxLines?: number; isSubAgentInternal?: boolean; // Whether this is a sub-agent internal tool } /** * Remove ANSI escape codes from text to prevent style leakage */ function removeAnsiCodes(text: string): string { return text.replace(/\x1b\[[0-9;]*m/g, ''); } /** * Display a compact preview of tool execution results * Shows a tree-like structure with limited content */ export default function ToolResultPreview({ toolName, result, maxLines = 5, isSubAgentInternal = false, }: ToolResultPreviewProps) { const {theme} = useTheme(); try { // Try to parse JSON result const data = JSON.parse(result); // Handle different tool types if (toolName.startsWith('subagent-')) { return renderSubAgentPreview(data, maxLines, theme); } else if (toolName === 'terminal-execute') { return renderTerminalExecutePreview( data, maxLines, isSubAgentInternal, theme, ); } else if (toolName === 'filesystem-read') { return renderReadPreview(data, isSubAgentInternal, theme); } else if (toolName === 'filesystem-create') { return renderCreatePreview(data, theme); } else if ( toolName === 'filesystem-edit' || toolName === 'filesystem-replaceedit' ) { return renderEditSearchPreview(data, theme); } else if (toolName === 'websearch-search') { return renderWebSearchPreview(data, maxLines, theme); } else if (toolName === 'websearch-fetch') { return renderWebFetchPreview(data, theme); } else if (toolName.startsWith('ace-')) { return renderACEPreview(toolName, data, maxLines, theme); } else if (toolName.startsWith('todo-')) { return renderTodoPreview(toolName, data, maxLines, theme); } else if (toolName === 'ide-get_diagnostics') { return renderIdeDiagnosticsPreview(data, theme); } else if (toolName === 'skill-execute') { // skill-execute returns a string message, no preview needed // (the skill content is displayed elsewhere) return null; } else { // Generic preview for unknown tools return renderGenericPreview(data, maxLines, theme); } } catch { // If not JSON or parsing fails, return null (no preview) return null; } } function renderSubAgentPreview(data: any, _maxLines: number, theme: Theme) { // Sub-agent results have format: { success: boolean, result: string } if (!data.result) return null; // 简洁显示子代理执行结果 const lines = data.result.split('\n').filter((line: string) => line.trim()); return ( └─ Sub-agent completed ({lines.length}{' '} {lines.length === 1 ? 'line' : 'lines'} output) ); } function renderTerminalExecutePreview( data: any, maxLines: number, isSubAgentInternal: boolean, theme: Theme, ) { const hasError = data.exitCode !== 0; const hasStdout = data.stdout && data.stdout.trim(); const hasStderr = data.stderr && data.stderr.trim(); const sliceLines = (text: string | undefined, limit: number) => { if (!text) return {lines: [] as string[], truncated: false}; const lines = text.split('\n'); if (lines.length <= limit) return {lines, truncated: false}; return {lines: lines.slice(0, limit), truncated: true}; }; // 对于子代理内部的 terminal-execute：需要展示可读的执行结果（stdout/stderr/exitCode） // 但要限制行数，避免刷屏 if (isSubAgentInternal) { const stdoutPreview = sliceLines(data.stdout, maxLines); const stderrPreview = sliceLines(data.stderr, maxLines); return ( {data.command && ( ├─ command: {data.command} )} ├─ exitCode: {data.exitCode} {hasStdout && ( ├─ stdout: {stdoutPreview.lines.map((line: string, idx: number) => ( {removeAnsiCodes(line)} ))} {stdoutPreview.truncated && ( … )} )} {hasStderr && ( └─ stderr: {stderrPreview.lines.map((line: string, idx: number) => ( {removeAnsiCodes(line)} ))} {stderrPreview.truncated && ( … )} )} ); } // Simplified display: only show full output when exitCode !== 0 const showFullOutput = hasError; if (!showFullOutput) { // Success case - show stdout directly if (!hasStdout) { return ( └─ ✓ Exit code: {data.exitCode} ); } return ( ├─ command: {data.command} ├─ exitCode: {data.exitCode} ✓ ├─ stdout: {data.stdout.split('\n').map((line: string, idx: number) => ( {removeAnsiCodes(line)} ))} └─ executedAt: {data.executedAt} ); } // Error case - show full details including stderr return ( {/* Command */} ├─ command: {data.command} {/* Exit code with color indication */} ├─ exitCode: {data.exitCode} FAILED {/* Stdout - show completely if present */} {hasStdout && ( ├─ stdout: {data.stdout.split('\n').map((line: string, idx: number) => ( {removeAnsiCodes(line)} ))} )} {/* Stderr - show completely with red color if present */} {hasStderr && ( ├─ stderr: {data.stderr.split('\n').map((line: string, idx: number) => ( {removeAnsiCodes(line)} ))} )} {/* Execution time if available */} {data.executedAt && ( └─ executedAt: {data.executedAt} )} ); } function renderReadPreview( data: any, isSubAgentInternal: boolean, theme: Theme, ) { if (!data.content) return null; // 简洁显示：只显示读取的行数信息 const lines = data.content.split('\n'); const readLineCount = lines.length; const totalLines = data.totalLines || readLineCount; // For sub-agent internal tools, show even more minimal info if (isSubAgentInternal) { return ( └─ Read {readLineCount} lines {totalLines > readLineCount ? ` of ${totalLines} total` : ''} ); } // 如果是读取部分行，显示范围 const rangeInfo = data.startLine && data.endLine ? ` (lines ${data.startLine}-${data.endLine})` : ''; return ( └─ Read {readLineCount} lines{rangeInfo} {totalLines > readLineCount ? ` of ${totalLines} total` : ''} ); } function renderACEPreview( _toolName: string, data: any, maxLines: number, theme: Theme, ) { // 聚合后的统一工具 ace-search 通过 result shape 推断子动作 const isObject = data && typeof data === 'object' && !Array.isArray(data); // text_search: 数组，元素含 content + line if ( Array.isArray(data) && data.length > 0 && data[0] && 'content' in data[0] && 'line' in data[0] ) { return ( └─ Found {data.length} {data.length === 1 ? 'match' : 'matches'} ); } // find_references: 数组，元素含 referenceType if ( Array.isArray(data) && data.length > 0 && data[0] && 'referenceType' in data[0] ) { return ( └─ Found {data.length}{' '} {data.length === 1 ? 'reference' : 'references'} ); } // file_outline: 数组（可空），元素含 name + type，但不含 referenceType / content if ( Array.isArray(data) && (data.length === 0 || (data[0] && 'name' in data[0] && 'type' in data[0] && !('referenceType' in data[0]) && !('content' in data[0]))) ) { if (data.length === 0) { return ( └─ No symbols in file ); } return ( └─ Found {data.length} {data.length === 1 ? 'symbol' : 'symbols'} in file ); } // semantic_search: 对象，含 symbols / references + totalResults if ( isObject && ('symbols' in data || 'references' in data) && 'totalResults' in data ) { const totalResults = (data.symbols?.length || 0) + (data.references?.length || 0); if (totalResults === 0) { return ( └─ No results found ); } return ( ├─ {data.symbols?.length || 0}{' '} {(data.symbols?.length || 0) === 1 ? 'symbol' : 'symbols'} └─ {data.references?.length || 0}{' '} {(data.references?.length || 0) === 1 ? 'reference' : 'references'} ); } // find_definition: 对象，含 name + filePath + line（且不是 semantic_search） if ( isObject && 'name' in data && 'filePath' in data && 'line' in data && !('totalResults' in data) ) { return ( └─ Found {data.type} {data.name} at {data.filePath}:{data.line} ); } // 空数组（text_search / find_references 无结果） if (Array.isArray(data) && data.length === 0) { return ( └─ No matches found ); } // Generic ACE tool preview return renderGenericPreview(data, maxLines, theme); } function renderCreatePreview(data: any, theme: Theme) { // Simple success message for create/write operations return ( └─ {data.message || data} ); } function renderEditSearchPreview(data: any, theme: Theme) { return ( {data.message && ( ├─ {data.message} )} {data.matchLocation && ( ├─ Match: lines {data.matchLocation.startLine}- {data.matchLocation.endLine} )} {data.totalLines && ( └─ Total lines: {data.totalLines} )} ); } function renderWebSearchPreview(data: any, _maxLines: number, theme: Theme) { if (!data.results || data.results.length === 0) { return ( └─ No results for "{data.query}" ); } return ( └─ Found {data.totalResults || data.results.length} results for " {data.query}" ); } function renderWebFetchPreview(data: any, theme: Theme) { const contentLength = data.textLength || data.content?.length || 0; return ( └─ Fetched {contentLength} characters from {data.title || 'page'} ); } function renderGenericPreview(data: any, maxLines: number, theme: Theme) { // Guard: if data is not an object (e.g., it's a string), skip preview // This prevents Object.entries from treating strings as character arrays if (typeof data !== 'object' || data === null) { return null; } // For unknown tool types, show first few properties const entries = Object.entries(data).slice(0, maxLines); if (entries.length === 0) return null; return ( {entries.map(([key, value], idx) => { const valueStr = typeof value === 'string' ? value.slice(0, 20) + (value.length > 20 ? '...' : '') : JSON.stringify(value).slice(0, 60); return ( {idx === entries.length - 1 ? '└─ ' : '├─ '} {key}: {valueStr} ); })} ); } function renderTodoPreview( _toolName: string, data: any, _maxLines: number, theme: Theme, ) { // Handle todo-manage (all actions return the same list JSON shape when applicable) // Debug: Check if data is actually the stringified result that needs parsing again // Some tools might return the result wrapped in content[0].text let todoData = data; // If data has content array (MCP format), extract the text if (data.content && Array.isArray(data.content) && data.content[0]?.text) { const textContent = data.content[0].text; // Skip parsing if it's a plain message string if ( textContent === 'No TODO list found' || textContent === 'TODO item not found' ) { return ( └─ {textContent} ); } // Try to parse JSON try { todoData = JSON.parse(textContent); } catch (e) { // If parsing fails, show the raw text return ( └─ {textContent} ); } } // Check if we have valid todo data if (!todoData.todos || !Array.isArray(todoData.todos)) { return ( └─ {todoData.message || 'No TODO list'} ); } // 只显示简洁的 TODO 状态提示，不显示完整的 TodoTree const totalTodos = todoData.todos.length; const completedTodos = todoData.todos.filter( (todo: any) => todo.status === 'completed', ).length; const pendingTodos = totalTodos - completedTodos; return ( └─ TODO: {pendingTodos} pending, {completedTodos} completed (total:{' '} {totalTodos}) ); } function renderIdeDiagnosticsPreview(data: any, theme: Theme) { // Handle ide-get_diagnostics result // Data format: { diagnostics: Diagnostic[], formatted: string, summary: string } if (!data.diagnostics || !Array.isArray(data.diagnostics)) { return ( └─ No diagnostics data ); } const diagnosticsCount = data.diagnostics.length; if (diagnosticsCount === 0) { return ( └─ No diagnostics found ); } // Count by severity const errorCount = data.diagnostics.filter( (d: any) => d.severity === 'error', ).length; const warningCount = data.diagnostics.filter( (d: any) => d.severity === 'warning', ).length; const infoCount = data.diagnostics.filter( (d: any) => d.severity === 'info', ).length; const hintCount = data.diagnostics.filter( (d: any) => d.severity === 'hint', ).length; return ( └─ Found {diagnosticsCount} diagnostic(s) {errorCount > 0 && ` (${errorCount} error${errorCount > 1 ? 's' : ''})`} {warningCount > 0 && ` (${warningCount} warning${warningCount > 1 ? 's' : ''})`} {infoCount > 0 && ` (${infoCount} info)`} {hintCount > 0 && ` (${hintCount} hint${hintCount > 1 ? 's' : ''})`} ); } ================================================ FILE: source/ui/contexts/ThemeContext.tsx ================================================ import React, { createContext, useContext, useState, useCallback, ReactNode, } from 'react'; import {ThemeType, themes, Theme, getCustomTheme} from '../themes/index.js'; import { getCurrentTheme, getDiffOpacity, setCurrentTheme, setDiffOpacity, } from '../../utils/config/themeConfig.js'; interface ThemeContextType { theme: Theme; themeType: ThemeType; diffOpacity: number; setThemeType: (type: ThemeType) => void; setDiffOpacity: (opacity: number) => void; refreshCustomTheme?: () => void; } export const ThemeContext = createContext( undefined, ); interface ThemeProviderProps { children: ReactNode; } export function ThemeProvider({children}: ThemeProviderProps) { const [themeType, setThemeTypeState] = useState(() => { // Load initial theme from config return getCurrentTheme(); }); const [diffOpacity, setDiffOpacityState] = useState(() => getDiffOpacity(), ); const [customThemeVersion, setCustomThemeVersion] = useState(0); const setThemeType = (type: ThemeType) => { setThemeTypeState(type); // Persist to config file setCurrentTheme(type); }; const handleSetDiffOpacity = (opacity: number) => { setDiffOpacityState(opacity); setDiffOpacity(opacity); }; const refreshCustomTheme = useCallback(() => { setCustomThemeVersion(v => v + 1); }, []); const getTheme = useCallback((): Theme => { if (themeType === 'custom') { // Force re-read custom theme when version changes void customThemeVersion; return getCustomTheme(); } return themes[themeType]; }, [themeType, customThemeVersion]); const baseTheme = getTheme(); const value: ThemeContextType = { theme: { ...baseTheme, colors: { ...baseTheme.colors, diffOpacity, }, }, themeType, diffOpacity, setThemeType, setDiffOpacity: handleSetDiffOpacity, refreshCustomTheme, }; return ( {children} ); } export function useTheme(): ThemeContextType { const context = useContext(ThemeContext); if (!context) { throw new Error('useTheme must be used within a ThemeProvider'); } return context; } ================================================ FILE: source/ui/pages/ChatScreen.tsx ================================================ import React, {useEffect, useRef} from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import {useI18n} from '../../i18n/I18nContext.js'; import {useTheme} from '../contexts/ThemeContext.js'; import ChatFooter from '../components/chat/ChatFooter.js'; import {getSnowConfig} from '../../utils/config/apiConfig.js'; import {getAllProfiles} from '../../utils/config/configManager.js'; import {useSessionSave} from '../../hooks/session/useSessionSave.js'; import {useToolConfirmation} from '../../hooks/conversation/useToolConfirmation.js'; import {useChatLogic} from '../../hooks/conversation/useChatLogic.js'; import {useVSCodeState} from '../../hooks/integration/useVSCodeState.js'; import {useSnapshotState} from '../../hooks/session/useSnapshotState.js'; import {useStreamingState} from '../../hooks/conversation/useStreamingState.js'; import {useCommandHandler} from '../../hooks/conversation/useCommandHandler.js'; import {useTerminalSize} from '../../hooks/ui/useTerminalSize.js'; import {useTerminalFocus} from '../../hooks/ui/useTerminalFocus.js'; import {useBashMode} from '../../hooks/input/useBashMode.js'; import {useTerminalExecutionState} from '../../hooks/execution/useTerminalExecutionState.js'; import {useSchedulerExecutionState} from '../../hooks/execution/useSchedulerExecutionState.js'; import {useBackgroundProcesses} from '../../hooks/execution/useBackgroundProcesses.js'; import {usePanelState} from '../../hooks/ui/usePanelState.js'; import {connectionManager} from '../../utils/connection/ConnectionManager.js'; import {updateGlobalTokenUsage} from '../../utils/connection/contextManager.js'; import {sessionManager} from '../../utils/session/sessionManager.js'; import ChatScreenConversationView from './chatScreen/ChatScreenConversationView.js'; import ChatScreenPanels from './chatScreen/ChatScreenPanels.js'; import {useBackgroundProcessSelection} from './chatScreen/useBackgroundProcessSelection.js'; import {useChatScreenCommands} from './chatScreen/useChatScreenCommands.js'; import {useChatScreenInputHandler} from './chatScreen/useChatScreenInputHandler.js'; import {useChatScreenLocalState} from './chatScreen/useChatScreenLocalState.js'; import {useChatScreenModes} from './chatScreen/useChatScreenModes.js'; import {useChatScreenSessionLifecycle} from './chatScreen/useChatScreenSessionLifecycle.js'; import {useCodebaseIndexing} from './chatScreen/useCodebaseIndexing.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; import {resetTerminal} from '../../utils/execution/terminal.js'; const MIN_TERMINAL_HEIGHT = 10; type Props = { autoResume?: boolean; resumeSessionId?: string; enableYolo?: boolean; enablePlan?: boolean; }; export default function ChatScreen({ autoResume, resumeSessionId, enableYolo, enablePlan, }: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.chatScreen.headerTitle}`); const {theme} = useTheme(); const {columns: terminalWidth, rows: terminalHeight} = useTerminalSize(); const workingDirectory = process.cwd(); const { messages, setMessages, isSaving, pendingMessages, setPendingMessages, pendingMessagesRef, userInterruptedRef, remountKey, setRemountKey, setCurrentContextPercentage, currentContextPercentageRef, isExecutingTerminalCommand, setIsExecutingTerminalCommand, customCommandExecution, setCustomCommandExecution, isCompressing, setIsCompressing, compressionError, setCompressionError, showPermissionsPanel, setShowPermissionsPanel, showSubAgentDepthPanel, setShowSubAgentDepthPanel, restoreInputContent, setRestoreInputContent, inputDraftContent, setInputDraftContent, bashSensitiveCommand, setBashSensitiveCommand, suppressLoadingIndicator, setSuppressLoadingIndicator, hookError, setHookError, pendingUserQuestion, setPendingUserQuestion, requestUserQuestion, compressionStatus, setCompressionStatus, isResumingSession, setIsResumingSession, btwPrompt, setBtwPrompt, } = useChatScreenLocalState(); const { yoloMode, setYoloMode, planMode, setPlanMode, vulnerabilityHuntingMode, setVulnerabilityHuntingMode, toolSearchDisabled, setToolSearchDisabled, hybridCompressEnabled, setHybridCompressEnabled, teamMode, setTeamMode, simpleMode, showThinking, } = useChatScreenModes({enableYolo, enablePlan}); const streamingState = useStreamingState(); const vscodeState = useVSCodeState(); const snapshotState = useSnapshotState(messages.length); const bashMode = useBashMode(); const terminalExecutionState = useTerminalExecutionState(); const schedulerExecutionState = useSchedulerExecutionState(); const backgroundProcesses = useBackgroundProcesses(); const panelState = usePanelState(); const {hasFocus} = useTerminalFocus(); const { selectedProcessIndex, setSelectedProcessIndex, sortedBackgroundProcesses, } = useBackgroundProcessSelection(backgroundProcesses.processes); const {saveMessage, clearSavedMessages, initializeFromSession} = useSessionSave(); const commandsLoaded = useChatScreenCommands(workingDirectory); const { codebaseIndexing, setCodebaseIndexing, codebaseProgress, setCodebaseProgress, watcherEnabled, setWatcherEnabled, fileUpdateNotification, setFileUpdateNotification, codebaseAgentRef, } = useCodebaseIndexing(workingDirectory); const { pendingToolConfirmation, alwaysApprovedTools, requestToolConfirmation, isToolAutoApproved, addMultipleToAlwaysApproved, removeFromAlwaysApproved, clearAllAlwaysApproved, } = useToolConfirmation(workingDirectory); const handleCommandExecutionRef = useRef< ((command: string, result: any) => void) | undefined >(undefined); useEffect(() => { connectionManager.setStreamingState(streamingState.streamStatus); }, [streamingState.streamStatus]); useChatScreenSessionLifecycle({ autoResume, resumeSessionId, terminalWidth, remountKey, setRemountKey, setMessages, initializeFromSession, setIsResumingSession, setContextUsage: streamingState.setContextUsage, }); const { handleMessageSubmit, processMessage, handleHistorySelect, handleRollbackConfirm, handleUserQuestionAnswer, handleSessionPanelSelect, handleQuit, handleReindexCodebase, handleToggleCodebase, handleReviewCommitConfirm, handleEscKey, } = useChatLogic({ messages, setMessages, pendingMessages, setPendingMessages, streamingState, vscodeState, snapshotState, bashMode, yoloMode, planMode, vulnerabilityHuntingMode, teamMode, toolSearchDisabled, saveMessage, clearSavedMessages, setRemountKey, requestToolConfirmation, requestUserQuestion, isToolAutoApproved, addMultipleToAlwaysApproved, setRestoreInputContent, isCompressing, setIsCompressing, setCompressionError, currentContextPercentageRef, userInterruptedRef, pendingMessagesRef, setBashSensitiveCommand, pendingUserQuestion, setPendingUserQuestion, initializeFromSession, setShowSessionPanel: panelState.setShowSessionPanel, setShowReviewCommitPanel: panelState.setShowReviewCommitPanel, codebaseAgentRef, setCodebaseIndexing, setCodebaseProgress, setFileUpdateNotification, setWatcherEnabled, exitingApplicationText: t.hooks.exitingApplication, commandsLoaded, terminalExecutionState, backgroundProcesses, schedulerExecutionState, panelState, setIsExecutingTerminalCommand, setHookError, hasFocus, setSuppressLoadingIndicator, bashSensitiveCommand, handleCommandExecution: (command, result) => { handleCommandExecutionRef.current?.(command, result); }, pendingToolConfirmation, onCompressionStatus: setCompressionStatus, setIsResumingSession, }); function handleSwitchProfile() { panelState.handleSwitchProfile({ isStreaming: streamingState.isStreaming, hasPendingRollback: !!snapshotState.pendingRollback, hasPendingToolConfirmation: !!pendingToolConfirmation, hasPendingUserQuestion: !!pendingUserQuestion, }); } const handleProfileSelect = panelState.handleProfileSelect; const {handleCommandExecution} = useCommandHandler({ messages, setMessages, setPendingMessages, streamStatus: streamingState.streamStatus, setRemountKey, clearSavedMessages, setIsCompressing, setCompressionError, setShowSessionPanel: panelState.setShowSessionPanel, onResumeSessionById: handleSessionPanelSelect, setShowMcpPanel: panelState.setShowMcpPanel, setShowHelpPanel: panelState.setShowHelpPanel, setShowUsagePanel: panelState.setShowUsagePanel, setShowModelsPanel: panelState.setShowModelsPanel, setShowSubAgentDepthPanel, setShowCustomCommandConfig: panelState.setShowCustomCommandConfig, setShowSkillsCreation: panelState.setShowSkillsCreation, setShowSkillsListPanel: panelState.setShowSkillsListPanel, setShowRoleCreation: panelState.setShowRoleCreation, setShowRoleDeletion: panelState.setShowRoleDeletion, setShowRoleList: panelState.setShowRoleList, setShowRoleSubagentCreation: panelState.setShowRoleSubagentCreation, setShowRoleSubagentDeletion: panelState.setShowRoleSubagentDeletion, setShowRoleSubagentList: panelState.setShowRoleSubagentList, setShowWorkingDirPanel: panelState.setShowWorkingDirPanel, setShowReviewCommitPanel: panelState.setShowReviewCommitPanel, setShowDiffReviewPanel: panelState.setShowDiffReviewPanel, setShowConnectionPanel: panelState.setShowConnectionPanel, setConnectionPanelApiUrl: panelState.setConnectionPanelApiUrl, setShowPermissionsPanel, setShowBranchPanel: panelState.setShowBranchPanel, setShowIdeSelectPanel: panelState.setShowIdeSelectPanel, setShowNewPromptPanel: panelState.setShowNewPromptPanel, setShowTodoListPanel: panelState.setShowTodoListPanel, setShowPixelEditor: panelState.setShowPixelEditor, onSwitchProfile: handleSwitchProfile, setShowBackgroundPanel: backgroundProcesses.enablePanel, setYoloMode, setPlanMode, setVulnerabilityHuntingMode, setToolSearchDisabled, setHybridCompressEnabled, setTeamMode, setContextUsage: streamingState.setContextUsage, setCurrentContextPercentage, currentContextPercentageRef, setVscodeConnectionStatus: vscodeState.setVscodeConnectionStatus, setIsExecutingTerminalCommand, setCustomCommandExecution, processMessage, setBtwPrompt, onQuit: handleQuit, onReindexCodebase: handleReindexCodebase, onToggleCodebase: handleToggleCodebase, onCompressionStatus: setCompressionStatus, }); useEffect(() => { handleCommandExecutionRef.current = handleCommandExecution; }, [handleCommandExecution]); useEffect(() => { if (streamingState.contextUsage) { updateGlobalTokenUsage({ prompt_tokens: streamingState.contextUsage.prompt_tokens || 0, completion_tokens: streamingState.contextUsage.completion_tokens || 0, total_tokens: streamingState.contextUsage.total_tokens || 0, cache_creation_input_tokens: streamingState.contextUsage.cache_creation_input_tokens, cache_read_input_tokens: streamingState.contextUsage.cache_read_input_tokens, cached_tokens: streamingState.contextUsage.cached_tokens, max_tokens: getSnowConfig().maxContextTokens || 128000, }); sessionManager.updateContextUsage(streamingState.contextUsage); } else { updateGlobalTokenUsage(null); } }, [streamingState.contextUsage]); useChatScreenInputHandler({ backgroundProcesses, sortedBackgroundProcesses, selectedProcessIndex, setSelectedProcessIndex, terminalExecutionState, pendingToolConfirmation, pendingUserQuestion, bashSensitiveCommand, setBashSensitiveCommand, hookError, setHookError, snapshotState, panelState, handleEscKey, btwPrompt, }); const getFilteredProfiles = () => { const allProfiles = getAllProfiles(); const query = panelState.profileSearchQuery.toLowerCase(); const currentName = panelState.currentProfileName; const profilesWithMemoryState = allProfiles.map(profile => ({ ...profile, isActive: profile.displayName === currentName, })); if (!query) { return profilesWithMemoryState; } return profilesWithMemoryState.filter( profile => profile.name.toLowerCase().includes(query) || profile.displayName.toLowerCase().includes(query), ); }; const hasBlockingPanel = panelState.showSessionPanel || panelState.showMcpPanel || panelState.showUsagePanel || panelState.showHelpPanel || panelState.showProfileEditPanel || panelState.showModelsPanel || panelState.showCustomCommandConfig || panelState.showSkillsCreation || panelState.showRoleCreation || panelState.showRoleDeletion || panelState.showRoleList || panelState.showRoleSubagentCreation || panelState.showRoleSubagentDeletion || panelState.showRoleSubagentList || panelState.showWorkingDirPanel || panelState.showBranchPanel || panelState.showConnectionPanel || panelState.showNewPromptPanel || panelState.showTodoListPanel || panelState.showPixelEditor || showPermissionsPanel || showSubAgentDepthPanel; const shouldShowFooter = !pendingToolConfirmation && !pendingUserQuestion && !bashSensitiveCommand && !terminalExecutionState.state.needsInput && !schedulerExecutionState.state.isRunning && !hasBlockingPanel && !snapshotState.pendingRollback; // 统一处理：任何会隐藏输入框的场景（面板打开、footer 隐藏等）， // 都需要清空 draftContent，避免面板关闭后 ChatInput 重新挂载时 // 通过 draftContent 把旧文本恢复回输入框。 useEffect(() => { if (!shouldShowFooter) { setInputDraftContent(null); } }, [shouldShowFooter, setInputDraftContent]); // remountKey 变化时清空 draftContent： // /resume、/clear、/compact、/branch 等指令通过 setRemountKey 触发 ChatInput 重挂载， // 但旧组件在销毁前来不及通过 onDraftChange 上报空文本，导致新组件从旧草稿恢复。 const remountKeyRef = useRef(remountKey); useEffect(() => { if (remountKey !== remountKeyRef.current) { remountKeyRef.current = remountKey; setInputDraftContent(null); } }, [remountKey, setInputDraftContent]); const footerContextUsage = streamingState.contextUsage ? { inputTokens: streamingState.contextUsage.prompt_tokens, maxContextTokens: getSnowConfig().maxContextTokens || 4000, cacheCreationTokens: streamingState.contextUsage.cache_creation_input_tokens, cacheReadTokens: streamingState.contextUsage.cache_read_input_tokens, cachedTokens: streamingState.contextUsage.cached_tokens, } : undefined; if (terminalHeight < MIN_TERMINAL_HEIGHT) { return ( {t.chatScreen.terminalTooSmall} {t.chatScreen.terminalResizePrompt .replace('{current}', terminalHeight.toString()) .replace('{required}', MIN_TERMINAL_HEIGHT.toString())} {t.chatScreen.terminalMinHeight} ); } if (!commandsLoaded || isResumingSession) { return ( {isResumingSession ? t.chatScreen.sessionLoading : t.chatScreen.chatInitializing} ); } return ( { setRestoreInputContent({text: prompt}); }} handleRollbackConfirm={handleRollbackConfirm} /> {shouldShowFooter && ( { vscodeState.setVscodeConnectionStatus(status); if (message) { const commandMessage = { role: 'command' as const, content: message, commandName: 'ide', }; setMessages(prev => [...prev, commandMessage]); } }} onIdeWorkingDirectoryChanged={() => { // Working directory changed via process.chdir(). // ChatHeader lives inside , so we must: // 1. Reset the terminal to clear stale Static output (incl. old cwd line). // 2. Bump remountKey to force to remount; the next render // will pick up the new process.cwd() in ChatHeader. resetTerminal(); setRemountKey(prev => prev + 1); }} btwPrompt={btwPrompt} onBtwClose={() => setBtwPrompt(null)} disabled={ !!pendingToolConfirmation || !!bashSensitiveCommand || isExecutingTerminalCommand || isCompressing || streamingState.isStopping } isStopping={streamingState.isStopping} isProcessing={ streamingState.isStreaming || isSaving || bashMode.state.isExecuting || isCompressing } chatHistory={messages} yoloMode={yoloMode} setYoloMode={setYoloMode} planMode={planMode} setPlanMode={setPlanMode} vulnerabilityHuntingMode={vulnerabilityHuntingMode} setVulnerabilityHuntingMode={setVulnerabilityHuntingMode} toolSearchDisabled={toolSearchDisabled} hybridCompressEnabled={hybridCompressEnabled} teamMode={teamMode} setTeamMode={setTeamMode} contextUsage={footerContextUsage} initialContent={restoreInputContent} draftContent={inputDraftContent} onDraftChange={setInputDraftContent} onContextPercentageChange={setCurrentContextPercentage} onInitialContentConsumed={() => setRestoreInputContent(null)} showProfilePicker={panelState.showProfilePanel} setShowProfilePicker={panelState.setShowProfilePanel} profileSelectedIndex={panelState.profileSelectedIndex} setProfileSelectedIndex={panelState.setProfileSelectedIndex} getFilteredProfiles={getFilteredProfiles} profileSearchQuery={panelState.profileSearchQuery} setProfileSearchQuery={panelState.setProfileSearchQuery} vscodeConnectionStatus={vscodeState.vscodeConnectionStatus} editorContext={vscodeState.editorContext} codebaseIndexing={codebaseIndexing} codebaseProgress={codebaseProgress} watcherEnabled={watcherEnabled} fileUpdateNotification={fileUpdateNotification} currentProfileName={panelState.currentProfileName} isCompressing={isCompressing} compressionError={compressionError} backgroundProcesses={backgroundProcesses.processes} showBackgroundPanel={backgroundProcesses.showPanel} selectedProcessIndex={selectedProcessIndex} terminalWidth={terminalWidth} // Loading indicator props isStreaming={streamingState.isStreaming} isSaving={isSaving} hasPendingToolConfirmation={!!pendingToolConfirmation} hasPendingUserQuestion={!!pendingUserQuestion} hasBlockingOverlay={ !!bashSensitiveCommand || suppressLoadingIndicator || (bashMode.state.isExecuting && !!bashMode.state.currentCommand) || (terminalExecutionState.state.isExecuting && !terminalExecutionState.state.isBackgrounded && !!terminalExecutionState.state.command) || (customCommandExecution?.isRunning ?? false) } animationFrame={streamingState.animationFrame} retryStatus={streamingState.retryStatus} codebaseSearchStatus={streamingState.codebaseSearchStatus} isReasoning={streamingState.isReasoning} streamTokenCount={streamingState.streamTokenCount} elapsedSeconds={streamingState.elapsedSeconds} currentModel={streamingState.currentModel} compressBlockToast={streamingState.compressBlockToast} /> )} ); } ================================================ FILE: source/ui/pages/CodeBaseConfigScreen.tsx ================================================ import React, {useState, useEffect, useCallback, useRef} from 'react'; import {Box, Text, useInput} from 'ink'; import Gradient from 'ink-gradient'; import {Alert} from '@inkjs/ui'; import TextInput from 'ink-text-input'; import ScrollableSelectInput from '../components/common/ScrollableSelectInput.js'; import { loadCodebaseConfig, saveCodebaseConfig, type CodebaseConfig, } from '../../utils/config/codebaseConfig.js'; import {useI18n} from '../../i18n/index.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; onSave?: () => void; inlineMode?: boolean; }; type ConfigField = | 'enabled' | 'enableAgentReview' | 'enableReranking' | 'embeddingSettings' | 'embeddingType' | 'embeddingModelName' | 'embeddingBaseUrl' | 'embeddingApiKey' | 'embeddingDimensions' | 'batchSettings' | 'batchMaxLines' | 'batchConcurrency' | 'chunkingMaxLinesPerChunk' | 'chunkingMinLinesPerChunk' | 'chunkingMinCharsPerChunk' | 'chunkingOverlapLines' | 'rerankingSettings' | 'rerankingModelName' | 'rerankingBaseUrl' | 'rerankingApiKey' | 'rerankingContextLength' | 'rerankingTopN'; const focusEventTokenRegex = /(?:\x1b)?\[[0-9;]*[IO]/g; const isFocusEventInput = (value?: string) => { if (!value) { return false; } if ( value === '\x1b[I' || value === '\x1b[O' || value === '[I' || value === '[O' ) { return true; } const trimmed = value.trim(); if (!trimmed) { return false; } const tokens = trimmed.match(focusEventTokenRegex); if (!tokens) { return false; } const normalized = trimmed.replace(/\s+/g, ''); const tokensCombined = tokens.join(''); return tokensCombined === normalized; }; const stripFocusArtifacts = (value: string) => { if (!value) { return ''; } return value .replace(/\x1b\[[0-9;]*[IO]/g, '') .replace(/\[[0-9;]*[IO]/g, '') .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, ''); }; export default function CodeBaseConfigScreen({ onBack, onSave, inlineMode = false, }: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.codebaseConfig.title}`); const {theme} = useTheme(); // Configuration state const [enabled, setEnabled] = useState(false); const [enableAgentReview, setEnableAgentReview] = useState(true); const [enableReranking, setEnableReranking] = useState(false); const [embeddingType, setEmbeddingType] = useState< 'jina' | 'ollama' | 'gemini' | 'mistral' >('jina'); const [embeddingModelName, setEmbeddingModelName] = useState(''); const [embeddingBaseUrl, setEmbeddingBaseUrl] = useState(''); const [embeddingApiKey, setEmbeddingApiKey] = useState(''); const [embeddingDimensions, setEmbeddingDimensions] = useState(1536); const [batchMaxLines, setBatchMaxLines] = useState(10); const [batchConcurrency, setBatchConcurrency] = useState(1); const [chunkingMaxLinesPerChunk, setChunkingMaxLinesPerChunk] = useState(200); const [chunkingMinLinesPerChunk, setChunkingMinLinesPerChunk] = useState(10); const [chunkingMinCharsPerChunk, setChunkingMinCharsPerChunk] = useState(20); const [chunkingOverlapLines, setChunkingOverlapLines] = useState(20); const [rerankingModelName, setRerankingModelName] = useState(''); const [rerankingBaseUrl, setRerankingBaseUrl] = useState(''); const [rerankingApiKey, setRerankingApiKey] = useState(''); const [rerankingContextLength, setRerankingContextLength] = useState(4096); const [rerankingTopN, setRerankingTopN] = useState(5); // UI state const [currentField, setCurrentField] = useState('enabled'); const [isEditing, setIsEditing] = useState(false); const [embeddingExpanded, setEmbeddingExpanded] = useState(false); const [batchExpanded, setBatchExpanded] = useState(false); const [rerankingExpanded, setRerankingExpanded] = useState(false); const [toastMessage, setToastMessage] = useState(''); const [errors, setErrors] = useState([]); // Scrolling configuration const MAX_VISIBLE_FIELDS = 8; const embeddingSubFields: ConfigField[] = [ 'embeddingType', 'embeddingModelName', 'embeddingBaseUrl', 'embeddingApiKey', 'embeddingDimensions', ]; const batchSubFields: ConfigField[] = [ 'batchMaxLines', 'batchConcurrency', 'chunkingMaxLinesPerChunk', 'chunkingMinLinesPerChunk', 'chunkingMinCharsPerChunk', 'chunkingOverlapLines', ]; const rerankingSubFields: ConfigField[] = [ 'rerankingModelName', 'rerankingBaseUrl', 'rerankingApiKey', 'rerankingContextLength', 'rerankingTopN', ]; const allFields: ConfigField[] = [ 'enabled', 'enableAgentReview', 'enableReranking', 'embeddingSettings', ...(embeddingExpanded ? embeddingSubFields : []), 'rerankingSettings', ...(rerankingExpanded ? rerankingSubFields : []), 'batchSettings', ...(batchExpanded ? batchSubFields : []), ]; // Embedding type options const embeddingTypeOptions = [ {label: 'Jina & OpenAI', value: 'jina' as const}, {label: 'Ollama', value: 'ollama' as const}, {label: 'Gemini', value: 'gemini' as const}, {label: 'Mistral', value: 'mistral' as const}, ]; const currentFieldIndex = allFields.indexOf(currentField); const totalFields = allFields.length; const toastTimerRef = useRef | null>(null); const showToast = useCallback((msg: string) => { if (toastTimerRef.current) { clearTimeout(toastTimerRef.current); } setToastMessage(msg); toastTimerRef.current = setTimeout(() => { setToastMessage(''); toastTimerRef.current = null; }, 2000); }, []); useEffect(() => { loadConfiguration(); }, []); useEffect(() => { return () => { if (toastTimerRef.current) { clearTimeout(toastTimerRef.current); } }; }, []); const loadConfiguration = () => { const config = loadCodebaseConfig(); setEnabled(config.enabled); setEnableAgentReview(config.enableAgentReview); setEnableReranking(config.enableReranking); setEmbeddingType(config.embedding.type || 'jina'); setEmbeddingModelName(config.embedding.modelName); setEmbeddingBaseUrl(config.embedding.baseUrl); setEmbeddingApiKey(config.embedding.apiKey); setEmbeddingDimensions(config.embedding.dimensions); setBatchMaxLines(config.batch.maxLines); setBatchConcurrency(config.batch.concurrency); setChunkingMaxLinesPerChunk(config.chunking.maxLinesPerChunk); setChunkingMinLinesPerChunk(config.chunking.minLinesPerChunk); setChunkingMinCharsPerChunk(config.chunking.minCharsPerChunk); setChunkingOverlapLines(config.chunking.overlapLines); setRerankingModelName(config.reranking.modelName); setRerankingBaseUrl(config.reranking.baseUrl); setRerankingApiKey(config.reranking.apiKey); setRerankingContextLength(config.reranking.contextLength); setRerankingTopN(config.reranking.topN); }; const saveConfiguration = () => { // Validation const validationErrors: string[] = []; if (enabled) { // Embedding configuration is required if (!embeddingModelName.trim()) { validationErrors.push(t.codebaseConfig.validationModelNameRequired); } if (!embeddingBaseUrl.trim()) { validationErrors.push(t.codebaseConfig.validationBaseUrlRequired); // Embedding API key is optional (for local deployments like Ollama) // if (!embeddingApiKey.trim()) { // validationErrors.push('Embedding API key is required when enabled'); // } } if (embeddingDimensions <= 0) { validationErrors.push(t.codebaseConfig.validationDimensionsPositive); } // Batch configuration validation if (batchMaxLines <= 0) { validationErrors.push(t.codebaseConfig.validationMaxLinesPositive); } if (batchConcurrency <= 0) { validationErrors.push(t.codebaseConfig.validationConcurrencyPositive); } // Chunking configuration validation if (chunkingMaxLinesPerChunk <= 0) { validationErrors.push( t.codebaseConfig.validationMaxLinesPerChunkPositive, ); } if (chunkingMinLinesPerChunk <= 0) { validationErrors.push( t.codebaseConfig.validationMinLinesPerChunkPositive, ); } if (chunkingMinCharsPerChunk <= 0) { validationErrors.push( t.codebaseConfig.validationMinCharsPerChunkPositive, ); } if (chunkingOverlapLines < 0) { validationErrors.push( t.codebaseConfig.validationOverlapLinesNonNegative, ); } if (chunkingOverlapLines >= chunkingMaxLinesPerChunk) { validationErrors.push( t.codebaseConfig.validationOverlapLessThanMaxLines, ); } // Reranking configuration validation if (enableReranking) { if (!rerankingModelName.trim()) { validationErrors.push( t.codebaseConfig.validationRerankingModelNameRequired, ); } if (!rerankingBaseUrl.trim()) { validationErrors.push( t.codebaseConfig.validationRerankingBaseUrlRequired, ); } if (rerankingContextLength <= 0) { validationErrors.push( t.codebaseConfig.validationRerankingContextLengthPositive, ); } if (rerankingTopN <= 0) { validationErrors.push( t.codebaseConfig.validationRerankingTopNPositive, ); } } } if (validationErrors.length > 0) { setErrors(validationErrors); return; } try { const config: CodebaseConfig = { enabled, enableAgentReview, enableReranking, embedding: { type: embeddingType, modelName: embeddingModelName, baseUrl: embeddingBaseUrl, apiKey: embeddingApiKey, dimensions: embeddingDimensions, }, batch: { maxLines: batchMaxLines, concurrency: batchConcurrency, }, chunking: { maxLinesPerChunk: chunkingMaxLinesPerChunk, minLinesPerChunk: chunkingMinLinesPerChunk, minCharsPerChunk: chunkingMinCharsPerChunk, overlapLines: chunkingOverlapLines, }, reranking: { modelName: rerankingModelName, baseUrl: rerankingBaseUrl, apiKey: rerankingApiKey, contextLength: rerankingContextLength, topN: rerankingTopN, }, }; saveCodebaseConfig(config); setErrors([]); // Trigger codebase config reload in ChatScreen if ((global as any).__reloadCodebaseConfig) { (global as any).__reloadCodebaseConfig(); } onSave?.(); } catch (error) { setErrors([ error instanceof Error ? error.message : t.codebaseConfig.saveError, ]); } }; const renderField = (field: ConfigField) => { const isActive = field === currentField; const isCurrentlyEditing = isActive && isEditing; switch (field) { case 'enabled': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.codebaseEnabled} {enabled ? t.codebaseConfig.enabled : t.codebaseConfig.disabled}{' '} {t.codebaseConfig.toggleHint} ); case 'enableAgentReview': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.agentReview} {enableAgentReview ? t.codebaseConfig.enabled : t.codebaseConfig.disabled}{' '} {t.codebaseConfig.toggleHint} ); case 'enableReranking': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.rerankingToggle} {enableReranking ? t.codebaseConfig.enabled : t.codebaseConfig.disabled}{' '} {t.codebaseConfig.toggleHint} ); case 'embeddingSettings': return ( {isActive ? '❯ ' : ' '} {embeddingExpanded ? '▼ ' : '▶ '} {t.codebaseConfig.embeddingSettingsGroup} {t.codebaseConfig.embeddingSettingsExpandHint} ); case 'embeddingType': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.embeddingType} {isEditing && isActive ? ( opt.value === embeddingType, )} isFocused={true} onSelect={item => { setEmbeddingType( item.value as 'jina' | 'ollama' | 'gemini' | 'mistral', ); setIsEditing(false); }} /> ) : ( {embeddingTypeOptions.find(opt => opt.value === embeddingType) ?.label || t.codebaseConfig.notSet}{' '} {t.codebaseConfig.toggleHint} )} ); case 'embeddingModelName': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.embeddingModelName} {isCurrentlyEditing && ( setEmbeddingModelName(stripFocusArtifacts(value)) } onSubmit={() => setIsEditing(false)} /> )} {!isCurrentlyEditing && ( {embeddingModelName || t.codebaseConfig.notSet} )} ); case 'embeddingBaseUrl': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.embeddingBaseUrl} {isCurrentlyEditing && ( setEmbeddingBaseUrl(stripFocusArtifacts(value)) } onSubmit={() => setIsEditing(false)} /> )} {!isCurrentlyEditing && ( {embeddingBaseUrl || t.codebaseConfig.notSet} )} ); case 'embeddingApiKey': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.embeddingApiKeyOptional} {isCurrentlyEditing && ( setEmbeddingApiKey(stripFocusArtifacts(value)) } onSubmit={() => setIsEditing(false)} mask="*" /> )} {!isCurrentlyEditing && ( {embeddingApiKey ? t.codebaseConfig.masked : t.codebaseConfig.notSet} )} ); case 'embeddingDimensions': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.embeddingDimensions} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {embeddingDimensions} )} {!isCurrentlyEditing && ( {embeddingDimensions} )} ); case 'batchSettings': return ( {isActive ? '❯ ' : ' '} {batchExpanded ? '▼ ' : '▶ '} {t.codebaseConfig.batchSettingsGroup} {t.codebaseConfig.batchSettingsExpandHint} ); case 'batchMaxLines': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.batchMaxLines} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {batchMaxLines} )} {!isCurrentlyEditing && ( {batchMaxLines} )} ); case 'batchConcurrency': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.batchConcurrency} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {batchConcurrency} )} {!isCurrentlyEditing && ( {batchConcurrency} )} ); case 'chunkingMaxLinesPerChunk': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.chunkingMaxLinesPerChunk} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {chunkingMaxLinesPerChunk} )} {!isCurrentlyEditing && ( {chunkingMaxLinesPerChunk} )} ); case 'chunkingMinLinesPerChunk': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.chunkingMinLinesPerChunk} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {chunkingMinLinesPerChunk} )} {!isCurrentlyEditing && ( {chunkingMinLinesPerChunk} )} ); case 'chunkingMinCharsPerChunk': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.chunkingMinCharsPerChunk} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {chunkingMinCharsPerChunk} )} {!isCurrentlyEditing && ( {chunkingMinCharsPerChunk} )} ); case 'chunkingOverlapLines': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.chunkingOverlapLines} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {chunkingOverlapLines} )} {!isCurrentlyEditing && ( {chunkingOverlapLines} )} ); case 'rerankingSettings': return ( {isActive ? '❯ ' : ' '} {rerankingExpanded ? '▼ ' : '▶ '} {t.codebaseConfig.rerankingSettingsGroup} {t.codebaseConfig.rerankingSettingsExpandHint} ); case 'rerankingModelName': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.rerankingModelName} {isCurrentlyEditing && ( setRerankingModelName(stripFocusArtifacts(value)) } onSubmit={() => setIsEditing(false)} /> )} {!isCurrentlyEditing && ( {rerankingModelName || t.codebaseConfig.notSet} )} ); case 'rerankingBaseUrl': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.rerankingBaseUrl} {isCurrentlyEditing && ( setRerankingBaseUrl(stripFocusArtifacts(value)) } onSubmit={() => setIsEditing(false)} /> )} {!isCurrentlyEditing && ( {rerankingBaseUrl || t.codebaseConfig.notSet} )} ); case 'rerankingApiKey': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.rerankingApiKey} {isCurrentlyEditing && ( setRerankingApiKey(stripFocusArtifacts(value)) } onSubmit={() => setIsEditing(false)} mask="*" /> )} {!isCurrentlyEditing && ( {rerankingApiKey ? t.codebaseConfig.masked : t.codebaseConfig.notSet} )} ); case 'rerankingContextLength': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.rerankingContextLength} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {rerankingContextLength} )} {!isCurrentlyEditing && ( {rerankingContextLength} )} ); case 'rerankingTopN': return ( {isActive ? '❯ ' : ' '} {t.codebaseConfig.rerankingTopN} {isCurrentlyEditing && ( {t.codebaseConfig.enterValue} {rerankingTopN} )} {!isCurrentlyEditing && ( {rerankingTopN} )} ); default: return null; } }; // Define numeric fields const numericFields: ConfigField[] = [ 'embeddingDimensions', 'batchMaxLines', 'batchConcurrency', 'chunkingMaxLinesPerChunk', 'chunkingMinLinesPerChunk', 'chunkingMinCharsPerChunk', 'chunkingOverlapLines', 'rerankingContextLength', 'rerankingTopN', ]; const isNumericField = (field: ConfigField) => numericFields.includes(field); const getNumericValue = (field: ConfigField): number => { switch (field) { case 'embeddingDimensions': return embeddingDimensions; case 'batchMaxLines': return batchMaxLines; case 'batchConcurrency': return batchConcurrency; case 'chunkingMaxLinesPerChunk': return chunkingMaxLinesPerChunk; case 'chunkingMinLinesPerChunk': return chunkingMinLinesPerChunk; case 'chunkingMinCharsPerChunk': return chunkingMinCharsPerChunk; case 'chunkingOverlapLines': return chunkingOverlapLines; case 'rerankingContextLength': return rerankingContextLength; case 'rerankingTopN': return rerankingTopN; default: return 0; } }; const setNumericValue = (field: ConfigField, value: number) => { switch (field) { case 'embeddingDimensions': setEmbeddingDimensions(value); break; case 'batchMaxLines': setBatchMaxLines(value); break; case 'batchConcurrency': setBatchConcurrency(value); break; case 'chunkingMaxLinesPerChunk': setChunkingMaxLinesPerChunk(value); break; case 'chunkingMinLinesPerChunk': setChunkingMinLinesPerChunk(value); break; case 'chunkingMinCharsPerChunk': setChunkingMinCharsPerChunk(value); break; case 'chunkingOverlapLines': setChunkingOverlapLines(value); break; case 'rerankingContextLength': setRerankingContextLength(value); break; case 'rerankingTopN': setRerankingTopN(value); break; } }; useInput((rawInput, key) => { const input = stripFocusArtifacts(rawInput); if (!input && isFocusEventInput(rawInput)) { return; } if (isFocusEventInput(rawInput)) { return; } // Handle numeric field editing if (isEditing && isNumericField(currentField)) { // Handle digit input if (input && input.match(/[0-9]/)) { const currentValue = getNumericValue(currentField); const newValue = parseInt(currentValue.toString() + input, 10); if (!isNaN(newValue)) { setNumericValue(currentField, newValue); } } else if (key.backspace || key.delete) { // Handle backspace/delete const currentValue = getNumericValue(currentField); const currentStr = currentValue.toString(); const newStr = currentStr.slice(0, -1); const newValue = parseInt(newStr, 10); setNumericValue(currentField, !isNaN(newValue) ? newValue : 0); } else if (key.return) { // Confirm and exit editing setIsEditing(false); } else if (key.escape) { // Cancel editing setIsEditing(false); loadConfiguration(); } return; } // When editing non-numeric fields, only handle escape if (isEditing) { if (key.escape) { setIsEditing(false); loadConfiguration(); } return; } // Navigation if (key.upArrow) { const currentIndex = allFields.indexOf(currentField); const newIndex = currentIndex > 0 ? currentIndex - 1 : allFields.length - 1; setCurrentField(allFields[newIndex]!); return; } if (key.downArrow) { const currentIndex = allFields.indexOf(currentField); const newIndex = currentIndex < allFields.length - 1 ? currentIndex + 1 : 0; setCurrentField(allFields[newIndex]!); return; } // Toggle enabled field if (key.return && currentField === 'enabled') { setEnabled(!enabled); return; } // Toggle enableAgentReview field (mutually exclusive with reranking) if (key.return && currentField === 'enableAgentReview') { const newValue = !enableAgentReview; setEnableAgentReview(newValue); if (newValue) { setEnableReranking(false); } return; } // Toggle enableReranking field (mutually exclusive with agent review) if (key.return && currentField === 'enableReranking') { if (!enableReranking) { if (!rerankingModelName.trim() || !rerankingBaseUrl.trim()) { showToast(t.codebaseConfig.rerankingNotConfigured); return; } } const newValue = !enableReranking; setEnableReranking(newValue); if (newValue) { setEnableAgentReview(false); } return; } // Toggle embedding settings expand/collapse if (key.return && currentField === 'embeddingSettings') { setEmbeddingExpanded(!embeddingExpanded); return; } // Toggle batch settings expand/collapse if (key.return && currentField === 'batchSettings') { setBatchExpanded(!batchExpanded); return; } // Toggle reranking settings expand/collapse if (key.return && currentField === 'rerankingSettings') { setRerankingExpanded(!rerankingExpanded); return; } // Enter editing mode for embeddingType to show selector if (key.return && currentField === 'embeddingType') { setIsEditing(true); return; } // Enter editing mode for text fields if ( key.return && currentField !== 'enabled' && currentField !== 'enableAgentReview' && currentField !== 'enableReranking' && currentField !== 'embeddingSettings' && currentField !== 'batchSettings' && currentField !== 'rerankingSettings' ) { setIsEditing(true); return; } // Save configuration (Ctrl+S or Escape when not editing) if ((key.ctrl && input === 's') || key.escape) { saveConfiguration(); if (!errors.length) { onBack(); } return; } }); return ( {!inlineMode && ( {t.codebaseConfig.title} {t.codebaseConfig.subtitle} )} {/* Position indicator - always visible */} {t.codebaseConfig.settingsPosition} ({currentFieldIndex + 1}/ {totalFields}) {totalFields > MAX_VISIBLE_FIELDS && ( {' '} {t.codebaseConfig.scrollHint} )} {/* Scrollable field list */} {(() => { // Calculate visible window if (allFields.length <= MAX_VISIBLE_FIELDS) { // Show all fields if less than max return allFields.map(field => renderField(field)); } // Calculate scroll window const halfWindow = Math.floor(MAX_VISIBLE_FIELDS / 2); let startIndex = Math.max(0, currentFieldIndex - halfWindow); let endIndex = Math.min( allFields.length, startIndex + MAX_VISIBLE_FIELDS, ); // Adjust if we're near the end if (endIndex - startIndex < MAX_VISIBLE_FIELDS) { startIndex = Math.max(0, endIndex - MAX_VISIBLE_FIELDS); } const visibleFields = allFields.slice(startIndex, endIndex); return visibleFields.map(field => renderField(field)); })()} {errors.length > 0 && ( {t.codebaseConfig.errors} {errors.map((error, index) => ( • {error} ))} )} {toastMessage && ( {toastMessage} )} {/* Navigation hints */} {isEditing ? ( {t.codebaseConfig.editingHint} ) : ( {t.codebaseConfig.navigationHint} )} ); } ================================================ FILE: source/ui/pages/ConfigScreen.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import Gradient from 'ink-gradient'; import {Alert} from '@inkjs/ui'; import { type ConfigScreenProps, MAX_VISIBLE_FIELDS, isSelectField, } from './configScreen/types.js'; import {useConfigState} from './configScreen/useConfigState.js'; import {useConfigInput} from './configScreen/useConfigInput.js'; import ConfigFieldRenderer from './configScreen/ConfigFieldRenderer.js'; import ConfigSelectPanel from './configScreen/ConfigSelectPanel.js'; import { ProfileCreateView, ProfileDeleteView, ProfileRenameView, LoadingView, ManualInputView, } from './configScreen/ConfigSubViews.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; export default function ConfigScreen({ onBack, onSave, inlineMode = false, targetProfileName, }: ConfigScreenProps) { const state = useConfigState({targetProfileName}); useConfigInput(state, {onBack, onSave}); const { t, theme, profileMode, loading, manualInputMode, isEditing, currentField, activeProfile, errors, currentFieldIndex, totalFields, fieldsDisplayWindow, hiddenAboveFieldsCount, hiddenBelowFieldsCount, getRequestUrl, } = state; useTerminalTitle(`Snow CLI - ${t.configScreen.title}`); if (profileMode === 'creating') { return ; } if (profileMode === 'deleting') { return ; } if (profileMode === 'renaming') { return ; } if (loading) { return ; } if (manualInputMode) { return ; } const isSelectEditing = isEditing && isSelectField(currentField); return ( {!inlineMode && ( {t.configScreen.title} {t.configScreen.subtitle} {activeProfile && ( {t.configScreen.activeProfile} {activeProfile} )} )} {/* Position indicator */} {t.configScreen.settingsPosition} ({currentFieldIndex + 1}/ {totalFields}) {totalFields > MAX_VISIBLE_FIELDS && ( {t.configScreen.scrollHint} {hiddenAboveFieldsCount > 0 && ( <> ·{' '} {t.configScreen.moreAbove.replace( '{count}', hiddenAboveFieldsCount.toString(), )} )} {hiddenBelowFieldsCount > 0 && ( <> ·{' '} {t.configScreen.moreBelow.replace( '{count}', hiddenBelowFieldsCount.toString(), )} )} )} {isSelectEditing ? ( ) : ( {fieldsDisplayWindow.items.map(field => ( ))} )} {errors.length > 0 && ( {t.configScreen.errors} {errors.map((error, index) => ( • {error} ))} )} {!isSelectEditing && ( {isEditing ? `${ currentField === 'maxContextTokens' || currentField === 'maxTokens' ? t.configScreen.editingHintNumeric : t.configScreen.editingHintGeneral } ${t.configScreen.requestUrlLabel}${getRequestUrl()}` : `${t.configScreen.navigationHint} ${t.configScreen.requestUrlLabel}${getRequestUrl()}`} )} ); } ================================================ FILE: source/ui/pages/CustomHeadersScreen.tsx ================================================ import React, {useState, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import {Alert} from '@inkjs/ui'; import TextInput from 'ink-text-input'; import { getCustomHeadersConfig, saveCustomHeadersConfig, type CustomHeadersConfig, type CustomHeadersItem, } from '../../utils/config/apiConfig.js'; import {useI18n} from '../../i18n/index.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; }; type View = 'list' | 'add' | 'edit' | 'editHeaders' | 'confirmDelete'; type ListAction = | 'activate' | 'deactivate' | 'edit' | 'delete' | 'add' | 'back'; export default function CustomHeadersScreen({onBack}: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.customHeaders.title}`); const {theme} = useTheme(); const [config, setConfig] = useState(() => { return ( getCustomHeadersConfig() || { active: '', schemes: [], } ); }); const [view, setView] = useState('list'); const [selectedIndex, setSelectedIndex] = useState(0); const [currentAction, setCurrentAction] = useState('add'); const [isEditing, setIsEditing] = useState(false); const [editName, setEditName] = useState(''); const [editHeaders, setEditHeaders] = useState>({}); const [editingField, setEditingField] = useState<'name' | 'headers'>('name'); const [error, setError] = useState(''); // Headers editing state const [headerKeys, setHeaderKeys] = useState([]); const [headerSelectedIndex, setHeaderSelectedIndex] = useState(0); const [headerEditingIndex, setHeaderEditingIndex] = useState(-1); const [headerEditingField, setHeaderEditingField] = useState<'key' | 'value'>( 'key', ); const [headerEditKey, setHeaderEditKey] = useState(''); const [headerEditValue, setHeaderEditValue] = useState(''); // 记住进入 editHeaders 之前的视图，用于正确返回 const [previousView, setPreviousView] = useState<'add' | 'edit'>('add'); const actions: ListAction[] = config.schemes.length > 0 ? config.active ? ['activate', 'deactivate', 'edit', 'delete', 'add', 'back'] : ['activate', 'edit', 'delete', 'add', 'back'] : ['add', 'back']; // 当配置变化时，确保 currentAction 在可用操作列表中 useEffect(() => { if (!actions.includes(currentAction)) { setCurrentAction(actions[0] || 'add'); } }, [config.schemes.length, config.active]); useEffect(() => { const savedConfig = getCustomHeadersConfig(); if (savedConfig) { setConfig(savedConfig); } }, [view]); const saveAndRefresh = (newConfig: CustomHeadersConfig) => { try { saveCustomHeadersConfig(newConfig); setConfig(newConfig); setError(''); return true; } catch (err) { setError(err instanceof Error ? err.message : t.customHeaders.saveError); return false; } }; const handleActivate = () => { if (config.schemes.length === 0 || selectedIndex >= config.schemes.length) return; const scheme = config.schemes[selectedIndex]!; const newConfig: CustomHeadersConfig = { ...config, active: scheme.id, }; if (saveAndRefresh(newConfig)) { setError(''); } }; const handleDeactivate = () => { const newConfig: CustomHeadersConfig = { ...config, active: '', }; if (saveAndRefresh(newConfig)) { setError(''); } }; const handleEdit = () => { if (config.schemes.length === 0 || selectedIndex >= config.schemes.length) return; const scheme = config.schemes[selectedIndex]!; setEditName(scheme.name); setEditHeaders(scheme.headers); setEditingField('name'); setView('edit'); }; const handleDelete = () => { setView('confirmDelete'); }; const confirmDelete = () => { if (config.schemes.length === 0 || selectedIndex >= config.schemes.length) return; const schemeToDelete = config.schemes[selectedIndex]!; const newSchemes = config.schemes.filter((_, i) => i !== selectedIndex); const newActive = config.active === schemeToDelete.id && newSchemes.length > 0 ? newSchemes[0]!.id : config.active === schemeToDelete.id ? '' : config.active; const newConfig: CustomHeadersConfig = { active: newActive, schemes: newSchemes, }; if (saveAndRefresh(newConfig)) { setSelectedIndex(Math.max(0, selectedIndex - 1)); setView('list'); } }; const handleAdd = () => { setEditName(''); setEditHeaders({}); setEditingField('name'); setView('add'); }; const saveNewScheme = () => { const newScheme: CustomHeadersItem = { id: Date.now().toString(), name: editName.trim() || 'Unnamed Scheme', headers: editHeaders, createdAt: new Date().toISOString(), }; const newConfig: CustomHeadersConfig = { ...config, schemes: [...config.schemes, newScheme], active: config.schemes.length === 0 ? newScheme.id : config.active, }; if (saveAndRefresh(newConfig)) { setView('list'); setSelectedIndex(config.schemes.length); } }; const saveEditedScheme = () => { if (config.schemes.length === 0 || selectedIndex >= config.schemes.length) return; const newConfig: CustomHeadersConfig = { ...config, schemes: config.schemes.map((s, i) => i === selectedIndex ? { ...s, name: editName.trim() || 'Unnamed Scheme', headers: editHeaders, } : s, ), }; if (saveAndRefresh(newConfig)) { setView('list'); } }; // Headers editing functions const enterHeadersEditMode = () => { // 保存当前视图（add 或 edit），以便从 editHeaders 返回时使用 setPreviousView(view as 'add' | 'edit'); setHeaderKeys(Object.keys(editHeaders)); setHeaderSelectedIndex(0); setHeaderEditingIndex(-1); setView('editHeaders'); }; const exitHeadersEditMode = () => { // 使用保存的 previousView 返回正确的视图 setView(previousView); }; const addNewHeader = () => { setHeaderEditKey(''); setHeaderEditValue(''); setHeaderEditingIndex(headerKeys.length); setHeaderEditingField('key'); }; const editHeaderAtIndex = (index: number) => { const key = headerKeys[index]!; setHeaderEditKey(key); setHeaderEditValue(editHeaders[key] || ''); setHeaderEditingIndex(index); setHeaderEditingField('key'); }; const saveHeaderEdit = (): Record => { const trimmedKey = headerEditKey.trim(); const trimmedValue = headerEditValue.trim(); if (!trimmedKey) { setHeaderEditingIndex(-1); return editHeaders; } const newHeaders = {...editHeaders}; if (headerEditingIndex < headerKeys.length) { const oldKey = headerKeys[headerEditingIndex]!; if (oldKey !== trimmedKey) { delete newHeaders[oldKey]; } } newHeaders[trimmedKey] = trimmedValue; setEditHeaders(newHeaders); setHeaderKeys(Object.keys(newHeaders)); setHeaderEditingIndex(-1); return newHeaders; }; const persistScheme = (headers: Record) => { if (previousView === 'add') { const newScheme: CustomHeadersItem = { id: Date.now().toString(), name: editName.trim() || 'Unnamed Scheme', headers, createdAt: new Date().toISOString(), }; const newConfig: CustomHeadersConfig = { ...config, schemes: [...config.schemes, newScheme], active: config.schemes.length === 0 ? newScheme.id : config.active, }; if (saveAndRefresh(newConfig)) { setSelectedIndex(config.schemes.length); setPreviousView('edit'); } } else { if (config.schemes.length === 0 || selectedIndex >= config.schemes.length) return; const newConfig: CustomHeadersConfig = { ...config, schemes: config.schemes.map((s, i) => i === selectedIndex ? { ...s, name: editName.trim() || 'Unnamed Scheme', headers, } : s, ), }; saveAndRefresh(newConfig); } }; const deleteHeaderAtIndex = (index: number) => { const key = headerKeys[index]!; const newHeaders = {...editHeaders}; delete newHeaders[key]; setEditHeaders(newHeaders); setHeaderKeys(Object.keys(newHeaders)); setHeaderSelectedIndex(Math.max(0, Math.min(index, headerKeys.length - 2))); }; // List view input handling useInput( (_input, key) => { if (view !== 'list') return; if (key.escape) { onBack(); } else if (key.upArrow) { if (config.schemes.length > 0) { setSelectedIndex(prev => prev > 0 ? prev - 1 : config.schemes.length - 1, ); } } else if (key.downArrow) { if (config.schemes.length > 0) { setSelectedIndex(prev => prev < config.schemes.length - 1 ? prev + 1 : 0, ); } } else if (key.leftArrow) { const currentIdx = actions.indexOf(currentAction); setCurrentAction( actions[currentIdx > 0 ? currentIdx - 1 : actions.length - 1]!, ); } else if (key.rightArrow) { const currentIdx = actions.indexOf(currentAction); setCurrentAction( actions[currentIdx < actions.length - 1 ? currentIdx + 1 : 0]!, ); } else if (key.return) { if (currentAction === 'activate') { handleActivate(); } else if (currentAction === 'deactivate') { handleDeactivate(); } else if (currentAction === 'edit') { handleEdit(); } else if (currentAction === 'delete') { handleDelete(); } else if (currentAction === 'add') { handleAdd(); } else if (currentAction === 'back') { onBack(); } } }, {isActive: view === 'list'}, ); // Add/Edit view input handling useInput( (input, key) => { if (view !== 'add' && view !== 'edit') return; if (key.escape) { setView('list'); setError(''); } else if (!isEditing && key.upArrow) { setEditingField('name'); } else if (!isEditing && key.downArrow) { setEditingField('headers'); } else if (key.return) { if (editingField === 'headers' && !isEditing) { enterHeadersEditMode(); } else if (isEditing) { setIsEditing(false); } else { setIsEditing(true); } } else if (input === 's' && (key.ctrl || key.meta)) { if (view === 'add') { saveNewScheme(); } else { saveEditedScheme(); } } }, {isActive: view === 'add' || view === 'edit'}, ); // Headers edit view input handling useInput( (input, key) => { if (view !== 'editHeaders') return; if (headerEditingIndex === -1) { // 列表浏览模式 if (key.escape) { exitHeadersEditMode(); } else if (key.upArrow) { setHeaderSelectedIndex(prev => prev > 0 ? prev - 1 : headerKeys.length, ); } else if (key.downArrow) { setHeaderSelectedIndex(prev => prev < headerKeys.length ? prev + 1 : 0, ); } else if (key.return) { if (headerSelectedIndex < headerKeys.length) { editHeaderAtIndex(headerSelectedIndex); } else { addNewHeader(); } } else if (key.delete || input === 'd') { if (headerSelectedIndex < headerKeys.length) { deleteHeaderAtIndex(headerSelectedIndex); } } else if (input === 's' && (key.ctrl || key.meta)) { persistScheme(editHeaders); } } else { // 编辑模式 if (key.escape) { setHeaderEditingIndex(-1); } else if (key.upArrow && !isEditing) { setHeaderEditingField('key'); } else if (key.downArrow && !isEditing) { setHeaderEditingField('value'); } else if (key.return) { if (isEditing) { setIsEditing(false); } else { setIsEditing(true); } } else if (input === 's' && (key.ctrl || key.meta)) { const newHeaders = saveHeaderEdit(); persistScheme(newHeaders); } } }, {isActive: view === 'editHeaders'}, ); // Delete confirmation input handling useInput( (input, key) => { if (view !== 'confirmDelete') return; if (key.escape || input === 'n' || input === 'N') { setView('list'); } else if (input === 'y' || input === 'Y' || key.return) { confirmDelete(); } }, {isActive: view === 'confirmDelete'}, ); // Render list view if (view === 'list') { const activeScheme = config.schemes.find(s => s.id === config.active); return ( {error && ( {error} )} {t.customHeaders.activeScheme}{' '} {activeScheme?.name || t.customHeaders.none} {config.schemes.length === 0 ? ( {t.customHeaders.noSchemesConfigured} ) : ( {t.customHeaders.availableSchemes} {config.schemes.map((scheme, index) => { const headerCount = Object.keys(scheme.headers).length; const headerPreview = headerCount > 0 ? Object.entries(scheme.headers) .slice(0, 2) .map(([k, v]) => `${k}: ${v}`) .join(', ') : ''; return ( {index === selectedIndex ? '❯ ' : ' '} {scheme.id === config.active ? '✓ ' : ' '} {scheme.name} {headerPreview && ( {' '} - {headerPreview.substring(0, 50)} {headerPreview.length > 50 ? '...' : ''} )} ); })} )} {t.customHeaders.actions} {actions.map(action => ( {currentAction === action ? '❯ ' : ' '} {action === 'activate' && t.customHeaders.activate} {action === 'deactivate' && t.customHeaders.deactivate} {action === 'edit' && t.customHeaders.edit} {action === 'delete' && t.customHeaders.delete} {action === 'add' && t.customHeaders.addNew} {action === 'back' && t.customHeaders.escBack} ))} {t.customHeaders.navigationHint} ); } // Render add/edit view if (view === 'add' || view === 'edit') { const headerCount = Object.keys(editHeaders).length; const headerPreview = headerCount > 0 ? Object.entries(editHeaders) .slice(0, 3) .map(([k, v]) => `${k}: ${v}`) .join(', ') : t.customHeaders.notSet; return ( {error && ( {error} )} {editingField === 'name' ? '❯ ' : ' '} {t.customHeaders.nameLabel} {editingField === 'name' && isEditing && ( )} {(!isEditing || editingField !== 'name') && ( {editName || t.customHeaders.notSet} )} {editingField === 'headers' ? '❯ ' : ' '} {t.customHeaders.headersLabel} ({headerCount}{' '} {t.customHeaders.headersConfigured}): {editingField === 'headers' && !isEditing ? ( {t.customHeaders.pressEnterToEdit} ) : ( {headerPreview.substring(0, 100)} {headerPreview.length > 100 ? '...' : ''} )} {t.customHeaders.editingHint} ); } // Render headers edit view if (view === 'editHeaders') { return ( {headerEditingIndex === -1 ? ( <> {t.customHeaders.headerList} {headerKeys.length === 0 ? ( {t.customHeaders.noHeadersConfigured} ) : ( {headerKeys.map((key, index) => { const isSelected = index === headerSelectedIndex; return ( {isSelected ? '❯ ' : ' '} {key}: {editHeaders[key]} ); })} )} {headerSelectedIndex === headerKeys.length ? '❯ ' : ' '} {t.customHeaders.addNewHeader} {t.customHeaders.headerNavigationHint} ) : ( <> {headerEditingField === 'key' ? '❯ ' : ' '} {t.customHeaders.keyLabel} {headerEditingField === 'key' && isEditing && ( )} {(!isEditing || headerEditingField !== 'key') && ( {headerEditKey || t.customHeaders.notSet} )} {headerEditingField === 'value' ? '❯ ' : ' '} {t.customHeaders.valueLabel} {headerEditingField === 'value' && isEditing && ( )} {(!isEditing || headerEditingField !== 'value') && ( {headerEditValue || t.customHeaders.notSet} )} {t.customHeaders.headerEditingHint} )} ); } // Render delete confirmation if (view === 'confirmDelete') { const schemeToDelete = config.schemes.length > 0 ? config.schemes[selectedIndex] : null; return ( {t.customHeaders.confirmDelete} {t.customHeaders.deleteConfirmMessage} " {schemeToDelete?.name} "? {t.customHeaders.confirmHint} ); } return null; } ================================================ FILE: source/ui/pages/CustomThemeScreen.tsx ================================================ import React, {useState, useCallback, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import Menu from '../components/common/Menu.js'; import DiffViewer from '../components/tools/DiffViewer.js'; import UserMessagePreview from '../components/chat/UserMessagePreview.js'; import {ThemeContext, useTheme} from '../contexts/ThemeContext.js'; import { ThemeColors, ThemeType, defaultCustomColors, getCustomTheme, } from '../themes/index.js'; import {saveCustomColors} from '../../utils/config/themeConfig.js'; import {useI18n} from '../../i18n/index.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: (nextSelectedTheme?: ThemeType) => void; }; type ColorKey = keyof ThemeColors; const colorKeys: ColorKey[] = [ 'background', 'text', 'border', 'diffAdded', 'diffRemoved', 'diffModified', 'lineNumber', 'lineNumberBorder', 'menuSelected', 'menuNormal', 'menuInfo', 'menuSecondary', 'error', 'warning', 'success', 'logoGradient', 'userMessageBackground', 'userMessageText', 'diffOpacity', ]; const sampleOldCode = `function greet(name) { console.log("Hello " + name); return "Welcome!"; }`; const sampleNewCode = `function greet(name: string): string { console.log(\`Hello \${name}\`); return \`Welcome, \${name}!\`; }`; export default function CustomThemeScreen({onBack}: Props) { const {setThemeType, refreshCustomTheme} = useTheme(); const {t} = useI18n(); useTerminalTitle( `Snow CLI - ${t.customTheme?.title || 'Custom Theme Editor'}`, ); const [colors, setColors] = useState(() => { const custom = getCustomTheme(); return custom.colors; }); const [editingKey, setEditingKey] = useState(null); const [editValue, setEditValue] = useState(''); const [infoText, setInfoText] = useState(''); const menuOptions = useMemo(() => { const options: Array<{label: string; value: string; infoText: string}> = colorKeys.map(key => ({ label: `${key}: ${colors[key]}`, value: key, infoText: t.customTheme?.colorHint || 'Press Enter to edit this color', })); options.push({ label: t.customTheme?.save || 'Save', value: 'save', infoText: t.customTheme?.saveInfo || 'Save custom theme colors', }); options.push({ label: t.customTheme?.reset || 'Reset to Default', value: 'reset', infoText: t.customTheme?.resetInfo || 'Reset all colors to default', }); options.push({ label: t.customTheme?.back || '← Back', value: 'back', infoText: t.customTheme?.backInfo || 'Return to theme settings', }); return options; }, [colors, t]); const saveAndExit = useCallback(() => { saveCustomColors(colors); refreshCustomTheme?.(); setThemeType('custom'); onBack('custom'); }, [colors, onBack, refreshCustomTheme, setThemeType]); const handleSelect = useCallback( (value: string) => { if (value === 'back') { onBack(); } else if (value === 'save') { saveAndExit(); } else if (value === 'reset') { setColors({...defaultCustomColors}); } else { const key = value as ColorKey; setEditingKey(key); // Handle array type for logoGradient const colorValue = colors[key]; setEditValue( Array.isArray(colorValue) ? colorValue.join(', ') : String(colorValue), ); } }, [onBack, saveAndExit, colors], ); const handleSelectionChange = useCallback((newInfoText: string) => { setInfoText(newInfoText); }, []); const handleEditSubmit = useCallback(() => { if (editingKey && editValue.trim()) { setColors(prev => { const newValue = editingKey === 'logoGradient' ? (editValue .split(',') .map(v => v.trim()) .filter(v => v) as [string, string, string]) : editingKey === 'diffOpacity' ? Math.max(0, Math.min(1, Number.parseFloat(editValue.trim()) || 0)) : editValue.trim(); return { ...prev, [editingKey]: newValue, }; }); } setEditingKey(null); setEditValue(''); }, [editingKey, editValue]); useInput((_input, key) => { if (key.escape) { if (editingKey) { setEditingKey(null); setEditValue(''); } else { saveAndExit(); } } }); if (editingKey) { return ( {t.customTheme?.editColor || 'Edit Color'}: {editingKey} {t.customTheme?.currentValue || 'Current'}: {Array.isArray(colors[editingKey]) ? (colors[editingKey] as [string, string, string]).join(', ') : String(colors[editingKey])} {t.customTheme?.newValue || 'New value'}: {t.customTheme?.colorFormat || 'Format: #RRGGBB or color name (red, blue, etc.)'} ESC: {t.customTheme?.cancel || 'Cancel'} | Enter:{' '} {t.customTheme?.confirm || 'Confirm'} ); } return ( {t.customTheme?.title || 'Custom Theme Editor'} {t.customTheme?.preview || 'Preview'}: {}, refreshCustomTheme, }} > {t.customTheme?.userMessagePreview || 'User message preview'}: {infoText && ( {infoText} )} ); } ================================================ FILE: source/ui/pages/ExitScreen.tsx ================================================ import React, {useEffect, useMemo, useState} from 'react'; import {Box, Text} from 'ink'; import Gradient from 'ink-gradient'; import chalk from 'chalk'; import {useI18n} from '../../i18n/index.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalSize} from '../../hooks/ui/useTerminalSize.js'; import {gracefulExit} from '../../utils/core/processManager.js'; import {sessionManager} from '../../utils/session/sessionManager.js'; import {readFile} from 'fs/promises'; import {homedir} from 'os'; import {join} from 'path'; import type {PixelGrid} from '../components/pixel-editor/types.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { version?: string; }; function dotLine(width: number): string { const count = Math.max(0, Math.floor(width / 3)); return Array.from({length: count}, () => '·').join(' '); } const EXIT_IMAGE_PATH = join(homedir(), '.snow', 'exit-image.json'); const BLOCK_CHAR = '\u2580'; export default function ExitScreen({version = '1.0.0'}: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.exitScreen.title}`); const {theme} = useTheme(); const {columns: terminalWidth} = useTerminalSize(); const [sessionId] = useState(() => sessionManager.getCurrentSession()?.id); const versionText = t.exitScreen.version.replace('{version}', version); const dotWidth = Math.max(12, Math.min(terminalWidth - 8, 42)); const dots = useMemo(() => dotLine(dotWidth), [dotWidth]); const colors = theme.colors; const [exitImageGrid, setExitImageGrid] = useState( undefined, ); const [isExitScreenReady, setIsExitScreenReady] = useState(false); useEffect(() => { let active = true; const loadExitImage = async () => { try { const content = await readFile(EXIT_IMAGE_PATH, 'utf8'); const data = JSON.parse(content) as { grid?: PixelGrid; enabled?: boolean; }; if (!active) return; if (data.grid && (data.enabled ?? true)) { setExitImageGrid(data.grid.map(row => [...row])); } else { setExitImageGrid(undefined); } } catch { if (active) { setExitImageGrid(undefined); } } finally { if (active) { // Mark screen ready only after async content decision finishes. setIsExitScreenReady(true); } } }; loadExitImage(); return () => { active = false; }; }, []); useEffect(() => { if (!isExitScreenReady) return; gracefulExit(); }, [isExitScreenReady]); const exitImageRows = useMemo(() => { if (!exitImageGrid) return []; const canvasHeight = exitImageGrid.length; const canvasWidth = exitImageGrid[0]?.length ?? 0; const rows: string[] = []; for (let charY = 0; charY < canvasHeight / 2; charY++) { let row = ''; for (let x = 0; x < canvasWidth; x++) { const topY = charY * 2; const bottomY = topY + 1; const topColor = exitImageGrid[topY]?.[x] ?? '#000000'; const bottomColor = exitImageGrid[bottomY]?.[x] ?? '#000000'; row += chalk.bgHex(bottomColor).hex(topColor)(BLOCK_CHAR); } rows.push(row); } return rows; }, [exitImageGrid]); return ( {dots} {exitImageRows.length > 0 && ( {exitImageRows.map((row, i) => ( {row} ))} )} ❆ SNOW CLI {'── '} {t.exitScreen.title} {' ──'} {t.exitScreen.goodbye} {t.exitScreen.thankYou} {sessionId && ( {`─── ${t.exitScreen.resumeSession} ───`} {'snow -c '} {sessionId} )} {dots} {versionText} ); } ================================================ FILE: source/ui/pages/HeadlessModeScreen.tsx ================================================ import React, {useState, useEffect} from 'react'; import {useStdout} from 'ink'; import ansiEscapes from 'ansi-escapes'; import {highlight} from 'cli-highlight'; import readline from 'readline'; import {type Message} from '../components/chat/MessageList.js'; import {handleConversationWithTools} from '../../hooks/conversation/useConversation.js'; import {useStreamingState} from '../../hooks/conversation/useStreamingState.js'; import {useToolConfirmation} from '../../hooks/conversation/useToolConfirmation.js'; import {useVSCodeState} from '../../hooks/integration/useVSCodeState.js'; import {useSessionSave} from '../../hooks/session/useSessionSave.js'; import {sessionManager} from '../../utils/session/sessionManager.js'; import {useI18n} from '../../i18n/I18nContext.js'; import { parseAndValidateFileReferences, createMessageWithFileInstructions, } from '../../utils/core/fileUtils.js'; import {isSensitiveCommand} from '../../utils/execution/sensitiveCommandManager.js'; import {getCurrentTheme} from '../../utils/config/themeConfig.js'; import {themes} from '../themes/index.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { prompt: string; sessionId?: string; onComplete: () => void; }; // Console-based markdown renderer functions function renderConsoleMarkdown(content: string): string { const blocks = parseConsoleMarkdown(content); return blocks.map(block => renderConsoleBlock(block)).join('\n'); } function parseConsoleMarkdown(content: string): any[] { const blocks: any[] = []; const lines = content.split('\n'); let i = 0; while (i < lines.length) { const line = lines[i] ?? ''; // Check for code block const codeBlockMatch = line.match(/^```(.*)$/); if (codeBlockMatch) { const language = codeBlockMatch[1]?.trim() || ''; const codeLines: string[] = []; i++; // Collect code block lines while (i < lines.length) { const currentLine = lines[i] ?? ''; if (currentLine.trim().startsWith('```')) { break; } codeLines.push(currentLine); i++; } blocks.push({ type: 'code', language, code: codeLines.join('\n'), }); i++; // Skip closing ``` continue; } // Check for heading const headingMatch = line.match(/^(#{1,6})\s+(.+)$/); if (headingMatch) { blocks.push({ type: 'heading', level: headingMatch[1]!.length, content: headingMatch[2]!.trim(), }); i++; continue; } // Check for list item const listMatch = line.match(/^[\s]*[*\-]\s+(.+)$/); if (listMatch) { const listItems: string[] = [listMatch[1]!.trim()]; i++; // Collect consecutive list items while (i < lines.length) { const currentLine = lines[i] ?? ''; const nextListMatch = currentLine.match(/^[\s]*[*\-]\s+(.+)$/); if (!nextListMatch) { break; } listItems.push(nextListMatch[1]!.trim()); i++; } blocks.push({ type: 'list', items: listItems, }); continue; } // Collect text lines const textLines: string[] = []; while (i < lines.length) { const currentLine = lines[i] ?? ''; if ( currentLine.trim().startsWith('```') || currentLine.match(/^#{1,6}\s+/) || currentLine.match(/^[\s]*[*\-]\s+/) ) { break; } textLines.push(currentLine); i++; } if (textLines.length > 0) { blocks.push({ type: 'text', content: textLines.join('\n'), }); } } return blocks; } function renderConsoleBlock(block: any): string { switch (block.type) { case 'code': { const highlightedCode = highlightConsoleCode(block.code, block.language); const languageLabel = block.language ? `\x1b[42m\x1b[30m ${block.language} \x1b[0m` : ''; return ( `\n\x1b[90m┌─ Code Block\x1b[0m\n` + (languageLabel ? `\x1b[90m│\x1b[0m ${languageLabel}\n` : '') + `\x1b[90m├─\x1b[0m\n` + `${highlightedCode}\n` + `\x1b[90m└─ End of Code\x1b[0m` ); } case 'heading': { const headingColors = ['\x1b[96m', '\x1b[94m', '\x1b[95m', '\x1b[93m']; const headingColor = headingColors[block.level - 1] || '\x1b[97m'; const prefix = '#'.repeat(block.level); return `\n${headingColor}${prefix} ${renderInlineFormatting( block.content, )}\x1b[0m`; } case 'list': { return ( '\n' + block.items .map( (item: string) => `\x1b[93m•\x1b[0m ${renderInlineFormatting(item)}`, ) .join('\n') ); } case 'text': { return ( '\n' + block.content .split('\n') .map((line: string) => line === '' ? '' : renderInlineFormatting(line), ) .join('\n') ); } default: return ''; } } function highlightConsoleCode(code: string, language: string): string { try { if (!language) { return code .split('\n') .map(line => `\x1b[90m│ \x1b[37m${line}\x1b[0m`) .join('\n'); } // Map common language aliases const languageMap: Record = { js: 'javascript', ts: 'typescript', py: 'python', rb: 'ruby', sh: 'bash', shell: 'bash', cs: 'csharp', 'c#': 'csharp', cpp: 'cpp', 'c++': 'cpp', yml: 'yaml', md: 'markdown', json: 'json', xml: 'xml', html: 'html', css: 'css', sql: 'sql', java: 'java', go: 'go', rust: 'rust', php: 'php', }; const mappedLanguage = languageMap[language.toLowerCase()] || language.toLowerCase(); const highlighted = highlight(code, { language: mappedLanguage, ignoreIllegals: true, }); return highlighted .split('\n') .map(line => `\x1b[90m│ \x1b[0m${line}`) .join('\n'); } catch { // If highlighting fails, return plain code return code .split('\n') .map(line => `\x1b[90m│ \x1b[37m${line}\x1b[0m`) .join('\n'); } } function renderInlineFormatting(text: string): string { // Handle inline code `code` text = text.replace(/`([^`]+)`/g, (_, code) => { return `\x1b[36m${code}\x1b[0m`; }); // Handle bold **text** or __text__ text = text.replace(/(\*\*|__)([^*_]+)\1/g, (_, __, content) => { return `\x1b[1m\x1b[97m${content}\x1b[0m`; }); // Handle italic *text* or _text_ text = text.replace(/(? { return `\x1b[3m\x1b[97m${content}\x1b[0m`; }); return text; } // Get theme colors const getTheme = () => { const currentTheme = getCurrentTheme(); return themes[currentTheme].colors; }; // Helper function to convert theme color to ANSI code const getAnsiColor = (color: string): string => { const colorMap: Record = { red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[34m', magenta: '\x1b[35m', cyan: '\x1b[36m', white: '\x1b[37m', gray: '\x1b[90m', }; return colorMap[color] || '\x1b[37m'; // default to white }; // Helper function to ask user for confirmation in headless mode async function askHeadlessConfirmation( toolName: string, toolArguments: string, ): Promise<'approve' | 'reject' | 'approve_always'> { return new Promise(resolve => { const theme = getTheme(); // Create readline interface const rl = readline.createInterface({ input: process.stdin, output: process.stdout, }); // Parse tool arguments to check if it's a sensitive command let command = ''; try { const args = JSON.parse(toolArguments); if (args.command) { command = args.command; } } catch { // Ignore parsing errors } // Check if it's a sensitive command const sensitiveCheck = isSensitiveCommand(command); const warningColor = getAnsiColor(theme.warning); const errorColor = getAnsiColor(theme.error); const infoColor = getAnsiColor(theme.menuInfo); const successColor = getAnsiColor(theme.success); const resetColor = '\x1b[0m'; // Display tool information with theme colors console.log( `\n${warningColor}⚠ Tool Confirmation Required${resetColor} ${ sensitiveCheck.isSensitive ? `${errorColor}(Sensitive Command)${resetColor}` : '' }`, ); console.log(`${infoColor}Tool:${resetColor} ${toolName}`); if (command) { console.log(`${infoColor}Command:${resetColor} ${command}`); } if (sensitiveCheck.isSensitive && sensitiveCheck.matchedCommand) { console.log( `${warningColor}Reason:${resetColor} ${sensitiveCheck.matchedCommand.description}`, ); } console.log(''); console.log(`${successColor}[A]${resetColor} Approve`); console.log(`${errorColor}[R]${resetColor} Reject`); console.log(''); // Ask for input rl.question(`${infoColor}Your choice:${resetColor} `, answer => { rl.close(); const choice = answer.trim().toLowerCase(); if (choice === 'r') { resolve('reject'); } else { // Default to approve resolve('approve'); } }); }); } export default function HeadlessModeScreen({ prompt, sessionId, onComplete, }: Props) { const [messages, setMessages] = useState([]); const [isComplete, setIsComplete] = useState(false); const [lastDisplayedIndex, setLastDisplayedIndex] = useState(-1); const [isWaitingForInput, setIsWaitingForInput] = useState(false); const {stdout} = useStdout(); const workingDirectory = process.cwd(); const {t} = useI18n(); useTerminalTitle('Snow CLI - Headless Mode'); // Use custom hooks const streamingState = useStreamingState(); const vscodeState = useVSCodeState(); const {saveMessage} = useSessionSave(); // Use tool confirmation hook const {isToolAutoApproved, addMultipleToAlwaysApproved} = useToolConfirmation(workingDirectory); // Listen for message changes to display AI responses and tool calls useEffect(() => { const lastMessage = messages[messages.length - 1]; const currentIndex = messages.length - 1; // Only display if this is a new message we haven't displayed yet if (!lastMessage || currentIndex <= lastDisplayedIndex) return; if (lastMessage.role === 'assistant') { if (lastMessage.toolPending) { // Tool is being executed - use same icon as ChatScreen with colors if (lastMessage.content.startsWith('⚡')) { console.log(`\n\x1b[93m⚡ ${lastMessage.content}\x1b[0m`); } else if (lastMessage.content.startsWith('✓')) { console.log(`\n\x1b[32m✓ ${lastMessage.content}\x1b[0m`); } else if (lastMessage.content.startsWith('✗')) { console.log(`\n\x1b[31m✗ ${lastMessage.content}\x1b[0m`); } else { console.log(`\n\x1b[96m❆ ${lastMessage.content}\x1b[0m`); } setLastDisplayedIndex(currentIndex); } else if (lastMessage.content && !lastMessage.streaming) { // Final response with markdown rendering and better formatting console.log(renderConsoleMarkdown(lastMessage.content)); // Show tool results if available with better styling if ( lastMessage.toolCall && lastMessage.toolCall.name === 'terminal-execute' ) { const args = lastMessage.toolCall.arguments; if (args.command) { console.log(`\n\x1b[90m┌─ Command\x1b[0m`); console.log(`\x1b[33m│ ${args.command}\x1b[0m`); } if (args.stdout && args.stdout.trim()) { console.log(`\x1b[90m├─ stdout\x1b[0m`); const stdoutLines = args.stdout.split('\n'); stdoutLines.forEach((line: string) => { console.log(`\x1b[90m│ \x1b[32m${line}\x1b[0m`); }); } if (args.stderr && args.stderr.trim()) { console.log(`\x1b[90m├─ stderr\x1b[0m`); const stderrLines = args.stderr.split('\n'); stderrLines.forEach((line: string) => { console.log(`\x1b[90m│ \x1b[31m${line}\x1b[0m`); }); } if (args.command || args.stdout || args.stderr) { console.log(`\x1b[90m└─ Execution complete\x1b[0m`); } } setLastDisplayedIndex(currentIndex); } } }, [messages, lastDisplayedIndex]); // Listen for streaming state to show loading status useEffect(() => { // Don't show thinking status when waiting for user input if (isWaitingForInput) return; if (streamingState.isStreaming) { if (streamingState.retryStatus && streamingState.retryStatus.isRetrying) { // Show retry status with colors if (streamingState.retryStatus.errorMessage) { console.log( `\n\x1b[31m${t.chatScreen.retryError.replace( '{message}', streamingState.retryStatus.errorMessage, )}\x1b[0m`, ); } if ( streamingState.retryStatus.remainingSeconds !== undefined && streamingState.retryStatus.remainingSeconds > 0 ) { console.log( `\n\x1b[93m${t.chatScreen.retryAttempt .replace('{current}', String(streamingState.retryStatus.attempt)) .replace('{max}', '5')} \x1b[93m${t.chatScreen.retryIn.replace( '{seconds}', String(streamingState.retryStatus.remainingSeconds), )}\x1b[93m...\x1b[0m`, ); } else { console.log( `\n\x1b[93m${t.chatScreen.retryResending .replace('{current}', String(streamingState.retryStatus.attempt)) .replace('{max}', '5')}\x1b[0m`, ); } } else { // Show normal thinking status with colors const thinkingText = streamingState.isReasoning ? 'Deep thinking...' : streamingState.streamTokenCount > 0 ? 'Writing...' : 'Thinking...'; process.stdout.write( `\r\x1b[96m❆\x1b[90m ${thinkingText} \x1b[33m${streamingState.elapsedSeconds}s\x1b[37m · \x1b[32m↓ ${streamingState.streamTokenCount} tokens\x1b[0m`, ); } } }, [ streamingState.isStreaming, streamingState.isReasoning, streamingState.elapsedSeconds, streamingState.streamTokenCount, streamingState.retryStatus, isWaitingForInput, t, ]); const processMessage = async () => { try { // Load existing session if sessionId is provided let loadedMessages: Message[] = []; let currentSessionId = sessionId; if (sessionId) { console.log(`\n\x1b[96m Loading session: ${sessionId}\x1b[0m`); const loadedSession = await sessionManager.loadSession(sessionId); if (loadedSession) { // Convert API messages to UI messages loadedMessages = loadedSession.messages.map( msg => ({ role: msg.role, content: msg.content, toolCall: msg.tool_calls ? { name: msg.tool_calls[0]?.function.name || '', arguments: msg.tool_calls[0]?.function.arguments || {}, } : undefined, } as Message), ); console.log( `\x1b[32m✓ Loaded ${loadedMessages.length} messages from session\x1b[0m\n`, ); } else { console.log( `\x1b[33m⚠ Session not found, starting new session\x1b[0m\n`, ); currentSessionId = undefined; } } // Parse and validate file references const {cleanContent, validFiles} = await parseAndValidateFileReferences( prompt, ); const regularFiles = validFiles.filter(f => !f.isImage); // Add user message to UI const userMessage: Message = { role: 'user', content: cleanContent, files: validFiles.length > 0 ? validFiles : undefined, }; // Combine loaded messages with new user message const allMessages = [...loadedMessages, userMessage]; setMessages(allMessages); streamingState.setIsStreaming(true); // Create new abort controller for this request const controller = new AbortController(); streamingState.setAbortController(controller); // Clear terminal and start headless output stdout.write(ansiEscapes.clearTerminal); // Print colorful banner console.log( `\x1b[94m╭─────────────────────────────────────────────────────────╮\x1b[0m`, ); console.log( `\x1b[94m│\x1b[96m ❆ Snow AI CLI - Headless Mode ❆ \x1b[94m│\x1b[0m`, ); console.log( `\x1b[94m╰─────────────────────────────────────────────────────────╯\x1b[0m`, ); // Print session info if continuing conversation if (loadedMessages.length > 0) { console.log(`\n\x1b[36m┌─ Continuing Session\x1b[0m`); console.log(`\x1b[90m│ Session ID: ${currentSessionId}\x1b[0m`); console.log( `\x1b[90m│ Previous messages: ${loadedMessages.length}\x1b[0m`, ); } // Print user prompt with styling console.log(`\n\x1b[36m┌─ User Query\x1b[0m`); console.log(`\x1b[97m│ ${cleanContent}\x1b[0m`); if (validFiles.length > 0) { console.log(`\x1b[36m├─ Files\x1b[0m`); validFiles.forEach(file => { const statusColor = file.exists ? '\x1b[32m' : '\x1b[31m'; const statusText = file.exists ? '✓' : '✗'; console.log( `\x1b[90m│ └─ ${statusColor}${statusText}\x1b[90m ${file.path}${ file.exists ? `\x1b[33m (${file.lineCount} lines)\x1b[90m` : '\x1b[31m (not found)\x1b[90m' }\x1b[0m`, ); }); } console.log(`\x1b[36m└─ Assistant Response\x1b[0m`); // Create message for AI const messageForAI = createMessageWithFileInstructions( cleanContent, regularFiles, vscodeState.vscodeConnected ? vscodeState.editorContext : undefined, ); // Start conversation with tool support await handleConversationWithTools({ userContent: messageForAI.content, imageContents: [], controller, messages: allMessages, saveMessage, setMessages, setStreamTokenCount: streamingState.setStreamTokenCount, requestToolConfirmation: async toolCall => { // In headless mode with YOLO, still need to confirm sensitive commands // Check if this is a sensitive command let needsConfirmation = false; if (toolCall.function.name === 'terminal-execute') { try { const args = JSON.parse(toolCall.function.arguments); const sensitiveCheck = isSensitiveCommand(args.command); needsConfirmation = sensitiveCheck.isSensitive; } catch { // If parsing fails, treat as normal command } } // If not sensitive, auto-approve (YOLO mode behavior) if (!needsConfirmation) { return 'approve'; } // For sensitive commands, ask for confirmation // Clear thinking status before showing confirmation process.stdout.write('\r\x1b[K'); // Clear current line setIsWaitingForInput(true); const confirmation = await askHeadlessConfirmation( toolCall.function.name, toolCall.function.arguments, ); setIsWaitingForInput(false); return confirmation; }, requestUserQuestion: async () => { throw new Error('askuser tool is not supported in headless mode'); }, isToolAutoApproved, addMultipleToAlwaysApproved, yoloModeRef: {current: true}, // Always use YOLO mode in headless planMode: false, // HeadlessMode doesn't support Plan mode setContextUsage: streamingState.setContextUsage, useBasicModel: false, getPendingMessages: () => [], clearPendingMessages: () => {}, setIsStreaming: streamingState.setIsStreaming, setIsReasoning: streamingState.setIsReasoning, setRetryStatus: streamingState.setRetryStatus, }); } catch (error) { console.error( `\n\x1b[31m✗ Error:\x1b[0m`, error instanceof Error ? `\x1b[91m${error.message}\x1b[0m` : '\x1b[91mUnknown error occurred\x1b[0m', ); } finally { // End streaming streamingState.setIsStreaming(false); streamingState.setAbortController(null); streamingState.setStreamTokenCount(0); setIsComplete(true); // Print session ID for continuous conversation const finalSession = sessionManager.getCurrentSession(); if (finalSession) { console.log(`\n\x1b[96m┌─ Session Information\x1b[0m`); console.log( `\x1b[96m│\x1b[0m Session ID: \x1b[33m${finalSession.id}\x1b[0m`, ); console.log( `\x1b[96m│\x1b[0m To continue this conversation, use:\x1b[0m`, ); console.log( `\x1b[96m│\x1b[0m \x1b[32msnow --ask "your next question" ${finalSession.id}\x1b[0m`, ); console.log(`\x1b[96m└─\x1b[0m\n`); // Output session ID in plain text for easy parsing by third-party tools // Format: SESSION_ID= console.log(`SESSION_ID=${finalSession.id}`); } // Wait a moment then call onComplete setTimeout(() => { onComplete(); }, 1000); } }; useEffect(() => { processMessage(); }, []); // Simple console output mode - don't render anything if (isComplete) { return null; } // Return empty fragment - we're using console.log for output return <>; } ================================================ FILE: source/ui/pages/HelpScreen.tsx ================================================ import React from 'react'; import {Box, Text, useInput} from 'ink'; import {useTheme} from '../contexts/ThemeContext.js'; import {useI18n} from '../../i18n/I18nContext.js'; import HelpPanel from '../components/panels/HelpPanel.js'; import {navigateTo} from '../../hooks/integration/useGlobalNavigation.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { // Future-proof: allow calling screen to decide where to go back. onBackDestination?: 'chat' | 'welcome'; }; export default function HelpScreen({onBackDestination = 'chat'}: Props) { const {theme} = useTheme(); const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.helpPanel.title}`); useInput((input, key) => { if (key.escape) { navigateTo(onBackDestination); return; } // Allow 'q' as a secondary exit key (common in pagers). if (input === 'q' || input === 'Q') { navigateTo(onBackDestination); } }); return ( {t.chatScreen.pressEscToClose} ); } ================================================ FILE: source/ui/pages/HooksConfigScreen.tsx ================================================ import React, {useState, useCallback} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import {Alert} from '@inkjs/ui'; import Menu from '../components/common/Menu.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useI18n} from '../../i18n/index.js'; import { getAllHookTypes, listConfiguredHooks, loadHookConfig, saveHookConfig, deleteHookConfig, type HookType, type HookScope, type HookRule, type HookAction, type HookActionType, isActionTypeAllowed, } from '../../utils/config/hooksConfig.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; defaultScopeIndex?: number; onScopeSelectionPersist?: (index: number) => void; }; type Screen = | 'scope-select' // 选择作用域（全局/项目） | 'hook-list' // Hook 列表 | 'hook-detail' // Hook 详情 | 'rule-edit' // 编辑规则 | 'action-edit'; // 编辑动作 type RuleField = 'description' | 'matcher'; type ActionField = 'enabled' | 'type' | 'command' | 'prompt' | 'timeout'; export default function HooksConfigScreen({ onBack, defaultScopeIndex = 0, onScopeSelectionPersist, }: Props) { const {theme} = useTheme(); const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.hooksConfig.title}`); const [screen, setScreen] = useState('scope-select'); const [selectedScope, setSelectedScope] = useState('project'); const [selectedHookType, setSelectedHookType] = useState( null, ); const [selectedRuleIndex, setSelectedRuleIndex] = useState(-1); const [editingRule, setEditingRule] = useState(null); const [selectedHookInfo, setSelectedHookInfo] = useState(''); // Track the scope menu index for persistence const [scopeMenuIndex, setScopeMenuIndex] = useState(defaultScopeIndex); // Sync with parent's defaultScopeIndex when it changes React.useEffect(() => { setScopeMenuIndex(defaultScopeIndex); }, [defaultScopeIndex]); // 规则编辑状态 const [editingRuleField, setEditingRuleField] = useState( null, ); const [ruleFieldValue, setRuleFieldValue] = useState(''); // Action 编辑状态 const [selectedActionIndex, setSelectedActionIndex] = useState(-1); const [editingAction, setEditingAction] = useState(null); const [editingActionField, setEditingActionField] = useState(null); const [actionFieldValue, setActionFieldValue] = useState(''); // 验证是否可以添加指定类型的 Action const canAddActionType = useCallback( (newType: HookActionType, currentHooks: HookAction[]): boolean => { if ( !selectedHookType || !isActionTypeAllowed(selectedHookType, newType) ) { return false; } // prompt 和 command 互斥：prompt 独占，command 不能与 prompt 共存 if (newType === 'prompt') { return currentHooks.length === 0; } if (newType === 'command') { return !currentHooks.some(h => h.type === 'prompt'); } return false; }, [selectedHookType], ); // 返回上一级 const handleBack = useCallback(() => { if (screen === 'scope-select') { onBack(); } else if (screen === 'hook-list') { setScreen('scope-select'); } else if (screen === 'hook-detail') { setScreen('hook-list'); setSelectedHookType(null); } else if (screen === 'rule-edit') { setScreen('hook-detail'); setEditingRule(null); setSelectedRuleIndex(-1); setEditingRuleField(null); } else if (screen === 'action-edit') { setScreen('rule-edit'); setEditingAction(null); setSelectedActionIndex(-1); setEditingActionField(null); } }, [screen, onBack]); // 作用域选择 const renderScopeSelect = () => { const options = [ { label: t.hooksConfig.scopeSelect.globalHooks, value: 'global', infoText: t.hooksConfig.scopeSelect.globalInfo, color: theme.colors.menuInfo, }, { label: t.hooksConfig.scopeSelect.projectHooks, value: 'project', infoText: t.hooksConfig.scopeSelect.projectInfo, color: theme.colors.success, }, { label: t.hooksConfig.scopeSelect.back, value: 'back', infoText: t.hooksConfig.scopeSelect.backInfo, color: theme.colors.error, }, ]; return ( <> { if (value === 'back') { onBack(); } else { setSelectedScope(value as HookScope); setScreen('hook-list'); } }} onSelectionChange={(infoText, value) => { setSelectedHookInfo(infoText); // Find index and persist const index = options.findIndex(opt => opt.value === value); if (index !== -1) { setScopeMenuIndex(index); onScopeSelectionPersist?.(index); } }} /> {selectedHookInfo && ( {selectedHookInfo} )} ); }; // Hook 类型列表 const renderHookList = () => { const allHooks = getAllHookTypes(); const configuredHooks = listConfiguredHooks(selectedScope); const options = allHooks.map(hookType => { const isConfigured = configuredHooks.includes(hookType); const rules = isConfigured ? loadHookConfig(hookType, selectedScope) : []; const ruleCount = rules.length; const icon = isConfigured ? '[✓]' : '[ ]'; return { label: `${icon} ${hookType}${ ruleCount > 0 ? ` (${ruleCount} ${t.hooksConfig.hookList.rules})` : '' }`, value: hookType, infoText: (t.hooksConfig.hookTypes as any)[hookType] || hookType, color: isConfigured ? theme.colors.success : theme.colors.menuNormal, }; }); options.push({ label: t.hooksConfig.hookList.back, value: 'back' as any, infoText: t.hooksConfig.hookList.backInfo, color: theme.colors.error, }); return ( <> {t.hooksConfig.hookList.title} -{' '} {selectedScope === 'global' ? t.hooksConfig.hookList.global : t.hooksConfig.hookList.project} { if (value === 'back') { handleBack(); } else { setSelectedHookType(value as HookType); setScreen('hook-detail'); } }} onSelectionChange={infoText => { setSelectedHookInfo(infoText); }} /> ); }; // Hook 详情页面 const renderHookDetail = () => { if (!selectedHookType) return null; const rules = loadHookConfig(selectedHookType, selectedScope); // 只有工具Hooks才显示matcher信息 const isToolHook = selectedHookType === 'beforeToolCall' || selectedHookType === 'toolConfirmation' || selectedHookType === 'afterToolCall'; const options = rules.map((rule, index) => ({ label: `${t.hooksConfig.hookDetail.rule} ${index + 1}: ${ rule.description }`, value: `rule-${index}`, infoText: `${rule.hooks.length} ${t.hooksConfig.hookDetail.actions}${ isToolHook && rule.matcher ? ` | ${t.hooksConfig.hookDetail.matcher}: ${rule.matcher}` : '' }`, color: theme.colors.menuNormal, })); options.push( { label: t.hooksConfig.hookDetail.addNewRule, value: 'add', infoText: t.hooksConfig.hookDetail.addNewRuleInfo, color: theme.colors.success, }, { label: t.hooksConfig.hookDetail.deleteHook, value: 'delete', infoText: t.hooksConfig.hookDetail.deleteHookInfo, color: theme.colors.warning, }, { label: t.hooksConfig.hookDetail.back, value: 'back', infoText: t.hooksConfig.hookDetail.backInfo, color: theme.colors.error, }, ); return ( <> {selectedHookType} {(t.hooksConfig.hookTypes as any)[selectedHookType] || selectedHookType} { if (value === 'back') { handleBack(); } else if (value === 'add') { // 创建新规则 setEditingRule({ description: 'New Rule', hooks: [], }); setSelectedRuleIndex(-1); setScreen('rule-edit'); } else if (value === 'delete') { // 删除配置 deleteHookConfig(selectedHookType, selectedScope); handleBack(); } else { // 编辑规则 const index = parseInt(value.replace('rule-', '')); setSelectedRuleIndex(index); setEditingRule({...rules[index]!}); setScreen('rule-edit'); } }} /> ); }; // 规则编辑页面 const renderRuleEdit = () => { if (!editingRule || !selectedHookType) return null; // 如果正在编辑字段，显示输入框 if (editingRuleField) { const isMatcherField = editingRuleField === 'matcher'; return ( {editingRuleField === 'description' ? t.hooksConfig.ruleEdit.editDescription : t.hooksConfig.ruleEdit.editMatcher} {isMatcherField && ( {t.hooksConfig.ruleEdit.matcherHint} )} > { // 保存字段值 setEditingRule({ ...editingRule, [editingRuleField]: ruleFieldValue, }); setEditingRuleField(null); setRuleFieldValue(''); }} /> {t.hooksConfig.ruleEdit.enterToSave} ); } // 只有工具Hooks才需要matcher const isToolHook = selectedHookType === 'beforeToolCall' || selectedHookType === 'toolConfirmation' || selectedHookType === 'afterToolCall'; const options = [ { label: `${t.hooksConfig.ruleEdit.editDescriptionLabel}: ${editingRule.description}`, value: 'edit-description', infoText: t.hooksConfig.ruleEdit.clickToEdit, color: theme.colors.menuInfo, }, ]; // 只有工具Hooks才显示matcher选项 if (isToolHook) { options.push({ label: `${t.hooksConfig.ruleEdit.editMatcherLabel}: ${ editingRule.matcher || t.hooksConfig.actionEdit.commandNotSet }`, value: 'edit-matcher', infoText: t.hooksConfig.ruleEdit.clickToEditMatcher, color: theme.colors.menuInfo, }); } // 显示所有 actions editingRule.hooks.forEach((action, index) => { const enabled = action.enabled !== false; const enabledIcon = enabled ? '[✓]' : '[ ]'; const actionLabel = action.type === 'command' ? `${action.command || ''}` : `${action.prompt || ''}`; const label = `${enabledIcon} ${index + 1}. ${ action.type }: ${actionLabel}`; options.push({ label, value: `action-${index}`, infoText: action.timeout ? `Timeout: ${action.timeout}ms` : 'No timeout', color: enabled ? theme.colors.menuNormal : theme.colors.menuSecondary, }); }); options.push( { label: t.hooksConfig.ruleEdit.addAction, value: 'add-action', infoText: t.hooksConfig.ruleEdit.addActionInfo, color: theme.colors.success, }, { label: t.hooksConfig.ruleEdit.deleteRule, value: 'delete-rule', infoText: t.hooksConfig.ruleEdit.deleteRuleInfo, color: theme.colors.warning, }, { label: t.hooksConfig.ruleEdit.saveRule, value: 'save', infoText: t.hooksConfig.ruleEdit.saveRuleInfo, color: theme.colors.success, }, { label: t.hooksConfig.ruleEdit.cancel, value: 'back', infoText: t.hooksConfig.ruleEdit.cancelInfo, color: theme.colors.error, }, ); return ( <> {t.hooksConfig.ruleEdit.title} {t.hooksConfig.ruleEdit.hint} { if (value === 'back') { handleBack(); } else if (value === 'save') { // 保存规则 const rules = loadHookConfig(selectedHookType, selectedScope); if (selectedRuleIndex >= 0) { // 更新现有规则 rules[selectedRuleIndex] = editingRule; } else { // 添加新规则 rules.push(editingRule); } saveHookConfig(selectedHookType, selectedScope, rules); handleBack(); } else if (value === 'add-action') { // 添加默认 action // 检查当前 hooks 中的类型，决定新 Action 的默认类型 const currentHooks = editingRule.hooks; const hasPrompt = currentHooks.some(h => h.type === 'prompt'); if (hasPrompt) { // 已有 Prompt，不能再添加任何 Action return; } // 决定新 Action 的默认类型 // 如果是 onSubAgentComplete 或 onStop，且没有现有 hooks，默认为 prompt // 否则只能使用 command const defaultType: HookActionType = (selectedHookType === 'onSubAgentComplete' || selectedHookType === 'onStop') && currentHooks.length === 0 ? 'prompt' : 'command'; const newAction: HookAction = defaultType === 'prompt' ? { type: 'prompt', prompt: 'What should I do next?', timeout: 30000, enabled: true, } : { type: 'command', command: 'echo "Hello from hook"', timeout: 5000, enabled: true, }; setEditingRule({ ...editingRule, hooks: [...editingRule.hooks, newAction], }); } else if (value === 'delete-rule') { // 删除当前规则 const rules = loadHookConfig(selectedHookType, selectedScope); if (selectedRuleIndex >= 0) { rules.splice(selectedRuleIndex, 1); saveHookConfig(selectedHookType, selectedScope, rules); } handleBack(); } else if (value === 'edit-description') { setEditingRuleField('description'); setRuleFieldValue(editingRule.description); } else if (value === 'edit-matcher') { setEditingRuleField('matcher'); setRuleFieldValue(editingRule.matcher || ''); } else if (value.startsWith('action-')) { // 编辑 action const index = parseInt(value.replace('action-', '')); setSelectedActionIndex(index); setEditingAction({...editingRule.hooks[index]!}); setScreen('action-edit'); } }} /> ); }; // Action 编辑页面 const renderActionEdit = () => { if (!editingAction || !editingRule) return null; // 如果正在编辑字段，显示输入框 if ( editingActionField && editingActionField !== 'enabled' && editingActionField !== 'type' ) { return ( 编辑 {editingActionField} > { // 保存字段值 const value = editingActionField === 'timeout' ? actionFieldValue ? parseInt(actionFieldValue) : undefined : actionFieldValue || undefined; setEditingAction({ ...editingAction, [editingActionField]: value, }); setEditingActionField(null); setActionFieldValue(''); }} /> {t.hooksConfig.actionEdit.enterToSave} ); } const enabled = editingAction.enabled !== false; const enabledIcon = enabled ? '[✓]' : '[ ]'; const options = [ { label: `${enabledIcon} ${t.hooksConfig.actionEdit.enabled}`, value: 'enabled', infoText: t.hooksConfig.actionEdit.enabledInfo, color: enabled ? theme.colors.success : theme.colors.menuSecondary, }, { label: `${t.hooksConfig.actionEdit.type}: ${editingAction.type}`, value: 'type', infoText: t.hooksConfig.actionEdit.typeInfo, color: theme.colors.menuInfo, }, ]; if (editingAction.type === 'command') { options.push({ label: `${t.hooksConfig.actionEdit.command}: ${ editingAction.command || t.hooksConfig.actionEdit.commandNotSet }`, value: 'command', infoText: t.hooksConfig.actionEdit.commandInfo, color: theme.colors.menuNormal, }); } else { options.push({ label: `${t.hooksConfig.actionEdit.prompt}: ${ editingAction.prompt || t.hooksConfig.actionEdit.promptNotSet }`, value: 'prompt', infoText: t.hooksConfig.actionEdit.promptInfo, color: theme.colors.menuNormal, }); } options.push( { label: `${t.hooksConfig.actionEdit.timeout}: ${ editingAction.timeout || t.hooksConfig.actionEdit.commandNotSet }`, value: 'timeout', infoText: t.hooksConfig.actionEdit.timeoutInfo, color: theme.colors.menuNormal, }, { label: t.hooksConfig.actionEdit.deleteAction, value: 'delete', infoText: t.hooksConfig.actionEdit.deleteActionInfo, color: theme.colors.warning, }, { label: t.hooksConfig.actionEdit.saveAction, value: 'save', infoText: t.hooksConfig.actionEdit.saveActionInfo, color: theme.colors.success, }, { label: t.hooksConfig.actionEdit.cancel, value: 'back', infoText: t.hooksConfig.actionEdit.cancelInfo, color: theme.colors.error, }, ); return ( <> {t.hooksConfig.actionEdit.title} {t.hooksConfig.actionEdit.hint} { if (value === 'back') { handleBack(); } else if (value === 'save') { // 保存 action const newHooks = [...editingRule.hooks]; if (selectedActionIndex >= 0) { newHooks[selectedActionIndex] = editingAction; } else { newHooks.push(editingAction); } setEditingRule({ ...editingRule, hooks: newHooks, }); handleBack(); } else if (value === 'delete') { // 删除 action const newHooks = editingRule.hooks.filter( (_, i) => i !== selectedActionIndex, ); setEditingRule({ ...editingRule, hooks: newHooks, }); handleBack(); } else if (value === 'enabled') { // 切换启用状态 setEditingAction({ ...editingAction, enabled: !enabled, }); } else if (value === 'type') { // 切换类型 const newType: HookActionType = editingAction.type === 'command' ? 'prompt' : 'command'; // 检查规则中除当前 Action 外的其他 Actions const otherActions = editingRule.hooks.filter( (_, i) => i !== selectedActionIndex, ); // 验证是否可以切换到新类型 if (!canAddActionType(newType, otherActions)) { // 不能切换类型，因为与现有 Actions 冲突 // 这里可以显示错误提示，暂时直接返回 return; } setEditingAction({ ...editingAction, type: newType, // 清除旧类型的字段 command: newType === 'command' ? editingAction.command : undefined, prompt: newType === 'prompt' ? editingAction.prompt : undefined, }); } else if (value === 'command') { setEditingActionField('command'); setActionFieldValue(editingAction.command || ''); } else if (value === 'prompt') { setEditingActionField('prompt'); setActionFieldValue(editingAction.prompt || ''); } else if (value === 'timeout') { setEditingActionField('timeout'); setActionFieldValue(editingAction.timeout?.toString() || ''); } }} /> ); }; // 处理键盘快捷键 useInput( (input, key) => { if (key.escape) { // 如果正在编辑字段，先取消编辑 if (editingRuleField) { setEditingRuleField(null); setRuleFieldValue(''); } else if (editingActionField) { setEditingActionField(null); setActionFieldValue(''); } else { // 否则返回上一级 handleBack(); } } else if (input === 'd' || input === 'D') { // D 键删除规则或 Action // 如果正在编辑字段，忽略 if (editingRuleField || editingActionField) { return; } if (screen === 'rule-edit' && editingRule && selectedHookType) { // 删除当前规则 const rules = loadHookConfig(selectedHookType, selectedScope); if (selectedRuleIndex >= 0) { rules.splice(selectedRuleIndex, 1); saveHookConfig(selectedHookType, selectedScope, rules); } handleBack(); } else if ( screen === 'action-edit' && editingAction && editingRule && selectedActionIndex >= 0 ) { // 删除当前 Action const newHooks = editingRule.hooks.filter( (_, i) => i !== selectedActionIndex, ); setEditingRule({ ...editingRule, hooks: newHooks, }); handleBack(); } } }, {isActive: true}, ); // 根据当前屏幕渲染 return ( {screen === 'scope-select' && renderScopeSelect()} {screen === 'hook-list' && renderHookList()} {screen === 'hook-detail' && renderHookDetail()} {screen === 'rule-edit' && renderRuleEdit()} {screen === 'action-edit' && renderActionEdit()} {selectedHookInfo && screen === 'hook-list' && ( {selectedHookInfo} )} ); } ================================================ FILE: source/ui/pages/LanguageSettingsScreen.tsx ================================================ import React, {useState, useCallback} from 'react'; import {Box, Text, useInput} from 'ink'; import Menu from '../components/common/Menu.js'; import {useI18n} from '../../i18n/index.js'; import type {Language} from '../../utils/config/languageConfig.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; inlineMode?: boolean; }; export default function LanguageSettingsScreen({ onBack, inlineMode = false, }: Props) { const {language, setLanguage, t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.welcome.languageSettings}`); const {theme} = useTheme(); const [selectedLanguage, setSelectedLanguage] = useState(language); const languageOptions = [ { label: 'English', value: 'en', infoText: 'Switch to English', }, { label: '简体中文', value: 'zh', infoText: '切换到简体中文', }, { label: '繁體中文', value: 'zh-TW', infoText: '切換到繁體中文', }, { label: '← Back', value: 'back', color: theme.colors.menuSecondary, infoText: 'Return to main menu', }, ]; const handleSelect = useCallback( (value: string) => { if (value === 'back') { onBack(); } else { const newLang = value as Language; setSelectedLanguage(newLang); setLanguage(newLang); // Auto return to menu after selection setTimeout(() => { onBack(); }, 300); } }, [onBack, setLanguage], ); const handleSelectionChange = useCallback((_infoText: string) => { // Could update some info display here if needed }, []); useInput((_input, key) => { if (key.escape) { onBack(); } }); return ( {!inlineMode && ( Language Settings / 语言设置 )} Current:{' '} {selectedLanguage === 'en' ? 'English' : selectedLanguage === 'zh' ? '简体中文' : '繁體中文'} ); } ================================================ FILE: source/ui/pages/MCPConfigScreen.tsx ================================================ import React, {useEffect, useState} from 'react'; import {Box, Text, useInput} from 'ink'; import {spawn, execSync} from 'child_process'; import {writeFileSync, readFileSync, existsSync, mkdirSync} from 'fs'; import {join} from 'path'; import {platform} from 'os'; import { getGlobalMCPConfig, getProjectMCPConfig, getGlobalMCPConfigFilePath, validateMCPConfig, type MCPConfigScope, } from '../../utils/config/apiConfig.js'; import {useI18n} from '../../i18n/I18nContext.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; onSave: () => void; }; function checkCommandExists(command: string): boolean { if (platform() === 'win32') { try { execSync(`where ${command}`, { stdio: 'ignore', windowsHide: true, }); return true; } catch { return false; } } const shells = ['/bin/sh', '/bin/bash', '/bin/zsh']; for (const shell of shells) { try { execSync(`command -v ${command}`, { stdio: 'ignore', shell, env: process.env, }); return true; } catch { // Try next shell } } return false; } function getSystemEditor(): string | null { const envEditor = process.env['VISUAL'] || process.env['EDITOR']; if (envEditor && checkCommandExists(envEditor)) { return envEditor; } if (platform() === 'win32') { const windowsEditors = ['notepad++', 'notepad', 'code', 'vim', 'nano']; for (const editor of windowsEditors) { if (checkCommandExists(editor)) { return editor; } } return null; } const editors = ['nano', 'vim', 'vi']; for (const editor of editors) { if (checkCommandExists(editor)) { return editor; } } return null; } function getConfigFilePath(scope: MCPConfigScope): string { if (scope === 'project') { return join(process.cwd(), '.snow', 'mcp-config.json'); } return getGlobalMCPConfigFilePath(); } function getConfigByScope(scope: MCPConfigScope) { return scope === 'project' ? getProjectMCPConfig() : getGlobalMCPConfig(); } interface I18nMessages { savedSuccess: string; configErrors: string; reverted: string; invalidJson: string; scopeProjectLabel: string; scopeGlobalLabel: string; } function openEditorForScope( scope: MCPConfigScope, onBack: () => void, i18nMessages: I18nMessages, ) { const configFilePath = getConfigFilePath(scope); const config = getConfigByScope(scope); const originalContent = JSON.stringify(config, null, 2); const dir = join(configFilePath, '..'); if (!existsSync(dir)) { mkdirSync(dir, {recursive: true}); } writeFileSync(configFilePath, originalContent, 'utf8'); const editor = getSystemEditor(); if (!editor) { console.error( 'No text editor found! Please set the EDITOR or VISUAL environment variable.', ); console.error(''); console.error('Examples:'); if (platform() === 'win32') { console.error(' set EDITOR=notepad'); console.error(' set EDITOR=code'); console.error(' set EDITOR=notepad++'); } else { console.error(' export EDITOR=nano'); console.error(' export EDITOR=vim'); console.error(' export EDITOR=code'); } console.error(''); console.error('Or install a text editor:'); if (platform() === 'win32') { console.error(' Windows: Notepad++ or VS Code'); } else { console.error(' Ubuntu/Debian: sudo apt-get install nano'); console.error(' CentOS/RHEL: sudo yum install nano'); console.error(' macOS: nano is usually pre-installed'); } onBack(); return; } if (process.stdin.isTTY) { process.stdin.pause(); } const child = spawn(editor, [configFilePath], { stdio: 'inherit', }); child.on('close', () => { if (process.stdin.isTTY) { process.stdin.resume(); process.stdin.setRawMode(true); } if (existsSync(configFilePath)) { try { const editedContent = readFileSync(configFilePath, 'utf8'); const parsedConfig = JSON.parse(editedContent); const validationErrors = validateMCPConfig(parsedConfig); if (validationErrors.length === 0) { const scopeLabel = scope === 'project' ? i18nMessages.scopeProjectLabel : i18nMessages.scopeGlobalLabel; console.log(i18nMessages.savedSuccess.replace('{scope}', scopeLabel)); } else { writeFileSync(configFilePath, originalContent, 'utf8'); console.error( i18nMessages.configErrors.replace( '{errors}', validationErrors.join(', '), ), ); console.error(i18nMessages.reverted); } } catch { writeFileSync(configFilePath, originalContent, 'utf8'); console.error(i18nMessages.invalidJson); } } onBack(); }); child.on('error', error => { if (process.stdin.isTTY) { process.stdin.resume(); process.stdin.setRawMode(true); } console.error('Failed to open editor:', error.message); onBack(); }); } export default function MCPConfigScreen({onBack}: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.mcpConfigScreen.title}`); const {theme} = useTheme(); const [selectedIndex, setSelectedIndex] = useState(0); const [editing, setEditing] = useState(false); const options: Array<{label: string; desc: string; scope: MCPConfigScope}> = [ { label: t.mcpConfigScreen.scopeProject, desc: '.snow/mcp-config.json', scope: 'project', }, { label: t.mcpConfigScreen.scopeGlobal, desc: '~/.snow/mcp-config.json', scope: 'global', }, ]; useInput((_input, key) => { if (editing) return; if (key.escape) { onBack(); return; } if (key.upArrow) { setSelectedIndex(prev => (prev > 0 ? prev - 1 : options.length - 1)); return; } if (key.downArrow) { setSelectedIndex(prev => (prev < options.length - 1 ? prev + 1 : 0)); return; } if (key.return) { setEditing(true); } }); useEffect(() => { if (!editing) return; const scope = options[selectedIndex]!.scope; openEditorForScope(scope, onBack, { savedSuccess: t.mcpConfigScreen.savedSuccess, configErrors: t.mcpConfigScreen.configErrors, reverted: t.mcpConfigScreen.reverted, invalidJson: t.mcpConfigScreen.invalidJson, scopeProjectLabel: t.mcpConfigScreen.scopeProject, scopeGlobalLabel: t.mcpConfigScreen.scopeGlobal, }); }, [editing]); if (editing) { return null; } return ( {t.mcpConfigScreen.title} {options.map((opt, idx) => { const isSelected = idx === selectedIndex; return ( {isSelected ? '❯ ' : ' '} {opt.label} {opt.desc} ); })} {t.mcpConfigScreen.navigationHint} ); } ================================================ FILE: source/ui/pages/PixelEditorScreen.tsx ================================================ import React, {useState, useEffect, useCallback, useMemo} from 'react'; import {Box, Text, useInput} from 'ink'; import {PixelEditor} from '../components/pixel-editor/index.js'; import {useI18n} from '../../i18n/index.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; import {navigateTo} from '../../hooks/integration/useGlobalNavigation.js'; import type {PixelGrid} from '../components/pixel-editor/types.js'; import {homedir} from 'os'; import {join} from 'path'; import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, statSync, } from 'fs'; const DRAW_DIR = join(homedir(), '.snow', 'draw'); const EXIT_IMAGE_PATH = join(homedir(), '.snow', 'exit-image.json'); function ensureDrawDir(): void { if (!existsSync(DRAW_DIR)) { mkdirSync(DRAW_DIR, {recursive: true}); } } function sanitizeFileName(name: string): string { return name.replace(/[^a-zA-Z0-9\u4e00-\u9fa5_-]/g, '_'); } function cropGrid(grid: PixelGrid): PixelGrid { if (!grid || grid.length === 0) return []; const height = grid.length; const width = grid[0]?.length ?? 0; let minY = height; let maxY = -1; let minX = width; let maxX = -1; for (let y = 0; y < height; y++) { for (let x = 0; x < width; x++) { if (grid[y]![x] !== '#000000') { minY = Math.min(minY, y); maxY = Math.max(maxY, y); minX = Math.min(minX, x); maxX = Math.max(maxX, x); } } } if (maxY < 0) return []; return grid.slice(minY, maxY + 1).map(row => row.slice(minX, maxX + 1)); } interface DrawingFile { name: string; fileName: string; updatedAt: string; } type View = 'menu' | 'editor' | 'manager'; type Props = { onBack?: () => void; }; export default function PixelEditorScreen({onBack}: Props) { const {t} = useI18n(); const ts = t.pixelEditorScreen; useTerminalTitle(`Snow CLI - ${ts.screenTitle}`); const [view, setView] = useState('menu'); const [editorReturnView, setEditorReturnView] = useState('menu'); const [editorKey, setEditorKey] = useState(0); const [initialGrid, setInitialGrid] = useState( undefined, ); const [editorInitialName, setEditorInitialName] = useState< string | undefined >(undefined); const [drawings, setDrawings] = useState([]); const [selectedIndex, setSelectedIndex] = useState(0); const [selectedNames, setSelectedNames] = useState>(new Set()); const [pendingDelete, setPendingDelete] = useState(false); const [message, setMessage] = useState(null); const [exitImageName, setExitImageName] = useState( undefined, ); const [exitImageEnabled, setExitImageEnabled] = useState(false); const loadDrawings = useCallback(() => { ensureDrawDir(); try { const files = readdirSync(DRAW_DIR) .filter(f => f.endsWith('.json')) .map(f => { const filePath = join(DRAW_DIR, f); try { const content = readFileSync(filePath, 'utf8'); const data = JSON.parse(content) as { name?: string; updatedAt?: string; }; const stat = statSync(filePath); return { name: data.name ?? f.replace(/\.json$/, ''), fileName: f, updatedAt: data.updatedAt ?? stat.mtime.toISOString(), }; } catch { return null; } }) .filter((d): d is DrawingFile => d !== null) .sort( (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(), ); setDrawings(files); } catch { setDrawings([]); } }, []); useEffect(() => { if (view === 'manager') { loadDrawings(); if (existsSync(EXIT_IMAGE_PATH)) { try { const content = readFileSync(EXIT_IMAGE_PATH, 'utf8'); const data = JSON.parse(content) as { name?: string; enabled?: boolean; }; setExitImageName(data.name); setExitImageEnabled(data.enabled ?? true); } catch { setExitImageName(undefined); setExitImageEnabled(false); } } else { setExitImageName(undefined); setExitImageEnabled(false); } } }, [view, loadDrawings]); useEffect(() => { setSelectedIndex(prev => { if (drawings.length === 0) return 0; return Math.min(prev, drawings.length - 1); }); }, [drawings.length]); useEffect(() => { if (!message) return; const id = setTimeout(() => setMessage(null), 1500); return () => clearTimeout(id); }, [message]); const handleSave = useCallback( (grid: PixelGrid, name: string) => { ensureDrawDir(); const safeName = sanitizeFileName(name); const filePath = join(DRAW_DIR, `${safeName}.json`); const data = { name, width: grid[0]?.length ?? 32, height: grid.length, grid, updatedAt: new Date().toISOString(), }; writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8'); if (exitImageEnabled && exitImageName === name) { try { const cropped = cropGrid(grid); const exitData = { name, width: cropped[0]?.length ?? 0, height: cropped.length, grid: cropped, enabled: true, updatedAt: new Date().toISOString(), }; writeFileSync( EXIT_IMAGE_PATH, JSON.stringify(exitData, null, 2), 'utf8', ); } catch { // ignore sync errors } } }, [exitImageEnabled, exitImageName], ); const handleLoad = useCallback((fileName: string): PixelGrid | undefined => { const filePath = join(DRAW_DIR, fileName); if (!existsSync(filePath)) return undefined; try { const content = readFileSync(filePath, 'utf8'); const data = JSON.parse(content) as {grid?: PixelGrid}; if (data.grid) { return data.grid.map(row => [...row]); } } catch { // ignore } return undefined; }, []); const deleteSelected = useCallback(() => { for (const name of selectedNames) { const filePath = join(DRAW_DIR, name); try { unlinkSync(filePath); } catch { // ignore } } setSelectedNames(new Set()); setPendingDelete(false); loadDrawings(); }, [selectedNames, loadDrawings]); const maxVisibleItems = 8; const displayWindow = useMemo(() => { if (drawings.length <= maxVisibleItems) { return { items: drawings, startIndex: 0, endIndex: drawings.length, }; } let startIndex = 0; if (selectedIndex >= maxVisibleItems) { startIndex = selectedIndex - maxVisibleItems + 1; } const endIndex = Math.min(drawings.length, startIndex + maxVisibleItems); return { items: drawings.slice(startIndex, endIndex), startIndex, endIndex, }; }, [drawings, selectedIndex]); useInput((input, key) => { if (view === 'menu') { if (key.escape || input === 'q' || input === 'Q') { if (onBack) { onBack(); } else { navigateTo('chat'); } return; } if (key.upArrow) { setSelectedIndex(prev => (prev > 0 ? prev - 1 : 1)); return; } if (key.downArrow) { setSelectedIndex(prev => (prev < 1 ? prev + 1 : 0)); return; } if (key.return) { if (selectedIndex === 0) { setInitialGrid(undefined); setEditorInitialName(undefined); setEditorKey(k => k + 1); setEditorReturnView('menu'); setView('editor'); } else { setSelectedIndex(0); setSelectedNames(new Set()); setPendingDelete(false); setView('manager'); } return; } return; } if (view === 'manager') { if (key.escape) { if (pendingDelete) { setPendingDelete(false); return; } setSelectedNames(new Set()); setSelectedIndex(0); setView('menu'); return; } if (pendingDelete) { if ( key.return || input === 'd' || input === 'D' || input === 'y' || input === 'Y' ) { deleteSelected(); return; } if (input === 'n' || input === 'N') { setPendingDelete(false); return; } return; } if (key.upArrow) { setSelectedIndex(prev => prev > 0 ? prev - 1 : Math.max(0, drawings.length - 1), ); return; } if (key.downArrow) { const maxIndex = Math.max(0, drawings.length - 1); setSelectedIndex(prev => (prev < maxIndex ? prev + 1 : 0)); return; } if (input === ' ') { const current = drawings[selectedIndex]; if (current) { setSelectedNames(prev => { const next = new Set(prev); if (next.has(current.fileName)) { next.delete(current.fileName); } else { next.add(current.fileName); } return next; }); } return; } if (input === 'd' || input === 'D') { if (selectedNames.size > 0) { setPendingDelete(true); } return; } if (input === 's' || input === 'S') { const current = drawings[selectedIndex]; if (current) { if (exitImageEnabled && exitImageName === current.name) { try { writeFileSync( EXIT_IMAGE_PATH, JSON.stringify({enabled: false}, null, 2), 'utf8', ); setExitImageEnabled(false); setExitImageName(undefined); setMessage(ts.exitImageDisabled); } catch { setMessage(ts.failedDisableExitImage); } } else { const grid = handleLoad(current.fileName); if (grid) { const cropped = cropGrid(grid); const data = { name: current.name, width: cropped[0]?.length ?? 0, height: cropped.length, grid: cropped, enabled: true, updatedAt: new Date().toISOString(), }; writeFileSync( EXIT_IMAGE_PATH, JSON.stringify(data, null, 2), 'utf8', ); setExitImageName(current.name); setExitImageEnabled(true); setMessage(ts.setAsExitImage.replace('{name}', current.name)); } } } return; } if (key.return) { const current = drawings[selectedIndex]; if (current) { const grid = handleLoad(current.fileName); if (grid) { setInitialGrid(grid); setEditorInitialName(current.name); setEditorKey(k => k + 1); setEditorReturnView('manager'); setView('editor'); } } return; } return; } }); const hiddenAboveCount = displayWindow.startIndex; const hiddenBelowCount = Math.max( 0, drawings.length - displayWindow.endIndex, ); const showOverflowHint = drawings.length > maxVisibleItems; if (view === 'editor') { return ( { setView(editorReturnView); setInitialGrid(undefined); }} onSave={handleSave} /> ); } if (view === 'manager') { return ( {ts.manageTitle} {drawings.length === 0 ? ( {ts.noDrawings} ) : ( displayWindow.items.map((drawing, index) => { const originalIndex = displayWindow.startIndex + index; const isSelected = originalIndex === selectedIndex; const isChecked = selectedNames.has(drawing.fileName); const isExitImage = exitImageEnabled && exitImageName === drawing.name; return ( {isSelected ? '❯ ' : ' '} {isChecked ? '[✓]' : '[ ]'} {drawing.name} {isExitImage ? ' ★' : ''} ); }) )} {pendingDelete ? ts.confirmDeleteMany.replace( '{count}', String(selectedNames.size), ) : ts.managerHint} {showOverflowHint && hiddenAboveCount > 0 && ( {ts.moreAbove.replace('{count}', String(hiddenAboveCount))} )} {showOverflowHint && hiddenBelowCount > 0 && ( {ts.moreBelow.replace('{count}', String(hiddenBelowCount))} )} {selectedNames.size > 0 && !pendingDelete && ( {ts.selectedCount.replace('{count}', String(selectedNames.size))} )} {message && {message}} ); } // menu const menuItems = [ts.newCanvas, ts.manageDrawings]; return ( {ts.screenTitle} {menuItems.map((item, index) => ( {selectedIndex === index ? '❯ ' : ' '} {item} ))} {ts.menuNavigateHint} ); } ================================================ FILE: source/ui/pages/ProxyConfigScreen.tsx ================================================ import React, {useState, useEffect} from 'react'; import {Box, Newline, Text, useInput} from 'ink'; import Gradient from 'ink-gradient'; import {Alert} from '@inkjs/ui'; import TextInput from 'ink-text-input'; import { getProxyConfig, updateProxyConfig, type ProxyConfig, type SearchEngineId, } from '../../utils/config/proxyConfig.js'; import { listSearchEngines, listSearchEnginesAsync, } from '../../mcp/engines/websearch/index.js'; import {useI18n} from '../../i18n/index.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; import ScrollableSelectInput from '../components/common/ScrollableSelectInput.js'; type Props = { onBack: () => void; onSave: () => void; inlineMode?: boolean; }; export default function ProxyConfigScreen({ onBack, onSave, inlineMode = false, }: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.proxyConfig.title}`); const {theme} = useTheme(); const [enabled, setEnabled] = useState(false); const [port, setPort] = useState('7890'); const [browserPath, setBrowserPath] = useState(''); const [searchEngine, setSearchEngine] = useState('duckduckgo'); const [currentField, setCurrentField] = useState< 'enabled' | 'searchEngine' | 'port' | 'browserPath' >('enabled'); const [errors, setErrors] = useState([]); const [isEditing, setIsEditing] = useState(false); // Available search engines (built-ins plus user plugins under // ~/.snow/plugin/search_engines/). Start with built-ins synchronously then // merge in plugin engines once they finish loading. const [availableEngines, setAvailableEngines] = useState(() => listSearchEngines(), ); useEffect(() => { const config = getProxyConfig(); setEnabled(config.enabled); setPort(config.port.toString()); setBrowserPath(config.browserPath || ''); setSearchEngine(config.searchEngine || 'duckduckgo'); let cancelled = false; void listSearchEnginesAsync().then(engines => { if (!cancelled) setAvailableEngines(engines); }); return () => { cancelled = true; }; }, []); const validateConfig = (): string[] => { const validationErrors: string[] = []; const portNum = parseInt(port, 10); if (isNaN(portNum) || portNum < 1 || portNum > 65535) { validationErrors.push(t.proxyConfig.portValidationError); } return validationErrors; }; const saveConfig = async () => { const validationErrors = validateConfig(); if (validationErrors.length === 0) { const config: ProxyConfig = { enabled, port: parseInt(port, 10), browserPath: browserPath.trim() || undefined, searchEngine, }; await updateProxyConfig(config); setErrors([]); return true; } else { setErrors(validationErrors); return false; } }; useInput((input, key) => { // Handle save/exit globally if (input === 's' && (key.ctrl || key.meta)) { saveConfig().then(success => { if (success) { onSave(); } }); } else if (key.escape) { saveConfig().then(() => onBack()); // Try to save even on escape } else if (key.return) { if (isEditing) { // Exit edit mode, return to navigation setIsEditing(false); } else { // Enter edit mode for the current field (toggle for the // boolean checkbox, list selection for searchEngine, text // input for the rest). if (currentField === 'enabled') { setEnabled(!enabled); } else { setIsEditing(true); } } } else if (!isEditing && key.upArrow) { const fields: Array<'enabled' | 'searchEngine' | 'port' | 'browserPath'> = ['enabled', 'searchEngine', 'port', 'browserPath']; const currentIndex = fields.indexOf(currentField); const newIndex = currentIndex > 0 ? currentIndex - 1 : fields.length - 1; setCurrentField(fields[newIndex]!); } else if (!isEditing && key.downArrow) { const fields: Array<'enabled' | 'searchEngine' | 'port' | 'browserPath'> = ['enabled', 'searchEngine', 'port', 'browserPath']; const currentIndex = fields.indexOf(currentField); const newIndex = currentIndex < fields.length - 1 ? currentIndex + 1 : 0; setCurrentField(fields[newIndex]!); } }); return ( {!inlineMode && ( {t.proxyConfig.title} {t.proxyConfig.subtitle} )} {currentField === 'enabled' ? '❯ ' : ' '} {t.proxyConfig.enableProxy} {enabled ? t.proxyConfig.enabled : t.proxyConfig.disabled}{' '} {t.proxyConfig.toggleHint} {currentField === 'searchEngine' ? '❯ ' : ' '} {t.proxyConfig.searchEngine} {currentField === 'searchEngine' && isEditing ? ( ({ label: e.name, value: e.id, }))} initialIndex={Math.max( 0, availableEngines.findIndex(e => e.id === searchEngine), )} isFocused={true} onSelect={item => { setSearchEngine(item.value as SearchEngineId); setIsEditing(false); }} /> ) : ( {availableEngines.find(e => e.id === searchEngine)?.name || searchEngine}{' '} {t.proxyConfig.toggleHint} )} {currentField === 'port' ? '❯ ' : ' '} {t.proxyConfig.proxyPort} {currentField === 'port' && isEditing && ( )} {(!isEditing || currentField !== 'port') && ( {port || t.proxyConfig.notSet} )} {currentField === 'browserPath' ? '❯ ' : ' '} {t.proxyConfig.browserPath} {currentField === 'browserPath' && isEditing && ( )} {(!isEditing || currentField !== 'browserPath') && ( {browserPath || t.proxyConfig.autoDetect} )} {errors.length > 0 && ( {t.proxyConfig.errors} {errors.map((error, index) => ( • {error} ))} )} {isEditing ? ( <> {t.proxyConfig.editingHint} ) : ( <> {t.proxyConfig.navigationHint} )} {t.proxyConfig.browserExamplesTitle} {t.proxyConfig.windowsExample} {' '} {t.proxyConfig.macosExample} {' '} {t.proxyConfig.linuxExample} {' '} {t.proxyConfig.browserExamplesFooter} ); } ================================================ FILE: source/ui/pages/SensitiveCommandConfigScreen.tsx ================================================ import React, {useState, useCallback, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import {Alert} from '@inkjs/ui'; import { getAllSensitiveCommands, toggleSensitiveCommand, addSensitiveCommand, removeSensitiveCommand, resetToDefaults, isDuplicatePattern, type SensitiveCommand, type SensitiveCommandScope, } from '../../utils/execution/sensitiveCommandManager.js'; import {useI18n} from '../../i18n/index.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; // Focus event handling const focusEventTokenRegex = /(?:\x1b)?\[[0-9;]*[IO]/g; const isFocusEventInput = (value?: string) => { if (!value) return false; if ( value === '\x1b[I' || value === '\x1b[O' || value === '[I' || value === '[O' ) { return true; } const trimmed = value.trim(); if (!trimmed) return false; const tokens = trimmed.match(focusEventTokenRegex); if (!tokens) return false; const normalized = trimmed.replace(/\s+/g, ''); const tokensCombined = tokens.join(''); return tokensCombined === normalized; }; const stripFocusArtifacts = (value: string) => { if (!value) return ''; return value .replace(/\x1b\[[0-9;]*[IO]/g, '') .replace(/\[[0-9;]*[IO]/g, '') .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, ''); }; type Props = { onBack: () => void; inlineMode?: boolean; }; type ViewMode = 'list' | 'scope-select' | 'add'; type ScopeSelectPurpose = 'add' | 'reset'; const SCOPE_OPTIONS: SensitiveCommandScope[] = ['project', 'global']; export default function SensitiveCommandConfigScreen({ onBack, inlineMode = false, }: Props) { const {t} = useI18n(); const {theme} = useTheme(); useTerminalTitle(`Snow CLI - ${t.sensitiveCommandConfig.title}`); const [commands, setCommands] = useState([]); const [selectedIndex, setSelectedIndex] = useState(0); const [viewMode, setViewMode] = useState('list'); const [showSuccess, setShowSuccess] = useState(false); const [successMessage, setSuccessMessage] = useState(''); // Confirmation states const [confirmDelete, setConfirmDelete] = useState(false); // Scope selection states const [scopeSelectIndex, setScopeSelectIndex] = useState(0); const [scopeSelectPurpose, setScopeSelectPurpose] = useState('add'); const [selectedScope, setSelectedScope] = useState('global'); const [confirmResetScope, setConfirmResetScope] = useState(false); // Add custom command fields const [customPattern, setCustomPattern] = useState(''); const [customDescription, setCustomDescription] = useState(''); const [addField, setAddField] = useState<'pattern' | 'description'>( 'pattern', ); const [addError, setAddError] = useState(''); const getScopeLabel = useCallback( (scope: SensitiveCommandScope) => { return scope === 'project' ? t.sensitiveCommandConfig.scopeProject : t.sensitiveCommandConfig.scopeGlobal; }, [t], ); // Load commands const loadCommands = useCallback(() => { const allCommands = getAllSensitiveCommands(); setCommands(allCommands); }, []); useEffect(() => { loadCommands(); }, [loadCommands]); // Handle list view input const handleListInput = useCallback( (input: string, key: any) => { if (key.escape) { if (confirmDelete) { setConfirmDelete(false); return; } onBack(); return; } if (key.upArrow) { if (commands.length === 0) return; setSelectedIndex(prev => (prev > 0 ? prev - 1 : commands.length - 1)); setConfirmDelete(false); } else if (key.downArrow) { if (commands.length === 0) return; setSelectedIndex(prev => (prev < commands.length - 1 ? prev + 1 : 0)); setConfirmDelete(false); } else if (input === ' ') { const cmd = commands[selectedIndex]; if (cmd) { toggleSensitiveCommand(cmd.id, cmd.scope); loadCommands(); const message = cmd.enabled ? t.sensitiveCommandConfig.disabledMessage : t.sensitiveCommandConfig.enabledMessage; setSuccessMessage(message.replace('{pattern}', cmd.pattern)); setShowSuccess(true); setTimeout(() => setShowSuccess(false), 2000); } } else if (input === 'a' || input === 'A') { setScopeSelectPurpose('add'); setScopeSelectIndex(0); setConfirmResetScope(false); setViewMode('scope-select'); } else if (input === 'd' || input === 'D') { const cmd = commands[selectedIndex]; if (cmd && !cmd.isPreset) { if (!confirmDelete) { setConfirmDelete(true); } else { removeSensitiveCommand(cmd.id, cmd.scope); loadCommands(); setSelectedIndex(prev => Math.min(prev, commands.length - 2)); setSuccessMessage( t.sensitiveCommandConfig.deletedMessage.replace( '{pattern}', cmd.pattern, ), ); setShowSuccess(true); setTimeout(() => setShowSuccess(false), 2000); setConfirmDelete(false); } } } else if (input === 'r' || input === 'R') { setScopeSelectPurpose('reset'); setScopeSelectIndex(0); setConfirmResetScope(false); setViewMode('scope-select'); } }, [commands, selectedIndex, onBack, loadCommands, confirmDelete, t], ); // Handle scope selection input (shared for add & reset) const handleScopeSelectInput = useCallback( (_input: string, key: any) => { if (key.escape) { if (confirmResetScope) { setConfirmResetScope(false); return; } setViewMode('list'); return; } if (confirmResetScope) { if (key.return) { const scope = SCOPE_OPTIONS[scopeSelectIndex]!; resetToDefaults(scope); loadCommands(); setSelectedIndex(0); setSuccessMessage(t.sensitiveCommandConfig.resetMessage); setShowSuccess(true); setTimeout(() => setShowSuccess(false), 2000); setConfirmResetScope(false); setViewMode('list'); } return; } if (key.upArrow) { setScopeSelectIndex(prev => prev > 0 ? prev - 1 : SCOPE_OPTIONS.length - 1, ); } else if (key.downArrow) { setScopeSelectIndex(prev => prev < SCOPE_OPTIONS.length - 1 ? prev + 1 : 0, ); } else if (key.return) { const scope = SCOPE_OPTIONS[scopeSelectIndex]!; if (scopeSelectPurpose === 'add') { setSelectedScope(scope); setViewMode('add'); setCustomPattern(''); setCustomDescription(''); setAddField('pattern'); setAddError(''); } else { setConfirmResetScope(true); } } }, [scopeSelectIndex, scopeSelectPurpose, confirmResetScope, loadCommands, t], ); // Handle add view input — ESC returns to scope-select const handleAddInput = useCallback((_input: string, key: any) => { if (key.escape) { setViewMode('scope-select'); setAddError(''); return; } if (key.tab) { setAddField(prev => (prev === 'pattern' ? 'description' : 'pattern')); } }, []); // Use input hook useInput( (input, key) => { if (viewMode === 'list') { handleListInput(input, key); } else if (viewMode === 'scope-select') { handleScopeSelectInput(input, key); } else { handleAddInput(input, key); } }, {isActive: true}, ); // Handle pattern input change const handlePatternChange = useCallback((value: string) => { if (!isFocusEventInput(value)) { setCustomPattern(stripFocusArtifacts(value)); setAddError(''); } }, []); // Handle description input change const handleDescriptionChange = useCallback((value: string) => { if (!isFocusEventInput(value)) { setCustomDescription(stripFocusArtifacts(value)); } }, []); // Handle add submit const handleAddSubmit = useCallback(() => { if (addField === 'pattern') { if (customPattern.trim()) { const {isDuplicate, existingScope} = isDuplicatePattern( customPattern.trim(), ); if (isDuplicate) { setAddError( t.sensitiveCommandConfig.duplicatePattern .replace('{pattern}', customPattern.trim()) .replace('{scope}', getScopeLabel(existingScope!)), ); return; } } setAddField('description'); } else { if (customPattern.trim() && customDescription.trim()) { try { addSensitiveCommand( customPattern.trim(), customDescription.trim(), selectedScope, ); loadCommands(); setViewMode('list'); setSuccessMessage( t.sensitiveCommandConfig.addedMessage.replace( '{pattern}', customPattern, ), ); setShowSuccess(true); setTimeout(() => setShowSuccess(false), 2000); setAddError(''); } catch (error: any) { if ( typeof error?.message === 'string' && error.message.startsWith('DUPLICATE:') ) { const scope = error.message.split(':')[1] as SensitiveCommandScope; setAddError( t.sensitiveCommandConfig.duplicatePattern .replace('{pattern}', customPattern.trim()) .replace('{scope}', getScopeLabel(scope)), ); } } } } }, [ addField, customPattern, customDescription, selectedScope, loadCommands, t, getScopeLabel, ]); // Scope selection view (shared for add & reset) if (viewMode === 'scope-select') { const isReset = scopeSelectPurpose === 'reset'; const title = isReset ? t.sensitiveCommandConfig.resetScopeSelectTitle : t.sensitiveCommandConfig.scopeSelectTitle; const scopeItems: Array<{ label: string; desc: string; scope: SensitiveCommandScope; }> = [ { label: t.sensitiveCommandConfig.scopeProject, desc: isReset ? t.sensitiveCommandConfig.resetProjectDesc : '.snow/sensitive-commands.json', scope: 'project', }, { label: t.sensitiveCommandConfig.scopeGlobal, desc: isReset ? t.sensitiveCommandConfig.resetGlobalDesc : '~/.snow/sensitive-commands.json', scope: 'global', }, ]; return ( {title} {scopeItems.map((item, idx) => { const isSelected = idx === scopeSelectIndex; return ( {isSelected ? '> ' : ' '} {item.label} {item.desc} ); })} {confirmResetScope && ( {t.sensitiveCommandConfig.confirmResetScopeMessage.replace( '{scope}', getScopeLabel(SCOPE_OPTIONS[scopeSelectIndex]!), )} )} {confirmResetScope ? t.sensitiveCommandConfig.confirmHint : t.sensitiveCommandConfig.scopeSelectHint} ); } if (viewMode === 'add') { return ( {t.sensitiveCommandConfig.addTitle.replace( '{scope}', getScopeLabel(selectedScope), )} {t.sensitiveCommandConfig.patternLabel} ❯{' '} {addError && ( ⚠️ {addError} )} {t.sensitiveCommandConfig.descriptionLabel} ❯{' '} {t.sensitiveCommandConfig.addEditingHint} ); } // Calculate visible range for scrolling const viewportHeight = 13; const startIndex = Math.max( 0, selectedIndex - Math.floor(viewportHeight / 2), ); const endIndex = Math.min(commands.length, startIndex + viewportHeight); const adjustedStart = Math.max(0, endIndex - viewportHeight); const selectedCmd = commands[selectedIndex]; return ( {t.sensitiveCommandConfig.title} {t.sensitiveCommandConfig.subtitle} {showSuccess && ( {successMessage} )} {commands.length === 0 ? ( {t.sensitiveCommandConfig.noCommands} ) : ( commands.map((cmd, index) => { if (index < adjustedStart || index >= endIndex) { return null; } const scopeTag = cmd.isPreset ? '' : ` · ${getScopeLabel(cmd.scope)}`; return ( {selectedIndex === index ? '❯ ' : ' '}[{cmd.enabled ? '✓' : ' '}]{' '} {cmd.pattern} {!cmd.isPreset && ( {' '} ({t.sensitiveCommandConfig.custom} {scopeTag}) )} ); }) )} {selectedCmd && !confirmDelete && ( {selectedCmd.description} ( {selectedCmd.enabled ? t.sensitiveCommandConfig.enabled : t.sensitiveCommandConfig.disabled} ) {!selectedCmd.isPreset && ` [${t.sensitiveCommandConfig.customLabel}]`} )} {confirmDelete && selectedCmd && ( {t.sensitiveCommandConfig.confirmDeleteMessage.replace( '{pattern}', selectedCmd.pattern, )} )} {confirmDelete ? t.sensitiveCommandConfig.confirmHint : t.sensitiveCommandConfig.listNavigationHint} ); } ================================================ FILE: source/ui/pages/SubAgentConfigScreen.tsx ================================================ import React, {useState, useCallback, useMemo, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import TextInput from 'ink-text-input'; import {Alert, Spinner} from '@inkjs/ui'; import {getMCPServicesInfo} from '../../utils/execution/mcpToolsManager.js'; import type {MCPServiceTools} from '../../utils/execution/mcpToolsManager.js'; import { createSubAgent, updateSubAgent, getSubAgent, validateSubAgent, } from '../../utils/config/subAgentConfig.js'; import { getAllProfiles, getActiveProfileName, } from '../../utils/config/configManager.js'; import {useI18n} from '../../i18n/index.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; // Focus event handling - prevent terminal focus events from appearing as input const focusEventTokenRegex = /(?:\x1b)?\[[0-9;]*[IO]/g; const isFocusEventInput = (value?: string) => { if (!value) { return false; } if ( value === '\x1b[I' || value === '\x1b[O' || value === '[I' || value === '[O' ) { return true; } const trimmed = value.trim(); if (!trimmed) { return false; } const tokens = trimmed.match(focusEventTokenRegex); if (!tokens) { return false; } const normalized = trimmed.replace(/\s+/g, ''); const tokensCombined = tokens.join(''); return tokensCombined === normalized; }; const stripFocusArtifacts = (value: string) => { if (!value) { return ''; } return value .replace(/\x1b\[[0-9;]*[IO]/g, '') .replace(/\[[0-9;]*[IO]/g, '') .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, ''); }; type Props = { onBack: () => void; onSave: () => void; inlineMode?: boolean; agentId?: string; // If provided, edit mode; otherwise, create mode }; type ToolCategory = { name: string; tools: string[]; }; type FormField = 'name' | 'description' | 'role' | 'configProfile' | 'tools'; export default function SubAgentConfigScreen({ onBack, onSave, inlineMode = false, agentId, }: Props) { const {theme} = useTheme(); const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.subAgentConfig.title}`); const [agentName, setAgentName] = useState(''); const [description, setDescription] = useState(''); const [role, setRole] = useState(''); const [roleExpanded, setRoleExpanded] = useState(false); const [selectedTools, setSelectedTools] = useState>(new Set()); const [currentField, setCurrentField] = useState('name'); const [selectedCategoryIndex, setSelectedCategoryIndex] = useState(0); const [selectedToolIndex, setSelectedToolIndex] = useState(0); const [showSuccess, setShowSuccess] = useState(false); const [saveError, setSaveError] = useState(null); const [isLoadingMCP, setIsLoadingMCP] = useState(true); const [mcpServices, setMcpServices] = useState([]); const [loadError, setLoadError] = useState(null); const isEditMode = !!agentId; const [isBuiltinAgent, setIsBuiltinAgent] = useState(false); // 选择器状态（索引）- 用于键盘导航 const [selectedConfigProfileIndex, setSelectedConfigProfileIndex] = useState(0); // 已确认选中的索引（用于显示勾选标记） const [confirmedConfigProfileIndex, setConfirmedConfigProfileIndex] = useState(-1); // Tool categories with translations const toolCategories: ToolCategory[] = [ { name: t.subAgentConfig.filesystemTools, tools: [ 'filesystem-read', 'filesystem-create', 'filesystem-replaceedit', 'filesystem-edit', ], }, { name: t.subAgentConfig.aceTools, tools: ['ace-search'], }, { name: t.subAgentConfig.codebaseTools, tools: ['codebase-search'], }, { name: t.subAgentConfig.terminalTools, tools: ['terminal-execute'], }, { name: t.subAgentConfig.todoTools, tools: ['todo-manage'], }, { name: t.subAgentConfig.webSearchTools, tools: ['websearch-search', 'websearch-fetch'], }, { name: t.subAgentConfig.ideTools, tools: ['ide-get_diagnostics'], }, { name: t.subAgentConfig.userInteractionTools || 'User Interaction', tools: ['askuser-ask_question'], }, { name: t.subAgentConfig.skillTools || 'Skills', tools: ['skill-execute'], }, ]; // 获取可用的配置文件列表 const availableProfiles = useMemo(() => { const profiles = getAllProfiles(); return profiles.map(p => p.name); }, []); // 在可用配置列表前添加"跟随全局"选项 // index 0 = 跟随全局（动态使用当前活跃配置），index 1..n = 指定配置文件 const profileOptions = useMemo(() => { const activeProfile = getActiveProfileName() || 'default'; const followGlobalLabel = t.subAgentConfig.followGlobal.replace( '{name}', activeProfile, ); return [followGlobalLabel, ...availableProfiles]; }, [availableProfiles, t]); // Initialize with current active configurations (non-edit mode) useEffect(() => { if (!agentId) { // 默认选中"跟随全局"（index 0），这样全局配置变化时子代理也会动态跟随 setSelectedConfigProfileIndex(0); setConfirmedConfigProfileIndex(0); } }, [availableProfiles, agentId]); useEffect(() => { if (!agentId) { return; } const agent = getSubAgent(agentId); if (!agent) { return; } const isBuiltin = [ 'agent_explore', 'agent_plan', 'agent_general', 'agent_analyze', 'agent_debug', ].includes(agentId); setIsBuiltinAgent(isBuiltin); setAgentName(agent.name); setDescription(agent.description); setRole(agent.role || ''); setSelectedTools(new Set(agent.tools || [])); // 加载配置文件索引 if (agent.configProfile) { // 已指定配置文件 → 在 profileOptions 中找到对应项（index 0 是跟随全局，所以 +1） const profileIndex = availableProfiles.findIndex( p => p === agent.configProfile, ); if (profileIndex >= 0) { setSelectedConfigProfileIndex(profileIndex + 1); setConfirmedConfigProfileIndex(profileIndex + 1); } } else { // 没有指定配置文件 → 默认选中"跟随全局"（index 0） setSelectedConfigProfileIndex(0); setConfirmedConfigProfileIndex(0); } }, [agentId, availableProfiles]); // Load MCP services on mount useEffect(() => { const loadMCPServices = async () => { try { setIsLoadingMCP(true); setLoadError(null); const services = await getMCPServicesInfo(); setMcpServices(services); } catch (error) { setLoadError( error instanceof Error ? error.message : 'Failed to load MCP services', ); } finally { setIsLoadingMCP(false); } }; loadMCPServices(); }, []); // Combine built-in and MCP tool categories const allToolCategories = useMemo(() => { const categories = [...toolCategories]; // Add custom MCP services as separate categories for (const service of mcpServices) { if (!service.isBuiltIn && service.connected && service.tools.length > 0) { categories.push({ name: `${service.serviceName} ${t.subAgentConfig.categoryMCP}`, tools: service.tools.map( tool => `${service.serviceName}-${tool.name}`, ), }); } } return categories; }, [mcpServices, toolCategories, t]); // Get all available tools const allTools = useMemo( () => allToolCategories.flatMap(cat => cat.tools), [allToolCategories], ); const handleToggleTool = useCallback((tool: string) => { setSelectedTools(prev => { const newSet = new Set(prev); if (newSet.has(tool)) { newSet.delete(tool); } else { newSet.add(tool); } return newSet; }); }, []); const handleToggleCategory = useCallback(() => { const category = allToolCategories[selectedCategoryIndex]; if (!category) return; const allSelected = category.tools.every(tool => selectedTools.has(tool)); setSelectedTools(prev => { const newSet = new Set(prev); if (allSelected) { // Deselect all in category category.tools.forEach(tool => newSet.delete(tool)); } else { // Select all in category category.tools.forEach(tool => newSet.add(tool)); } return newSet; }); }, [selectedCategoryIndex, selectedTools, allToolCategories]); const handleToggleCurrentTool = useCallback(() => { const category = allToolCategories[selectedCategoryIndex]; if (!category) return; const tool = category.tools[selectedToolIndex]; if (tool) { handleToggleTool(tool); } }, [ selectedCategoryIndex, selectedToolIndex, handleToggleTool, allToolCategories, ]); const handleSave = useCallback(() => { setSaveError(null); // Validate const errors = validateSubAgent({ name: agentName, description: description, tools: Array.from(selectedTools), }); if (errors.length > 0) { setSaveError(errors[0] || t.subAgentConfig.validationFailed); return; } try { // 使用 confirmedIndex，确保保存用户通过Space键确认的选择 // index 0 = 跟随全局（不保存具体配置名，运行时动态使用全局配置） // index > 0 = 指定配置文件（保存具体配置名） const selectedProfile = confirmedConfigProfileIndex > 0 ? availableProfiles[confirmedConfigProfileIndex - 1] : undefined; if (isEditMode && agentId) { // Update existing agent updateSubAgent(agentId, { name: agentName, description: description, role: role || undefined, tools: Array.from(selectedTools), configProfile: selectedProfile || undefined, }); } else { // Create new agent createSubAgent( agentName, description, Array.from(selectedTools), role || undefined, selectedProfile || undefined, ); } setShowSuccess(true); setTimeout(() => { setShowSuccess(false); onSave(); }, 1500); } catch (error) { setSaveError( error instanceof Error ? error.message : t.subAgentConfig.saveError, ); } }, [ agentName, description, role, selectedTools, confirmedConfigProfileIndex, availableProfiles, isEditMode, agentId, t, ]); useInput((rawInput, key) => { const input = stripFocusArtifacts(rawInput); // Ignore focus events completely if (!input && isFocusEventInput(rawInput)) { return; } if (isFocusEventInput(rawInput)) { return; } if (key.escape) { onBack(); return; } // ======================================== // 导航逻辑说明: // ↑↓键: 在主字段间导航 (name → description → role → configProfile → tools) // 在配置列表字段内导航，到达边界时跳到相邻主字段 // 在 tools 字段内导航工具列表，到达边界时跳到相邻主字段 // ←→键: 在所有主字段之间切换 (除了 tools 字段中用于切换工具分类) // Space: 切换选中状态 // ======================================== // 定义主字段顺序（用于导航） const mainFields: FormField[] = [ 'name', 'description', 'role', 'configProfile', 'tools', ]; const currentFieldIndex = mainFields.indexOf(currentField); if (key.upArrow) { // 配置列表字段：在列表内导航，到达顶部时跳到上一个主字段 if (currentField === 'configProfile') { if (profileOptions.length === 0 || selectedConfigProfileIndex === 0) { // 跳到上一个主字段 setCurrentField('role'); } else { setSelectedConfigProfileIndex(prev => prev - 1); } return; } else if (currentField === 'tools') { if (selectedToolIndex > 0) { setSelectedToolIndex(prev => prev - 1); } else if (selectedCategoryIndex > 0) { const prevCategory = allToolCategories[selectedCategoryIndex - 1]; setSelectedCategoryIndex(prev => prev - 1); setSelectedToolIndex( prevCategory ? prevCategory.tools.length - 1 : 0, ); } else { // 在 tools 顶部时跳到上一个主字段 setCurrentField('configProfile'); } return; } else { const prevIndex = currentFieldIndex > 0 ? currentFieldIndex - 1 : mainFields.length - 1; setCurrentField(mainFields[prevIndex]!); return; } } if (key.downArrow) { // 配置列表字段：在列表内导航，到达底部时跳到下一个主字段 if (currentField === 'configProfile') { if ( profileOptions.length === 0 || selectedConfigProfileIndex >= profileOptions.length - 1 ) { // 跳到下一个主字段 setCurrentField('tools'); setSelectedCategoryIndex(0); setSelectedToolIndex(0); } else { setSelectedConfigProfileIndex(prev => prev + 1); } return; } if (currentField === 'tools') { const currentCategory = allToolCategories[selectedCategoryIndex]; if (!currentCategory) return; if (selectedToolIndex < currentCategory.tools.length - 1) { setSelectedToolIndex(prev => prev + 1); } else if (selectedCategoryIndex < allToolCategories.length - 1) { setSelectedCategoryIndex(prev => prev + 1); setSelectedToolIndex(0); } else { // 在 tools 底部时跳到第一个主字段（循环） setCurrentField('name'); } return; } // 普通字段：跳到下一个主字段 const nextIndex = currentFieldIndex < mainFields.length - 1 ? currentFieldIndex + 1 : 0; setCurrentField(mainFields[nextIndex]!); return; } // Role field controls - Space to toggle expansion if (currentField === 'role' && input === ' ') { setRoleExpanded(prev => !prev); return; } // Config field controls - Space to toggle selection if (currentField === 'configProfile') { if (input === ' ') { setConfirmedConfigProfileIndex(prev => prev === selectedConfigProfileIndex ? -1 : selectedConfigProfileIndex, ); return; } } // Tool-specific controls if (currentField === 'tools') { if (key.leftArrow) { // Navigate to previous category if (selectedCategoryIndex > 0) { setSelectedCategoryIndex(prev => prev - 1); setSelectedToolIndex(0); } return; } if (key.rightArrow) { // Navigate to next category if (selectedCategoryIndex < allToolCategories.length - 1) { setSelectedCategoryIndex(prev => prev + 1); setSelectedToolIndex(0); } return; } if (input === ' ') { // Toggle current tool handleToggleCurrentTool(); return; } if (input === 'a' || input === 'A') { // Toggle all in category handleToggleCategory(); return; } } // Global left/right arrow navigation between main fields (except tools field which uses it for categories) if (key.leftArrow && currentField !== 'tools') { // Navigate to previous main field const prevIndex = currentFieldIndex > 0 ? currentFieldIndex - 1 : mainFields.length - 1; setCurrentField(mainFields[prevIndex]!); return; } if (key.rightArrow && currentField !== 'tools') { // Navigate to next main field const nextIndex = currentFieldIndex < mainFields.length - 1 ? currentFieldIndex + 1 : 0; setCurrentField(mainFields[nextIndex]!); return; } // Save with Enter key if (key.return) { handleSave(); return; } }); // 滚动列表渲染辅助函数（支持字符串数组和对象数组） const renderScrollableList = ( items: T[], selectedIndex: number, confirmedIndex: number, // 已确认选中的索引 isActive: boolean, maxVisible = 5, keyPrefix: string, ) => { const totalItems = items.length; // 如果没有可用项，显示提示信息 if (totalItems === 0) { return ( {t.subAgentConfig.noItems} ); } // 计算可见范围 let startIndex = Math.max(0, selectedIndex - Math.floor(maxVisible / 2)); let endIndex = Math.min(totalItems, startIndex + maxVisible); // 调整起始位置确保显示maxVisible个项目 if (endIndex - startIndex < maxVisible) { startIndex = Math.max(0, endIndex - maxVisible); } const visibleItems = items.slice(startIndex, endIndex); const hasMore = totalItems > maxVisible; return ( {startIndex > 0 && ( ↑{' '} {t.subAgentConfig.moreAbove.replace('{count}', String(startIndex))} )} {visibleItems.map((item, relativeIndex) => { const actualIndex = startIndex + relativeIndex; const isHighlighted = actualIndex === selectedIndex; const isConfirmed = actualIndex === confirmedIndex; const displayText = typeof item === 'string' ? item : item.name; return ( {isActive && isHighlighted ? '❯ ' : ' '} {isConfirmed ? '[✓] ' : '[ ] '} {displayText} ); })} {endIndex < totalItems && ( ↓{' '} {t.subAgentConfig.moreBelow.replace( '{count}', String(totalItems - endIndex), )} )} {isActive && hasMore && totalItems > 0 && ( {' '} {t.subAgentConfig.scrollToggleHint} )} {isActive && !hasMore && totalItems > 0 && ( {' '} {t.subAgentConfig.spaceToggleHint} )} ); }; // 滚动工具列表渲染辅助函数 const renderScrollableTools = ( tools: string[], selectedIndex: number, maxVisible = 5, ) => { const totalTools = tools.length; // 计算可见范围 let startIndex = Math.max(0, selectedIndex - Math.floor(maxVisible / 2)); let endIndex = Math.min(totalTools, startIndex + maxVisible); // 调整起始位置确保显示maxVisible个项目 if (endIndex - startIndex < maxVisible) { startIndex = Math.max(0, endIndex - maxVisible); } const visibleTools = tools.slice(startIndex, endIndex); const hasMore = totalTools > maxVisible; return ( {startIndex > 0 && ( ↑{' '} {t.subAgentConfig.moreTools.replace('{count}', String(startIndex))} )} {visibleTools.map((tool, relativeIndex) => { const actualIndex = startIndex + relativeIndex; const isCurrentTool = actualIndex === selectedIndex; return ( {isCurrentTool ? '❯ ' : ' '} {selectedTools.has(tool) ? '[✓]' : '[ ]'} {tool} ); })} {endIndex < totalTools && ( ↓{' '} {t.subAgentConfig.moreTools.replace( '{count}', String(totalTools - endIndex), )} )} {hasMore && ( {t.subAgentConfig.scrollToolsHint} )} ); }; const renderToolSelection = () => { return ( {t.subAgentConfig.toolSelection} {isLoadingMCP && ( )} {loadError && ( {t.subAgentConfig.mcpLoadError} {loadError} )} {allToolCategories.map((category, catIndex) => { const isCurrent = catIndex === selectedCategoryIndex; const selectedInCategory = category.tools.filter(tool => selectedTools.has(tool), ).length; return ( {isCurrent && currentField === 'tools' ? '▶ ' : ' '} {category.name} ({selectedInCategory}/{category.tools.length}) {isCurrent && currentField === 'tools' && renderScrollableTools(category.tools, selectedToolIndex, 5)} ); })} {t.subAgentConfig.selectedTools} {selectedTools.size} /{' '} {allTools.length} {t.subAgentConfig.toolsCount} ); }; return ( {!inlineMode && ( ❆{' '} {isEditMode ? t.subAgentConfig.titleEdit : t.subAgentConfig.titleNew}{' '} {t.subAgentConfig.title} )} {showSuccess && ( Sub-agent{' '} {isEditMode ? t.subAgentConfig.saveSuccessEdit : t.subAgentConfig.saveSuccessCreate}{' '} successfully! )} {saveError && ( {saveError} )} {/* Agent Name */} {t.subAgentConfig.agentName} {isBuiltinAgent && ( {t.subAgentConfig.builtinReadonly} )} {isBuiltinAgent ? ( {agentName} ) : ( setAgentName(stripFocusArtifacts(value))} placeholder={t.subAgentConfig.agentNamePlaceholder} focus={currentField === 'name'} /> )} {/* Description */} {t.subAgentConfig.description} {isBuiltinAgent && ( {t.subAgentConfig.builtinReadonly} )} {isBuiltinAgent ? ( {description} ) : ( setDescription(stripFocusArtifacts(value))} placeholder={t.subAgentConfig.descriptionPlaceholder} focus={currentField === 'description'} /> )} {/* Role */} {t.subAgentConfig.roleOptional} {isBuiltinAgent && ( {t.subAgentConfig.builtinReadonly} )} {!isBuiltinAgent && role && role.length > 100 && ( {' '} {t.subAgentConfig.roleExpandHint.replace( '{status}', roleExpanded ? t.subAgentConfig.roleExpanded : t.subAgentConfig.roleCollapsed, )} )} {isBuiltinAgent ? ( role && role.length > 100 && !roleExpanded ? ( {role.substring(0, 100)}... {' '} {t.subAgentConfig.roleViewFull} ) : ( {role} ) ) : role && role.length > 100 && !roleExpanded ? ( {role.substring(0, 100)}... ) : ( setRole(stripFocusArtifacts(value))} placeholder={t.subAgentConfig.rolePlaceholder} focus={currentField === 'role'} /> )} {/* Config Profile (Optional) */} {t.subAgentConfig.configProfile} {renderScrollableList( profileOptions, selectedConfigProfileIndex, confirmedConfigProfileIndex, // 确认选中的项 currentField === 'configProfile', 5, 'profile', )} {/* Tool Selection */} {renderToolSelection()} {/* Instructions */} {t.subAgentConfig.navigationHint} ); } ================================================ FILE: source/ui/pages/SubAgentListScreen.tsx ================================================ import React, {useState, useCallback, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import {Alert} from '@inkjs/ui'; import { getSubAgents, deleteSubAgent, type SubAgent, } from '../../utils/config/subAgentConfig.js'; import {useTerminalSize} from '../../hooks/ui/useTerminalSize.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useI18n} from '../../i18n/index.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; onAdd: () => void; onEdit: (agentId: string) => void; inlineMode?: boolean; defaultSelectedIndex?: number; onSelectionPersist?: (index: number) => void; }; export default function SubAgentListScreen({ onBack, onAdd, onEdit, inlineMode = false, defaultSelectedIndex = 0, onSelectionPersist, }: Props) { const {theme} = useTheme(); const {columns} = useTerminalSize(); const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.subAgentList.title}`); const [agents, setAgents] = useState([]); const [selectedIndex, setSelectedIndex] = useState(defaultSelectedIndex); const [showDeleteConfirm, setShowDeleteConfirm] = useState(false); const [deleteSuccess, setDeleteSuccess] = useState(false); const [deleteFailed, setDeleteFailed] = useState(false); // Sync with parent's defaultSelectedIndex when it changes useEffect(() => { setSelectedIndex(defaultSelectedIndex); }, [defaultSelectedIndex]); // Truncate text based on terminal width const truncateText = useCallback( (text: string, prefixLength: number = 0): string => { if (!text) return text; // Reserve space for indentation (3), prefix text, padding (5), and ellipsis (3) const maxLength = Math.max(20, columns - prefixLength - 3 - 5 - 3); if (text.length <= maxLength) return text; return text.substring(0, maxLength) + '...'; }, [columns], ); // Load agents on mount useEffect(() => { loadAgents(); }, []); const loadAgents = useCallback(() => { const loadedAgents = getSubAgents(); setAgents(loadedAgents); if (selectedIndex >= loadedAgents.length && loadedAgents.length > 0) { setSelectedIndex(loadedAgents.length - 1); } }, [selectedIndex]); const handleDelete = useCallback(() => { if (agents.length === 0) return; const agent = agents[selectedIndex]; if (!agent) return; const success = deleteSubAgent(agent.id); if (success) { setDeleteSuccess(true); setTimeout(() => setDeleteSuccess(false), 2000); loadAgents(); } else { setDeleteFailed(true); setTimeout(() => setDeleteFailed(false), 2000); } setShowDeleteConfirm(false); }, [agents, selectedIndex, loadAgents]); useInput((input, key) => { if (key.escape) { if (showDeleteConfirm) { setShowDeleteConfirm(false); } else { onBack(); } return; } if (showDeleteConfirm) { if (input === 'y' || input === 'Y') { handleDelete(); } else if (input === 'n' || input === 'N') { setShowDeleteConfirm(false); } return; } if (key.upArrow) { const newIndex = selectedIndex > 0 ? selectedIndex - 1 : agents.length - 1; setSelectedIndex(newIndex); onSelectionPersist?.(newIndex); } else if (key.downArrow) { const newIndex = selectedIndex < agents.length - 1 ? selectedIndex + 1 : 0; setSelectedIndex(newIndex); onSelectionPersist?.(newIndex); } else if (key.return) { if (agents.length > 0) { const agent = agents[selectedIndex]; if (agent) { onSelectionPersist?.(selectedIndex); onEdit(agent.id); } } } else if (input === 'a' || input === 'A') { onSelectionPersist?.(selectedIndex); onAdd(); } else if (input === 'd' || input === 'D') { if (agents.length > 0) { const agent = agents[selectedIndex]; if (agent?.builtin) { // 系统内置子代理直接显示错误提示 setDeleteFailed(true); setTimeout(() => setDeleteFailed(false), 2000); } else { setShowDeleteConfirm(true); } } } }); return ( {!inlineMode && ( ❆ {t.subAgentList.title} )} {deleteSuccess && ( {t.subAgentList.deleteSuccess} )} {deleteFailed && ( {t.subAgentList.deleteFailed} )} {showDeleteConfirm && agents[selectedIndex] && ( {t.subAgentList.deleteConfirm.replace( '{name}', agents[selectedIndex].name, )} )} {agents.length === 0 ? ( {t.subAgentList.noAgents} {t.subAgentList.noAgentsHint} ) : ( {t.subAgentList.agentsCount.replace( '{count}', agents.length.toString(), )} {agents.map((agent, index) => { const isSelected = index === selectedIndex; return ( {isSelected ? '❯ ' : ' '} {agent.name} {isSelected && ( {t.subAgentList.description}{' '} {truncateText( agent.description || t.subAgentList.noDescription, t.subAgentList.description.length, )} {t.subAgentList.toolsCount.replace( '{count}', (agent.tools?.length || 0).toString(), )} {t.subAgentList.updated}{' '} {agent.updatedAt ? new Date(agent.updatedAt).toLocaleString() : 'N/A'} )} ); })} )} {t.subAgentList.navigationHint} ); } ================================================ FILE: source/ui/pages/SystemPromptConfigScreen.tsx ================================================ import React, {useState, useEffect} from 'react'; import {Box, Text, useInput} from 'ink'; import {Alert} from '@inkjs/ui'; import TextInput from 'ink-text-input'; import {spawn, execSync} from 'child_process'; import {writeFileSync, readFileSync, existsSync, unlinkSync} from 'fs'; import {join} from 'path'; import {platform, tmpdir} from 'os'; import { getSystemPromptConfig, saveSystemPromptConfig, type SystemPromptConfig, type SystemPromptItem, } from '../../utils/config/apiConfig.js'; import {useI18n} from '../../i18n/index.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; }; type View = 'list' | 'add' | 'edit' | 'confirmDelete' | 'editWithEditor'; type ListAction = | 'activate' | 'deactivate' | 'edit' | 'delete' | 'add' | 'back'; function checkCommandExists(command: string): boolean { if (platform() === 'win32') { // Windows: 使用 where 命令检查 try { execSync(`where ${command}`, { stdio: 'ignore', windowsHide: true, }); return true; } catch { return false; } } // Unix/Linux/macOS: 使用 command -v const shells = ['/bin/sh', '/bin/bash', '/bin/zsh']; for (const shell of shells) { try { execSync(`command -v ${command}`, { stdio: 'ignore', shell, env: process.env, }); return true; } catch { // Try next shell } } return false; } function getSystemEditor(): string | null { // 优先使用环境变量指定的编辑器 (所有平台) const envEditor = process.env['VISUAL'] || process.env['EDITOR']; if (envEditor && checkCommandExists(envEditor)) { return envEditor; } if (platform() === 'win32') { // Windows: 按优先级检测常见编辑器 const windowsEditors = ['notepad++', 'notepad', 'code', 'vim', 'nano']; for (const editor of windowsEditors) { if (checkCommandExists(editor)) { return editor; } } return null; } // Unix/Linux/macOS: 按优先级检测常见编辑器 const editors = ['nano', 'vim', 'vi']; for (const editor of editors) { if (checkCommandExists(editor)) { return editor; } } return null; } export default function SystemPromptConfigScreen({onBack}: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.systemPromptConfig.title}`); const {theme} = useTheme(); const [config, setConfig] = useState(() => { return ( getSystemPromptConfig() || { active: [], prompts: [], } ); }); const [view, setView] = useState('list'); const [selectedIndex, setSelectedIndex] = useState(0); const [currentAction, setCurrentAction] = useState('add'); const [isEditing, setIsEditing] = useState(false); const [editName, setEditName] = useState(''); const [editContent, setEditContent] = useState(''); const [editingField, setEditingField] = useState<'name' | 'content'>('name'); const [error, setError] = useState(''); const [successMessage, setSuccessMessage] = useState(''); const actions: ListAction[] = config.prompts.length > 0 ? config.active.length > 0 ? ['activate', 'deactivate', 'edit', 'delete', 'add', 'back'] : ['activate', 'edit', 'delete', 'add', 'back'] : ['add', 'back']; // 当配置变化时，确保 currentAction 在可用操作列表中 useEffect(() => { if (!actions.includes(currentAction)) { setCurrentAction(actions[0] || 'add'); } }, [config.prompts.length, config.active]); useEffect(() => { // 保存配置时刷新 const savedConfig = getSystemPromptConfig(); if (savedConfig) { setConfig(savedConfig); } }, [view]); const saveAndRefresh = (newConfig: SystemPromptConfig) => { try { saveSystemPromptConfig(newConfig); setConfig(newConfig); setError(''); return true; } catch (err) { setError( err instanceof Error ? err.message : t.systemPromptConfig.saveError, ); return false; } }; const handleActivate = () => { if (config.prompts.length === 0 || selectedIndex >= config.prompts.length) return; const prompt = config.prompts[selectedIndex]!; const isAlreadyActive = config.active.includes(prompt.id); const newActive = isAlreadyActive ? config.active.filter(id => id !== prompt.id) : [...config.active, prompt.id]; const newConfig: SystemPromptConfig = { ...config, active: newActive, }; if (saveAndRefresh(newConfig)) { setError(''); } }; const handleDeactivate = () => { const newConfig: SystemPromptConfig = { ...config, active: [], }; if (saveAndRefresh(newConfig)) { setError(''); } }; const handleEdit = () => { if (config.prompts.length === 0 || selectedIndex >= config.prompts.length) return; const prompt = config.prompts[selectedIndex]!; setEditName(prompt.name); setEditContent(prompt.content); setEditingField('name'); setView('edit'); }; const handleEditWithExternalEditor = async () => { if (config.prompts.length === 0 || selectedIndex >= config.prompts.length) return; const prompt = config.prompts[selectedIndex]!; const editor = getSystemEditor(); if (!editor) { setError(t.systemPromptConfig.editorNotFound); return; } // 创建临时文件 const tempFile = join(tmpdir(), `snow-prompt-${Date.now()}.txt`); writeFileSync(tempFile, prompt.content || '', 'utf8'); // 暂停 Ink 应用以让编辑器接管终端 if (process.stdin.isTTY) { process.stdin.pause(); } const child = spawn(editor, [tempFile], { stdio: 'inherit', }); child.on('close', () => { // 恢复 Ink 应用 if (process.stdin.isTTY) { process.stdin.resume(); process.stdin.setRawMode(true); } // 读取编辑后的内容 if (existsSync(tempFile)) { try { const editedContent = readFileSync(tempFile, 'utf8'); const newConfig: SystemPromptConfig = { ...config, prompts: config.prompts.map((p, i) => i === selectedIndex ? { ...p, content: editedContent, } : p, ), }; if (saveAndRefresh(newConfig)) { setSuccessMessage(t.systemPromptConfig.editorSaved); // 3秒后清除成功消息 setTimeout(() => setSuccessMessage(''), 3000); } // 清理临时文件 unlinkSync(tempFile); } catch (err) { setError( err instanceof Error ? err.message : t.systemPromptConfig.editorEditFailed, ); } } }); child.on('error', error => { // 恢复 Ink 应用 if (process.stdin.isTTY) { process.stdin.resume(); process.stdin.setRawMode(true); } setError(`${t.systemPromptConfig.editorOpenFailed}: ${error.message}`); if (existsSync(tempFile)) { unlinkSync(tempFile); } }); }; const handleDelete = () => { setView('confirmDelete'); }; const confirmDelete = () => { if (config.prompts.length === 0 || selectedIndex >= config.prompts.length) return; const promptToDelete = config.prompts[selectedIndex]!; const newPrompts = config.prompts.filter((_, i) => i !== selectedIndex); const newActive = config.active.filter(id => id !== promptToDelete.id); const newConfig: SystemPromptConfig = { active: newActive, prompts: newPrompts, }; if (saveAndRefresh(newConfig)) { setSelectedIndex(Math.max(0, selectedIndex - 1)); setView('list'); } }; const handleAdd = () => { setEditName(''); setEditContent(''); setEditingField('name'); setView('add'); }; const saveNewPrompt = () => { const newPrompt: SystemPromptItem = { id: Date.now().toString(), name: editName.trim() || 'Unnamed Prompt', content: editContent, createdAt: new Date().toISOString(), }; const newConfig: SystemPromptConfig = { ...config, prompts: [...config.prompts, newPrompt], active: config.prompts.length === 0 ? [newPrompt.id] : config.active, }; if (saveAndRefresh(newConfig)) { setView('list'); setSelectedIndex(config.prompts.length); } }; const saveEditedPrompt = () => { if (config.prompts.length === 0 || selectedIndex >= config.prompts.length) return; const newConfig: SystemPromptConfig = { ...config, prompts: config.prompts.map((p, i) => i === selectedIndex ? { ...p, name: editName.trim() || 'Unnamed Prompt', content: editContent, } : p, ), }; if (saveAndRefresh(newConfig)) { setView('list'); } }; // List view input handling useInput( (_input, key) => { if (view !== 'list') return; if (key.escape) { onBack(); } else if (key.upArrow) { if (config.prompts.length > 0) { setSelectedIndex(prev => prev > 0 ? prev - 1 : config.prompts.length - 1, ); } } else if (key.downArrow) { if (config.prompts.length > 0) { setSelectedIndex(prev => prev < config.prompts.length - 1 ? prev + 1 : 0, ); } } else if (_input === ' ') { // 空格键快速切换当前选中项的激活状态 handleActivate(); } else if (key.leftArrow) { const currentIdx = actions.indexOf(currentAction); setCurrentAction( actions[currentIdx > 0 ? currentIdx - 1 : actions.length - 1]!, ); } else if (key.rightArrow) { const currentIdx = actions.indexOf(currentAction); setCurrentAction( actions[currentIdx < actions.length - 1 ? currentIdx + 1 : 0]!, ); } else if (key.return) { if (currentAction === 'activate') { handleActivate(); } else if (currentAction === 'deactivate') { handleDeactivate(); } else if (currentAction === 'edit') { handleEdit(); } else if (currentAction === 'delete') { handleDelete(); } else if (currentAction === 'add') { handleAdd(); } else if (currentAction === 'back') { onBack(); } } }, {isActive: view === 'list'}, ); // Add/Edit view input handling useInput( (input, key) => { if (view !== 'add' && view !== 'edit') return; if (key.escape) { // First ESC: Cancel editing and return to list without saving setView('list'); setError(''); } else if (!isEditing && key.upArrow) { setEditingField('name'); } else if (!isEditing && key.downArrow) { setEditingField('content'); } else if (key.return) { if (isEditing) { setIsEditing(false); } else { setIsEditing(true); } } else if (input === 's' && (key.ctrl || key.meta)) { // Ctrl+S saves and returns to list if (view === 'add') { saveNewPrompt(); } else { saveEditedPrompt(); } } else if ( !isEditing && editingField === 'content' && (input === 'e' || input === 'E') ) { // 按E键打开外部编辑器 if (view === 'edit') { handleEditWithExternalEditor(); } } }, {isActive: view === 'add' || view === 'edit'}, ); // Delete confirmation input handling useInput( (input, key) => { if (view !== 'confirmDelete') return; if (key.escape || input === 'n' || input === 'N') { setView('list'); } else if (input === 'y' || input === 'Y' || key.return) { confirmDelete(); } }, {isActive: view === 'confirmDelete'}, ); // Render list view if (view === 'list') { const activePromptNames = config.active .map(id => config.prompts.find(p => p.id === id)?.name) .filter(Boolean) .join(', '); return ( {error && ( {error} )} {t.systemPromptConfig.activePrompt}{' '} {activePromptNames || t.systemPromptConfig.none} {config.active.length > 0 && ( {' '} ( {t.systemPromptConfig.activeCount.replace( '{count}', String(config.active.length), )} ) )} {config.prompts.length === 0 ? ( {t.systemPromptConfig.noPromptsConfigured} ) : ( {t.systemPromptConfig.availablePrompts} {config.prompts.map((prompt, index) => ( {index === selectedIndex ? '❯ ' : ' '} {config.active.includes(prompt.id) ? '[✓] ' : '[ ] '} {prompt.name} {typeof prompt.content === 'string' && prompt.content.length > 0 && ( {' '} - {prompt.content.substring(0, 50)} {prompt.content.length > 50 ? '...' : ''} )} ))} )} {t.systemPromptConfig.actions} {actions.map(action => ( {currentAction === action ? '❯ ' : ' '} {action === 'activate' && t.systemPromptConfig.activate} {action === 'deactivate' && t.systemPromptConfig.deactivate} {action === 'edit' && t.systemPromptConfig.edit} {action === 'delete' && t.systemPromptConfig.delete} {action === 'add' && t.systemPromptConfig.addNew} {action === 'back' && t.systemPromptConfig.escBack} ))} {t.systemPromptConfig.navigationHint} ); } // Render add/edit view if (view === 'add' || view === 'edit') { return ( {error && ( {error} )} {editingField === 'name' ? '❯ ' : ' '} {t.systemPromptConfig.nameLabel} {editingField === 'name' && isEditing && ( )} {(!isEditing || editingField !== 'name') && ( {editName || t.systemPromptConfig.notSet} )} {editingField === 'content' ? '❯ ' : ' '} {t.systemPromptConfig.contentLabel} {editingField === 'content' && isEditing && ( )} {(!isEditing || editingField !== 'content') && ( {editContent ? editContent.substring(0, 100) + (editContent.length > 100 ? '...' : '') : t.systemPromptConfig.notSet} )} {t.systemPromptConfig.editingHint} {view === 'edit' && editingField === 'content' && !isEditing && ( {t.systemPromptConfig.externalEditorHint} )} {successMessage && ( {successMessage} )} {error && ( {error} )} ); } // Render delete confirmation if (view === 'confirmDelete') { const promptToDelete = config.prompts.length > 0 ? config.prompts[selectedIndex] : null; return ( {t.systemPromptConfig.confirmDelete} {t.systemPromptConfig.deleteConfirmMessage} " {promptToDelete?.name} "? {t.systemPromptConfig.confirmHint} ); } return null; } ================================================ FILE: source/ui/pages/TaskManagerScreen.tsx ================================================ import React, {useState, useEffect, useCallback} from 'react'; import {Box, Text, useInput} from 'ink'; import {Alert} from '@inkjs/ui'; import {useTheme} from '../contexts/ThemeContext.js'; import {useI18n} from '../../i18n/index.js'; import { taskManager, type TaskListItem, type Task, } from '../../utils/task/taskManager.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; type Props = { onBack: () => void; onResumeTask?: (taskId?: string) => void; }; export default function TaskManagerScreen({onBack, onResumeTask}: Props) { const {theme} = useTheme(); const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.taskManager.title}`); const [tasks, setTasks] = useState([]); const [selectedIndex, setSelectedIndex] = useState(0); const [scrollOffset, setScrollOffset] = useState(0); const [markedTasks, setMarkedTasks] = useState>(new Set()); const [isLoading, setIsLoading] = useState(true); const [viewMode, setViewMode] = useState<'list' | 'detail'>('list'); const [detailTask, setDetailTask] = useState(null); const [pendingAction, setPendingAction] = useState<{ type: 'delete' | 'continue'; taskId?: string; timestamp: number; } | null>(null); const [rejectInputMode, setRejectInputMode] = useState(false); const [rejectReason, setRejectReason] = useState(''); const VISIBLE_ITEMS = 5; const loadTasks = useCallback(async () => { setIsLoading(true); try { const taskList = await taskManager.listTasks(); setTasks(taskList); } catch (error) { console.error('Failed to load tasks:', error); setTasks([]); } finally { setIsLoading(false); } }, []); useEffect(() => { void loadTasks(); }, [loadTasks]); useEffect(() => { if (pendingAction) { const timer = setTimeout(() => { setPendingAction(null); }, 2000); return () => clearTimeout(timer); } return undefined; }, [pendingAction]); const handleDeleteTask = useCallback( async (taskId: string) => { if (!taskId) return; const success = await taskManager.deleteTask(taskId); if (success) { await loadTasks(); if (selectedIndex >= tasks.length - 1 && selectedIndex > 0) { setSelectedIndex(selectedIndex - 1); } } }, [loadTasks, selectedIndex, tasks.length], ); useInput((input, key) => { if (isLoading) return; // 拒绝输入模式处理 if (rejectInputMode && viewMode === 'detail' && detailTask) { if (key.return) { if (rejectReason.trim()) { void (async () => { const success = await taskManager.rejectSensitiveCommand( detailTask.id, rejectReason.trim(), ); if (success) { setRejectInputMode(false); setRejectReason(''); await loadTasks(); setViewMode('list'); } })(); } return; } if (key.escape) { setRejectInputMode(false); setRejectReason(''); return; } if (key.backspace || key.delete) { setRejectReason(prev => prev.slice(0, -1)); return; } if (input && !key.ctrl && !key.meta) { setRejectReason(prev => prev + input); return; } return; } // A键:同意敏感命令 if ((input === 'a' || input === 'A') && !key.ctrl) { if (viewMode === 'detail' && detailTask?.status === 'paused') { void (async () => { const success = await taskManager.approveSensitiveCommand( detailTask.id, ); if (success) { await loadTasks(); setViewMode('list'); } })(); return; } } // R键:拒绝敏感命令或刷新 if ((input === 'r' || input === 'R') && !key.ctrl) { if (viewMode === 'detail' && detailTask?.status === 'paused') { setRejectInputMode(true); setRejectReason(''); return; } if (viewMode === 'list') { void loadTasks(); } return; } if ((input === 'c' || input === 'C') && !key.ctrl) { if (viewMode === 'detail' && detailTask) { // 检查任务是否已完成 if (detailTask.status !== 'completed') { setPendingAction({ type: 'continue', taskId: detailTask.id, timestamp: Date.now(), }); return; } if ( pendingAction?.type === 'continue' && pendingAction.taskId === detailTask.id && Date.now() - pendingAction.timestamp < 2000 ) { setPendingAction(null); void (async () => { const sessionId = await taskManager.convertTaskToSession( detailTask.id, ); if (sessionId && onResumeTask) { onResumeTask(); } })(); } else { setPendingAction({ type: 'continue', taskId: detailTask.id, timestamp: Date.now(), }); } } return; } if (key.escape) { if (viewMode === 'detail') { setViewMode('list'); setDetailTask(null); } else { onBack(); } return; } if (key.upArrow) { setSelectedIndex(prev => { const newIndex = Math.max(0, prev - 1); if (newIndex < scrollOffset) { setScrollOffset(newIndex); } return newIndex; }); return; } if (key.downArrow) { setSelectedIndex(prev => { const newIndex = Math.min(tasks.length - 1, prev + 1); if (newIndex >= scrollOffset + VISIBLE_ITEMS) { setScrollOffset(newIndex - VISIBLE_ITEMS + 1); } return newIndex; }); return; } if (input === ' ') { const currentTask = tasks[selectedIndex]; if (currentTask) { setMarkedTasks(prev => { const next = new Set(prev); if (next.has(currentTask.id)) { next.delete(currentTask.id); } else { next.add(currentTask.id); } return next; }); } return; } if (input === 'd' || input === 'D') { if (markedTasks.size > 0) { if ( pendingAction?.type === 'delete' && !pendingAction.taskId && Date.now() - pendingAction.timestamp < 2000 ) { setPendingAction(null); const deleteMarked = async () => { const ids = Array.from(markedTasks); await Promise.all(ids.map(id => taskManager.deleteTask(id))); await loadTasks(); setMarkedTasks(new Set()); if (selectedIndex >= tasks.length && tasks.length > 0) { setSelectedIndex(tasks.length - 1); } }; void deleteMarked(); } else { setPendingAction({ type: 'delete', timestamp: Date.now(), }); } } else if (tasks.length > 0) { const currentTaskId = tasks[selectedIndex]?.id || ''; if ( pendingAction?.type === 'delete' && pendingAction.taskId === currentTaskId && Date.now() - pendingAction.timestamp < 2000 ) { setPendingAction(null); void handleDeleteTask(currentTaskId); } else { setPendingAction({ type: 'delete', taskId: currentTaskId, timestamp: Date.now(), }); } } return; } if (input === 'r' || input === 'R') { if (viewMode === 'list') { void loadTasks(); } return; } if (key.return && tasks.length > 0) { const selectedTask = tasks[selectedIndex]; if (selectedTask) { void (async () => { const fullTask = await taskManager.loadTask(selectedTask.id); if (fullTask) { setDetailTask(fullTask); setViewMode('detail'); } })(); } return; } }); const getStatusColor = useCallback((status: TaskListItem['status']) => { switch (status) { case 'pending': return 'yellow'; case 'running': return 'cyan'; case 'paused': return 'magenta'; case 'completed': return 'green'; case 'failed': return 'red'; default: return 'gray'; } }, []); const getStatusIcon = useCallback((status: TaskListItem['status']) => { switch (status) { case 'pending': return '○'; case 'running': return '◐'; case 'paused': return '⏸'; case 'completed': return '●'; case 'failed': return '✗'; default: return '?'; } }, []); const formatDate = useCallback((timestamp: number): string => { const date = new Date(timestamp); const now = new Date(); const diffMs = now.getTime() - date.getTime(); const diffMinutes = Math.floor(diffMs / (1000 * 60)); const diffHours = Math.floor(diffMinutes / 60); const diffDays = Math.floor(diffHours / 24); if (diffMinutes < 1) return 'now'; if (diffMinutes < 60) return `${diffMinutes}m`; if (diffHours < 24) return `${diffHours}h`; if (diffDays < 7) return `${diffDays}d`; return date.toLocaleDateString('en-US', {month: 'short', day: 'numeric'}); }, []); if (isLoading) { return ( {t.taskManager.loadingTasks} ); } if (tasks.length === 0) { return ( {t.taskManager.noTasksFound} • {t.taskManager.noTasksHint} •{' '} {t.taskManager.escToClose} ); } if (viewMode === 'detail' && detailTask) { return ( {t.taskManager.taskDetailsTitle} {detailTask.status === 'paused' ? t.taskManager.backToList : `${t.taskManager.continueHint} • ${t.taskManager.backToList}`} {t.taskManager.titleLabel} {detailTask.title || t.taskManager.untitled} {t.taskManager.statusLabel} {getStatusIcon(detailTask.status)} {detailTask.status} {t.taskManager.createdLabel} {new Date(detailTask.createdAt).toLocaleString()} {t.taskManager.updatedLabel} {new Date(detailTask.updatedAt).toLocaleString()} {t.taskManager.messagesLabel.replace( '{count}', String(detailTask.messages.length), )} {detailTask.status === 'paused' && detailTask.pausedInfo?.sensitiveCommand && ( {t.taskManager.sensitiveCommandDetected} {t.taskManager.commandLabel} {detailTask.pausedInfo.sensitiveCommand.command} {detailTask.pausedInfo.sensitiveCommand.description && ( {detailTask.pausedInfo.sensitiveCommand.description} )} {!rejectInputMode ? ( {t.taskManager.approveRejectHint} ) : ( {t.taskManager.enterRejectionReason} {rejectReason} █ {t.taskManager.submitCancelHint} )} )} {pendingAction?.type === 'continue' && pendingAction.taskId === detailTask.id && ( {detailTask.status !== 'completed' ? t.taskManager.taskNotCompleted : t.taskManager.confirmConvertToSession} )} ); } const visibleTasks = tasks.slice(scrollOffset, scrollOffset + VISIBLE_ITEMS); const hasMore = tasks.length > scrollOffset + VISIBLE_ITEMS; const hasPrevious = scrollOffset > 0; const currentTask = tasks[selectedIndex]; return ( {t.taskManager.tasksCount .replace('{current}', String(selectedIndex + 1)) .replace('{total}', String(tasks.length))} {currentTask && ` • ${t.taskManager.messagesCount.replace( '{count}', String(currentTask.messageCount), )}`} {markedTasks.size > 0 && ( {' '} •{' '} {t.taskManager.markedCount.replace( '{count}', String(markedTasks.size), )} )} {t.taskManager.navigationHint} {hasPrevious && ( {' '} {t.taskManager.moreAbove.replace('{count}', String(scrollOffset))} )} {visibleTasks.map((task, index) => { const actualIndex = scrollOffset + index; const isSelected = actualIndex === selectedIndex; const isMarked = markedTasks.has(task.id); const cleanTitle = (task.title || t.taskManager.untitled).replace( /[\r\n\t]+/g, ' ', ); const timeStr = formatDate(task.updatedAt); const truncatedTitle = cleanTitle.length > 50 ? cleanTitle.slice(0, 47) + '...' : cleanTitle; return ( {isSelected ? '❯ ' : ' '} {isMarked && ( ●{' '} )} {getStatusIcon(task.status)} {' '} {truncatedTitle} {' '} • {timeStr} ); })} {hasMore && ( {' '} {t.taskManager.moreBelow.replace( '{count}', String(tasks.length - scrollOffset - VISIBLE_ITEMS), )} )} {pendingAction?.type === 'delete' && ( {pendingAction.taskId ? t.taskManager.deleteConfirm : t.taskManager.deleteMultipleConfirm.replace( '{count}', String(markedTasks.size), )} )} ); } ================================================ FILE: source/ui/pages/ThemeSettingsScreen.tsx ================================================ import React, { useMemo, useCallback, useState, useEffect, Suspense, } from 'react'; import {Box, Text, useInput, useStdout} from 'ink'; import {Alert, Spinner} from '@inkjs/ui'; import Menu from '../components/common/Menu.js'; import DiffViewer from '../components/tools/DiffViewer.js'; import UserMessagePreview from '../components/chat/UserMessagePreview.js'; import {useTheme} from '../contexts/ThemeContext.js'; import {ThemeType} from '../themes/index.js'; import {useI18n} from '../../i18n/index.js'; import {getSimpleMode, setSimpleMode} from '../../utils/config/themeConfig.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; const CustomThemeScreen = React.lazy(() => import('./CustomThemeScreen.js')); type Props = { onBack: () => void; inlineMode?: boolean; }; type Screen = 'main' | 'custom'; const sampleOldCode = `function greet(name) { console.log("Hello " + name); return "Welcome!"; }`; const sampleNewCode = `function greet(name: string): string { console.log(\`Hello \${name}\`); return \`Welcome, \${name}!\`; }`; export default function ThemeSettingsScreen({ onBack, inlineMode = false, }: Props) { const {themeType, setThemeType, diffOpacity, setDiffOpacity} = useTheme(); const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.themeSettings.title}`); const {stdout} = useStdout(); // Use themeType from context which is already loaded from config const [selectedTheme, setSelectedTheme] = useState(themeType); const [infoText, setInfoText] = useState(''); const [screen, setScreen] = useState('main'); const [simpleMode, setSimpleModeState] = useState(() => getSimpleMode(), ); const terminalHeight = stdout?.rows || 24; const themeMenuHeight = Math.max(4, Math.min(8, terminalHeight - 18)); // Load simple mode on mount useEffect(() => { setSimpleModeState(getSimpleMode()); }, []); const handleToggleSimpleMode = useCallback(() => { const newSimpleMode = !simpleMode; setSimpleModeState(newSimpleMode); setSimpleMode(newSimpleMode); }, [simpleMode]); const handleAdjustDiffOpacity = useCallback(() => { const nextOpacity = diffOpacity >= 1 ? 0.3 : diffOpacity + 0.1; setDiffOpacity(Number(nextOpacity.toFixed(2))); }, [diffOpacity, setDiffOpacity]); const themeOptions = useMemo( () => [ { label: `${t.themeSettings.simpleMode} ${ simpleMode ? t.themeSettings.enabled : t.themeSettings.disabled }`, value: 'simple-mode', infoText: t.themeSettings.simpleModeInfo, }, { label: `${t.themeSettings.diffOpacity} ${Math.round( diffOpacity * 100, )}%`, value: 'diff-opacity', infoText: t.themeSettings.diffOpacityInfo, }, { label: selectedTheme === 'dark' ? `✓ ${t.themeSettings.darkTheme}` : t.themeSettings.darkTheme, value: 'dark', infoText: t.themeSettings.darkThemeInfo, }, { label: selectedTheme === 'light' ? `✓ ${t.themeSettings.lightTheme}` : t.themeSettings.lightTheme, value: 'light', infoText: t.themeSettings.lightThemeInfo, }, { label: selectedTheme === 'github-dark' ? `✓ ${t.themeSettings.githubDark}` : t.themeSettings.githubDark, value: 'github-dark', infoText: t.themeSettings.githubDarkInfo, }, { label: selectedTheme === 'rainbow' ? `✓ ${t.themeSettings.rainbow}` : t.themeSettings.rainbow, value: 'rainbow', infoText: t.themeSettings.rainbowInfo, }, { label: selectedTheme === 'solarized-dark' ? `✓ ${t.themeSettings.solarizedDark}` : t.themeSettings.solarizedDark, value: 'solarized-dark', infoText: t.themeSettings.solarizedDarkInfo, }, { label: selectedTheme === 'nord' ? `✓ ${t.themeSettings.nord}` : t.themeSettings.nord, value: 'nord', infoText: t.themeSettings.nordInfo, }, { label: selectedTheme === 'tiffany' ? `✓ ${t.themeSettings.tiffany}` : t.themeSettings.tiffany, value: 'tiffany', infoText: t.themeSettings.tiffanyInfo, }, { label: selectedTheme === 'macaron-pink' ? `✓ ${t.themeSettings.macaronPink}` : t.themeSettings.macaronPink, value: 'macaron-pink', infoText: t.themeSettings.macaronPinkInfo, }, { label: selectedTheme === 'custom' ? `✓ ${t.themeSettings?.custom || 'Custom'}` : t.themeSettings?.custom || 'Custom', value: 'custom', infoText: t.themeSettings?.customInfo || 'Use your own custom colors', }, { label: t.themeSettings?.editCustom || 'Edit Custom Theme...', value: 'edit-custom', infoText: t.themeSettings?.editCustomInfo || 'Customize theme colors', }, { label: t.themeSettings.back, value: 'back', color: 'gray', infoText: t.themeSettings.backInfo, }, ], [selectedTheme, simpleMode, diffOpacity, t], ); const handleSelect = useCallback( (value: string) => { if (value === 'back') { // Restore original theme if cancelled setThemeType(selectedTheme); onBack(); } else if (value === 'simple-mode') { // Toggle simple mode handleToggleSimpleMode(); } else if (value === 'diff-opacity') { handleAdjustDiffOpacity(); } else if (value === 'edit-custom') { // Go to custom theme editor setScreen('custom'); } else { // Confirm and apply the theme (Enter pressed) const newTheme = value as ThemeType; setSelectedTheme(newTheme); setThemeType(newTheme); } }, [ onBack, setThemeType, selectedTheme, handleToggleSimpleMode, handleAdjustDiffOpacity, ], ); const handleSelectionChange = useCallback( (newInfoText: string, value: string) => { setInfoText(newInfoText); // Preview theme on selection change (navigation) if ( value === 'back' || value === 'edit-custom' || value === 'simple-mode' || value === 'diff-opacity' ) { // Restore to selected theme when hovering on "Back", "Edit Custom", or "Simple Mode" setThemeType(selectedTheme); } else { // Preview the theme setThemeType(value as ThemeType); } }, [setThemeType, selectedTheme], ); const handleBackFromCustom = useCallback((nextSelectedTheme?: ThemeType) => { setScreen('main'); if (nextSelectedTheme) { setSelectedTheme(nextSelectedTheme); } }, []); useInput( (_input, key) => { if (key.escape) { // Restore original theme on ESC setThemeType(selectedTheme); onBack(); } }, {isActive: screen === 'main'}, ); if (screen === 'custom') { return ( }> ); } return ( {!inlineMode && ( {t.themeSettings.title} )} {t.themeSettings.current}{' '} {themeOptions .find(opt => opt.value === selectedTheme) ?.label.replace('✓ ', '') || selectedTheme} {t.themeSettings.preview} {t.themeSettings.userMessagePreview} {infoText && ( {infoText} )} ); } ================================================ FILE: source/ui/pages/WelcomeScreen.tsx ================================================ import React, { useState, useMemo, useCallback, useEffect, useRef, Suspense, } from 'react'; import {Box, Text, useStdout} from 'ink'; import ansiEscapes from 'ansi-escapes'; import Spinner from 'ink-spinner'; import Menu from '../components/common/Menu.js'; import {ChatHeaderLogo} from '../components/special/ChatHeader.js'; import {useTerminalSize} from '../../hooks/ui/useTerminalSize.js'; import {useI18n} from '../../i18n/index.js'; import {getUpdateNotice, onUpdateNotice} from '../../utils/ui/updateNotice.js'; import {useTheme} from '../contexts/ThemeContext.js'; import UpdateNotice from '../components/common/UpdateNotice.js'; import {useTerminalTitle} from '../../hooks/ui/useTerminalTitle.js'; import {runUpdateAndExit} from '../../utils/core/runUpdate.js'; // Lazy load all configuration screens for better startup performance const ConfigScreen = React.lazy(() => import('./ConfigScreen.js')); const ProxyConfigScreen = React.lazy(() => import('./ProxyConfigScreen.js')); const SubAgentConfigScreen = React.lazy( () => import('./SubAgentConfigScreen.js'), ); const SubAgentListScreen = React.lazy(() => import('./SubAgentListScreen.js')); const SensitiveCommandConfigScreen = React.lazy( () => import('./SensitiveCommandConfigScreen.js'), ); const CodeBaseConfigScreen = React.lazy( () => import('./CodeBaseConfigScreen.js'), ); const SystemPromptConfigScreen = React.lazy( () => import('./SystemPromptConfigScreen.js'), ); const CustomHeadersScreen = React.lazy( () => import('./CustomHeadersScreen.js'), ); const LanguageSettingsScreen = React.lazy( () => import('./LanguageSettingsScreen.js'), ); const ThemeSettingsScreen = React.lazy( () => import('./ThemeSettingsScreen.js'), ); const HooksConfigScreen = React.lazy(() => import('./HooksConfigScreen.js')); const MCPConfigScreen = React.lazy(() => import('./MCPConfigScreen.js')); // 模块级标志：保证 SNOW CLI LOGO 的逐字符出现动画在整个进程生命周期内只播放一次。 // 任何后续的重渲染（菜单切换返回、终端 resize 触发的 remount 等）都直接显示完整 LOGO， // 不会再次触发动画。 let hasPlayedLogoRevealAnimation = false; // LOGO 完整版可见字符总数（3 行 × 21 字符 = 63），用作 reveal 的上限。 // 中等版（36）小于该值，所以同一个 totalChars 也能让中等版提前完成动画。 const LOGO_REVEAL_MAX_CHARS = 63; // 每个字符出现的间隔时间（毫秒），决定动画的整体速度。 const LOGO_REVEAL_INTERVAL_MS = 10; type Props = { version?: string; onMenuSelect?: (value: string) => void; defaultMenuIndex?: number; onMenuSelectionPersist?: (index: number) => void; }; type InlineView = | 'menu' | 'config' | 'proxy-config' | 'codebase-config' | 'subagent-list' | 'subagent-add' | 'subagent-edit' | 'sensitive-commands' | 'systemprompt' | 'customheaders' | 'hooks-config' | 'mcp-config' | 'language-settings' | 'theme-settings'; export default function WelcomeScreen({ version = '1.0.0', onMenuSelect, defaultMenuIndex = 0, onMenuSelectionPersist, }: Props) { const {t} = useI18n(); useTerminalTitle(`Snow CLI - ${t.welcome.title}`); const {theme} = useTheme(); const [infoText, setInfoText] = useState(t.welcome.startChatInfo); const [inlineView, setInlineView] = useState('menu'); const [updateNotice, setUpdateNoticeState] = useState(getUpdateNotice()); const [editingAgentId, setEditingAgentId] = useState(); const {columns: terminalWidth} = useTerminalSize(); const {stdout} = useStdout(); const isInitialMount = useRef(true); // LOGO 逐字符出现动画： // - revealChars === undefined 表示动画已结束（或本次进程之前已播放过），完整显示。 // - 数字值表示当前可见的字符数，会从 0 递增到 LOGO_REVEAL_MAX_CHARS。 // 使用模块级 hasPlayedLogoRevealAnimation 保证只在首次进入时播放一次。 const [logoRevealChars, setLogoRevealChars] = useState( () => (hasPlayedLogoRevealAnimation ? undefined : 0), ); useEffect(() => { if (hasPlayedLogoRevealAnimation) return; const interval = setInterval(() => { setLogoRevealChars(prev => { if (prev === undefined) return undefined; const next = prev + 1; if (next >= LOGO_REVEAL_MAX_CHARS) { clearInterval(interval); hasPlayedLogoRevealAnimation = true; // 切换为 undefined 让 ChatHeaderLogo 直接渲染完整字符串， // 后续重渲染不再走遮罩逻辑。 return undefined; } return next; }); }, LOGO_REVEAL_INTERVAL_MS); return () => clearInterval(interval); }, []); // 当终端宽度变化触发清屏时，先渲染为 null 一帧，把 ink/log-update 内部 // "上一帧"缓存重置为空字符串；下一帧再切回 false 恢复完整内容， // 使新内容必然作为差异被完整写出，避免清屏后画面丢失。 const [isResizing, setIsResizing] = useState(false); const inlineDivider = useMemo(() => { const dividerWidth = Math.max(0, terminalWidth - 2); return dividerWidth > 0 ? '-'.repeat(dividerWidth) : ''; }, [terminalWidth]); // Local state for menu index, synced with parent's defaultMenuIndex const [currentMenuIndex, setCurrentMenuIndex] = useState(defaultMenuIndex); // Track sub-menu indices for persistence const [subAgentListIndex, setSubAgentListIndex] = useState(0); const [hooksConfigIndex, setHooksConfigIndex] = useState(0); // Sync with parent's defaultMenuIndex when it changes useEffect(() => { setCurrentMenuIndex(defaultMenuIndex); }, [defaultMenuIndex]); useEffect(() => { const unsubscribe = onUpdateNotice(notice => { setUpdateNoticeState(notice); }); return unsubscribe; }, []); const hasUpdate = !!updateNotice; const menuOptions = useMemo( () => [ { label: t.welcome.startChat, value: 'chat', infoText: t.welcome.startChatInfo, clearTerminal: true, }, { label: t.welcome.resumeLastChat, value: 'resume-last', infoText: t.welcome.resumeLastChatInfo, clearTerminal: true, }, { label: t.welcome.apiSettings, value: 'config', infoText: t.welcome.apiSettingsInfo, }, { label: t.welcome.proxySettings, value: 'proxy', infoText: t.welcome.proxySettingsInfo, }, { label: t.welcome.codebaseSettings, value: 'codebase', infoText: t.welcome.codebaseSettingsInfo, }, { label: t.welcome.systemPromptSettings, value: 'systemprompt', infoText: t.welcome.systemPromptSettingsInfo, }, { label: t.welcome.customHeadersSettings, value: 'customheaders', infoText: t.welcome.customHeadersSettingsInfo, }, { label: t.welcome.mcpSettings, value: 'mcp', infoText: t.welcome.mcpSettingsInfo, }, { label: t.welcome.subAgentSettings, value: 'subagent', infoText: t.welcome.subAgentSettingsInfo, }, { label: t.welcome.sensitiveCommands, value: 'sensitive-commands', infoText: t.welcome.sensitiveCommandsInfo, }, { label: t.welcome.hooksSettings, value: 'hooks', infoText: t.welcome.hooksSettingsInfo, }, { label: t.welcome.languageSettings, value: 'language', infoText: t.welcome.languageSettingsInfo, }, { label: t.welcome.themeSettings, value: 'theme', infoText: t.welcome.themeSettingsInfo, }, ...(hasUpdate ? [ { label: `${t.welcome.updateNow}${ updateNotice ? ` (v${updateNotice.latestVersion})` : '' }`, value: 'update-now', color: '#FFD700', infoText: t.welcome.updateNowInfo, clearTerminal: true, }, ] : []), { label: t.welcome.exit, value: 'exit', color: 'rgb(232, 131, 136)', infoText: t.welcome.exitInfo, }, ], [t, hasUpdate, updateNotice], ); const [remountKey, setRemountKey] = useState(0); // Cache menuOptions value-to-index map for O(1) lookups const optionsIndexMap = useMemo(() => { const map = new Map(); menuOptions.forEach((opt, idx) => { map.set(opt.value, idx); }); return map; }, [menuOptions]); const handleSelectionChange = useCallback( (newInfoText: string, value: string) => { // Only update if infoText actually changed (avoid unnecessary re-renders) setInfoText(prev => (prev === newInfoText ? prev : newInfoText)); // Use cached map for O(1) index lookup instead of O(n) findIndex const index = optionsIndexMap.get(value); if (index !== undefined) { setCurrentMenuIndex(index); onMenuSelectionPersist?.(index); } }, [optionsIndexMap, onMenuSelectionPersist], ); const handleInlineMenuSelect = useCallback( (value: string) => { // Persist the selected index before navigating const index = menuOptions.findIndex(opt => opt.value === value); if (index !== -1) { setCurrentMenuIndex(index); onMenuSelectionPersist?.(index); } // Handle inline views (config, proxy, codebase, subagent) or pass through to parent if (value === 'config') { setInlineView('config'); } else if (value === 'proxy') { setInlineView('proxy-config'); } else if (value === 'codebase') { setInlineView('codebase-config'); } else if (value === 'subagent') { setInlineView('subagent-list'); } else if (value === 'sensitive-commands') { setInlineView('sensitive-commands'); } else if (value === 'systemprompt') { setInlineView('systemprompt'); } else if (value === 'customheaders') { setInlineView('customheaders'); } else if (value === 'mcp') { setInlineView('mcp-config'); } else if (value === 'hooks') { setInlineView('hooks-config'); } else if (value === 'language') { setInlineView('language-settings'); } else if (value === 'theme') { setInlineView('theme-settings'); } else if (value === 'update-now') { // Hand the terminal over to npm: unmount Ink and exec the update. // runUpdateAndExit() does not return — the process exits when // the npm child finishes. runUpdateAndExit(); } else { // Pass through to parent for other actions (chat, exit, etc.) onMenuSelect?.(value); } }, [onMenuSelect, menuOptions, onMenuSelectionPersist], ); const handleBackToMenu = useCallback(() => { setInlineView('menu'); }, []); const handleConfigSave = useCallback(() => { setInlineView('menu'); }, []); const handleSubAgentAdd = useCallback(() => { setEditingAgentId(undefined); setInlineView('subagent-add'); }, []); const handleSubAgentEdit = useCallback((agentId: string) => { setEditingAgentId(agentId); setInlineView('subagent-edit'); }, []); const handleSubAgentBack = useCallback(() => { // 从三级返回二级时清除终端以避免残留显示 stdout.write(ansiEscapes.clearTerminal); setRemountKey(prev => prev + 1); setInlineView('subagent-list'); }, [stdout]); const handleSubAgentSave = useCallback(() => { // 保存后返回二级列表，清除终端以避免残留显示 stdout.write(ansiEscapes.clearTerminal); setRemountKey(prev => prev + 1); setInlineView('subagent-list'); }, [stdout]); // 终端宽度变化时清屏并强制重新绘制，避免 ink/log-update 因为旧内容尺寸 // 与新尺寸不匹配而留下残影/错位。 // 关键：清屏后必须先渲染为 null 一帧（让 log-update 的内部缓存被刷成空字符串）， // 下一 tick 再切回 false，这样下一帧的真实内容就会作为完整新内容被写出， // 不再依赖被移除的顶部 来"补回"内容。 useEffect(() => { if (isInitialMount.current) { isInitialMount.current = false; return; } const handler = setTimeout(() => { stdout.write(ansiEscapes.clearTerminal); setIsResizing(true); setRemountKey(prev => prev + 1); // 在下一个事件循环 tick 切回 false，确保 React 至少 commit 了 // 一次"渲染为 null"的中间帧，从而真正重置 log-update 的上一帧缓存。 setImmediate(() => { setIsResizing(false); }); }, 200); // 防抖，避免连续 resize 时频繁清屏 return () => { clearTimeout(handler); }; }, [terminalWidth, stdout]); // Loading fallback component for lazy-loaded screens const loadingFallback = ( Loading... ); // Estimated logo column width passed to ChatHeaderLogo for responsive sizing. // Outer paddingX(2) + round border(2) = 4 columns reserved; right half also // pays for the 1-col vertical divider and inner paddingX(2 on each side = 4). const logoColumnWidth = Math.max(0, Math.floor((terminalWidth - 4) / 2) - 5); // 右侧 LOGO 区只有在 logoColumnWidth >= 20（中等/完整 LOGO 才会被渲染）时才有意义。 // 否则 ChatHeaderLogo 在 hideCompact 模式下会返回 null，留下一个空的右半区—— // 此时直接把整个圆角框让给 Menu 占满，不再做左右拆分。 const showLogoPane = logoColumnWidth >= 20; // 当右侧 LOGO 走"完整最大版"分支（terminalWidth >= 30，对应这里 logoColumnWidth >= 30） // 且存在更新提示时：把更新提示从顶部移到右侧 LOGO 下方，LOGO 区改为顶端对齐让 LOGO 上移， // 这样在宽终端下能更紧凑地利用右半区的垂直空间。 const isFullLogoPane = showLogoPane && logoColumnWidth >= 30; const showUpdateNoticeInLogoPane = isFullLogoPane && !!updateNotice; // 调整终端宽度后清屏的中间帧：渲染为 null，强制 log-update 把上一帧缓存 // 重置为空字符串，下一帧的真实内容才能作为完整新内容被写出。 if (isResizing) { return null; } return ( {inlineView === 'menu' && updateNotice && !showUpdateNoticeInLogoPane && ( )} {/* Unified rounded frame: - 宽终端：Menu (left 50%) | Logo + version + greeting (right 50%) - 窄终端（logoColumnWidth < 20，LOGO 不会渲染）：整框只放 Menu，不再拆分左右两半 */} {onMenuSelect && inlineView === 'menu' && ( {showLogoPane ? ( <> {/* 左半 Menu：把竖线分隔放到这里的 right border 上。 原因：Menu 内部会因 scroll 提示（↑ N more above / ↓ N more below） 在不同选中项下出现/消失，行高动态变化。row 容器高度跟随更高的 Menu， 若把竖线放在右半 Logo Box 上，yoga 不一定会把右半 stretch 到 row 高度， 会导致竖线只画 Logo 自身那几行。把竖线挂在 Menu Box 上则自然贴满全高。 */} v{version} • {t.welcome.subtitle} {showUpdateNoticeInLogoPane && updateNotice && ( )} ) : ( )} {/* 框内底部说明区：使用上边框作为横向分隔线，与外框融为一体 */} {infoText} )} {/* Render inline view content based on current state */} {inlineView !== 'menu' && ( {inlineDivider} )} {inlineView === 'config' && ( )} {inlineView === 'proxy-config' && ( )} {inlineView === 'codebase-config' && ( )} {inlineView === 'subagent-list' && ( )} {inlineView === 'subagent-add' && ( )} {inlineView === 'subagent-edit' && ( )} {inlineView === 'sensitive-commands' && ( )} {inlineView === 'systemprompt' && ( )} {inlineView === 'customheaders' && ( )} {inlineView === 'mcp-config' && ( )} {inlineView === 'hooks-config' && ( )} {inlineView === 'language-settings' && ( )} {inlineView === 'theme-settings' && ( )} ); } ================================================ FILE: source/ui/pages/chatScreen/ChatScreenConversationView.tsx ================================================ import React from 'react'; import {Box, Static} from 'ink'; import type {Message} from '../../components/chat/MessageList.js'; import PendingMessages from '../../components/chat/PendingMessages.js'; import ToolConfirmation from '../../components/tools/ToolConfirmation.js'; import AskUserQuestion from '../../components/special/AskUserQuestion.js'; import { BashCommandConfirmation, BashCommandExecutionStatus, } from '../../components/bash/BashCommandConfirmation.js'; import {CustomCommandExecutionDisplay} from '../../components/bash/CustomCommandExecutionDisplay.js'; import {SchedulerCountdown} from '../../components/scheduler/SchedulerCountdown.js'; import MessageRenderer from '../../components/chat/MessageRenderer.js'; import ChatHeader from '../../components/special/ChatHeader.js'; import {HookErrorDisplay} from '../../components/special/HookErrorDisplay.js'; import {CompressionStatus} from '../../components/compression/CompressionStatus.js'; import type {CompressionStatus as CompressionStatusType} from '../../components/compression/CompressionStatus.js'; import type {HookErrorDetails} from '../../../utils/execution/hookResultInterpreter.js'; import type { BashSensitiveCommandState, CustomCommandExecutionState, PendingMessageInput, PendingUserQuestionState, } from './types.js'; type Props = { remountKey: number; terminalWidth: number; workingDirectory: string; simpleMode: boolean; messages: Message[]; showThinking: boolean; pendingMessages: PendingMessageInput[]; pendingToolConfirmation: any; pendingUserQuestion: PendingUserQuestionState; bashSensitiveCommand: BashSensitiveCommandState; terminalExecutionState: any; schedulerExecutionState: any; customCommandExecution: CustomCommandExecutionState; bashMode: any; hookError: HookErrorDetails | null; handleUserQuestionAnswer: (result: any) => void; setHookError: React.Dispatch>; compressionStatus: CompressionStatusType | null; }; export default function ChatScreenConversationView({ remountKey, terminalWidth, workingDirectory, simpleMode, messages, showThinking, pendingMessages, pendingToolConfirmation, pendingUserQuestion, bashSensitiveCommand, terminalExecutionState, schedulerExecutionState, customCommandExecution, bashMode, hookError, handleUserQuestionAnswer, setHookError, compressionStatus, }: Props) { return ( <> , ...messages .filter(m => !m.streaming) .map((message, index, filteredMessages) => ( )), ]} > {item => item} {hookError && ( )} {compressionStatus && ( )} {/* 当同时存在工具确认和交互问题时，优先显示交互组件（AskUserQuestion）*/} {pendingToolConfirmation && !pendingUserQuestion && ( { setHookError(error); }} /> )} {bashSensitiveCommand && ( )} {bashMode.state.isExecuting && bashMode.state.currentCommand && ( )} {customCommandExecution && ( )} {terminalExecutionState.state.isExecuting && !terminalExecutionState.state.isBackgrounded && terminalExecutionState.state.command && ( )} {schedulerExecutionState?.state?.isRunning && schedulerExecutionState?.state?.description && ( )} {pendingUserQuestion && ( )} ); } ================================================ FILE: source/ui/pages/chatScreen/ChatScreenPanels.tsx ================================================ import React, {lazy, Suspense} from 'react'; import {Box, Text} from 'ink'; import Spinner from 'ink-spinner'; import type {Dispatch, SetStateAction} from 'react'; import type {Message} from '../../components/chat/MessageList.js'; import PanelsManager from '../../components/panels/PanelsManager.js'; import FileRollbackConfirmation, { type RollbackMode, } from '../../components/tools/FileRollbackConfirmation.js'; import { saveCustomCommand, registerCustomCommands, } from '../../../utils/commands/custom.js'; import { createSkillFromGenerated, createSkillTemplate, } from '../../../utils/commands/skills.js'; import {sessionManager} from '../../../utils/session/sessionManager.js'; import type { PanelActions, PanelState, } from '../../../hooks/ui/usePanelState.js'; import PixelEditorScreen from '../PixelEditorScreen.js'; const PermissionsPanel = lazy( () => import('../../components/panels/PermissionsPanel.js'), ); const NewPromptPanel = lazy( () => import('../../components/panels/NewPromptPanel.js'), ); const SubAgentDepthPanel = lazy( () => import('../../components/panels/SubAgentDepthPanel.js'), ); const ProfileEditPanel = lazy( () => import('../../components/panels/ProfileEditPanel.js'), ); const ModelsPanel = lazy(() => import('../../components/panels/ModelsPanel.js').then(m => ({ default: m.ModelsPanel, })), ); type SnapshotState = { snapshotFileCount: Map; pendingRollback: { messageIndex: number; fileCount: number; filePaths?: string[]; notebookCount?: number; teamCount?: number; } | null; }; type Props = { terminalWidth: number; workingDirectory: string; panelState: PanelState & PanelActions; snapshotState: SnapshotState; handleSessionPanelSelect: (sessionId: string) => Promise; showPermissionsPanel: boolean; setShowPermissionsPanel: Dispatch>; showSubAgentDepthPanel: boolean; setShowSubAgentDepthPanel: Dispatch>; modelsPanelAdvancedModel: string; modelsPanelBasicModel: string; alwaysApprovedTools: Set; removeFromAlwaysApproved: (toolName: string) => void; clearAllAlwaysApproved: () => void; setMessages: Dispatch>; t: any; onPromptAccept: (prompt: string) => void; handleRollbackConfirm: ( mode: RollbackMode | null, selectedFiles?: string[], ) => void; }; export default function ChatScreenPanels({ terminalWidth, workingDirectory, panelState, snapshotState, handleSessionPanelSelect, showPermissionsPanel, setShowPermissionsPanel, showSubAgentDepthPanel, setShowSubAgentDepthPanel, modelsPanelAdvancedModel, modelsPanelBasicModel, alwaysApprovedTools, removeFromAlwaysApproved, clearAllAlwaysApproved, setMessages, t, onPromptAccept, handleRollbackConfirm, }: Props) { return ( <> { await saveCustomCommand( name, command, type, description, location, workingDirectory, ); await registerCustomCommands(workingDirectory); panelState.setShowCustomCommandConfig(false); const typeDesc = type === 'execute' ? t.customCommand.resultTypeExecute : t.customCommand.resultTypePrompt; const locationDesc = location === 'global' ? t.customCommand.resultLocationGlobal : t.customCommand.resultLocationProject; const content = t.customCommand.saveSuccessMessage .replace('{name}', name) .replace('{type}', typeDesc) .replace('{location}', locationDesc); const successMessage: Message = { role: 'command', content, commandName: 'custom', }; setMessages(prev => [...prev, successMessage]); }} onSkillsSave={async (skillName, description, location, generated) => { const result = generated ? await createSkillFromGenerated( skillName, description, generated, location, workingDirectory, ) : await createSkillTemplate( skillName, description, location, workingDirectory, ); panelState.setShowSkillsCreation(false); if (result.success) { const locationDesc = location === 'global' ? t.skillsCreation.locationGlobal : t.skillsCreation.locationProject; const modeDesc = generated ? t.skillsCreation.resultModeAi : t.skillsCreation.resultModeManual; const content = t.skillsCreation.createSuccessMessage .replace('{name}', skillName) .replace('{mode}', modeDesc) .replace('{location}', locationDesc) .replace('{path}', result.path); const successMessage: Message = { role: 'command', content, commandName: 'skills', }; setMessages(prev => [...prev, successMessage]); } else { const errorText = result.error || t.skillsCreation.errorUnknown; const content = t.skillsCreation.createErrorMessage.replace( '{error}', errorText, ); const errorMessage: Message = { role: 'command', content, commandName: 'skills', }; setMessages(prev => [...prev, errorMessage]); } }} onRoleSave={async location => { const {createRoleFile} = await import( '../../../utils/commands/role.js' ); const result = await createRoleFile(location, workingDirectory); panelState.setShowRoleCreation(false); if (result.success) { const locationDesc = location === 'global' ? t.roleCreation.locationGlobal : t.roleCreation.locationProject; const content = t.roleCreation.createSuccessMessage .replace('{location}', locationDesc) .replace('{path}', result.path); const successMessage: Message = { role: 'command', content, commandName: 'role', }; setMessages(prev => [...prev, successMessage]); } else { const errorText = result.error || t.roleCreation.errorUnknown; const content = t.roleCreation.createErrorMessage.replace( '{error}', errorText, ); const errorMessage: Message = { role: 'command', content, commandName: 'role', }; setMessages(prev => [...prev, errorMessage]); } }} onRoleSubagentSave={async (agentName, location) => { const {createRoleSubagentFile} = await import( '../../../utils/commands/roleSubagent.js' ); const result = await createRoleSubagentFile( agentName, location, workingDirectory, ); panelState.setShowRoleSubagentCreation(false); if (result.success) { const locationDesc = location === 'global' ? t.roleSubagentCreation?.locationGlobal || 'Global' : t.roleSubagentCreation?.locationProject || 'Project'; const content = ( t.roleSubagentCreation?.createSuccessMessage || 'Created sub-agent role successfully! | Agent: {agent} | Location: {location} | Path: {path}' ) .replace('{agent}', agentName) .replace('{location}', locationDesc) .replace('{path}', result.path); const successMessage: Message = { role: 'command', content, commandName: 'role-subagent', }; setMessages(prev => [...prev, successMessage]); } else { const errorText = result.error || t.roleSubagentCreation?.errorUnknown || 'Unknown error'; const content = ( t.roleSubagentCreation?.createErrorMessage || 'Failed to create sub-agent role: {error}' ).replace('{error}', errorText); const errorMessage: Message = { role: 'command', content, commandName: 'role-subagent', }; setMessages(prev => [...prev, errorMessage]); } }} onRoleSubagentDelete={async (agentName, location) => { const {deleteRoleSubagentFile} = await import( '../../../utils/commands/roleSubagent.js' ); const result = await deleteRoleSubagentFile( agentName, location, workingDirectory, ); panelState.setShowRoleSubagentDeletion(false); if (result.success) { const locationDesc = location === 'global' ? t.roleSubagentDeletion?.locationGlobal || 'Global' : t.roleSubagentDeletion?.locationProject || 'Project'; const content = ( t.roleSubagentDeletion?.deleteSuccessMessage || 'Deleted sub-agent role successfully! | Agent: {agent} | Location: {location} | Path: {path}' ) .replace('{agent}', agentName) .replace('{location}', locationDesc) .replace('{path}', result.path); const successMessage: Message = { role: 'command', content, commandName: 'role-subagent', }; setMessages(prev => [...prev, successMessage]); } else { const errorText = result.error || t.roleSubagentDeletion?.errorUnknown || 'Unknown error'; const content = ( t.roleSubagentDeletion?.deleteErrorMessage || 'Failed to delete sub-agent role: {error}' ).replace('{error}', errorText); const errorMessage: Message = { role: 'command', content, commandName: 'role-subagent', }; setMessages(prev => [...prev, errorMessage]); } }} onRoleDelete={async location => { const {deleteRoleFile} = await import( '../../../utils/commands/role.js' ); const result = await deleteRoleFile(location, workingDirectory); panelState.setShowRoleDeletion(false); if (result.success) { const locationDesc = location === 'global' ? t.roleDeletion.locationGlobal : t.roleDeletion.locationProject; const content = t.roleDeletion.deleteSuccessMessage .replace('{location}', locationDesc) .replace('{path}', result.path); const successMessage: Message = { role: 'command', content, commandName: 'role', }; setMessages(prev => [...prev, successMessage]); } else { const errorText = result.error || t.roleDeletion.errorUnknown; const content = t.roleDeletion.deleteErrorMessage.replace( '{error}', errorText, ); const errorMessage: Message = { role: 'command', content, commandName: 'role', }; setMessages(prev => [...prev, errorMessage]); } }} /> {panelState.showNewPromptPanel && ( Loading... } > { panelState.setShowNewPromptPanel(false); onPromptAccept(prompt); }} onCancel={() => { panelState.setShowNewPromptPanel(false); }} /> )} {showSubAgentDepthPanel && ( Loading... } > setShowSubAgentDepthPanel(false)} /> )} {showPermissionsPanel && ( Loading... } > setShowPermissionsPanel(false)} /> )} {snapshotState.pendingRollback && ( )} {panelState.showPixelEditor && ( panelState.setShowPixelEditor(false)} /> )} {panelState.showModelsPanel && ( Loading... } > panelState.setShowModelsPanel(false)} /> )} {/* ProfileEditPanel：从 ProfilePanel 按右方向键进入， 编辑指定 profile（不切换 active）。ESC 由 ConfigScreen 内部处理： 保存配置并通过 onBack 触发 closeProfileEditAndReturnToPicker， 返回到 ProfilePanel（picker）。 */} {panelState.showProfileEditPanel && panelState.editingProfileName && ( Loading... } > )} ); } ================================================ FILE: source/ui/pages/chatScreen/types.ts ================================================ export type PendingMessageInput = { text: string; images?: Array<{data: string; mimeType: string}>; }; export type InputImage = { type: 'image'; data: string; mimeType: string; }; export type RestoreInputContent = { text: string; images?: InputImage[]; } | null; export type DraftContent = RestoreInputContent; export type BashSensitiveCommandState = { command: string; resolve: (proceed: boolean) => void; } | null; export type CustomCommandExecutionState = { commandName: string; command: string; isRunning: boolean; output: string[]; exitCode?: number | null; error?: string; } | null; export type PendingUserQuestionResult = { selected: string | string[]; customInput?: string; cancelled?: boolean; }; export type PendingUserQuestionState = { question: string; options: string[]; toolCall: any; resolve: (result: PendingUserQuestionResult) => void; } | null; export type CodebaseProgressState = { totalFiles: number; processedFiles: number; totalChunks: number; currentFile: string; status: string; error?: string; } | null; export type FileUpdateNotificationState = { file: string; timestamp: number; } | null; ================================================ FILE: source/ui/pages/chatScreen/useBackgroundProcessSelection.ts ================================================ import {useEffect, useMemo, useState} from 'react'; import type {BackgroundProcess} from '../../../hooks/execution/useBackgroundProcesses.js'; export function useBackgroundProcessSelection(processes: BackgroundProcess[]) { const [selectedProcessIndex, setSelectedProcessIndex] = useState(0); const sortedBackgroundProcesses = useMemo(() => { return [...processes].sort((a, b) => { if (a.status === 'running' && b.status !== 'running') return -1; if (a.status !== 'running' && b.status === 'running') return 1; return b.startedAt.getTime() - a.startedAt.getTime(); }); }, [processes]); useEffect(() => { if ( sortedBackgroundProcesses.length > 0 && selectedProcessIndex >= sortedBackgroundProcesses.length ) { setSelectedProcessIndex(sortedBackgroundProcesses.length - 1); } }, [sortedBackgroundProcesses.length, selectedProcessIndex]); return { selectedProcessIndex, setSelectedProcessIndex, sortedBackgroundProcesses, }; } ================================================ FILE: source/ui/pages/chatScreen/useChatScreenCommands.ts ================================================ import {useEffect, useState} from 'react'; import {registerCustomCommands} from '../../../utils/commands/custom.js'; export function useChatScreenCommands(workingDirectory: string) { const [commandsLoaded, setCommandsLoaded] = useState(false); useEffect(() => { let isMounted = true; Promise.all([ import('../../../utils/commands/clear.js'), import('../../../utils/commands/profiles.js'), import('../../../utils/commands/simple.js'), import('../../../utils/commands/resume.js'), import('../../../utils/commands/mcp.js'), import('../../../utils/commands/yolo.js'), import('../../../utils/commands/plan.js'), import('../../../utils/commands/init.js'), import('../../../utils/commands/ide.js'), import('../../../utils/commands/compact.js'), import('../../../utils/commands/home.js'), import('../../../utils/commands/review.js'), import('../../../utils/commands/gitline.js'), import('../../../utils/commands/role.js'), import('../../../utils/commands/roleSubagent.js'), import('../../../utils/commands/usage.js'), import('../../../utils/commands/export.js'), import('../../../utils/commands/agent.js'), import('../../../utils/commands/todoPicker.js'), import('../../../utils/commands/todolist.js'), import('../../../utils/commands/help.js'), import('../../../utils/commands/custom.js'), import('../../../utils/commands/skills.js'), import('../../../utils/commands/quit.js'), import('../../../utils/commands/reindex.js'), import('../../../utils/commands/codebase.js'), import('../../../utils/commands/addDir.js'), import('../../../utils/commands/permissions.js'), import('../../../utils/commands/branch.js'), import('../../../utils/commands/backend.js'), import('../../../utils/commands/loop.js'), import('../../../utils/commands/models.js'), import('../../../utils/commands/subagentDepth.js'), import('../../../utils/commands/worktree.js'), import('../../../utils/commands/newPrompt.js'), import('../../../utils/commands/autoformat.js'), import('../../../utils/commands/toolsearch.js'), import('../../../utils/commands/hybridCompress.js'), import('../../../utils/commands/team.js'), import('../../../utils/commands/btw.js'), import('../../../utils/commands/deepresearch.js'), import('../../../utils/commands/pixel.js'), ]) .then(async () => { await registerCustomCommands(workingDirectory); if (isMounted) { setCommandsLoaded(true); } }) .catch(error => { console.error('Failed to load commands:', error); if (isMounted) { setCommandsLoaded(true); } }); return () => { isMounted = false; }; }, [workingDirectory]); return commandsLoaded; } ================================================ FILE: source/ui/pages/chatScreen/useChatScreenInputHandler.ts ================================================ import type {Dispatch, SetStateAction} from 'react'; import {useInput} from 'ink'; import { isPickerActive, setPickerActive, } from '../../../utils/ui/pickerState.js'; import type {BackgroundProcess} from '../../../hooks/execution/useBackgroundProcesses.js'; import type {PendingConfirmation} from '../../../hooks/conversation/useToolConfirmation.js'; import type {HookErrorDetails} from '../../../utils/execution/hookResultInterpreter.js'; import type { BashSensitiveCommandState, PendingUserQuestionState, } from './types.js'; type InputKey = { escape: boolean; ctrl: boolean; upArrow?: boolean; downArrow?: boolean; return?: boolean; }; type BackgroundProcessesState = { showPanel: boolean; killProcess: (id: string) => void; hidePanel: () => void; }; type Options = { backgroundProcesses: BackgroundProcessesState; sortedBackgroundProcesses: BackgroundProcess[]; selectedProcessIndex: number; setSelectedProcessIndex: Dispatch>; terminalExecutionState: any; pendingToolConfirmation: PendingConfirmation | null; pendingUserQuestion: PendingUserQuestionState; bashSensitiveCommand: BashSensitiveCommandState; setBashSensitiveCommand: Dispatch>; hookError: HookErrorDetails | null; setHookError: Dispatch>; snapshotState: any; panelState: {handleEscapeKey: () => boolean}; handleEscKey: (key: InputKey, input: string) => boolean; btwPrompt: string | null; }; export function useChatScreenInputHandler({ backgroundProcesses, sortedBackgroundProcesses, selectedProcessIndex, setSelectedProcessIndex, terminalExecutionState, pendingToolConfirmation, pendingUserQuestion, bashSensitiveCommand, setBashSensitiveCommand, hookError, setHookError, snapshotState, panelState, handleEscKey, btwPrompt, }: Options) { useInput((input, key) => { // BtwPanel is active — it owns all keyboard input, skip everything here if (btwPrompt) return; if (backgroundProcesses.showPanel) { if (key.escape) { backgroundProcesses.hidePanel(); return; } if (sortedBackgroundProcesses.length > 0) { if (key.upArrow) { setSelectedProcessIndex(prev => prev > 0 ? prev - 1 : sortedBackgroundProcesses.length - 1, ); return; } if (key.downArrow) { setSelectedProcessIndex(prev => prev < sortedBackgroundProcesses.length - 1 ? prev + 1 : 0, ); return; } if (key.return) { const selectedProcess = sortedBackgroundProcesses[selectedProcessIndex]; if (selectedProcess && selectedProcess.status === 'running') { backgroundProcesses.killProcess(selectedProcess.id); } return; } } } if ( key.ctrl && input === 'b' && terminalExecutionState.state.isExecuting && !terminalExecutionState.state.isBackgrounded ) { Promise.all([ import('../../../mcp/bash.js'), import('../../../hooks/execution/useBackgroundProcesses.js'), ]).then(([{markCommandAsBackgrounded}, {showBackgroundPanel}]) => { markCommandAsBackgrounded(); showBackgroundPanel(); }); terminalExecutionState.moveToBackground(); return; } if (pendingToolConfirmation || pendingUserQuestion) { return; } if (bashSensitiveCommand) { if (input.toLowerCase() === 'y') { bashSensitiveCommand.resolve(true); setBashSensitiveCommand(null); } else if (input.toLowerCase() === 'n' || key.escape) { bashSensitiveCommand.resolve(false); setBashSensitiveCommand(null); } return; } if (hookError && key.escape) { setHookError(null); return; } if (snapshotState.pendingRollback) { if (key.escape) { snapshotState.setPendingRollback(null); } return; } if (key.escape && panelState.handleEscapeKey()) { return; } if (key.escape && isPickerActive()) { setPickerActive(false); return; } if (handleEscKey(key, input)) { return; } }); } ================================================ FILE: source/ui/pages/chatScreen/useChatScreenLocalState.ts ================================================ import {useCallback, useEffect, useRef, useState} from 'react'; import type {Message} from '../../components/chat/MessageList.js'; import type {HookErrorDetails} from '../../../utils/execution/hookResultInterpreter.js'; import type {CompressionStatus} from '../../components/compression/CompressionStatus.js'; import type { BashSensitiveCommandState, CustomCommandExecutionState, DraftContent, PendingMessageInput, PendingUserQuestionResult, PendingUserQuestionState, RestoreInputContent, } from './types.js'; export function useChatScreenLocalState() { const [messages, setMessages] = useState([]); const [isSaving] = useState(false); const [pendingMessages, setPendingMessages] = useState( [], ); const pendingMessagesRef = useRef([]); const userInterruptedRef = useRef(false); const [remountKey, setRemountKey] = useState(0); const [currentContextPercentage, setCurrentContextPercentage] = useState(0); const currentContextPercentageRef = useRef(0); const [isExecutingTerminalCommand, setIsExecutingTerminalCommand] = useState(false); const [customCommandExecution, setCustomCommandExecution] = useState(null); const [isCompressing, setIsCompressing] = useState(false); const [compressionError, setCompressionError] = useState(null); const [showPermissionsPanel, setShowPermissionsPanel] = useState(false); const [showSubAgentDepthPanel, setShowSubAgentDepthPanel] = useState(false); const [restoreInputContent, setRestoreInputContent] = useState(null); const [inputDraftContent, setInputDraftContent] = useState(null); const [bashSensitiveCommand, setBashSensitiveCommand] = useState(null); const [suppressLoadingIndicator, setSuppressLoadingIndicator] = useState(false); const hadBashSensitiveCommandRef = useRef(false); const [hookError, setHookError] = useState(null); const [pendingUserQuestion, setPendingUserQuestion] = useState(null); const [compressionStatus, setCompressionStatus] = useState(null); const [isResumingSession, setIsResumingSession] = useState(false); const [btwPrompt, setBtwPrompt] = useState(null); useEffect(() => { currentContextPercentageRef.current = currentContextPercentage; }, [currentContextPercentage]); useEffect(() => { pendingMessagesRef.current = pendingMessages; }, [pendingMessages]); useEffect(() => { const hasPanel = !!bashSensitiveCommand; const hadPanel = hadBashSensitiveCommandRef.current; hadBashSensitiveCommandRef.current = hasPanel; if (hasPanel) { setSuppressLoadingIndicator(true); return undefined; } if (hadPanel && !hasPanel) { setSuppressLoadingIndicator(true); const timer = setTimeout(() => { setSuppressLoadingIndicator(false); }, 120); return () => clearTimeout(timer); } return undefined; }, [bashSensitiveCommand]); // restoreInputContent must be cleared only after ChatInput actually consumes it. // During rollback confirmation the footer is hidden, so clearing by timeout here // can drop the restored user message before the input is remounted. const requestUserQuestion = useCallback( async ( question: string, options: string[], toolCall: any, ): Promise => { return new Promise(resolve => { setPendingUserQuestion({ question, options, toolCall, resolve, }); }); }, [], ); return { messages, setMessages, isSaving, pendingMessages, setPendingMessages, pendingMessagesRef, userInterruptedRef, remountKey, setRemountKey, currentContextPercentage, setCurrentContextPercentage, currentContextPercentageRef, isExecutingTerminalCommand, setIsExecutingTerminalCommand, customCommandExecution, setCustomCommandExecution, isCompressing, setIsCompressing, compressionError, setCompressionError, showPermissionsPanel, setShowPermissionsPanel, showSubAgentDepthPanel, setShowSubAgentDepthPanel, restoreInputContent, setRestoreInputContent, inputDraftContent, setInputDraftContent, bashSensitiveCommand, setBashSensitiveCommand, suppressLoadingIndicator, setSuppressLoadingIndicator, hookError, setHookError, pendingUserQuestion, setPendingUserQuestion, requestUserQuestion, compressionStatus, setCompressionStatus, isResumingSession, setIsResumingSession, btwPrompt, setBtwPrompt, }; } ================================================ FILE: source/ui/pages/chatScreen/useChatScreenModes.ts ================================================ import {useEffect, useState} from 'react'; import {configEvents} from '../../../utils/config/configEvents.js'; import {getSnowConfig} from '../../../utils/config/apiConfig.js'; import { getToolSearchEnabled, setToolSearchEnabled as persistToolSearchEnabled, getYoloMode, setYoloMode as persistYoloMode, getPlanMode, setPlanMode as persistPlanMode, getVulnerabilityHuntingMode, setVulnerabilityHuntingMode as persistVulnerabilityHuntingMode, getHybridCompressEnabled, setHybridCompressEnabled as persistHybridCompressEnabled, getTeamMode, setTeamMode as persistTeamMode, } from '../../../utils/config/projectSettings.js'; import {getSimpleMode} from '../../../utils/config/themeConfig.js'; type Options = { enableYolo?: boolean; enablePlan?: boolean; }; export function useChatScreenModes({enableYolo, enablePlan}: Options) { const [yoloMode, setYoloMode] = useState(() => { if (enableYolo !== undefined) { return enableYolo; } return getYoloMode(); }); const [planMode, setPlanMode] = useState(() => { if (enablePlan !== undefined) { return enablePlan; } return getPlanMode(); }); const [vulnerabilityHuntingMode, setVulnerabilityHuntingMode] = useState(() => getVulnerabilityHuntingMode(), ); const [toolSearchDisabled, setToolSearchDisabled] = useState( () => !getToolSearchEnabled(), ); const [hybridCompressEnabled, setHybridCompressEnabled] = useState(() => getHybridCompressEnabled(), ); const [teamMode, setTeamMode] = useState(() => getTeamMode()); const [simpleMode, setSimpleMode] = useState(() => getSimpleMode()); const [showThinking, setShowThinking] = useState(() => { const config = getSnowConfig(); return config.showThinking !== false; }); useEffect(() => { persistYoloMode(yoloMode); }, [yoloMode]); useEffect(() => { persistPlanMode(planMode); }, [planMode]); useEffect(() => { persistVulnerabilityHuntingMode(vulnerabilityHuntingMode); }, [vulnerabilityHuntingMode]); useEffect(() => { persistToolSearchEnabled(!toolSearchDisabled); }, [toolSearchDisabled]); useEffect(() => { persistHybridCompressEnabled(hybridCompressEnabled); }, [hybridCompressEnabled]); useEffect(() => { persistTeamMode(teamMode); }, [teamMode]); useEffect(() => { const interval = setInterval(() => { const currentSimpleMode = getSimpleMode(); if (currentSimpleMode !== simpleMode) { setSimpleMode(currentSimpleMode); } }, 1000); return () => clearInterval(interval); }, [simpleMode]); useEffect(() => { const handleConfigChange = (event: {type: string; value: any}) => { if (event.type === 'showThinking') { setShowThinking(event.value); } else if (event.type === 'simpleMode') { // /simple 命令切换后通过事件即时同步 React state， // 避免 1s 轮询造成 ChatHeader 第一次重挂载时仍用旧值。 setSimpleMode(Boolean(event.value)); } }; configEvents.onConfigChange(handleConfigChange); return () => { configEvents.removeConfigChangeListener(handleConfigChange); }; }, []); return { yoloMode, setYoloMode, planMode, setPlanMode, vulnerabilityHuntingMode, setVulnerabilityHuntingMode, toolSearchDisabled, setToolSearchDisabled, hybridCompressEnabled, setHybridCompressEnabled, teamMode, setTeamMode, simpleMode, showThinking, }; } ================================================ FILE: source/ui/pages/chatScreen/useChatScreenSessionLifecycle.ts ================================================ import {useEffect, useRef} from 'react'; import type {Dispatch, SetStateAction} from 'react'; import {useStdout} from 'ink'; import ansiEscapes from 'ansi-escapes'; import type {Message} from '../../components/chat/MessageList.js'; import type {UsageInfo} from '../../../api/types.js'; import { sessionManager, type ChatMessage as SessionChatMessage, } from '../../../utils/session/sessionManager.js'; import {convertSessionMessagesToUI} from '../../../utils/session/sessionConverter.js'; type Options = { autoResume?: boolean; resumeSessionId?: string; terminalWidth: number; remountKey: number; setRemountKey: Dispatch>; setMessages: Dispatch>; initializeFromSession: (messages: SessionChatMessage[]) => void; setIsResumingSession?: (value: boolean) => void; setContextUsage?: Dispatch>; }; export function useChatScreenSessionLifecycle({ autoResume, resumeSessionId, terminalWidth, remountKey, setRemountKey, setMessages, initializeFromSession, setIsResumingSession, setContextUsage, }: Options) { const {stdout} = useStdout(); const isInitialMount = useRef(true); useEffect(() => { if (!autoResume) { sessionManager.clearCurrentSession(); return; } const resumeSession = async () => { setIsResumingSession?.(true); try { let targetSessionId = resumeSessionId; if (!targetSessionId) { const sessions = await sessionManager.listSessions(); if (sessions.length > 0) { targetSessionId = sessions[0]?.id; } } if (targetSessionId) { const session = await sessionManager.loadSession(targetSessionId); if (session) { const uiMessages = convertSessionMessagesToUI(session.messages); setMessages(uiMessages); initializeFromSession(session.messages); setContextUsage?.(session.contextUsage ?? null); } } } catch (error) { console.error('Failed to auto-resume session:', error); } finally { setIsResumingSession?.(false); } }; resumeSession(); }, [autoResume, resumeSessionId, initializeFromSession, setMessages]); useEffect(() => { if (isInitialMount.current) { isInitialMount.current = false; return; } const handler = setTimeout(() => { stdout.write(ansiEscapes.clearTerminal); setRemountKey(prev => prev + 1); }, 200); return () => { clearTimeout(handler); }; // stdout 对象可能在每次渲染时变化，移除以避免循环 }, [terminalWidth, setRemountKey]); useEffect(() => { if (remountKey === 0) { return; } const reloadMessages = async () => { const currentSession = sessionManager.getCurrentSession(); if (currentSession && currentSession.messages.length > 0) { const uiMessages = convertSessionMessagesToUI(currentSession.messages); setMessages(uiMessages); } }; reloadMessages(); }, [remountKey, setMessages]); } ================================================ FILE: source/ui/pages/chatScreen/useCodebaseIndexing.ts ================================================ import {useEffect, useRef, useState} from 'react'; import {CodebaseIndexAgent} from '../../../agents/codebaseIndexAgent.js'; import {validateGitignore} from '../../../utils/codebase/gitignoreValidator.js'; import {loadCodebaseConfig} from '../../../utils/config/codebaseConfig.js'; import {logger} from '../../../utils/core/logger.js'; import type { CodebaseProgressState, FileUpdateNotificationState, } from './types.js'; type ProgressData = NonNullable; function toProgressState(progressData: ProgressData): ProgressData { return { totalFiles: progressData.totalFiles, processedFiles: progressData.processedFiles, totalChunks: progressData.totalChunks, currentFile: progressData.currentFile, status: progressData.status, error: progressData.error, }; } export function useCodebaseIndexing(workingDirectory: string) { const [codebaseIndexing, setCodebaseIndexing] = useState(false); const [codebaseProgress, setCodebaseProgress] = useState(null); const [watcherEnabled, setWatcherEnabled] = useState(false); const [fileUpdateNotification, setFileUpdateNotification] = useState(null); const codebaseAgentRef = useRef(null); useEffect(() => { const notifyFileUpdate = (file: string) => { setFileUpdateNotification({ file, timestamp: Date.now(), }); setTimeout(() => { setFileUpdateNotification(null); }, 3000); }; const syncProgress = (progressData: ProgressData) => { setCodebaseProgress(toProgressState(progressData)); if (progressData.totalFiles === 0 && progressData.currentFile) { notifyFileUpdate(progressData.currentFile); } }; const startCodebaseIndexing = async () => { try { const config = loadCodebaseConfig(); if (!config.enabled) { if (codebaseAgentRef.current) { logger.info('Codebase feature disabled, stopping agent'); await codebaseAgentRef.current.stop(); codebaseAgentRef.current.stopWatching(); codebaseAgentRef.current = null; setCodebaseIndexing(false); setWatcherEnabled(false); } return; } const validation = validateGitignore(workingDirectory); if (!validation.isValid) { setCodebaseProgress({ totalFiles: 0, processedFiles: 0, totalChunks: 0, currentFile: '', status: 'error', error: validation.error, }); setWatcherEnabled(false); logger.error(validation.error || 'Validation error'); return; } const agent = new CodebaseIndexAgent(workingDirectory); codebaseAgentRef.current = agent; (global as any).__codebaseAgent = agent; const progress = await agent.getProgress(); if (progress.status === 'completed' && progress.totalChunks > 0) { agent.startWatching(syncProgress); setWatcherEnabled(true); return; } const wasWatcherEnabled = await agent.isWatcherEnabled(); if (wasWatcherEnabled) { logger.info('Restoring file watcher from previous session'); agent.startWatching(syncProgress); setWatcherEnabled(true); setCodebaseIndexing(false); } setCodebaseIndexing(true); agent.start(progressData => { syncProgress(progressData); if ( progressData.status === 'completed' || progressData.status === 'error' ) { setCodebaseIndexing(false); if (progressData.status === 'completed') { agent.startWatching(syncProgress); setWatcherEnabled(true); } } }); } catch (error) { console.error('Failed to start codebase indexing:', error); setCodebaseIndexing(false); } }; startCodebaseIndexing(); return () => { if (codebaseAgentRef.current) { codebaseAgentRef.current.stop(); codebaseAgentRef.current.stopWatching(); setWatcherEnabled(false); } }; }, [workingDirectory]); useEffect(() => { (global as any).__stopCodebaseIndexing = async () => { if (codebaseAgentRef.current) { await codebaseAgentRef.current.stop(); codebaseAgentRef.current.stopWatching(); await codebaseAgentRef.current.waitForWatcherClose(); setCodebaseIndexing(false); setWatcherEnabled(false); setCodebaseProgress(null); } }; return () => { delete (global as any).__stopCodebaseIndexing; }; }, []); return { codebaseIndexing, setCodebaseIndexing, codebaseProgress, setCodebaseProgress, watcherEnabled, setWatcherEnabled, fileUpdateNotification, setFileUpdateNotification, codebaseAgentRef, }; } ================================================ FILE: source/ui/pages/configScreen/ConfigFieldRenderer.tsx ================================================ import React from 'react'; import {Box, Text} from 'ink'; import TextInput from 'ink-text-input'; import {Select} from '@inkjs/ui'; import ScrollableSelectInput from '../../components/common/ScrollableSelectInput.js'; import {stripFocusArtifacts, type ConfigField} from './types.js'; import type {ConfigStateReturn} from './useConfigState.js'; type Props = { field: ConfigField; state: ConfigStateReturn; }; export default function ConfigFieldRenderer({field, state}: Props) { const { t, theme, currentField, isEditing, // Profile profiles, activeProfile, // API settings baseUrl, setBaseUrl, apiKey, setApiKey, requestMethod, requestMethodOptions, systemPromptId, activeSystemPromptIds, customHeadersSchemeId, activeCustomHeadersSchemeId, anthropicBeta, anthropicCacheTTL, setAnthropicCacheTTL, anthropicSpeed, setAnthropicSpeed, enableAutoCompress, autoCompressThreshold, showThinking, streamingDisplay, thinkingEnabled, thinkingMode, thinkingBudgetTokens, thinkingEffort, geminiThinkingEnabled, geminiThinkingLevel, setGeminiThinkingLevel, responsesReasoningEnabled, responsesReasoningEffort, setResponsesReasoningEffort, responsesVerbosity, setResponsesVerbosity, responsesFastMode, chatThinkingEnabled, chatReasoningEffort, supportsXHigh, // Model settings advancedModel, basicModel, maxContextTokens, maxTokens, streamIdleTimeoutSec, toolResultTokenLimit, // Helpers getSystemPromptNameById, getCustomHeadersSchemeNameById, } = state; const isActive = field === currentField; const isCurrentlyEditing = isEditing && isActive; const activeIndicator = isActive ? '❯ ' : ' '; const activeColor = isActive ? theme.colors.menuSelected : theme.colors.menuNormal; switch (field) { case 'profile': return ( {activeIndicator} {t.configScreen.profile} {!isCurrentlyEditing && ( {profiles.find(p => p.name === activeProfile)?.displayName || activeProfile} )} ); case 'baseUrl': return ( {activeIndicator} {t.configScreen.baseUrl} {isCurrentlyEditing && ( setBaseUrl(stripFocusArtifacts(value))} placeholder="https://api.openai.com/v1" /> )} {!isCurrentlyEditing && ( {baseUrl || t.configScreen.notSet} )} ); case 'apiKey': return ( {activeIndicator} {t.configScreen.apiKey} {isCurrentlyEditing && ( setApiKey(stripFocusArtifacts(value))} placeholder="sk-..." mask="*" /> )} {!isCurrentlyEditing && ( {apiKey ? '*'.repeat(Math.min(apiKey.length, 20)) : t.configScreen.notSet} )} ); case 'requestMethod': return ( {activeIndicator} {t.configScreen.requestMethod} {!isCurrentlyEditing && ( {requestMethodOptions.find(opt => opt.value === requestMethod) ?.label || t.configScreen.notSet} )} ); case 'systemPromptId': { let display = t.configScreen.followGlobalNone; if (systemPromptId === '') { display = t.configScreen.notUse; } else if (Array.isArray(systemPromptId) && systemPromptId.length > 0) { display = systemPromptId .map(id => getSystemPromptNameById(id)) .join(', '); } else if (systemPromptId && typeof systemPromptId === 'string') { display = getSystemPromptNameById(systemPromptId); } else if (activeSystemPromptIds.length > 0) { const activeNames = activeSystemPromptIds .map(id => getSystemPromptNameById(id)) .join(', '); display = t.configScreen.followGlobal.replace('{name}', activeNames); } return ( {activeIndicator} {t.configScreen.systemPrompt} {!isCurrentlyEditing && ( {display || t.configScreen.notSet} )} ); } case 'customHeadersSchemeId': { let display = t.configScreen.followGlobalNone; if (customHeadersSchemeId === '') { display = t.configScreen.notUse; } else if (customHeadersSchemeId) { display = getCustomHeadersSchemeNameById(customHeadersSchemeId); } else if (activeCustomHeadersSchemeId) { display = t.configScreen.followGlobal.replace( '{name}', getCustomHeadersSchemeNameById(activeCustomHeadersSchemeId), ); } return ( {activeIndicator} {t.configScreen.customHeadersField} {!isCurrentlyEditing && ( {display || t.configScreen.notSet} )} ); } case 'anthropicBeta': return ( {activeIndicator} {t.configScreen.anthropicBeta} {anthropicBeta ? t.configScreen.enabled : t.configScreen.disabled}{' '} {t.configScreen.toggleHint} ); case 'anthropicCacheTTL': return ( {activeIndicator} {t.configScreen.anthropicCacheTTL} {isEditing && isActive ? ( { setAnthropicCacheTTL(item.value as '5m' | '1h'); state.setIsEditing(false); }} /> ) : ( {anthropicCacheTTL === '5m' ? t.configScreen.anthropicCacheTTL5m : t.configScreen.anthropicCacheTTL1h}{' '} {t.configScreen.toggleHint} )} ); case 'anthropicSpeed': return ( {activeIndicator} {t.configScreen.anthropicSpeed} {isEditing && isActive ? ( { setAnthropicSpeed( item.value === '__NONE__' ? undefined : (item.value as 'fast' | 'standard'), ); state.setIsEditing(false); }} /> ) : ( {anthropicSpeed === 'fast' ? t.configScreen.anthropicSpeedFast : anthropicSpeed === 'standard' ? t.configScreen.anthropicSpeedStandard : t.configScreen.anthropicSpeedNotUsed} )} ); case 'enableAutoCompress': return ( {activeIndicator} {t.configScreen.enableAutoCompress} {enableAutoCompress ? t.configScreen.enabled : t.configScreen.disabled}{' '} {t.configScreen.toggleHint} ); case 'autoCompressThreshold': { const actualThreshold = Math.floor( (maxContextTokens * autoCompressThreshold) / 100, ); return ( {activeIndicator} {t.configScreen.autoCompressThreshold} {isCurrentlyEditing && ( {t.configScreen.enterValue} {autoCompressThreshold}% {t.configScreen.autoCompressThresholdHint ?.replace('{percentage}', autoCompressThreshold.toString()) .replace('{maxContext}', maxContextTokens.toString()) .replace( '{actualThreshold}', actualThreshold.toLocaleString(), )} )} {!isCurrentlyEditing && ( {autoCompressThreshold}% → {actualThreshold.toLocaleString()}{' '} tokens {isActive && ( {t.configScreen.autoCompressThresholdDesc} )} )} ); } return ( {activeIndicator} {t.configScreen.autoCompressThreshold} {isCurrentlyEditing && ( {t.configScreen.enterValue} {autoCompressThreshold} )} {!isCurrentlyEditing && ( {autoCompressThreshold} )} ); case 'showThinking': return ( {activeIndicator} {t.configScreen.showThinking} {showThinking ? t.configScreen.enabled : t.configScreen.disabled}{' '} {t.configScreen.toggleHint} ); case 'streamingDisplay': return ( {activeIndicator} {t.configScreen.streamingDisplay} {streamingDisplay ? t.configScreen.enabled : t.configScreen.disabled}{' '} {t.configScreen.toggleHint} ); case 'thinkingEnabled': return ( {activeIndicator} {t.configScreen.thinkingEnabled} {thinkingEnabled ? t.configScreen.enabled : t.configScreen.disabled}{' '} {t.configScreen.toggleHint} ); case 'thinkingMode': return ( {activeIndicator} {t.configScreen.thinkingMode} {thinkingMode === 'tokens' ? t.configScreen.thinkingModeTokens : t.configScreen.thinkingModeAdaptive} ); case 'thinkingBudgetTokens': if (thinkingMode !== 'tokens') return null; return ( {activeIndicator} {t.configScreen.thinkingBudgetTokens} {isCurrentlyEditing && ( {t.configScreen.enterValue} {thinkingBudgetTokens} )} {!isCurrentlyEditing && ( {thinkingBudgetTokens} )} ); case 'thinkingEffort': if (thinkingMode !== 'adaptive') return null; return ( {activeIndicator} {t.configScreen.thinkingEffort} {thinkingEffort} ); case 'geminiThinkingEnabled': return ( {activeIndicator} {t.configScreen.geminiThinkingEnabled} {geminiThinkingEnabled ? t.configScreen.enabled : t.configScreen.disabled}{' '} {t.configScreen.toggleHint} ); case 'geminiThinkingLevel': return ( {activeIndicator} {t.configScreen.geminiThinkingLevel} {isCurrentlyEditing && ( { setResponsesReasoningEffort( value as 'none' | 'low' | 'medium' | 'high' | 'xhigh', ); state.setIsEditing(false); }} /> )} ); case 'responsesVerbosity': return ( {activeIndicator} {t.configScreen.responsesVerbosity} {!isCurrentlyEditing && ( {responsesVerbosity.toUpperCase()} )} {isCurrentlyEditing && (