feat(tutorial): switch to tutorial-v2.md with new-tab preview (#785)

* feat(tutorial): switch to tutorial-v2.md with new-tab preview

- Point tutorial-service and electron-builder to tutorial-v2.md
- Add 'tutorial' TabType with fixed TUTORIAL_TAB_ID constant
- TabContent renders TutorialViewer in a ScrollArea for tutorial tabs
- TutorialBanner opens tutorial New Tab instead of settings panel
- OnboardingView opens tutorial New Tab on completion instead of Sheet popup
- SettingsPanel "教程" nav item opens tutorial New Tab and closes settings
- TabBar handleActivate handles tutorial tab without changing app mode

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(tutorial): use __dirname for dev path, add tutorial-v2.md to git

- Fix dev-mode path: __dirname (dist/) is stable across worktrees,
  app.getAppPath() ../../ breaks when worktree is outside the monorepo
- Add tutorial/tutorial-v2.md to git so worktrees can access it

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(tutorial): use __dirname for dev-mode tutorial path

app.getAppPath() ../../ breaks in worktrees outside the monorepo root.
__dirname (dist/) → ../../../tutorial/ is stable regardless of worktree location.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(tutorial): use DiffTabContent for tutorial tab (TOC support)

- Export getTutorialFilePath from tutorial-service
- Add GET_TUTORIAL_FILE_PATH IPC channel
- TabContent tutorial branch uses DiffTabContent with previewOnly+readOnly

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(tutorial): use resources/tutorial.md for dev-mode path

Copies tutorial-v2.md into resources/tutorial.md so build:resources
puts it at dist/resources/tutorial.md — same path as __dirname/resources/
in dev mode, matching prod behavior.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(tutorial): use getTutorialContent + MarkdownRichEditor instead of DiffTabContent

DiffTabContent's path auth rejects the tutorial file.
Switch to getTutorialContent IPC (no auth) + MarkdownRichEditor + MarkdownToc directly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(tutorial): move TOC to left, use markdownTocOpenAtom

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(tutorial): remove unused getTutorialFilePath IPC chain and dead settings tab

清理迭代遗留：删除全程未被渲染层消费的 getTutorialFilePath IPC 链路
（chat 常量 / ipc handler / preload 绑定，函数降级为模块内私有），
并移除 SettingsPanel 中因 handleTabChange 拦截而不可达的 tutorial 分支
及孤儿组件 TutorialViewer。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: ErlichLiu

apps/electron/electron-builder.yml

@@ -55,7 +55,7 @@ extraResources:
     filter:
       - "**/*"
   # 教程文件（教程查看器 + 欢迎对话使用）
-  - from: ../../tutorial/tutorial.md
+  - from: ../../tutorial/tutorial-v2.md
     to: tutorial.md
   # Proma 品牌 Logo 素材（品牌素材下载功能使用）
   - from: resources/proma-logos

apps/electron/resources/tutorial.md

@@ -22,8 +22,8 @@ function getTutorialFilePath(): string {
   if (app.isPackaged) {
     return join(process.resourcesPath, 'tutorial.md')
   }
-  // 开发模式：app.getAppPath() → apps/electron/
-  return join(app.getAppPath(), '../../tutorial/tutorial.md')
+  // 开发模式：resources/ 经 build:resources 复制到 dist/resources/
+  return join(__dirname, 'resources/tutorial.md')
 }
 
 /**

apps/electron/src/main/lib/tutorial-service.ts

@@ -9,7 +9,7 @@ import { TooltipProvider } from './components/ui/tooltip'
 import { SettingsDialog } from './components/settings/SettingsDialog'
 import { conversationsAtom } from './atoms/chat-atoms'
 import { environmentCheckDialogOpenAtom } from './atoms/environment'
-import { tabsAtom, activeTabIdAtom, openTab } from './atoms/tab-atoms'
+import { tabsAtom, activeTabIdAtom, openTab, TUTORIAL_TAB_ID } from './atoms/tab-atoms'
 import type { AppShellContextType } from './contexts/AppShellContext'
 
 export default function App(): React.ReactElement {
@@ -44,18 +44,24 @@ export default function App(): React.ReactElement {
     initialize()
   }, [])
 
-  // 完成 onboarding 回调：创建欢迎对话
-  const handleOnboardingComplete = async () => {
+  // 完成 onboarding 回调：创建欢迎对话，可选打开教程 Tab
+  const handleOnboardingComplete = async (openTutorial?: boolean) => {
     setShowOnboarding(false)
 
+    if (openTutorial) {
+      const tabs = store.get(tabsAtom)
+      const result = openTab(tabs, { type: 'tutorial', sessionId: TUTORIAL_TAB_ID, title: 'Proma 使用教程' })
+      store.set(tabsAtom, result.tabs)
+      store.set(activeTabIdAtom, result.activeTabId)
+      return
+    }
+
     try {
       const meta = await window.electronAPI.createWelcomeConversation()
       if (meta) {
-        // 添加到对话列表
         const conversations = store.get(conversationsAtom)
         store.set(conversationsAtom, [meta, ...conversations])
 
-        // 打开对话标签页
         const tabs = store.get(tabsAtom)
         const result = openTab(tabs, {
           type: 'chat',

apps/electron/src/renderer/App.tsx

@@ -22,11 +22,15 @@ import type { PreviewFile } from './preview-atoms'
 // ===== 类型定义 =====
 
 /** 标签页类型（Settings 不作为 Tab，保留独立视图） */
-export type TabType = 'chat' | 'agent' | 'scratch' | 'preview'
+export type TabType = 'chat' | 'agent' | 'scratch' | 'preview' | 'tutorial'
 
 /** Scratch Pad 专用的固定 sessionId */
 export const SCRATCH_PAD_ID = '__scratch-pad__'
 
+/** 教程 Tab 固定 ID */
+export const TUTORIAL_TAB_ID = '__tutorial__'
+export const TUTORIAL_TAB_TITLE = 'Proma 使用教程'
+
 /** 会话预览 Tab 的 ID 前缀：运行时临时入口，不参与持久化 */
 const PREVIEW_TAB_PREFIX = '__preview__:'
 
@@ -202,7 +206,7 @@ function isSessionTab(tab: TabItem): boolean {
 }
 
 function getPersistentTabs(tabs: TabItem[]): TabItem[] {
-  return tabs.filter((tab) => tab.id !== SCRATCH_PAD_ID && !isPreviewTab(tab))
+  return tabs.filter((tab) => tab.id !== SCRATCH_PAD_ID && tab.id !== TUTORIAL_TAB_ID && !isPreviewTab(tab))
 }
 
 export function getPersistableTabState(
@@ -239,6 +243,19 @@ export function openTab(
     }
   }
 
+  if (item.type === 'tutorial') {
+    const tutorialTab: TabItem = tabs.find((t) => t.id === TUTORIAL_TAB_ID) ?? {
+      id: TUTORIAL_TAB_ID,
+      type: 'tutorial',
+      sessionId: TUTORIAL_TAB_ID,
+      title: TUTORIAL_TAB_TITLE,
+    }
+    return {
+      tabs: [scratchTab, tutorialTab],
+      activeTabId: TUTORIAL_TAB_ID,
+    }
+  }
+
   if (item.type === 'preview') {
     const ownerAgentTab = tabs.find((t) => t.type === 'agent' && t.sessionId === item.sessionId) ?? {
       id: item.sessionId,

apps/electron/src/renderer/atoms/tab-atoms.ts

@@ -12,36 +12,24 @@ import { useMemo, useState } from 'react'
 import { useAtomValue, useSetAtom } from 'jotai'
 import { GraduationCap, ChevronRight, ChevronLeft, HardDriveDownload, Users } from 'lucide-react'
 import { Button } from '@/components/ui/button'
-import {
-  Sheet,
-  SheetContent,
-  SheetHeader,
-  SheetTitle,
-} from '@/components/ui/sheet'
-import { ScrollArea } from '@/components/ui/scroll-area'
-import { TutorialViewer } from '@/components/tutorial/TutorialViewer'
 import { EnvironmentCheckPanel } from '@/components/environment/EnvironmentCheckPanel'
 import { isShellEnvironmentOkAtom } from '@/atoms/environment'
 import { detectIsWindows } from '@/lib/platform'
 import { migrationImportDialogOpenAtom } from '@/atoms/migration-atoms'
 
 interface OnboardingViewProps {
-  /** 完成回调（进入主界面） */
-  onComplete: () => void
+  onComplete: (openTutorial?: boolean) => void
 }
 
 export function OnboardingView({ onComplete }: OnboardingViewProps) {
-  const [showTutorial, setShowTutorial] = useState(false)
   const [step, setStep] = useState<'welcome' | 'environment'>('welcome')
   const isWindows = useMemo(() => detectIsWindows(), [])
   const shellOk = useAtomValue(isShellEnvironmentOkAtom)
   const setMigrationImportDialogOpen = useSetAtom(migrationImportDialogOpenAtom)
 
-  const handleFinish = async () => {
-    await window.electronAPI.updateSettings({
-      onboardingCompleted: true,
-    })
-    onComplete()
+  const handleFinish = async (openTutorial?: boolean) => {
+    await window.electronAPI.updateSettings({ onboardingCompleted: true })
+    onComplete(openTutorial)
   }
 
   const handleNextFromWelcome = () => {
@@ -70,7 +58,7 @@ export function OnboardingView({ onComplete }: OnboardingViewProps) {
           <div className="w-full max-w-2xl">
             <div className="space-y-3">
               <button
-                onClick={() => setShowTutorial(true)}
+                onClick={() => handleFinish(true)}
                 className="w-full rounded-xl bg-gradient-to-r from-primary/5 via-primary/10 to-primary/5 border border-primary/15 p-4 flex items-center gap-4 hover:from-primary/10 hover:via-primary/15 hover:to-primary/10 transition-colors text-left"
               >
                 <div className="w-10 h-10 rounded-xl bg-primary/10 flex items-center justify-center flex-shrink-0">
@@ -170,7 +158,7 @@ export function OnboardingView({ onComplete }: OnboardingViewProps) {
             </Button>
             <div className="flex gap-3">
               <Button
-                onClick={handleFinish}
+                onClick={() => handleFinish()}
                 variant={shellOk ? 'default' : 'outline'}
               >
                 {shellOk ? '开始使用' : '稍后处理（进入主界面）'}
@@ -179,22 +167,6 @@ export function OnboardingView({ onComplete }: OnboardingViewProps) {
           </div>
         </div>
       )}
-
-      <Sheet open={showTutorial} onOpenChange={setShowTutorial}>
-        <SheetContent side="right" className="w-[560px] sm:max-w-[560px] p-0">
-          <SheetHeader className="px-6 pt-6 pb-4 border-b">
-            <SheetTitle className="flex items-center gap-2">
-              <GraduationCap size={18} className="text-primary" />
-              Proma 使用教程
-            </SheetTitle>
-          </SheetHeader>
-          <ScrollArea className="h-[calc(100vh-80px)]">
-            <div className="px-6 py-4">
-              <TutorialViewer />
-            </div>
-          </ScrollArea>
-        </SheetContent>
-      </Sheet>
     </div>
   )
 }

apps/electron/src/renderer/components/onboarding/OnboardingView.tsx

@@ -6,7 +6,7 @@
  */
 
 import * as React from "react";
-import { useAtom, useAtomValue } from "jotai";
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { cn } from "@/lib/utils";
 import {
   Settings,
@@ -26,10 +26,11 @@ import {
   HardDrive,
 } from "lucide-react";
 import { ScrollArea } from "@/components/ui/scroll-area";
-import { settingsTabAtom, channelFormDirtyAtom, settingsCloseRequestedAtom } from "@/atoms/settings-tab";
+import { settingsTabAtom, channelFormDirtyAtom, settingsCloseRequestedAtom, settingsOpenAtom } from "@/atoms/settings-tab";
 import type { SettingsTab } from "@/atoms/settings-tab";
 import { appModeAtom } from "@/atoms/app-mode";
 import { hasUpdateAtom } from "@/atoms/updater";
+import { tabsAtom, activeTabIdAtom, openTab, TUTORIAL_TAB_ID } from "@/atoms/tab-atoms";
 import { hasEnvironmentIssuesAtom } from "@/atoms/environment";
 import {
   AlertDialog,
@@ -50,7 +51,6 @@ import { AgentSettings } from "./AgentSettings";
 import { PromptSettings } from "./PromptSettings";
 import { ToolSettings } from "./ToolSettings";
 import { BotHubSettings } from "./BotHubSettings";
-import { TutorialViewer } from "../tutorial/TutorialViewer";
 import { ShortcutSettings } from "./ShortcutSettings";
 import { VoiceInputSettings } from "./VoiceInputSettings";
 import { MigrationSettings } from "./MigrationSettings";
@@ -132,8 +132,6 @@ function renderTabContent(tab: SettingsTab): React.ReactElement {
       return <AboutSettings />;
     case "bots":
       return <BotHubSettings />;
-    case "tutorial":
-      return <TutorialViewer />;
     case "shortcuts":
       return <ShortcutSettings />;
     case "voice-input":
@@ -142,6 +140,9 @@ function renderTabContent(tab: SettingsTab): React.ReactElement {
       return <MigrationSettings />;
     case "storage":
       return <StorageSettings />;
+    default:
+      // tutorial 等特殊 tab 由 handleTabChange 拦截打开主区 Tab，不会在此渲染
+      return <GeneralSettings />;
   }
 }
 
@@ -155,9 +156,12 @@ export function SettingsPanel({
   const [activeTab, setActiveTab] = useAtom(settingsTabAtom);
   const channelFormDirty = useAtomValue(channelFormDirtyAtom);
   const [closeRequested, setCloseRequested] = useAtom(settingsCloseRequestedAtom);
+  const setSettingsOpen = useSetAtom(settingsOpenAtom);
   const appMode = useAtomValue(appModeAtom);
   const hasUpdate = useAtomValue(hasUpdateAtom);
   const hasEnvironmentIssues = useAtomValue(hasEnvironmentIssuesAtom);
+  const [mainTabs, setMainTabs] = useAtom(tabsAtom);
+  const setMainActiveTabId = useSetAtom(activeTabIdAtom);
 
   /** 统一的退出拦截对话框状态 */
   type PendingAction = { type: 'tab'; tabId: SettingsTab } | { type: 'close' } | null
@@ -180,8 +184,15 @@ export function SettingsPanel({
     setPendingAction(null)
   }
 
-  /** 切换标签页时检测是否有未保存内容 */
+  /** 切换标签页时检测是否有未保存内容，tutorial 特殊处理：打开 New Tab 并关闭设置 */
   const handleTabChange = (tabId: SettingsTab): void => {
+    if (tabId === 'tutorial') {
+      const result = openTab(mainTabs, { type: 'tutorial', sessionId: TUTORIAL_TAB_ID, title: 'Proma 使用教程' })
+      setMainTabs(result.tabs)
+      setMainActiveTabId(result.activeTabId)
+      setSettingsOpen(false)
+      return
+    }
     if (tabId === activeTab) return
     if (activeTab === 'channels' && channelFormDirty) {
       setPendingAction({ type: 'tab', tabId })

apps/electron/src/renderer/components/settings/SettingsPanel.tsx

@@ -108,8 +108,7 @@ export function TabBar(): React.ReactElement {
           agentWorkspaceId: session.workspaceId,
         }).catch(console.error)
       }
-    } else if (tab.type === 'scratch') {
-      // Agent 模式下切到 Scratch Pad 时保持右侧文件面板不收起
+    } else if (tab.type === 'scratch' || tab.type === 'tutorial') {
       setCurrentConversationId(null)
       if (appMode !== 'agent') {
         setCurrentAgentSessionId(null)

apps/electron/src/renderer/components/tabs/TabBar.tsx

@@ -6,11 +6,14 @@
  */
 
 import * as React from 'react'
-import { useAtomValue } from 'jotai'
+import { useAtom, useAtomValue } from 'jotai'
 import { tabsAtom } from '@/atoms/tab-atoms'
+import { markdownTocOpenAtom } from '@/atoms/markdown-toc'
 import { ChatView } from '@/components/chat'
 import { AgentView } from '@/components/agent'
 import { PreviewTabContent } from '@/components/diff/PreviewTabContent'
+import { MarkdownRichEditor } from '@/components/diff/MarkdownRichEditor'
+import { MarkdownToc } from '@/components/diff/MarkdownToc'
 import { ScratchPadView } from '@/components/scratch-pad/ScratchPadView'
 import { TabErrorBoundary } from './TabErrorBoundary'
 
@@ -41,6 +44,10 @@ export function TabContent({ tabId }: TabContentProps): React.ReactElement {
     return <ScratchPadView />
   }
 
+  if (tab.type === 'tutorial') {
+    return <TutorialTabContent />
+  }
+
   if (tab.type === 'chat') {
     return (
       <TabErrorBoundary key={tab.sessionId} sessionId={tab.sessionId}>
@@ -63,3 +70,30 @@ export function TabContent({ tabId }: TabContentProps): React.ReactElement {
     </TabErrorBoundary>
   )
 }
+
+function TutorialTabContent(): React.ReactElement {
+  const [content, setContent] = React.useState<string | null>(null)
+  const [tocOpen] = useAtom(markdownTocOpenAtom)
+  const scrollRef = React.useRef<HTMLDivElement>(null)
+
+  React.useEffect(() => {
+    window.electronAPI.getTutorialContent().then(setContent).catch(console.error)
+  }, [])
+
+  if (content === null) return <div className="flex h-full items-center justify-center text-xs text-muted-foreground">加载中...</div>
+
+  return (
+    <div className="relative flex h-full min-h-0 overflow-hidden">
+      <MarkdownToc containerRef={scrollRef as React.RefObject<HTMLElement>} contentKey={content.slice(0, 100)} enabled={tocOpen} />
+      <div ref={scrollRef} className="flex-1 min-w-0 overflow-y-auto p-8">
+        <MarkdownRichEditor
+          value={content}
+          editing={false}
+          onChange={() => {}}
+          onSave={() => {}}
+          onCancel={() => {}}
+        />
+      </div>
+    </div>
+  )
+}

apps/electron/src/renderer/components/tabs/TabContent.tsx

@@ -8,41 +8,38 @@
  */
 
 import * as React from 'react'
-import { useSetAtom } from 'jotai'
+import { useAtom, useSetAtom } from 'jotai'
 import { GraduationCap, X } from 'lucide-react'
 import { Button } from '@/components/ui/button'
-import { settingsTabAtom, settingsOpenAtom } from '@/atoms/settings-tab'
+import { tabsAtom, activeTabIdAtom, openTab, TUTORIAL_TAB_ID } from '@/atoms/tab-atoms'
 
 export function TutorialBanner(): React.ReactElement | null {
   const [visible, setVisible] = React.useState(false)
   const [dismissed, setDismissed] = React.useState(true)
-  const setSettingsOpen = useSetAtom(settingsOpenAtom)
-  const setSettingsTab = useSetAtom(settingsTabAtom)
+  const [tabs, setTabs] = useAtom(tabsAtom)
+  const setActiveTabId = useSetAtom(activeTabIdAtom)
 
-  // 初始化：从主进程读取 settings 判断是否需要显示
   React.useEffect(() => {
     window.electronAPI
       .getSettings()
       .then((settings) => {
         if (!settings.tutorialBannerDismissed) {
           setDismissed(false)
-          // 延迟 1.5 秒显示，避免页面加载时的干扰
           setTimeout(() => setVisible(true), 1500)
         }
       })
       .catch(console.error)
   }, [])
 
-  // 关闭横幅并持久化
   const handleDismiss = async () => {
     setVisible(false)
     await window.electronAPI.updateSettings({ tutorialBannerDismissed: true })
   }
 
-  // 立即学习：跳转到设置教程页并关闭横幅
   const handleLearnNow = async () => {
-    setSettingsTab('tutorial')
-    setSettingsOpen(true)
+    const result = openTab(tabs, { type: 'tutorial', sessionId: TUTORIAL_TAB_ID, title: 'Proma 使用教程' })
+    setTabs(result.tabs)
+    setActiveTabId(result.activeTabId)
     await handleDismiss()
   }
 
@@ -102,7 +99,7 @@ export function TutorialBanner(): React.ReactElement | null {
 
         {/* 提示文字 */}
         <p className="text-[11px] text-muted-foreground/60 mt-3 text-center">
-          你可以随时在 设置 &gt; 教程 中查看完整教程
+          你可以随时点击顶栏「教程」标签重新打开
         </p>
       </div>
     </div>