@yushaw/sanqian-chat

Sanqian chat UI components and hooks for third-party Electron apps.

Phase 1 (Core Chat)

• Streaming chat messages
• Thinking section
• Tool call timeline
• HITL prompts
• Simplified input (text + send + stop)

Install

npm install @yushaw/sanqian-chat

Publish

From the repo root:

npm publish --workspace=@yushaw/sanqian-chat

Or from the package directory:

cd packages/chat
npm publish

Usage (Renderer)

import { SanqianChat, createSdkAdapter } from '@yushaw/sanqian-chat/renderer';
import { SanqianSDK } from '@yushaw/sanqian-sdk';

const sdk = new SanqianSDK({
  appName: 'my-app',
  appVersion: '0.1.0',
  tools: [],
});

const adapter = createSdkAdapter({
  getSdk: () => sdk,
  getAgentId: () => 'assistant',
});

export function App() {
  return (
    <div className="h-full">
      <SanqianChat
        adapter={adapter}
        config={{
          theme: 'auto',
          accentColor: '#e85d75',
          locale: 'zh',
        }}
      />
    </div>
  );
}

API Reference

See packages/chat/API.md and packages/chat/API.zh-CN.md.

Notes

• Style modes: Default is 'safe' (no Tailwind preflight, safe for embedding). Use 'full' for standalone windows.
  • Set window.__SANQIAN_CHAT_STYLE_MODE__ = 'full' for full styles including preflight
  • Set window.__SANQIAN_CHAT_DISABLE_STYLES__ = true to disable auto-injection
• CSS files:
  • @yushaw/sanqian-chat/renderer/styles/safe.css - Safe (no preflight, includes utilities)
  • @yushaw/sanqian-chat/renderer/styles/chat.css - Full (includes Tailwind preflight)
  • @yushaw/sanqian-chat/renderer/styles/variables.css - Variables only
• Sanqian should be running when the SDK connects.
• Additional capabilities (history, agents, files, settings) will be added in later phases.

Developing Styles

CSS uses a modular structure with a single source of truth:

src/renderer/styles/
├── coreCss.ts        # ← EDIT THIS (CSS variables + utilities)
├── preflightCss.ts   # Tailwind preflight (don't edit)
├── safeCss.ts        # Auto-generated (imports coreCss)
├── chatCss.ts        # Auto-generated (imports coreCss + preflight)
├── safe.css          # Auto-generated
└── chat.css          # Auto-generated

To modify styles:

1. Edit coreCss.ts
2. Run npm run build:css to regenerate all files
3. Or just run npm run build (includes CSS generation)

Changelog

0.2.7 (2026-01-06)

• Added: External resource reference support
  • useResourcePicker hook - manage resource picker state, search, pagination
  • ResourcePicker component - two-level picker (providers → resources)
  • ResourceChip / ResourceChipList - display attached resources
  • AddResourceButton - + button with dropdown menu
• Added: ChatAdapter extensions: listResourceProviders, getResourceList, onLocaleChanged
• Added: FloatingWindow.notifyLocaleChanged(locale) and ChatPanel.notifyLocaleChanged(locale) - notify renderer when locale changes
• Added: sendMessage now accepts options.attachedResources
• Added: Message rendering displays attached resources in user messages
• Added: New types: AttachedResource, ResourcePickerItem, ContextProviderInfo
• Changed: AppContextProvider.getList now accepts options parameter for search/pagination

2025-01-03

• Added: Focus persistence - input keeps focus when clicking empty areas (unless selecting text)
• Added: Cmd+N (macOS) / Ctrl+N (Windows) keyboard shortcut for new chat
• Added: Hover tooltip with shortcut hint on new chat button

2025-01-02

• Changed: CSS modular structure - single source of truth (coreCss.ts)
• Changed: .prose uses font-size: inherit for external control
• Changed: IntermediateSteps uses relative font sizes (rem instead of px)
• Fixed: position default value conflict with rememberWindowState
• Fixed: IPC now forwards start event (with run_id) to renderer
• Fixed: Center position calculation uses workArea (supports multi-monitor/dock)
• Fixed: console.log only outputs in devMode
• Fixed: Global style pollution - default to 'safe' mode (no Tailwind preflight)
• Fixed: cancelStream now calls sdk.cancelRun() for real cancellation

Tech Debt / Future Optimizations

Low Priority (记录于 2026-01-05)

1. FloatingChat 命名优化

   • FloatingChat 实际是通用组件（embedded + floating），名字有误导
   • 可考虑改名为 ChatContainer 或 ChatView
   • 文件：src/renderer/components/FloatingChat.tsx

2. Header 按钮复用

   • FloatingChat 内联了 <ModeToggleButton> + <AttachButton>
   • 可改用 <PanelHeaderButtons /> 与 CompactChat 保持一致
   • 文件：src/renderer/components/FloatingChat.tsx:134-136

3. useCallback 依赖优化 (微优化)

   • useAttachState.ts:68: toggle 依赖 state，每次 state 变化重建
   • useChatPanel.ts:86: toggleMode 依赖 mode，每次 mode 变化重建
   • 可用 useRef 避免重建，但当前影响可忽略
   • 文件：src/renderer/hooks/useAttachState.ts, src/renderer/hooks/useChatPanel.ts

Changelog

2026-01-11

Ask AI 焦点管理

• ChatPanel.focusInput() 方法：完整的焦点管理，支持 floating 和 embedded 模式
  • macOS: app.focus({ steal: true }) 确保应用获得前台焦点
  • floatingWindow.focus() / webContents.focus() 确保窗口和 BrowserView 获得焦点
  • IPC 消息通知渲染进程聚焦输入框
• ChatAdapter.onFocusInput 接口：渲染进程监听焦点事件
• SanqianChatAPI.onFocusInput preload API

Bug 修复

• 修复 session resources 发送前被删除的问题（移除了发送时的 removeSessionResource 调用）
• 修复 AttachedResourceTags 深色模式样式（使用正确的 CSS 变量）
• 清理 chip 布局的多余 padding/margin

2026-01-10

Session Resources 功能实现

新增应用主动推送临时上下文的能力（Session Resources）：

• ChatAdapter 接口新增 getSessionResources、onSessionResourceEvent、removeSessionResource 方法
• useChat hook 新增 sessionResources 状态和 removeSessionResource 回调
• FloatingChat / CompactChat 组件支持显示 session resources chips
• IPC adapter 实现 session resources 相关 API

详见设计文档：docs/session-resources-design.md