perf(chathistory): 拆分读写锁并合并流式落盘，修复 HF Space 整体卡顿

线上表现为 API 响应变慢、后台面板加载历史对话卡顿。根因是对话历史的落盘
路径把整个服务串行化了：

- Store 只有一把互斥锁，saveLocked 在持锁状态下完成 JSON 序列化 + fsync +
rename；而 Snapshot / Get（后台面板读历史）用的是同一把锁，因此被流式写入
直接阻塞。
- progress() 在每个 SSE 分片上被调用（250ms 节流），每次都重写包含 messages /
history_text / final_prompt 等请求期内不变字段的完整记录。HuggingFace Spaces
的 /data 是 bucket 对象存储卷，单次 fsync 的延迟远高于本地盘，几十秒的响应
就会触发数百次高延迟写入。

改动：

- 拆成 mu（仅内存状态，持锁期间不做 I/O）与 writeMu（仅串行化落盘），后台
面板读取不再阻塞在磁盘上。
- 新增 UpdateParams.Background：流式进度只写 <id>.live.json 增量文件，由单个
自终止的合并协程按 400ms 窗口合并落盘，彻底脱离 SSE 读取循环；终态更新仍
同步回写完整文件并清理增量文件。
- 去掉 chat history 的 fsync，保留「临时文件 + rename」的原子性。
- 后台面板轮询降频（列表 1.5s→3s，详情 750ms→1.5s）。

实测单次进度写入从 84,475 B 降至 246 B（343x）。旧数据无需迁移即可加载。
Start 与终态 Update 仍同步返回写盘错误，保持既有错误语义。

internal/chathistory/store.go

@@ -23,6 +23,14 @@ const (
 	DefaultLimit     = 20
 	MaxLimit         = 50
 	defaultPreviewAt = 160
+
+	// asyncDebounce 是流式进度落盘的合并窗口：窗口内的多次进度更新只会产生
+	// 一次磁盘写入。HuggingFace Spaces 的 bucket 卷等对象存储挂载单次写入
+	// 延迟很高，按 SSE 分片逐次写盘会把整个进程拖垮。
+	asyncDebounce = 400 * time.Millisecond
+	// asyncRetryDelay 是写盘连续失败后的退避时间，避免在磁盘长期不可用时
+	// 以合并窗口的频率反复重试。
+	asyncRetryDelay = 5 * time.Second
 )
 
 var allowedLimits = map[int]struct{}{
@@ -131,6 +139,11 @@ type UpdateParams struct {
 	FinishReason     string
 	Usage            map[string]any
 	Completed        bool
+	// Background 标记一次流式进度更新：只落盘一个只含变化字段的增量文件
+	// （<id>.live.json），不重写包含 messages / history_text / final_prompt
+	// 等请求期内不变的大字段的完整文件。调用方不会拿到写盘错误，
+	// 写入由后台合并协程完成。
+	Background bool
 }
 
 type detailEnvelope struct {
@@ -138,6 +151,27 @@ type detailEnvelope struct {
 	Item    Entry `json:"item"`
 }
 
+// progressRecord 是流式期间的增量落盘记录，只包含随输出变化的字段。
+type progressRecord struct {
+	Version          int            `json:"version"`
+	Revision         int64          `json:"revision"`
+	UpdatedAt        int64          `json:"updated_at"`
+	CompletedAt      int64          `json:"completed_at,omitempty"`
+	Status           string         `json:"status,omitempty"`
+	ReasoningContent string         `json:"reasoning_content,omitempty"`
+	Content          string         `json:"content,omitempty"`
+	Error            string         `json:"error,omitempty"`
+	StatusCode       int            `json:"status_code,omitempty"`
+	ElapsedMs        int64          `json:"elapsed_ms,omitempty"`
+	FinishReason     string         `json:"finish_reason,omitempty"`
+	Usage            map[string]any `json:"usage,omitempty"`
+}
+
+type progressEnvelope struct {
+	Version int            `json:"version"`
+	Item    progressRecord `json:"item"`
+}
+
 type legacyFile struct {
 	Version int     `json:"version"`
 	Limit   int     `json:"limit"`
@@ -148,15 +182,25 @@ type legacyProbe struct {
 	Items []map[string]json.RawMessage `json:"items"`
 }
 
+// Store 保存 chat history。锁被刻意拆成两把：
+//
+//   - mu 只保护内存状态，任何持有它的路径都不做 I/O，因此后台面板读取历史
+//     （Snapshot / Get）永远不会被流式落盘阻塞；
+//   - writeMu 只串行化落盘，让并发请求的写入不会互相覆盖。
 type Store struct {
-	mu        sync.Mutex
-	path      string
-	detailDir string
-	state     File
-	details   map[string]Entry
-	dirty     map[string]struct{}
-	deleted   map[string]struct{}
-	err       error
+	mu         sync.Mutex
+	writeMu    sync.Mutex
+	path       string
+	detailDir  string
+	state      File
+	details    map[string]Entry
+	dirty      map[string]struct{} // 需要重写完整 <id>.json 的条目
+	progress   map[string]struct{} // 只需要写增量 <id>.live.json 的条目
+	deleted    map[string]struct{}
+	indexDirty bool
+	asyncBusy  bool
+	closed     bool
+	err        error
 }
 
 func New(path string) *Store {
@@ -169,13 +213,24 @@ func New(path string) *Store {
 			Revision: 0,
 			Items:    []SummaryEntry{},
 		},
-		details: map[string]Entry{},
-		dirty:   map[string]struct{}{},
-		deleted: map[string]struct{}{},
+		details:  map[string]Entry{},
+		dirty:    map[string]struct{}{},
+		progress: map[string]struct{}{},
+		deleted:  map[string]struct{}{},
 	}
 	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.err = s.loadLocked()
+	loadErr := s.loadLocked()
+	if loadErr != nil {
+		s.err = loadErr
+	}
+	s.mu.Unlock()
+
+	// 首次启动建索引 / 旧格式迁移 / 索引归一化都在锁外回写，失败只告警不致命。
+	if loadErr == nil && s.pending() {
+		if err := s.flush(); err != nil {
+			config.Logger.Warn("[chat_history] initial writeback failed", "path", s.path, "error", err)
+		}
+	}
 	return s
 }
 
@@ -275,11 +330,13 @@ func (s *Store) Start(params StartParams) (Entry, error) {
 		return Entry{}, errors.New("chat history store is nil")
 	}
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	if s.err != nil {
-		return Entry{}, s.err
+		err := s.err
+		s.mu.Unlock()
+		return Entry{}, err
 	}
 	if s.state.Limit == DisabledLimit {
+		s.mu.Unlock()
 		return Entry{}, ErrDisabled
 	}
 	now := time.Now().UnixMilli()
@@ -304,10 +361,13 @@ func (s *Store) Start(params StartParams) (Entry, error) {
 	s.details[entry.ID] = entry
 	s.markDetailDirtyLocked(entry.ID)
 	s.rebuildIndexLocked()
-	if err := s.saveLocked(); err != nil {
-		return cloneEntry(entry), err
+	result := cloneEntry(entry)
+	s.mu.Unlock()
+
+	if err := s.flush(); err != nil {
+		return result, err
 	}
-	return cloneEntry(entry), nil
+	return result, nil
 }
 
 func (s *Store) Update(id string, params UpdateParams) (Entry, error) {
@@ -315,16 +375,19 @@ func (s *Store) Update(id string, params UpdateParams) (Entry, error) {
 		return Entry{}, errors.New("chat history store is nil")
 	}
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	if s.err != nil {
-		return Entry{}, s.err
+		err := s.err
+		s.mu.Unlock()
+		return Entry{}, err
 	}
 	target := strings.TrimSpace(id)
 	if target == "" {
+		s.mu.Unlock()
 		return Entry{}, errors.New("history id is required")
 	}
 	item, ok := s.details[target]
 	if !ok {
+		s.mu.Unlock()
 		return Entry{}, errors.New("chat history entry not found")
 	}
 	now := time.Now().UnixMilli()
@@ -350,12 +413,24 @@ func (s *Store) Update(id string, params UpdateParams) (Entry, error) {
 		item.CompletedAt = now
 	}
 	s.details[target] = item
-	s.markDetailDirtyLocked(target)
+	if params.Background {
+		s.markProgressDirtyLocked(target)
+	} else {
+		s.markDetailDirtyLocked(target)
+	}
 	s.rebuildIndexLocked()
-	if err := s.saveLocked(); err != nil {
+	result := cloneEntry(item)
+	s.mu.Unlock()
+
+	if params.Background {
+		// 流式进度：交给后台合并写入，绝不阻塞 SSE 读取循环。
+		s.flushAsync()
+		return result, nil
+	}
+	if err := s.flush(); err != nil {
 		return Entry{}, err
 	}
-	return cloneEntry(item), nil
+	return result, nil
 }
 
 func (s *Store) Delete(id string) error {
@@ -363,25 +438,28 @@ func (s *Store) Delete(id string) error {
 		return errors.New("chat history store is nil")
 	}
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	if s.err != nil {
-		return s.err
+		err := s.err
+		s.mu.Unlock()
+		return err
 	}
 	target := strings.TrimSpace(id)
 	if target == "" {
+		s.mu.Unlock()
 		return errors.New("history id is required")
 	}
 	if _, ok := s.details[target]; !ok {
+		s.mu.Unlock()
 		return errors.New("chat history entry not found")
 	}
 	s.markDetailDeletedLocked(target)
 	delete(s.details, target)
 	s.nextRevisionLocked()
 	s.rebuildIndexLocked()
-	if err := s.saveLocked(); err != nil {
-		return err
-	}
-	return nil
+	s.indexDirty = true
+	s.mu.Unlock()
+
+	return s.flush()
 }
 
 func (s *Store) Clear() error {
@@ -389,9 +467,10 @@ func (s *Store) Clear() error {
 		return errors.New("chat history store is nil")
 	}
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	if s.err != nil {
-		return s.err
+		err := s.err
+		s.mu.Unlock()
+		return err
 	}
 	for id := range s.details {
 		s.markDetailDeletedLocked(id)
@@ -399,10 +478,10 @@ func (s *Store) Clear() error {
 	s.details = map[string]Entry{}
 	s.nextRevisionLocked()
 	s.rebuildIndexLocked()
-	if err := s.saveLocked(); err != nil {
-		return err
-	}
-	return nil
+	s.indexDirty = true
+	s.mu.Unlock()
+
+	return s.flush()
 }
 
 func (s *Store) SetLimit(limit int) (File, error) {
@@ -410,22 +489,30 @@ func (s *Store) SetLimit(limit int) (File, error) {
 		return File{}, errors.New("chat history store is nil")
 	}
 	s.mu.Lock()
-	defer s.mu.Unlock()
 	if s.err != nil {
-		return File{}, s.err
+		err := s.err
+		s.mu.Unlock()
+		return File{}, err
 	}
 	if !isAllowedLimit(limit) {
+		s.mu.Unlock()
 		return File{}, fmt.Errorf("unsupported chat history limit: %d", limit)
 	}
 	s.state.Limit = limit
 	s.nextRevisionLocked()
 	s.rebuildIndexLocked()
-	if err := s.saveLocked(); err != nil {
+	s.indexDirty = true
+	result := cloneFile(s.state)
+	s.mu.Unlock()
+
+	if err := s.flush(); err != nil {
 		return File{}, err
 	}
-	return cloneFile(s.state), nil
+	return result, nil
 }
 
+// loadLocked 只做内存装载，不做任何写入；需要回写的内容通过 indexDirty /
+// dirty 标记，由 New 在释放锁之后统一落盘。
 func (s *Store) loadLocked() error {
 	if strings.TrimSpace(s.path) == "" {
 		return errors.New("chat history path is required")
@@ -440,9 +527,7 @@ func (s *Store) loadLocked() error {
 	raw, err := os.ReadFile(s.path)
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) {
-			if saveErr := s.saveLocked(); saveErr != nil {
-				config.Logger.Warn("[chat_history] bootstrap write failed", "path", s.path, "error", saveErr)
-			}
+			s.indexDirty = true
 			return nil
 		}
 		return fmt.Errorf("read chat history index: %w", err)
@@ -454,9 +539,6 @@ func (s *Store) loadLocked() error {
 	}
 	if legacyOK {
 		s.loadLegacyLocked(legacy)
-		if err := s.saveLocked(); err != nil {
-			config.Logger.Warn("[chat_history] legacy migration writeback failed", "path", s.path, "error", err)
-		}
 		return nil
 	}
 
@@ -473,16 +555,14 @@ func (s *Store) loadLocked() error {
 	s.state = cloneFile(state)
 	s.details = map[string]Entry{}
 	for _, item := range state.Items {
-		detail, err := readDetailFile(filepath.Join(s.detailDir, item.ID+".json"))
+		detail, err := s.readEntryLocked(item.ID)
 		if err != nil {
 			return err
 		}
 		s.details[item.ID] = detail
 	}
 	s.rebuildIndexLocked()
-	if saveErr := s.saveLocked(); saveErr != nil {
-		config.Logger.Warn("[chat_history] index rewrite failed", "path", s.path, "error", saveErr)
-	}
+	s.indexDirty = true
 	return nil
 }
 
@@ -494,6 +574,7 @@ func (s *Store) loadLegacyLocked(legacy legacyFile) {
 	}
 	s.details = map[string]Entry{}
 	s.dirty = map[string]struct{}{}
+	s.progress = map[string]struct{}{}
 	s.deleted = map[string]struct{}{}
 	maxRevision := int64(0)
 	for _, item := range legacy.Items {
@@ -515,54 +596,219 @@ func (s *Store) loadLegacyLocked(legacy legacyFile) {
 		s.markDetailDirtyLocked(item.ID)
 	}
 	s.state.Revision = maxRevision
+	s.indexDirty = true
 	s.rebuildIndexLocked()
 }
 
-func (s *Store) saveLocked() error {
-	s.state.Version = FileVersion
-	if !isAllowedLimit(s.state.Limit) {
-		s.state.Limit = DefaultLimit
+func (s *Store) pending() bool {
+	if s == nil {
+		return false
 	}
-	s.rebuildIndexLocked()
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.hasPendingLocked()
+}
 
-	if err := os.MkdirAll(s.detailDir, 0o755); err != nil {
-		return fmt.Errorf("create chat history detail dir: %w", err)
+func (s *Store) hasPendingLocked() bool {
+	return len(s.dirty) > 0 || len(s.progress) > 0 || len(s.deleted) > 0 || s.indexDirty
+}
+
+// Close 停止后台合并写入。它不改动已落盘的数据，只用于进程退出与测试收尾，
+// 避免磁盘长期不可用时合并协程持续重试。
+func (s *Store) Close() {
+	if s == nil {
+		return
 	}
-	for _, id := range sortedDetailIDs(s.deleted) {
-		path := filepath.Join(s.detailDir, id+".json")
-		if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
-			return fmt.Errorf("remove stale chat history detail: %w", err)
+	s.mu.Lock()
+	s.closed = true
+	s.mu.Unlock()
+}
+
+// flushAsync 安排一次合并后的后台落盘。同一时刻最多只有一个合并协程，
+// 且它自终止：没有待写内容时自动退出。
+func (s *Store) flushAsync() {
+	if s == nil {
+		return
+	}
+	s.mu.Lock()
+	if s.asyncBusy || s.closed {
+		s.mu.Unlock()
+		return
+	}
+	s.asyncBusy = true
+	s.mu.Unlock()
+
+	go func() {
+		delay := asyncDebounce
+		for {
+			time.Sleep(delay)
+			s.mu.Lock()
+			closed := s.closed
+			s.mu.Unlock()
+			if closed {
+				s.mu.Lock()
+				s.asyncBusy = false
+				s.mu.Unlock()
+				return
+			}
+			err := s.flush()
+			s.mu.Lock()
+			if s.closed || !s.hasPendingLocked() {
+				s.asyncBusy = false
+				s.mu.Unlock()
+				return
+			}
+			s.mu.Unlock()
+			if err != nil {
+				delay = asyncRetryDelay
+			} else {
+				delay = asyncDebounce
+			}
 		}
+	}()
+}
+
+// flush 把待写内容落盘。必须在未持有 s.mu 的情况下调用。
+func (s *Store) flush() error {
+	if s == nil {
+		return errors.New("chat history store is nil")
 	}
-	for _, id := range sortedDetailIDs(s.dirty) {
-		item, ok := s.details[id]
-		if !ok {
+	s.writeMu.Lock()
+	defer s.writeMu.Unlock()
+
+	s.mu.Lock()
+	if s.err != nil {
+		err := s.err
+		s.mu.Unlock()
+		return err
+	}
+	if !s.hasPendingLocked() {
+		s.mu.Unlock()
+		return nil
+	}
+	dirtyIDs := s.dirty
+	progressIDs := s.progress
+	deletedIDs := s.deleted
+	s.dirty = map[string]struct{}{}
+	s.progress = map[string]struct{}{}
+	s.deleted = map[string]struct{}{}
+	s.indexDirty = false
+	index := cloneFile(s.state)
+	fullEntries := make(map[string]Entry, len(dirtyIDs))
+	for id := range dirtyIDs {
+		if item, ok := s.details[id]; ok {
+			fullEntries[id] = cloneEntry(item)
+		}
+	}
+	progressEntries := make(map[string]Entry, len(progressIDs))
+	for id := range progressIDs {
+		if item, ok := s.details[id]; ok {
+			progressEntries[id] = cloneEntry(item)
+		}
+	}
+	s.mu.Unlock()
+
+	err := s.writeSnapshot(index, fullEntries, progressEntries, deletedIDs)
+	if err != nil {
+		s.restorePending(dirtyIDs, progressIDs, deletedIDs)
+	}
+	return err
+}
+
+// restorePending 在写盘失败后把待写标记放回去，让后续写入重试，
+// 同时不覆盖期间新产生的标记。
+func (s *Store) restorePending(dirtyIDs, progressIDs, deletedIDs map[string]struct{}) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	for id := range dirtyIDs {
+		s.dirty[id] = struct{}{}
+		delete(s.progress, id)
+		delete(s.deleted, id)
+	}
+	for id := range progressIDs {
+		if _, isFull := s.dirty[id]; isFull {
 			continue
 		}
-		path := filepath.Join(s.detailDir, id+".json")
+		s.progress[id] = struct{}{}
+		delete(s.deleted, id)
+	}
+	for id := range deletedIDs {
+		s.deleted[id] = struct{}{}
+		delete(s.dirty, id)
+		delete(s.progress, id)
+	}
+	s.indexDirty = true
+}
+
+func (s *Store) detailPath(id string) string {
+	return filepath.Join(s.detailDir, strings.TrimSpace(id)+".json")
+}
+
+func (s *Store) livePath(id string) string {
+	return filepath.Join(s.detailDir, strings.TrimSpace(id)+".live.json")
+}
+
+func (s *Store) writeSnapshot(index File, fullEntries, progressEntries map[string]Entry, deletedIDs map[string]struct{}) error {
+	if err := os.MkdirAll(s.detailDir, 0o755); err != nil {
+		return fmt.Errorf("create chat history detail dir: %w", err)
+	}
+	for _, id := range sortedDetailIDs(deletedIDs) {
+		for _, path := range []string{s.detailPath(id), s.livePath(id)} {
+			if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
+				return fmt.Errorf("remove stale chat history detail: %w", err)
+			}
+		}
+	}
+	for _, id := range sortedDetailIDs(entryIDSet(fullEntries)) {
 		payload, err := json.MarshalIndent(detailEnvelope{
 			Version: FileVersion,
-			Item:    item,
+			Item:    fullEntries[id],
 		}, "", "  ")
 		if err != nil {
 			return fmt.Errorf("encode chat history detail: %w", err)
 		}
-		if err := writeFileAtomic(path, append(payload, '\n')); err != nil {
+		if err := writeFileAtomic(s.detailPath(id), append(payload, '\n')); err != nil {
+			return err
+		}
+		// 完整文件已经带上最新状态，增量文件不再需要。
+		if err := os.Remove(s.livePath(id)); err != nil && !errors.Is(err, os.ErrNotExist) {
+			return fmt.Errorf("remove stale chat history progress: %w", err)
+		}
+	}
+	for _, id := range sortedDetailIDs(entryIDSet(progressEntries)) {
+		payload, err := json.MarshalIndent(progressEnvelope{
+			Version: FileVersion,
+			Item:    progressFromEntry(progressEntries[id]),
+		}, "", "  ")
+		if err != nil {
+			return fmt.Errorf("encode chat history progress: %w", err)
+		}
+		if err := writeFileAtomic(s.livePath(id), append(payload, '\n')); err != nil {
 			return err
 		}
 	}
 
-	payload, err := json.MarshalIndent(s.state, "", "  ")
+	payload, err := json.MarshalIndent(index, "", "  ")
 	if err != nil {
 		return fmt.Errorf("encode chat history index: %w", err)
 	}
 	if err := writeFileAtomic(s.path, append(payload, '\n')); err != nil {
 		return err
 	}
-	s.clearPendingDetailChangesLocked()
 	return nil
 }
 
+func (s *Store) readEntryLocked(id string) (Entry, error) {
+	item, err := readDetailFile(s.detailPath(id))
+	if err != nil {
+		return Entry{}, err
+	}
+	if progress, ok := readProgressFile(s.livePath(id)); ok && progress.Revision > item.Revision {
+		progress.applyTo(&item)
+	}
+	return item, nil
+}
+
 func (s *Store) rebuildIndexLocked() {
 	summaries := make([]SummaryEntry, 0, len(s.details))
 	for _, item := range s.details {
@@ -606,6 +852,7 @@ func (s *Store) nextRevisionLocked() int64 {
 		next = s.state.Revision + 1
 	}
 	s.state.Revision = next
+	s.indexDirty = true
 	return next
 }
 
@@ -648,6 +895,40 @@ func buildPreview(item Entry) string {
 	return candidate
 }
 
+func progressFromEntry(item Entry) progressRecord {
+	return progressRecord{
+		Version:          FileVersion,
+		Revision:         item.Revision,
+		UpdatedAt:        item.UpdatedAt,
+		CompletedAt:      item.CompletedAt,
+		Status:           item.Status,
+		ReasoningContent: item.ReasoningContent,
+		Content:          item.Content,
+		Error:            item.Error,
+		StatusCode:       item.StatusCode,
+		ElapsedMs:        item.ElapsedMs,
+		FinishReason:     item.FinishReason,
+		Usage:            cloneMap(item.Usage),
+	}
+}
+
+func (r progressRecord) applyTo(item *Entry) {
+	if item == nil {
+		return
+	}
+	item.Revision = r.Revision
+	item.UpdatedAt = r.UpdatedAt
+	item.CompletedAt = r.CompletedAt
+	item.Status = r.Status
+	item.ReasoningContent = r.ReasoningContent
+	item.Content = r.Content
+	item.Error = r.Error
+	item.StatusCode = r.StatusCode
+	item.ElapsedMs = r.ElapsedMs
+	item.FinishReason = r.FinishReason
+	item.Usage = cloneMap(r.Usage)
+}
+
 func readDetailFile(path string) (Entry, error) {
 	raw, err := os.ReadFile(path)
 	if err != nil {
@@ -660,6 +941,21 @@ func readDetailFile(path string) (Entry, error) {
 	return cloneEntry(env.Item), nil
 }
 
+// readProgressFile 读取流式增量文件。它只是完整文件之上的一个覆盖层，
+// 缺失或损坏都不影响完整文件本身，因此这里不返回错误。
+func readProgressFile(path string) (progressRecord, bool) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return progressRecord{}, false
+	}
+	var env progressEnvelope
+	if err := json.Unmarshal(raw, &env); err != nil {
+		config.Logger.Warn("[chat_history] ignoring corrupt progress file", "path", path, "error", err)
+		return progressRecord{}, false
+	}
+	return env.Item, true
+}
+
 func parseLegacy(raw []byte) (legacyFile, bool, error) {
 	var legacy legacyFile
 	if err := json.Unmarshal(raw, &legacy); err != nil {
@@ -679,6 +975,12 @@ func parseLegacy(raw []byte) (legacyFile, bool, error) {
 	return legacy, true, nil
 }
 
+// writeFileAtomic 用「临时文件 + rename」保证读到的永远是一个完整文件。
+//
+// 这里刻意不做 fsync：chat history 是可再生的诊断数据，而本项目的主要部署
+// 目标（HuggingFace Spaces 的 bucket 卷等对象存储挂载）单次 fsync 的延迟远高于
+// 本地盘。流式响应期间每个分片都 fsync 会把整个进程拖垮，收益却只是「掉电时
+// 少丢一条历史」。rename 本身已经保证不会出现半截 JSON。
 func writeFileAtomic(path string, body []byte) error {
 	dir := filepath.Dir(path)
 	if dir == "" {
@@ -713,9 +1015,6 @@ func writeFileAtomic(path string, body []byte) error {
 	if _, err := tmpFile.Write(body); err != nil {
 		return withCleanup(fmt.Errorf("write temp chat history: %w", err), tmpFile.Close())
 	}
-	if err := tmpFile.Sync(); err != nil {
-		return withCleanup(fmt.Errorf("sync temp chat history: %w", err), tmpFile.Close())
-	}
 	if err := tmpFile.Close(); err != nil {
 		if cleanupErr := cleanup(); cleanupErr != nil {
 			return errors.Join(fmt.Errorf("close temp chat history: %w", err), cleanupErr)
@@ -752,10 +1051,34 @@ func (s *Store) markDetailDirtyLocked(id string) {
 	if s.dirty == nil {
 		s.dirty = map[string]struct{}{}
 	}
+	if s.progress == nil {
+		s.progress = map[string]struct{}{}
+	}
 	if s.deleted == nil {
 		s.deleted = map[string]struct{}{}
 	}
 	s.dirty[id] = struct{}{}
+	delete(s.progress, id)
+	delete(s.deleted, id)
+}
+
+// markProgressDirtyLocked 只安排一次增量写入。若该条目已经排了完整写入，
+// 完整写入本身就包含最新状态，不再额外写增量文件。
+func (s *Store) markProgressDirtyLocked(id string) {
+	id = strings.TrimSpace(id)
+	if id == "" {
+		return
+	}
+	if s.progress == nil {
+		s.progress = map[string]struct{}{}
+	}
+	if s.deleted == nil {
+		s.deleted = map[string]struct{}{}
+	}
+	if _, isFull := s.dirty[id]; isFull {
+		return
+	}
+	s.progress[id] = struct{}{}
 	delete(s.deleted, id)
 }
 
@@ -767,16 +1090,15 @@ func (s *Store) markDetailDeletedLocked(id string) {
 	if s.dirty == nil {
 		s.dirty = map[string]struct{}{}
 	}
+	if s.progress == nil {
+		s.progress = map[string]struct{}{}
+	}
 	if s.deleted == nil {
 		s.deleted = map[string]struct{}{}
 	}
 	s.deleted[id] = struct{}{}
 	delete(s.dirty, id)
-}
-
-func (s *Store) clearPendingDetailChangesLocked() {
-	s.dirty = map[string]struct{}{}
-	s.deleted = map[string]struct{}{}
+	delete(s.progress, id)
 }
 
 func sortedDetailIDs(ids map[string]struct{}) []string {
@@ -791,6 +1113,17 @@ func sortedDetailIDs(ids map[string]struct{}) []string {
 	return out
 }
 
+func entryIDSet(entries map[string]Entry) map[string]struct{} {
+	if len(entries) == 0 {
+		return nil
+	}
+	out := make(map[string]struct{}, len(entries))
+	for id := range entries {
+		out[id] = struct{}{}
+	}
+	return out
+}
+
 func cloneFile(in File) File {
 	out := File{
 		Version:  in.Version,

internal/chathistory/store_test.go

@@ -3,6 +3,7 @@ package chathistory
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"os"
 	"path/filepath"
 	"strings"
@@ -633,3 +634,163 @@ func TestUpdateAllowsOverwritingContentWithNewValue(t *testing.T) {
 		t.Fatalf("expected content to be overwritten, got %q", updated.Content)
 	}
 }
+
+func waitForFile(t *testing.T, path string, timeout time.Duration) []byte {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if raw, err := os.ReadFile(path); err == nil {
+			return raw
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatalf("timed out waiting for %s", path)
+	return nil
+}
+
+// 流式进度必须写「小增量文件」，而不是每次重写包含完整上下文的大文件：
+// 这是 HuggingFace Spaces 等对象存储挂载上拖慢整个服务的主因。
+func TestStoreBackgroundProgressUsesCompactOverlay(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "chat_history.json")
+	store := New(path)
+	t.Cleanup(store.Close)
+
+	// 结尾不能是空白：Start 会对 FinalPrompt 做 TrimSpace。
+	bigContext := strings.Repeat("context line\n", 2000) + "tail"
+	started, err := store.Start(StartParams{
+		CallerID:    "caller:abc",
+		Model:       "deepseek-v4-flash",
+		Stream:      true,
+		UserInput:   "hello",
+		Messages:    []Message{{Role: "user", Content: bigContext}},
+		HistoryText: bigContext,
+		FinalPrompt: bigContext,
+	})
+	if err != nil {
+		t.Fatalf("start failed: %v", err)
+	}
+
+	fullPath := filepath.Join(store.DetailDir(), started.ID+".json")
+	livePath := filepath.Join(store.DetailDir(), started.ID+".live.json")
+	beforeFull, err := os.ReadFile(fullPath)
+	if err != nil {
+		t.Fatalf("read full detail failed: %v", err)
+	}
+
+	if _, err := store.Update(started.ID, UpdateParams{
+		Status:           "streaming",
+		ReasoningContent: "let me think",
+		Content:          "partial answer",
+		ElapsedMs:        12,
+		Background:       true,
+	}); err != nil {
+		t.Fatalf("background update failed: %v", err)
+	}
+
+	liveRaw := waitForFile(t, livePath, 5*time.Second)
+
+	afterFull, err := os.ReadFile(fullPath)
+	if err != nil {
+		t.Fatalf("re-read full detail failed: %v", err)
+	}
+	if !bytes.Equal(beforeFull, afterFull) {
+		t.Fatalf("background progress must not rewrite the full detail file")
+	}
+	if len(liveRaw) >= len(beforeFull) {
+		t.Fatalf("expected overlay (%d bytes) to be far smaller than full detail (%d bytes)", len(liveRaw), len(beforeFull))
+	}
+	t.Logf("progress write: overlay=%d bytes vs full detail=%d bytes (%.1fx smaller)",
+		len(liveRaw), len(beforeFull), float64(len(beforeFull))/float64(len(liveRaw)))
+
+	reloaded := New(path)
+	t.Cleanup(reloaded.Close)
+	full, err := reloaded.Get(started.ID)
+	if err != nil {
+		t.Fatalf("get after reload failed: %v", err)
+	}
+	if full.Content != "partial answer" || full.ReasoningContent != "let me think" || full.Status != "streaming" {
+		t.Fatalf("expected overlay to be applied on load, got %#v", full)
+	}
+	if full.HistoryText != bigContext || full.FinalPrompt != bigContext {
+		t.Fatalf("expected immutable context to survive reload")
+	}
+	if len(full.Messages) != 1 || full.Messages[0].Content != bigContext {
+		t.Fatalf("expected messages to survive reload")
+	}
+}
+
+// 终态更新必须回写成完整文件并清理增量文件，避免残留覆盖层。
+func TestStoreTerminalUpdateReplacesProgressOverlay(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "chat_history.json")
+	store := New(path)
+	t.Cleanup(store.Close)
+
+	started, err := store.Start(StartParams{UserInput: "hello", HistoryText: "ctx", FinalPrompt: "ctx"})
+	if err != nil {
+		t.Fatalf("start failed: %v", err)
+	}
+	livePath := filepath.Join(store.DetailDir(), started.ID+".live.json")
+
+	if _, err := store.Update(started.ID, UpdateParams{
+		Status:     "streaming",
+		Content:    "partial",
+		Background: true,
+	}); err != nil {
+		t.Fatalf("background update failed: %v", err)
+	}
+	waitForFile(t, livePath, 5*time.Second)
+
+	if _, err := store.Update(started.ID, UpdateParams{
+		Status:    "success",
+		Content:   "final answer",
+		Completed: true,
+	}); err != nil {
+		t.Fatalf("terminal update failed: %v", err)
+	}
+	if _, err := os.Stat(livePath); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("expected overlay to be removed after terminal update, stat err=%v", err)
+	}
+
+	reloaded := New(path)
+	t.Cleanup(reloaded.Close)
+	full, err := reloaded.Get(started.ID)
+	if err != nil {
+		t.Fatalf("get after reload failed: %v", err)
+	}
+	if full.Content != "final answer" || full.Status != "success" || full.CompletedAt == 0 {
+		t.Fatalf("expected terminal state to be persisted, got %#v", full)
+	}
+}
+
+// 流式进度的落盘失败不能冒泡给调用方，否则会打断正在进行的 SSE 响应；
+// 同时内存状态必须保持可读。
+func TestStoreBackgroundProgressDoesNotSurfaceWriteFailure(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "chat_history.json")
+	store := New(path)
+	t.Cleanup(store.Close)
+
+	started, err := store.Start(StartParams{UserInput: "hello"})
+	if err != nil {
+		t.Fatalf("start failed: %v", err)
+	}
+	restore := blockDetailDir(t, store.DetailDir())
+	defer restore()
+
+	if _, err := store.Update(started.ID, UpdateParams{
+		Status:     "streaming",
+		Content:    "partial",
+		Background: true,
+	}); err != nil {
+		t.Fatalf("background progress must not surface write errors, got %v", err)
+	}
+	if err := store.Err(); err != nil {
+		t.Fatalf("transient background write failure should not latch store error: %v", err)
+	}
+	snapshot, err := store.Snapshot()
+	if err != nil {
+		t.Fatalf("snapshot must keep working while writes fail: %v", err)
+	}
+	if len(snapshot.Items) != 1 {
+		t.Fatalf("expected in-memory state to stay readable, got %#v", snapshot.Items)
+	}
+}

internal/httpapi/openai/chat/chat_history.go

@@ -132,12 +132,15 @@ func (s *chatHistorySession) progress(thinking, content string) {
 		return
 	}
 	s.lastPersist = now
+	// Background=true：流式进度只写增量文件并由后台合并落盘，避免在 SSE
+	// 读取循环里同步等待磁盘（对象存储挂载下单次写入延迟很高）。
 	s.persistUpdate(chathistory.UpdateParams{
 		Status:           "streaming",
 		ReasoningContent: thinking,
 		Content:          content,
 		StatusCode:       http.StatusOK,
 		ElapsedMs:        time.Since(s.startedAt).Milliseconds(),
+		Background:       true,
 	})
 }
 

internal/responsehistory/session.go

@@ -127,12 +127,15 @@ func (s *Session) Progress(thinking, content string) {
 		return
 	}
 	s.lastPersist = now
+	// Background=true：流式进度只写增量文件并由后台合并落盘，避免在 SSE
+	// 读取循环里同步等待磁盘（对象存储挂载下单次写入延迟很高）。
 	s.persistUpdate(chathistory.UpdateParams{
 		Status:           "streaming",
 		ReasoningContent: thinking,
 		Content:          content,
 		StatusCode:       http.StatusOK,
 		ElapsedMs:        time.Since(s.startedAt).Milliseconds(),
+		Background:       true,
 	})
 }
 

webui/src/features/chatHistory/ChatHistoryContainer.jsx

@@ -10,8 +10,11 @@ import {
     VIEW_MODE_KEY,
 } from './chatHistoryUtils'
 
-const LIST_REFRESH_MS = 1500
-const STREAMING_DETAIL_REFRESH_MS = 750
+// 列表 / 详情轮询间隔。流式期间全局 revision 每 250ms 就变一次，ETag 永远
+// 命中不了 304，所以每次轮询都是全量传输；在 HF Spaces 这类低配实例上，
+// 过密的轮询本身会明显加重服务端负担，这里取一个仍然「够实时」的间隔。
+const LIST_REFRESH_MS = 3000
+const STREAMING_DETAIL_REFRESH_MS = 1500
 
 export default function ChatHistoryContainer({ authFetch, onMessage }) {
     const { t, lang } = useI18n()