Git Worktree with Claude Code

A Complete Usage Guide

Parallel development workflows without stashing or branch switching

1. Overview

Git Worktree is a built-in Git feature that lets you check out multiple branches simultaneously, each in its own dedicated directory, while sharing a single .git repository. When used together with Claude Code, it enables parallel, isolated AI-assisted development sessions — each session working on a different branch without interfering with one another.

1.1 Why Use Worktrees?

Traditional git workflow forces you to stash changes, switch branches, work, then switch back. Every context switch disrupts your flow. Worktrees solve this by giving each task a permanent, isolated directory:

• No stashing — each worktree has its own working tree and index.
• Run multiple Claude Code sessions simultaneously on different features.
• Keep a stable main branch always ready to read or run.
• Drastically reduce cognitive overhead when juggling multiple tasks.

1.2 How Worktrees Relate to Claude Code

Claude Code is a terminal-based AI coding agent. Because it operates on the filesystem inside a directory, it respects worktree boundaries naturally. You can:

• Open a separate terminal tab for each worktree.
• Start a dedicated Claude Code session per tab with claude.
• Let Claude work independently on each feature without cross-contamination.

Key Concept: A worktree is NOT a clone — it shares the same .git database. Creating 5 worktrees uses almost no extra disk space for the repo history. Only the working files are separate.

2. Prerequisites

• Git 2.5 or later (worktrees were introduced in 2.5).
• Claude Code installed: npm install -g @anthropic-ai/claude-code (requires Node.js 18+).
• A local Git repository with at least one commit.
• Familiarity with basic Git concepts (branches, commits, merges).

3. Core Concepts

3.1 Linked Worktree vs Main Worktree

Every repository has exactly one main worktree (where .git/ lives). All additional worktrees created with git worktree add are called linked worktrees. They store a small .git file (not a directory) pointing back to the main repository’s object database.

3.2 Branch Exclusivity

Git enforces that a branch can be checked out in at most one worktree at a time. Attempting to check out a branch that is already checked out elsewhere will produce an error. This prevents accidental conflicts between worktree sessions.

Important: If you try to check out the same branch in two worktrees, Git will refuse with:

1	fatal: 'feature/my-branch' is already checked out at '/path/to/other-worktree'

Always use distinct branch names per worktree.

4. Creating a Worktree Based on Your Latest Local Commit

The most common scenario is creating a new worktree that starts from where your current work is — the latest commit on your main (or current) branch.

4.1 Verify Your Starting Point

1
2
3
4
5

# Show current branch and last commit
git log --oneline -5

# Make sure everything is committed (no dirty state on main)
git status

4.2 Create the Worktree with a New Branch

1
2
3
4
5
6
7
8
9
10

# Syntax: git worktree add <path> -b <new-branch> [<start-point>]

# Create from the current HEAD (latest local commit):
git worktree add ../my-project-feature -b feature/my-feature

# Create from a specific branch tip:
git worktree add ../my-project-fix -b fix/critical-bug main

# Create from a specific commit hash:
git worktree add ../my-project-exp -b experiment/alpha abc1234

Use a sibling directory (../project-feature) to keep worktrees organised alongside your main repo:

1
2
3
4

~/projects/
  my-project/          ← main worktree (.git lives here)
  my-project-feature/  ← linked worktree for feature/my-feature
  my-project-fix/      ← linked worktree for fix/critical-bug

4.3 What Happens Under the Hood

• Git creates the directory at the specified path.
• It creates a .git file (not folder) inside that directory pointing to the main repo.
• A new branch is created at the specified start point (defaults to HEAD).
• The branch is checked out into the new directory.
• The new branch is registered in .git/worktrees/ inside the main repo.

4.4 Open Claude Code in the New Worktree

1
2
3
4
5
6
7
8

# In a new terminal tab:
cd ../my-project-feature

# Start Claude Code
claude

# Or for trusted projects (skips permission prompts):
claude --dangerously-skip-permissions

Pro Tip: Use terminal multiplexers like tmux or iTerm2 with named panes:

1 2 3

Pane 1: cd ~/projects/my-project && claude (main branch — read-only reference) Pane 2: cd ~/projects/my-project-feat && claude (feature branch — active development) Pane 3: cd ~/projects/my-project-fix && claude (hotfix branch — urgent fix)

5. Making Commits Inside a Worktree

Once inside a linked worktree, all standard Git commands work exactly as expected. The worktree has its own index (staging area) and working tree, completely isolated from other worktrees.

5.1 Normal Commit Workflow

1
2
3
4
5
6
7
8
9
10
11
12
13

# Navigate to the worktree
cd ../my-project-feature

# Stage changes
git add .
# or selectively:
git add src/components/Button.tsx

# Commit
git commit -m "feat: add responsive button component"

# Check status
git log --oneline -3

5.2 Committing from Within Claude Code

You can ask Claude Code to commit directly. Inside the worktree directory, Claude will use the correct branch automatically:

1
2

> Please implement the search filter component, then commit the changes
>   with a conventional commit message.

Claude Code will run git add, write a commit message, and execute git commit on your behalf. Because it is running inside the linked worktree directory, it commits to feature/my-feature — not main.

5.3 Pushing the Branch to Remote

1
2
3
4
5

# From within the worktree directory:
git push -u origin feature/my-feature

# Subsequent pushes (tracking is set):
git push

6. Listing and Inspecting Worktrees

1
2
3
4
5
6
7
8
9
10

# List all worktrees for the current repository:
git worktree list

# Example output:
# /Users/alice/projects/my-project          a3f91bc [main]
# /Users/alice/projects/my-project-feature  d4e82ca [feature/my-feature]
# /Users/alice/projects/my-project-fix      a3f91bc [fix/critical-bug]

# Verbose output with full details:
git worktree list --porcelain

7. Merging the Worktree Branch Back Into Main

When your feature or fix is ready, you have two primary strategies for integrating it back into main:

Strategy A: Merge Commit — Preserving Branch History (Diverge + Converge)

A standard git merge creates a merge commit that explicitly records the point where two diverged histories converged. This is the safest strategy and is preferred for shared, long-lived branches.

Step 1 — Ensure the feature branch is ready

1
2
3
4
5

cd ../my-project-feature

git status              # must be clean
git log --oneline -5   # verify your commits look right
git push origin feature/my-feature

Step 2 — Switch to main and pull latest changes

1
2
3
4

cd ../my-project

git checkout main
git pull origin main

Step 3 — Merge the feature branch

1
2
3
4
5

# Merge with an explicit merge commit (no fast-forward):
git merge --no-ff feature/my-feature -m "Merge feature/my-feature into main"

# If you want a fast-forward when possible (linear if no divergence):
git merge feature/my-feature

Step 4 — Resolve conflicts (if any)

1
2
3
4
5
6
7

# Git will mark conflicted files with <<<<<<<, =======, >>>>>>>
# Edit the files to resolve, then:
git add <resolved-file>
git merge --continue

# Or abort and start over:
git merge --abort

Step 5 — Push main

1

git push origin main

Resulting history graph:

1
2
3
4
5
6

* 9f4a1bc (main) Merge feature/my-feature into main
|\
| * d4e82ca feat: add responsive button component
| * c3d71ab feat: add button props interface
|/
* a3f91bc Initial commit (the shared start point)

Strategy B: Rebase — Linear History (Replay Without Divergence)

A rebase moves your feature commits on top of the latest main, rewriting them so the history appears linear. There are no merge commits. This is ideal for clean pull request histories or personal feature branches not yet shared with others.

Warning: Never rebase branches that have already been pushed and shared with other developers. Rewriting shared history forces others to do a hard reset. Only rebase private or PR branches.

Step 1 — Rebase the feature branch onto main

1
2
3
4
5
6
7
8
9
10

cd ../my-project-feature

# Fetch latest main first:
git fetch origin main

# Rebase: replay our commits on top of origin/main:
git rebase origin/main

# Interactive rebase (squash/edit/reorder commits before integrating):
git rebase -i origin/main

Step 2 — Resolve conflicts during rebase

1
2
3
4
5
6
7
8
9
10

# If a conflict occurs, Git pauses at the offending commit.
# Fix the conflict in your editor, then:
git add <resolved-file>
git rebase --continue

# Skip a particular commit (use with care):
git rebase --skip

# Abort and return to the original state:
git rebase --abort

Step 3 — Fast-forward main to include the rebased branch

1
2
3
4
5
6
7
8
9

cd ../my-project

git checkout main
git pull origin main        # ensure main is up-to-date

# Fast-forward merge (no merge commit needed — history is linear):
git merge feature/my-feature

git push origin main

Resulting history graph:

1
2
3
4
5

* d4e82ca' (main) feat: add responsive button component  ← rebased copy
* c3d71ab' feat: add button props interface               ← rebased copy
* a3f91bc Initial commit

# Note the ' marks — commits are rewritten with new hashes.

Strategy C: Squash Merge — Collapse All Commits into One

A squash merge condenses all commits from the feature branch into a single staged change, which you then commit manually onto main. The individual commit history is discarded. This keeps main‘s history extremely clean.

1
2
3
4
5
6
7
8
9
10
11

cd ../my-project
git checkout main
git pull origin main

# Squash all feature commits into the working tree (staged, not committed):
git merge --squash feature/my-feature

# Commit with a single descriptive message:
git commit -m "feat: add responsive button component with props (#42)"

git push origin main

8. Comparison of Integration Strategies

9. Removing a Worktree After Merging

1
2
3
4
5
6
7
8
9
10
11
12

# From the main worktree directory (or anywhere in the repo):
git worktree remove ../my-project-feature

# If the worktree has untracked or uncommitted changes, force removal:
git worktree remove --force ../my-project-feature

# Prune stale references (e.g., if you deleted the directory manually):
git worktree prune

# Optionally delete the branch as well:
git branch -d feature/my-feature
git push origin --delete feature/my-feature

10. Full End-to-End Example

Scenario: Add a dark-mode toggle while a hotfix is in progress.

Step 1 — Check current state

1
2
3
4
5

cd ~/projects/my-app
git log --oneline -3
# e7a3c1b (HEAD -> main, origin/main) chore: update dependencies
# 4f92d88 feat: add user profile page
# 1a8bc34 init: scaffold project

Step 2 — Create two worktrees from HEAD

1
2
3
4
5
6
7

git worktree add ../my-app-darkmode  -b feature/dark-mode
git worktree add ../my-app-hotfix    -b fix/login-crash

git worktree list
# ~/projects/my-app          e7a3c1b [main]
# ~/projects/my-app-darkmode e7a3c1b [feature/dark-mode]
# ~/projects/my-app-hotfix   e7a3c1b [fix/login-crash]

Step 3 — Work on both in parallel with Claude Code

1
2
3
4
5
6
7

# Terminal tab 1 — dark mode feature:
cd ~/projects/my-app-darkmode && claude
> Implement a dark-mode toggle that persists in localStorage.

# Terminal tab 2 — hotfix:
cd ~/projects/my-app-hotfix && claude
> Fix the login crash when email contains a + character.

Step 4 — Commit in each worktree independently

1
2
3
4

# In my-app-hotfix (fix is urgent, merge first):
git add src/auth/login.ts
git commit -m "fix: handle + character in email during login"
git push origin fix/login-crash

Step 5 — Merge the hotfix (fast-forward, linear history)

1
2
3
4
5

cd ~/projects/my-app
git checkout main
git pull origin main
git merge fix/login-crash
git push origin main

Step 6 — Rebase dark-mode onto updated main

1
2
3

cd ~/projects/my-app-darkmode
git fetch origin main
git rebase origin/main   # replays dark-mode commits on top of the hotfix

Step 7 — Merge dark-mode with a merge commit (to preserve history)

1
2
3

cd ~/projects/my-app
git merge --no-ff feature/dark-mode -m "Merge feature/dark-mode into main"
git push origin main

Step 8 — Clean up

1
2
3
4

git worktree remove ../my-app-darkmode
git worktree remove ../my-app-hotfix
git branch -d feature/dark-mode fix/login-crash
git push origin --delete feature/dark-mode fix/login-crash

11. Quick Reference

12. Troubleshooting

Branch already checked out

1

fatal: 'feature/my-feature' is already checked out at '/path/to/worktree'

Solution: use a different branch name, or remove the existing worktree first with git worktree remove /path/to/worktree.

Detached HEAD in a worktree

If you created a worktree without -b, it enters detached HEAD state. Create a branch to stabilise it:

1

git switch -c feature/my-new-branch

Rebase conflicts with many commits

When rebasing a long-lived branch, squash your commits first to reduce conflict surface area:

1
2

git rebase -i HEAD~N     # squash N commits into one
git rebase origin/main   # then rebase the single commit

Claude Code editing the wrong branch

Always verify the branch before starting Claude Code:

1
2
3

cd ../my-project-feature
git branch --show-current   # must show: feature/my-feature
claude

13. Best Practices

• Name worktree directories after their branches for clarity (my-app-feature-dark-mode).
• Keep worktrees as siblings of the main repo, not nested inside it.
• Always commit or stash inside a worktree before removing it — git worktree remove will refuse if there are local changes.
• Use git worktree prune periodically to clean stale references from deleted directories.
• Prefer merge --no-ff for team branches to preserve history; use rebase only on private branches.
• Run git fetch inside each worktree independently — fetch does not automatically propagate across worktrees.
• For long-running features, periodically rebase onto main to minimise merge conflicts later.

14. Summary

Git Worktree combined with Claude Code creates a powerful parallel development environment. Each worktree is a fully functional Git checkout — commits, pushes, rebases, and merges all work exactly as on any normal branch.

1. Create a worktree from the latest local commit with git worktree add <path> -b <branch>.
2. Open a separate Claude Code session (claude) inside each worktree directory.
3. Commit and push from within the worktree — it always operates on the correct branch.
4. Integrate back into main using a merge commit (diverge + converge), a rebase (linear), or a squash merge (single commit).
5. Clean up with git worktree remove and git branch -d once merged.

Git Worktrees do not replace your understanding of branches — they amplify it. Every workflow that works with branches works equally well with worktrees. The only constraint is that each branch can live in at most one worktree at a time.

可能導致 localstorage 被清空的副作用，進一步導致登錄狀態失效

時間：2026-04-30
系統：Fedora 43 KDE Plasma 6.6.4 (Wayland)
備份目錄：~/.font-config-backup/20260430-120735/

目標

把系統全局默認字體換成 CaskaydiaMono Nerd Font（拉丁/代碼）+
Sarasa Gothic TC（繁中），解決原來 Noto Sans CJK 在 Bold 字重下繁中
“糊成一團”的問題；同時修復 Ghostty 沒加粗、沒上色的配置缺失。

範圍覆蓋：KDE 桌面、Konsole、Ghostty、GTK 應用、Flatpak 沙盒應用。
未動：VS Code / Cursor（用戶確認無問題，且兩者各有獨立字體設定）。

關鍵發現（執行前的診斷）

1. CascadiaMono 完全不含 CJK 字形（fc-scan 驗證：CJK Unified
   Ideographs 0/20992，Hiragana 0/96，Hangul 0/11184）。所以 Chinese
   渲染必須由 fallback 字體承擔。原以爲它支持中文是 fontconfig fallback
   到 Noto Sans CJK 在背後工作的錯覺。
2. 系統原本繁中 Bold 解析到 NotoSansCJK-VF.ttc Bold —— 是真實 Bold，
   不是合成。問題出在 Variable Font 在小字號 + 繁中 + Bold 三重壓力下
   hinting 退化。
3. Ghostty ~/.config/ghostty/config 只有一行 shell-integration = zsh，
   完全沒設字體 / 主題 / bold 行爲。
4. Konsole 沒有自定義 profile，跑系統默認。
5. Plasma 6 + kwriteconfig6 可用。
6. 已裝 7 個 Flatpak 應用（DataGrip / Spotify / GoldenDict / PodmanDesktop
   / Typora / Inkscape / LocalSend），需要 fonts 目錄掛載授權才能看到
   新字體。

安裝的字體

CaskaydiaMono Nerd Font（來源：~/Downloads/CascadiaMono.zip）

• 路徑：~/.local/share/fonts/CaskaydiaMono/
• 數量：36 個 ttf
• 變體：
  • Nerd Font（雙寬圖標，通用）
  • Nerd Font Mono（單寬圖標，終端嚴格對齊）
  • Nerd Font Propo（比例間距，UI 用）
  • 各含 12 個字重/斜體（ExtraLight / Light / SemiLight / Regular /
    SemiBold / Bold + 各自 Italic）

Sarasa Gothic（來源：GitHub be5invis/Sarasa-Gothic v1.0.37）

• 路徑：~/.local/share/fonts/SarasaGothic/
• 數量：4 個 ttc（Sarasa-{Regular,Bold,Italic,BoldItalic}.ttc，總 322MB）
• 每個 ttc 內含全部區域（TC/SC/J/HC/CL）× 全部變體（Gothic/Mono/Term/
  Fixed/UI/Slab）
• 我們實際使用的是 TC 子集中的：
  • Sarasa Gothic TC（比例，UI 用）
  • Sarasa Mono TC（等寬 1.0× 配 Cascadia Mono）

配置變更

1. ~/.config/fontconfig/fonts.conf（新建）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

generic family aliases:
  monospace  → CaskaydiaMono Nerd Font Mono → Sarasa Mono TC → Noto fallback
  sans-serif → CaskaydiaMono Nerd Font Propo → Sarasa Gothic TC → Noto fallback
  serif      → Noto Serif → Noto Serif CJK TC

per-language strong bindings：
  zh-tw  monospace  → Sarasa Mono TC
  zh-tw  sans-serif → Sarasa Gothic TC
  zh-tw  serif      → Noto Serif CJK TC
  zh-hk  → Sarasa *-HC
  zh-cn  → Sarasa *-SC
  ja     → Sarasa *-J

global rules：
  embolden = false       (禁用合成加粗，避免雙重加粗導致糊)
  embeddedbitmap = false
  hinting = slight, antialias = true, lcdfilter = lcddefault

2. ~/.config/kdeglobals（修改 6 個鍵）

3. Konsole

• ~/.config/konsolerc 加 [Desktop Entry] DefaultProfile=Cascadia.profile
• ~/.local/share/konsole/Cascadia.profile（新建）：
  • Font = CaskaydiaMono Nerd Font Mono, 11pt
  • BoldIntense = true
  • UseFontLineCharacters = true
  • HistorySize = 10000

4. Ghostty ~/.config/ghostty/config（從 1 行擴展爲完整配置）

1
2
3
4
5
6
7
8
9
10
11

shell-integration = zsh

font-family             = CaskaydiaMono Nerd Font Mono
font-family-bold        = CaskaydiaMono Nerd Font Mono
font-family-italic      = CaskaydiaMono Nerd Font Mono
font-family-bold-italic = CaskaydiaMono Nerd Font Mono
font-size               = 11

font-synthetic-style = no-bold,no-italic,no-bold-italic
bold-is-bright       = false
theme                = catppuccin-mocha

這裏 bold-is-bright = false 是關鍵 —— 之前”沒加粗”是因爲 Ghostty
默認把 bold 屬性當成”變亮顏色”，我們強制它走真實 Bold 字體文件。

5. GTK 應用（gsettings org.gnome.desktop.interface）

6. Flatpak（7 個應用全部加 read-only 掛載）

1

flatpak override --user --filesystem=~/.local/share/fonts:ro <app>

應用：com.jetbrains.DataGrip / com.spotify.Client /
io.github.xiaoyifang.goldendict_ng / io.podman_desktop.PodmanDesktop /
io.typora.Typora / org.inkscape.Inkscape / org.localsend.localsend_app

驗證結果（fc-match）

1
2
3
4
5
6
7

默認 monospace            → CaskaydiaMono Nerd Font Mono Regular ✓
繁中 monospace            → Sarasa Mono TC Regular              ✓
繁中 monospace Bold       → Sarasa Mono TC Bold (real)          ✓
默認 sans-serif           → CaskaydiaMono Nerd Font Propo Regular ✓
繁中 sans-serif           → Sarasa Gothic TC Regular            ✓
繁中 sans-serif Bold      → Sarasa Gothic TC Bold (Sarasa-Bold.ttc) ✓
繁中 serif                → Noto Serif CJK TC Regular           ✓

繁中 Bold 從原來的 NotoSansCJK-VF（VF hinting 退化）切到了
Sarasa-Bold.ttc（手工逐像素 hinting）—— 這是本次修復的核心。

備份與還原

備份內容（~/.font-config-backup/20260430-120735/）

還原命令

1
2
3
4
5
6
7
8

# 完整還原（默認）
bun ~/.font-config-backup/20260430-120735/restore.ts

# 還原配置但保留字體文件（之後想自己選用）
bun ~/.font-config-backup/20260430-120735/restore.ts --keep-fonts

# 預演（不實際修改任何東西）
bun ~/.font-config-backup/20260430-120735/restore.ts --dry-run

restore.ts 已用 --dry-run 驗證可正常運行。

後續事項

1. 重啓會話讓 Plasma shell 拾取新字體：

   1	kquitapp6 plasmashell && kstart plasmashell &

   或者直接登出再登錄。已開的 Konsole / Ghostty / Firefox / Typora
   窗口需要關了重開。

2. Ghostty 主題改：編輯 ~/.config/ghostty/config 最後一行，
   ghostty +list-themes 看可選項。

3. DataGrip（JetBrains Flatpak）字體要在 IDE 內 Settings → Editor →
   Font 裏手動選 CaskaydiaMono Nerd Font Mono。權限掛載已做完。

4. 可選清理：~/Downloads/Sarasa-TTC-1.0.37.7z（143MB）已用完
   可刪。

5. 如果繁中加粗仍然偏糊：可以再加一條 fontconfig 規則把繁中 Bold
   重映射到 Medium 字重（Sarasa 有 Medium/SemiBold 字重可選）。在
   實際使用幾天後再評估。

Date: 2026-04-30
Environment: Fedora 43, KDE Plasma 6, Wayland session, kwin 6.6.4
Install location: /home/edge/.local/share/activitywatch/ (官方 bundle 直接解壓)

TL;DR

ActivityWatch 在登入後並沒有「真正壞掉」——子模組 (aw-server, aw-watcher-window, aw-watcher-afk) 一直在背景記錄；但 tray 管理器 aw-qt 在 Wayland session 下啟動時 crash，所以工作列看不到圖示，也無法用 tray 選單控制服務。額外地，autostart 引用的 Icon=activitywatch 從未被安裝到 hicolor 主題，KDE 自動啟動面板裡的條目顯示空白圖示。

兩個問題都已修復，登出/登入後 tray 圖示會自動出現。

動了什麼

最終 autostart .desktop 內容：

1
2
3
4
5
6
7
8
9
10
11
12
13

[Desktop Entry]
Name=ActivityWatch
GenericName=Time-tracking application
Comment=Open source time-tracking application with a focus on extensibility and privacy.
Exec=env QT_QPA_PLATFORM=xcb /home/edge/.local/share/activitywatch/aw-qt
Hidden=false
StartupNotify=true
Terminal=false
Type=Application
X-GNOME-Autostart-enabled=true
Version=1.0
Icon=activitywatch
Categories=Utility;

診斷過程

1. 先排除「以為設過 systemctl」的記憶

• ~/.config/systemd/user/ 整個目錄不存在
• systemctl --user list-unit-files | grep activitywatch 空
• /usr/lib/systemd/user/ 只有 plasma-kactivitymanagerd.service（KDE 自家 kactivitymanagerd，名字相像但跟 ActivityWatch 無關，可能是這個導致記憶混淆）

→ 結論：systemd user unit 從未被裝起來，過去能跑是靠 XDG autostart。

2. autostart 機制本身正常

~/.config/autostart/aw-qt.desktop 存在，且 Exec= 已是絕對路徑。今天 10:10 的 log 顯示 aw-qt 確實有被登入時拉起來。所以 autostart 不是問題。

3. 子模組還在跑、但 aw-qt 自己不見了

1
2
3
4
5

ps -ef | grep aw-
edge  3524  2386  ...  aw-server/aw-server         (10:10 起)
edge  3603  2386  ...  aw-watcher-window/...       (10:10 起)
edge  3606  2386  ...  aw-watcher-afk/...          (10:10 起)
# 沒有 aw-qt

這三個的 PPID = 2386，而 PID 2386 是 systemd --user——表示它們本來的父進程 (aw-qt) 死了，被 systemd 收養。子進程沒掛是因為 aw-qt 以 subprocess.Popen 啟動它們，並沒有在自身退出時 kill 掉它們。

4. 在前景重跑 aw-qt 抓到真正的錯誤

1
2
3
4
5

$ /home/edge/.local/share/activitywatch/aw-qt
... [INFO] Creating trayicon... (aw_qt.trayicon:208)
/home/edge/.local/share/activitywatch/aw-qt: symbol lookup error:
  /home/edge/.local/share/activitywatch/libQt6WaylandClient.so.6:
  undefined symbol: wl_proxy_marshal_flags

找到了。 之前 log 永遠停在 Creating trayicon... 是因為 dynamic linker 在 trayicon 階段才 lazy-load Qt wayland plugin，符號解析失敗 → 進程被 kernel 直接幹掉，沒有機會寫任何錯誤到 log file。

5. 改用 XWayland 驗證假設

1
2
3

$ env QT_QPA_PLATFORM=xcb /home/edge/.local/share/activitywatch/aw-qt
... [INFO] Creating trayicon...
... [INFO] Initialized aw-qt and trayicon successfully

成功。tray 圖示出現。

根本原因

問題 A — aw-qt 在 Wayland 下 crash

ActivityWatch bundle 內附 libQt6WaylandClient.so.6，這個 .so 引用 wl_proxy_marshal_flags 這個 symbol（屬於 libwayland-client，在 wayland 1.20 之後才加入）。

Bundle 內同時附了一份較舊的 libwayland-client.so.0，aw-qt 啟動時 LD_LIBRARY_PATH 把 bundle 目錄擺在最前，於是 Qt6WaylandClient 解析 wl_proxy_marshal_flags 時去 bundle 裡的舊 libwayland 找——找不到——symbol lookup error。

換句話說這是 bundle 內部的版本不一致 bug：打包者把新版 Qt wayland plugin 跟舊版 libwayland 放在一起。在 Wayland session（KDE Plasma 6、GNOME 都是）才會踩到，X11 session 不會，因為不會去 dlopen Qt wayland plugin。

為什麼 Windows 沒這問題？ Windows 平台根本沒有 Qt wayland plugin，aw-qt 只走 Win32 native，不踩這條程式碼路徑。

修法： QT_QPA_PLATFORM=xcb 強制 Qt 走 XCB plugin（XWayland），跳過 wayland plugin 的載入。tray icon 走 StatusNotifierItem D-Bus protocol，KDE 對 XWayland 的 SNI 支援很好，視覺體驗跟 native Wayland 沒差。

問題 B — .desktop 圖示渲染不出來

KDE 自動啟動面板裡 ActivityWatch 條目的圖示空白。

之前 Icon= 雖然指了絕對路徑 /home/edge/.local/share/activitywatch/media/logo/logo.png，但 KDE Plasma 6 自動啟動面板不接受絕對路徑——它只查 freedesktop icon theme 的 name。Bundle 從未把 activitywatch 圖示安裝到 ~/.local/share/icons/hicolor/，所以查不到 → 顯示空白。

修法： 把 bundle media/logo/ 下的三種尺寸 (512×512 PNG, 128×128 PNG, scalable SVG) 安裝到對應的 hicolor 目錄，跑 gtk-update-icon-cache，並把 Icon= 改回 freedesktop name activitywatch。

解決辦法（最終做法）

1
2
3
4
5
6
7
8
9
10
11

# 1. 安裝 hicolor 圖示
mkdir -p ~/.local/share/icons/hicolor/{512x512,128x128,scalable}/apps
cp ~/.local/share/activitywatch/media/logo/logo.png      ~/.local/share/icons/hicolor/512x512/apps/activitywatch.png
cp ~/.local/share/activitywatch/media/logo/logo-128.png  ~/.local/share/icons/hicolor/128x128/apps/activitywatch.png
cp ~/.local/share/activitywatch/media/logo/logo.svg      ~/.local/share/icons/hicolor/scalable/apps/activitywatch.svg
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor/

# 2. 修 autostart .desktop
#    將 Exec= 改成 `env QT_QPA_PLATFORM=xcb /home/edge/.local/share/activitywatch/aw-qt`
#    將 Icon= 改成 `activitywatch`
$EDITOR ~/.config/autostart/aw-qt.desktop

驗證

登出/登入後：

• Plasma 工作列 system tray 出現 ActivityWatch 圖示
• 點開 tray 選單能看到 Modules 列表（aw-server / aw-watcher-window / aw-watcher-afk 都 running）
• KDE「系統設定 → 啟動與關機 → 自動啟動」面板裡 ActivityWatch 條目有正確圖示
• http://localhost:5600 web UI 可訪問

後續建議

• bundle 升級時可重新測試 native Wayland：哪天上游打包修好 Qt wayland plugin 跟 libwayland 的版本錯位，可以拿掉 QT_QPA_PLATFORM=xcb。判斷方法：直接 ~/.local/share/activitywatch/aw-qt（不帶 env），看是否有 Initialized aw-qt and trayicon successfully。
• 若想要 systemctl 化管理（重啟、status、journald log），可改成 systemd user service：建 ~/.config/systemd/user/aw-qt.service，ExecStart=env QT_QPA_PLATFORM=xcb /home/edge/.local/share/activitywatch/aw-qt，PartOf=graphical-session.target，WantedBy=graphical-session.target，並把 ~/.config/autostart/aw-qt.desktop 設 Hidden=true 避免雙重啟動。本次採用 XDG autostart 簡單方案，未動 systemd。
• 目前的 orphan 子進程：今天 10:10 起的 server/watcher 由 systemd 收養而非新 aw-qt，新的 aw-qt tray 選單裡的 Stop/Restart 控制不到那批。日常使用無影響（資料都進同一個 sqlite）。如果在意，重開機或手動 pkill -f 'aw-(server|watcher)' + 重啟 aw-qt 即可重新接管。

參考檔案

• Crash log（保留樣本）：~/.cache/activitywatch/log/aw-qt/aw-qt_2026-04-30T11-37-26.log 之後的前景輸出
• Bundle desktop template (上游原始)：/home/edge/.local/share/activitywatch/aw-qt.desktop
• 修改後的 autostart：~/.config/autostart/aw-qt.desktop

Font Awesome

tabler

url: https://tabler.io/icons

Brand SVG

https://simpleicons.org/

随着大语言模型（LLM）的快速发展，越来越多开发者开始构建基于 AI 的应用，例如聊天机器人、智能助手、自动化工作流等。在这一领域，LangChain 和 Dify 是两个非常流行的工具，但它们解决的问题并不相同。

本文将用简单清晰的方式介绍它们的概念、功能，以及它们之间的区别。

一、什么是 LangChain

LangChain

LangChain 是一个 开源框架，用于开发基于大型语言模型（LLM）的应用程序，例如聊天机器人、智能助手或自动化工具。([IBM][1])

它提供了一套工具和组件，帮助开发者：

• 调用各种 AI 模型（如 OpenAI、Claude、Llama 等）
• 构建复杂的 AI 工作流程
• 连接外部数据源
• 构建智能代理（AI Agent）

简单来说：

LangChain 是一个用代码构建 AI 应用的开发框架。

LangChain 的核心能力

1 统一调用大模型

LangChain 可以作为不同 AI 模型的统一接口。

例如：

• OpenAI
• Anthropic
• HuggingFace
• 本地模型

开发者可以在不同模型之间切换，而无需大量修改代码。([Elastic][2])

2 Chain（链式工作流）

LangChain 的核心概念是 Chain（链）。

它允许将多个 AI 步骤串联成一个流程，例如：

1
2
3
4
5
6
7
8
9

用户问题
 ↓
检索相关文档
 ↓
生成 Prompt
 ↓
调用 LLM
 ↓
返回答案

这种方式可以构建复杂的 AI 工作流程。

3 RAG（检索增强生成）

RAG 是现代 AI 应用的重要架构。

流程通常是：

1
2
3
4
5
6
7

用户提问
 ↓
向量数据库搜索
 ↓
找到相关文档
 ↓
交给 LLM 生成回答

LangChain 可以很方便地连接各种数据库和数据源，实现 AI 知识库。

4 Agent（AI Agent）

LangChain 还支持 AI Agent。

AI 可以：

• 调用 API
• 使用工具
• 访问数据库
• 自动执行任务

例如：

1
2
3

用户：查一下东京天气
AI → 调用天气 API
AI → 生成回答

二、什么是 Dify

Dify

Dify 是一个 开源 AI 应用开发平台，用于快速创建和部署 AI 应用。

与 LangChain 不同：

Dify 更像一个可视化平台，而不是代码框架。

它提供了一套界面，可以让开发者甚至非程序员通过配置构建 AI 应用。([Information Development Europe B.V.][3])

Dify 的核心功能

1 可视化 AI 应用构建

Dify 提供拖拽式界面，可以直接设计 AI 工作流。

例如：

1
2
3
4
5
6
7

用户输入
 ↓
知识库搜索
 ↓
LLM 生成回答
 ↓
返回结果

整个流程可以通过 UI 配置完成。

2 内置 RAG 知识库

Dify 支持上传各种数据：

• PDF
• 文档
• Markdown
• 网站内容

系统会自动：

• 切分文本
• 生成向量
• 构建知识库

然后用于 AI 问答。

3 Workflow（AI 工作流）

Dify 支持构建复杂工作流，例如：

1
2
3
4
5
6
7

用户输入
 ↓
判断意图
 ↓
调用 API
 ↓
生成 AI 回答

很多企业用它来构建：

• AI 客服
• AI 知识库
• 自动化助手

4 API 与部署

Dify 创建的 AI 应用可以直接变成 API，供前端调用。

因此它也可以作为 AI 后端服务。

三、LangChain 与 Dify 的区别

两者最重要的区别在于 开发方式不同。

简单理解：

• LangChain = AI 编程框架
• Dify = AI 应用平台

四、什么时候使用 LangChain

LangChain 更适合：

• 开发复杂 AI 系统
• 构建自定义 Agent
• 深度控制 AI 工作流程
• 与现有系统深度集成

例如：

• AI 搜索引擎
• 自动化分析系统
• 多 Agent 系统

五、什么时候使用 Dify

Dify 更适合：

• 快速构建 AI 应用
• AI 客服
• AI 知识库
• AI 产品原型

例如：

• 企业内部问答系统
• AI 助手
• AI 工作流工具

六、LangChain 与 Dify 可以一起使用

在实际项目中，两者并不是竞争关系。

常见架构是：

1
2
3
4
5
6
7

Frontend
   ↓
Dify API
   ↓
LangChain
   ↓
LLM

或者：

1
2

复杂逻辑 → LangChain
应用管理 → Dify

这样既能保持灵活性，也能提高开发效率。

zustand selector

需要使用多个独立 selector。

下面的写法每次render都会返回一个新对象，在 React 19 的 useSyncExternalStore 下会触发你看到的 The result of getSnapshot should be cached，然后一路把整个树拖进无限更新，最后又表现成 InputBase 被动 effect 爆栈。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const {
authSession,
capabilityLevel,
hasAuthSession,
needsOnboarding,
needsVerification,
status,
} = useAuthSessionStore(state => ({
authSession: state.authSession,
capabilityLevel: state.capabilityLevel,
hasAuthSession: state.hasAuthSession,
needsOnboarding: state.needsOnboarding,
needsVerification: state.needsVerification,
status: state.status,
}));

原文地址 steamcommunity.com

总结

吾辈的启动项：-vulkan -novid -console +m_rawinput 1 -heapsize 6000000 -processheap -high -num_edicts 4096

然后，一定要替换dxvk_d3d9.dll，详细办法见使用 DXVK 使 Vulkan API 效率更高，启动项一定要加-vulkan

原文

本收藏為個人自用的遊戲優化方法、指令、管理模組之用途。

我需要紀錄我是如何「自定義」遊戲內容，並做個資訊彙總，也助於有看見此收藏的玩家們（不保證 100% 對大家有效）。

啟動選項（Launch Options）

版本一

-vulkan -autoconfig -lv -heapsize 6000000 -novid -processheap -high -num_edicts 4096

-heapsize 调动内存
-novid 自动跳过开头动画
-lv 低血腥模式，千万不要开清理尸体
-autoconfig 解决核显玩家游戏黑的问题
-num_edicts 给求生最大内存缓存 -heapsize不能大于-num_edicts（不然会加载进不去地图,换算单位，600万=4096）
-processheap：这个指令要求游戏使用指定的堆进行内存分配
high：将游戏的进程优先级设置为“高”，给予CPU最高优先级

版本二

我個人使用的：

-novid -console +m_rawinput 1 +cl_crosshair_alpha 0

啟動選項個別說明：

• -novid：跳過遊戲片頭動畫。99% 的玩家必定要輸入的指令之一，節省你的時間。
• -console：啟動時自動開啟控制台。只是為了方便看控制台，非必要參數。
• +m_rawinput 1：啟用 Raw Input，讓遊戲直接讀滑鼠輸入，降低受 Windows 指標加速 / 敏感度干擾的機率。
• +cl_crosshair_alpha 0：關閉遊戲內準心，用於 Addons 的自定義準心。
• -insecure：進入不安全模式。有修改遊戲的腳本 Addons，這是必要指令，因為你需要讓腳本 Addons「正常執行」，這對於開啟「本地伺服器」的主機玩家來說有幫助。（注意，這將會無法連接 Valve 官方伺服器）。
• -vulkan：使用 Vulkan API 渲染遊戲。助於降低 CPU 使用率，也『可能』降低 RAM 使用率，一般來說這是給 Mac 和 Linux 系統使用的 API，有人實測 Vulkan API 在 Windows 系統下有「優化」的感覺，非必要選項，可嘗試。
  DirectX9 vs Vulkan(DXVK 2.6.1)：
  https://www.youtube.com/watch?v=tRX-GR0hhvk

縮短遊戲載入時間

訂閱的 Addons 下載完成後，都放入 Addons 資料夾，並取消訂閱

實際做法是：

1. 訂閱一個 Addons 後進入遊戲。

2. 遊戲自動下載該 Addons，下載完畢後關閉遊戲。

3. 進入到「left4dead2」資料夾的「addons」。

4. 將「workshop」資料夾內的所有檔案複製到上一層「addons」資料夾，並取消訂閱所有 Addons。

5. 重啟遊戲發現不再檢查 Addons 更新，這使遊戲啟動速度更快。

為何每次開遊戲都在等 Addons 載入？原因就是 L4D2 會自動檢查訂閱 Addons 是否需要更新，而訂閱越多 Addons 載入越久。其實不是每個 Addons 都需要一直更新。
從此 Reddit 文章的回覆中習得到的方法。

終極 CFG 最佳設置

The Ultimate Left 4 Dead 2 Config (autoexec) by J. [github.com]，是由 J 為 L4D2 修改的 CFG 配置檔，這是他花大量心血與時間研究出的終極方案。

使用 DXVK 使 Vulkan API 效率更高

Vulkan API 透過 DXVK [github.com] 使轉換效率越來越高，效能可能比 DirectX API 還要高。

安裝方法：

1. 下載最新版本的 DXVK [github.com] tar.gz 壓縮檔。

2. 進到 tar.gz 壓縮檔內，路徑：「drvk - 版本號」資料夾 → 「x32」資料夾 → 複製「d3d9.dll」檔案

3. 打開「Left 4 Dead 2」資料夾 → 「bin」資料夾 → 先備份「dxvk_d3d9.dll」檔案 → 再用「d3d9.dll」去取代原始「dxvk_d3d9.dll」，記得檔案命名為「dxvk_d3d9.dll」。

4. L4D2 啟動選項一定要添加-vulkan

測試方法：

非常簡單，打開遊戲後設定視窗化，並查看視窗名稱是否有「-vulkan」字樣，有就是成功了。

！免責聲明！

任何修改遊戲之行為導致帳戶被 Ben，由當事人自行承擔。

今天吾辈遇到了这个错误，TypeError: undefined is not an object (evaluating 't.graph')，完整报错在底下，属实看不出任何猫腻，完完全全卡住了。

之后想到很多问题啊，比如，两个schema会不会导致冲突啊，然而在重新bun install，也解决不了问题的情况下思路卡住了，不过想到了bun.lock没删，再加上版本的确不匹配，

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

YOUR_WORKSPACE_DIR\package\auth $ bunx prisma --version  
Loaded Prisma config from prisma.config.ts.

Prisma schema loaded from prisma\schema.prisma.
prisma               : 7.3.0
@prisma/client       : 7.4.2
Operating System     : win32
Architecture         : x64
Node.js              : v25.6.0
TypeScript           : 5.9.2
Query Compiler       : enabled
PSL                  : @prisma/prisma-schema-wasm 7.5.0-10.94a226be1cf2967af2541cca5529f0f7ba866919
Schema Engine        : schema-engine-cli 94a226be1cf2967af2541cca5529f0f7ba866919 (at ..\..\node_modules\.bun\@prisma+engines@7.4.2\node_modules\@prisma\engines\schema-engine-windows.exe)
Default Engines Hash : 94a226be1cf2967af2541cca5529f0f7ba866919
Studio               : 0.13.1

我也不能确定，但是当时大概就是这个输出。

所幸更新了一下版本，最后确定了问题，得到的教训就是prisma一定要锁定版本，最好不要写”^7.4.2”，直接写”7.4.2”，不过吾辈目前还是写了^就是了，只不过因为有两个数据库，所以更新的话需要改8个地方（每个包四个），不知道怎么解决会比较好呢？

完整报错

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

6 | `)}};var Vu={red:be,gray:lt,dim:it,bold:G,underline:ot,highlightSource:e=>e.highlight()},qu={red:e=>e,gray:e=>e,dim:e=>e,bold:e=>e,underline:e=>e,highlightSource:e=>e};function ju({message:e,originalMethod:t,isPanic:r,callArguments:n}){return{functionName:`prisma.${t}()`,message:e,isPanic:r??!1,callArguments:n}}function Uu({callsite:e,message:t,originalMethod:r,isPanic:n,callArguments:i},o){let s=ju({message:t,originalMethod:r,isPanic:n,callArguments:i});if(!e||typeof window<"u"||process.env.NODE_ENV==="production")return s;let a=e.getLocation();if(!a||!a.lineNumber||!a.columnNumber)return s;let l=Math.max(1,a.lineNumber-3),u=Xt.read(a.fileName)?.slice(l,a.lineNumber),c=u?.lineAt(a.lineNumber);if(u&&c){let p=Qu(c),d=Bu(c);if(!d)return s;s.functionName=`${d.code})`,s.location=a,n||(u=u.mapLineAt(a.lineNumber,h=>h.slice(0,d.openingBraceIndex))),u=o.highlightSource(u);let f=String(u.lastLineNumber).length;if(s.contextLines=u.mapLines((h,x)=>o.gray(String(x).padStart(f))+" "+h).mapLines(h=>o.dim(h)).prependSymbol | ... truncated 
 7 | `)}function Hu(e){let t=[e.fileName];return e.lineNumber&&t.push(String(e.lineNumber)),e.columnNumber&&t.push(String(e.columnNumber)),t.join(":")}function er(e){let t=e.showColors?Vu:qu,r;return r=Uu(e,t),Ju(r,t)}var so=U(cn());function to(e,t,r){let n=ro(e),i=Gu(n),o=Wu(i);o?tr(o,t,r):t.addErrorMessage(()=>"Unknown error")}function ro(e){return e.errors.flatMap(t=>t.kind==="Union"?ro(t):[t])}function Gu(e){let t=new Map,r=[];for(let n of e){if(n.kind!=="InvalidArgumentType"){r.push(n);continue}let i=`${n.selectionPath.join(".")}:${n.argumentPath.join(".")}`,o=t.get(i);o?t.set(i,{...n,argument:{...n.argument,typeNames:zu(o.argument.typeNames,n.argument.typeNames)}}):t.set(i,n)}return r.push(...t.values()),r}function zu(e,t){return[...new Set(e.concat(t))]}function Wu(e){return ln(e,(t,r)=>{let n=Xi(t),i=Xi(r);return n!==i?n-i:eo(t)-eo(r)})}function Xi(e){let t=0;return Array.isArray(e.selectionPath)&&(t+=e.selectionPath.length),Array.isArray(e.argumentPath)&&(t+=e.argumentPath.length),t}function eo(e){switch( | ... truncated 
 8 | `)}getCurrentLineLength(){return this.currentLine.length}indentedCurrentLine(){let t=this.currentLine.padStart(this.currentLine.length+2*this.currentIndent);return this.marginSymbol?this.marginSymbol+t.slice(1):t}};no();var rr=class{constructor(t){this.value=t}write(t){t.write(this.value)}markAsError(){this.value.markAsError()}};var nr=e=>e,ir={bold:nr,red:nr,green:nr,dim:nr,enabled:!1},oo={bold:G,red:be,green:st,dim:it,enabled:!0},Le={write(e){e.writeLine(",")}};var Y=class{constructor(t){this.contents=t}isUnderlined=!1;color=t=>t;underline(){return this.isUnderlined=!0,this}setColor(t){return this.color=t,this}write(t){let r=t.getCurrentLineLength();t.write(this.color(this.contents)),this.isUnderlined&&t.afterNextNewline(()=>{t.write(" ".repeat(r)).writeLine(this.color("~".repeat(this.contents.length)))})}};var pe=class{hasError=!1;markAsError(){return this.hasError=!0,this}};var $e=class extends pe{items=[];addItem(t){return this.items.push(new rr(t)),this}getField(t){return this.items[t]}getPrintWidth(){r | ... truncated 
 9 | Note that ${s.bold("include")} statements only accept relation fields.`,a})}function Yu(e,t,r){let n=t.arguments.getDeepSubSelectionValue(e.selectionPath)?.asObject();if(n){let i=n.getField("omit")?.value.asObject();if(i){Xu(e,t,i);return}if(n.hasField("select")){ec(e,t);return}}if(r?.[ce(e.outputType.name)]){tc(e,t);return}t.addErrorMessage(()=>`Unknown field at "${e.selectionPath.join(".")} selection"`)}function Xu(e,t,r){r.removeAllFields();for(let n of e.outputType.fields)r.addSuggestion(new q(n.name,"false"));t.addErrorMessage(n=>`The ${n.red("omit")} statement includes every field of the model ${n.bold(e.outputType.name)}. At least one field must be included in the result`)}function ec(e,t){let r=e.outputType,n=t.arguments.getDeepSelectionParent(e.selectionPath)?.value,i=n?.isEmpty()??!1;n&&(n.removeAllFields(),uo(n,r)),t.addErrorMessage(o=>i?`The ${o.red("`select`")} statement for type ${o.bold(r.name)} must not be empty. ${ht(o)}`:`The ${o.red("`select`")} statement for type ${o.bold(r.name)} needs ${ | ... truncated 
10 | `)}};function Ue(e){return new dn(go(e))}function go(e){let t=new Ve;for(let[r,n]of Object.entries(e)){let i=new sr(r,yo(n));t.addField(i)}return t}function yo(e){if(typeof e=="string")return new k(JSON.stringify(e));if(typeof e=="number"||typeof e=="boolean")return new k(String(e));if(typeof e=="bigint")return new k(`${e}n`);if(e===null)return new k("null");if(e===void 0)return new k("undefined");if(Fe(e))return new k(`new Prisma.Decimal("${e.toFixed()}")`);if(e instanceof Uint8Array)return Buffer.isBuffer(e)?new k(`Buffer.alloc(${e.byteLength})`):new k(`new Uint8Array(${e.byteLength})`);if(e instanceof Date){let t=Zt(e)?e.toISOString():"Invalid Date";return new k(`new Date("${t}")`)}return e instanceof fo.ObjectEnumValue?new k(`Prisma.${e._getName()}`):je(e)?new k(`prisma.${ce(e.modelName)}.$fields.${e.name}`):Array.isArray(e)?hc(e):typeof e=="object"?go(e):new k(Object.prototype.toString.call(e))}function hc(e){let t=new $e;for(let r of e)t.addItem(yo(r));return t}function ar(e,t){let r=t==="pretty"?oo:ir, | ... truncated 
11 | `);return t.reduce(function(r,n){var i=Dc(n)||Mc(n)||$c(n)||Uc(n)||qc(n);return i&&r.push(i),r},[])}var Oc=/^\s*at (.*?) ?\(((?:file|https?|blob|chrome-extension|native|eval|webpack|rsc|<anonymous>|\/|[a-z]:\\|\\\\).*?)(?::(\d+))?(?::(\d+))?\)?\s*$/i,Nc=/\((\S*)(?::(\d+))(?::(\d+))\)/;function Dc(e){var t=Oc.exec(e);if(!t)return null;var r=t[2]&&t[2].indexOf("native")===0,n=t[2]&&t[2].indexOf("eval")===0,i=Nc.exec(t[2]);return n&&i!=null&&(t[2]=i[1],t[3]=i[2],t[4]=i[3]),{file:r?null:t[2],methodName:t[1]||Tt,arguments:r?[t[2]]:[],lineNumber:t[3]?+t[3]:null,column:t[4]?+t[4]:null}}var Fc=/^\s*at (?:((?:\[object object\])?.+) )?\(?((?:file|ms-appx|https?|webpack|rsc|blob):.*?):(\d+)(?::(\d+))?\)?\s*$/i;function Mc(e){var t=Fc.exec(e);return t?{file:t[2],methodName:t[1]||Tt,arguments:[],lineNumber:+t[3],column:t[4]?+t[4]:null}:null}var _c=/^\s*(.*?)(?:\((.*?)\))?(?:^|@)((?:file|https?|blob|chrome|webpack|rsc|resource|\[native).*?|[^@]*bundle)(?::(\d+))?(?::(\d+))?\s*$/i,Lc=/(\S+) line (\d+)(?: > eval line \d+)* > | ... truncated 

TypeError: undefined is not an object (evaluating 't.graph')
 clientVersion: "7.3.0",

      at new ii (YOUR_WORKSPACE_DIR\node_modules\@prisma\client\runtime\client.js:11:56375)
      at Fa (YOUR_WORKSPACE_DIR\node_modules\@prisma\client\runtime\client.js:11:56244)
      at deserialize (YOUR_WORKSPACE_DIR\node_modules\@prisma\client\runtime\client.js:11:57817)
      at new jt (YOUR_WORKSPACE_DIR\node_modules\@prisma\client\runtime\client.js:57:17465)
      at ml (YOUR_WORKSPACE_DIR\node_modules\@prisma\client\runtime\client.js:58:6195)
      at new t (YOUR_WORKSPACE_DIR\node_modules\@prisma\client\runtime\client.js:75:71)
      at YOUR_WORKSPACE_DIR\package\server\prisma\client.ts:28:23

generate by chatGPT

为什么 AI 生成的页面总是紫色？以及如何“去 AI 味”

最近刷到一个有趣的梗：Tailwind 创始人调侃地为当年把 bg-indigo-500 设成默认按钮色道歉——因为现在几乎所有 AI 生成的 UI 都是那种“熟悉的紫色”。你是不是也有同样的感觉？一眼 AI，大片紫、渐变卡片、圆角阴影三件套。

这不是错觉，这是模式收敛。

当你用类似这样的提示词：

站在产品经理和设计师的角度，使用 HTML 设计一个番茄工作法 iOS 应用原型图……

AI 会优先选择它训练数据中“最常见、最安全、最不出错”的组合：Tailwind + 紫色主色 + 柔和渐变 + 大圆角 + 轻阴影。因为这是当前主流开源组件库和 SaaS 产品的审美均值。

如果你不指定风格，它就会回到“统计平均值”。这就是紫色泛滥的根本原因。

一、为什么 AI 会收敛到紫色？

原因可以拆成三个层面。

第一，训练数据分布。
Tailwind、Shadcn、Radix、各类 SaaS 模板大量使用 Indigo / Violet 系主色。模型学习到的“现代 UI”≈“紫色卡片 + 柔和渐变”。

第二，风险最小化。
紫色既不像红色那么激进，也不像绿色那样有语义歧义（成功/错误），是一个“中性偏科技感”的安全选择。

第三，提示词太宽泛。
“现代化”“精美”“完整”“可直接实现”这些词没有具体约束，模型只能调用默认范式。

本质不是 AI 审美差，而是你没有给它风格边界。

二、如何让 AI 不再生成“紫色默认模板”

核心思路：把抽象词换成可执行设计约束。

不要说“现代化”，要说：

• 主色：#0F172A 深灰蓝
• 辅助色：#22C55E 番茄计时状态绿色
• 强调色：#F97316 橙色
• 禁止使用紫色系

不要说“iOS 风格”，要说：

• 使用 iOS 17 Human Interface Guidelines 风格
• 采用大标题 + 分组卡片
• 模糊背景 + 半透明材质
• 使用 SF Pro 字体（或等价替代）

不要说“精美完整”，要说：

• 必须包含以下状态：

  • 未开始
  • 计时中
  • 暂停
  • 结束统计页

• 明确列出组件结构

示例改写提示词：

使用原生 HTML + CSS（不依赖 Tailwind CDN），设计一个番茄工作法 iOS 风格应用原型。
主色为 #22C55E，禁止使用紫色系。
采用玻璃拟态（glassmorphism）设计，圆角 16px，阴影为柔和扩散阴影。
字体使用本地 Inter 或 SF Pro 替代。
页面需包含：计时首页、计时中状态、暂停弹窗、统计页。
所有组件需可直接供 Vue 3 项目拆分实现。

当你给出明确的视觉约束，AI 的输出会明显提升。

三、进阶玩法：定义“设计技能（Skill）”

与其每次重写提示词，不如抽象成一套“设计规范模板”。

你可以建立一个本地 prompt 模板，例如：

1
2
3
4
5
6
7
8
9

Design System:
- Style: Minimal + iOS native
- Radius: 12px
- Spacing scale: 4px system
- Typography: 16px base, 1.5 line-height
- Primary color: #0EA5E9
- No purple
- No Tailwind CDN
- Use semantic class naming

以后所有 UI 生成都附带这段规范。

这本质上是“定义 Agent Skill”，而不是每次临时对话。

四、如何“二开”AI 生成的项目

如果已经生成了一个“紫色 Tailwind 模板”，怎么改？

建议按下面步骤做：

1. 去框架化（可选）

如果你希望长期维护：

• 去掉 CDN
• 把 Tailwind 样式提取为变量
• 或重写为 SCSS / CSS Modules

2. 抽离 Design Token

建立：

1
2
3
4
5

:root {
  --color-primary: #22C55E;
  --color-bg: #F8FAFC;
  --radius-base: 12px;
}

替换所有硬编码的 bg-indigo-500。

3. 组件化重构（Vue）

拆分结构：

1
2
3
4
5

/components
  TimerDisplay.vue
  ControlButtons.vue
  StatsCard.vue
  PauseDialog.vue

把原始 HTML 拆成 Vue 组件。

4. 建立状态机

番茄钟不是静态页面，它是状态驱动：

1

idle -> running -> paused -> finished

用 Vue ref 或 pinia 建立状态流，而不是靠 DOM 切换。

五、真正去 AI 味的方法

“去 AI 味”不是换颜色，而是增加“选择”。

AI 模板最大的问题是：

• 所有按钮一样
• 所有卡片一样
• 所有阴影一样

真实设计不会这么均匀。

你可以：

• 给主 CTA 更强对比
• 给统计页用不同布局结构
• 刻意打破 8px 统一圆角
• 控制留白，而不是平均分布

设计的灵魂在于“节奏差异”，而不是整齐。

六、总结

AI 生成紫色页面不是 bug，而是统计平均。

当提示词过于抽象时，模型会回到默认模板。
想要真正定制化 UI，你必须给出：

• 明确色彩体系
• 明确设计风格
• 明确状态结构
• 明确技术栈限制

从“让 AI 设计”转变为“让 AI 按规范实现设计”。

这样生成的页面，才会真正变成你的作品，而不是一眼 AI。

原文地址 blog.1loli.link

问题描述

我在神舟 T8 Pro E64 (616QY) 笔记本上尝试开启安全启动 (Secure Boot) 时，BIOS 提示当前处于 “Setup Mode”，需要切换到”User Mode” 才能成功开启。

经过大量尝试和查阅资料，发现此型号笔记本由广达代工，其 BIOS 隐藏了大量高级选项，包括关键的密钥管理 (Key Management) 设置页面，导致无法通过常规方法解决。

本文记录了解决此问题的完整过程。

教程

核心思路是通过修改 BIOS，将隐藏的 “Key Management” 菜单显示出来，然后手动注册安全启动所需的密钥文件。

第一步：提取并修改 BIOS

1. 提取 BIOS 文件

   • 对于 Intel 芯片组的主板，可以使用官方 CSME System Tools 包中的 Flash Programming Tool (FPT) 来提取和刷入 BIOS。
   • 注意：刷入前可能需要先禁用 BIOS 的写保护功能（如果 BIOS 支持该功能）。

2. 编辑 BIOS 文件

   • 使用 UEFI-Editor 工具打开提取出的 BIOS 文件。
   • 根据该工具的教程，在 BIOS 设置中找到安全启动 (Secure Boot) 相关的菜单。
   • 定位到被隐藏的 “Key Management” 项目（通常会被标记为 Suppressed），解除其隐藏状态。
   • 保存修改后的 BIOS 文件。

3. 刷入修改后的 BIOS

   • 使用 Flash Programming Tool (FPT) 将修改后的 BIOS 文件刷回主板。

第二步：准备安全启动密钥文件

1. 下载密钥文件

   • 访问微软在 GitHub 上的官方仓库：secureboot_objects。
   • 下载最新版本的 dbx, db, KEK, PK 文件。
     

2. 准备存储介质

   • 将下载的所有密钥文件解压，并存放至一个 FAT32 格式的 U 盘根目录。

第三步：手动导入密钥并配置启动项

1. 进入 BIOS 设置

   • 重启电脑，进入 BIOS 设置界面。此时，你应该可以在安全启动菜单下看到之前被隐藏的 “Key Management” 选项。
     

2. 检查密钥状态

   • 进入 “Key Management” 页面，检查 PK, KEK, db, dbx 的状态。在我的情况中，这些项目初始大小均为 0KB，且尝试恢复出厂默认密钥 (Restore Default PK) 会提示失败。
     

3. 手动导入密钥

   • 依次选择 PK, KEK, db, dbx 选项，并从之前准备好的 U 盘中手动导入对应的文件。
     

4. 注册 Windows 启动文件

   • 在 “Key Management” 页面中，找到并选择 “Enroll Efi Image” 选项。

   • 浏览到你的 Windows 启动分区 (ESP 分区)。

   • 选择 Windows 的启动文件，路径通常为 /EFI/Microsoft/Boot/bootmgfw.efi，并确认导入。
     

     第四步：开启并验证安全启动

5. 开启安全启动

   • 完成上述所有操作后，返回上一级菜单，尝试开启安全启动 (Secure Boot)。此时应该可以被正常设置为 “Enabled”。
     

6. 保存并退出

   • 按 F10 保存更改并重启电脑。

7. 验证结果

   • 进入 Windows 系统后，打开 “Windows 安全中心” 或运行 msinfo32 (系统信息)，可以查看到安全启动状态是否已成功开启。

注意：如果在启动过程中遇到红色的提示框，显示 “Verification failed” 或类似的验证失败信息，这通常意味着启动文件验证不通过。你需要重新执行第三步的第 4 点，确保导入了正确的 bootmgfw.efi 文件。

众所周知，机械革命不是一个好的电脑厂商。

所以虽然Intel 14900 系列一直有着问题，但是想要让他们去更新bios那是想都不要想的。

所以基本上得要自己想办法去更新微码。

二六年二月二十三日朋友告诉吾辈，微码是可以自己手动更新的，感恩。

需要用到的 Tool

Flash Programming Tool (FPT)

对于Intel芯片组的主板，FPT 作为 CSME System Tools 包中的一部分，用来提取和刷入 BIOS。
注意：刷入前可能需要先禁用 BIOS 的写保护功能（如果 BIOS 支持该功能）。

MMTool

American Megatrends Inc. 公司 Aptio 工具套件的一部分，所以自然是没有直接下载方案的

下载

UEFI-Editor

GitHub: https://github.com/BoringBoredom/UEFI-Editor

结论先说：
是的，用 uv 会比传统 pip + venv 更好。
尤其是在你这种 Windows + GPU + 需要长期维护模型环境的场景下。

下面我给你一个完整、工程级别的 uv 安装方案，而不是简单替换几条命令。

一、为什么用 uv 更好？

uv（Astral 出品）本质是一个高性能的 Python 包管理器 + 虚拟环境工具，优势在于：

• 🚀 速度远快于 pip
• 🔒 更可靠的依赖解析
• 📦 更好的 lock 管理
• 🧼 虚拟环境结构更干净
• 🧠 不污染全局 Python

在 AI 项目（尤其是 PyTorch + CUDA 这种复杂依赖）里，环境污染是灾难。
uv 可以显著降低这种风险。

二、使用 uv 安装 ComfyUI（Windows 原生方案）

Step 1：安装 uv

在 PowerShell 里执行：

1

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

然后确认：

1

uv --version

Step 2：克隆 ComfyUI

1
2

git clone https://github.com/comfyanonymous/ComfyUI.git C:\ComfyUI
cd C:\ComfyUI

Step 3：用 uv 创建虚拟环境

推荐方式（指定 Python 3.10）

1

uv venv --python 3.10

这会在当前目录创建：

1

.venv/

然后激活：

1

.venv\Scripts\activate

Step 4：使用 uv 安装依赖（替代 pip）

1

uv pip install -r requirements.txt

⚠️ 这里 uv 会调用它自己的 resolver，比 pip 更稳定。

三、关于 PyTorch + CUDA（重点）

ComfyUI 本质是依赖 PyTorch 的。

通常你需要：

1

uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

⚠️ 这里的 cu121 要根据你的 CUDA 版本决定。

检查方式：

1

nvidia-smi

如果是 RTX 40 系列，一般推荐 CUDA 12.x。

四、启动 ComfyUI

有两种方式：

方式一（推荐）

直接用 uv 运行：

1

uv run python main.py

方式二

激活环境后：

1

python main.py

浏览器打开：

1

http://127.0.0.1:8188

五、如果你想做“工程级”管理（进阶）

你可以进一步改成：

1
2
3

uv init
uv add -r requirements.txt
uv lock

这样会生成：

1
2

uv.lock
pyproject.toml

以后环境是完全可复现的。

这对于长期维护 Stable Diffusion 节点非常重要。

六、推荐的最佳实践结构

我个人建议你这样组织：

1
2
3
4
5
6

C:\AI\
   ├── ComfyUI\
   │     ├── .venv\
   │     ├── models\
   │     └── custom_nodes\
   └── other_sd_project\

每个项目独立 venv。

不要共享 Python。

不要全局 pip install。

七、什么时候不需要 uv？

如果：

• 你只是临时跑一跑
• 用官方 portable 版本
• 不打算长期维护

那 uv 不是必须。

但如果你：

• 想深度调优
• 会装大量 custom nodes
• 可能换 torch 版本
• 可能升级 CUDA

那 uv 会极大提升稳定性。

八、额外建议（非常关键）

1. 永远不要用系统 Python
2. 不要用 Anaconda（AI 环境冲突率高）
3. 关闭 Windows Defender 对模型目录的实时扫描（会严重影响速度）
4. GPU 驱动要用 Studio Driver

如果你愿意，我可以帮你做一个：

• RTX 4080 / CUDA 12.x 最优 torch 组合建议
• ComfyUI 性能优化参数
• VRAM 省显存启动方案

你是想走“稳定生产环境”，还是“实验性环境”？
我可以给你两个完全不同的配置策略。

很好，这个报错信息其实非常清晰，我们逐层拆解。

一句话结论

你现在安装的是：

CPU 版本的 PyTorch

而不是 CUDA 版本。

所以 ComfyUI 在初始化 GPU 时直接炸掉：

1

AssertionError: Torch not compiled with CUDA enabled

证据在哪里？

关键日志：

1
2
3
4

Found comfy_kitchen backend cuda:
{'available': False,
 'disabled': True,
 'unavailable_reason': 'CUDA not available on this system'}

以及：

1

Torch not compiled with CUDA enabled

这不是驱动问题。

这不是 CUDA 13.1 问题。

这 100% 是：

你当前 venv 里装的是 CPU torch

为什么会发生？

因为你之前执行了：

1

uv pip install -r requirements.txt

而 requirements.txt 里通常只写：

1

torch

默认行为是：

pip 安装 CPU 版 torch

除非你明确指定 CUDA index-url。

正确修复步骤（非常重要）

在 ComfyUI 目录：

1️⃣ 激活你的虚拟环境

1

.venv\Scripts\activate

2️⃣ 彻底卸载当前 torch

1

uv pip uninstall torch torchvision torchaudio -y

确保完全移除。

3️⃣ 安装 CUDA 12.1 版本（推荐）

1

uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

⚠️ 必须指定 index-url。

4️⃣ 验证

1

python -c "import torch; print(torch.cuda.is_available()); print(torch.version.cuda)"

你应该看到：

1
2

True
12.1

然后再运行

1

uv run python main.py

为什么不是 CUDA 13.1？

因为：

• 驱动支持 CUDA 13.1
• PyTorch 目前稳定构建是 cu121
• 驱动向下兼容

完全没问题。

再解释一下日志里的 triton

1
2

Found comfy_kitchen backend triton:
ImportError: No module named 'triton'

这个不是致命问题。

• Triton 是优化后端
• 可选
• 不影响 GPU 是否可用

真正的问题只有：

1

Torch not compiled with CUDA enabled

你现在环境的真实状态

你犯的经典错误

先装 requirements，再装 torch

正确顺序是：

1. 先装 GPU torch
2. 再装 requirements

否则 requirements 会装 CPU 版本覆盖。

如果你想更干净一点（推荐）

直接删除 .venv：

1

rmdir /s /q .venv

然后：

1
2
3
4
5

uv venv --python 3.10
.venv\Scripts\activate

uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
uv pip install -r requirements.txt

这是最干净的做法。

如果你愿意，我可以帮你做一个：

• RTX 40 系列稳定配置
• ComfyUI 高显存优化参数
• SDXL / Flux 最佳启动参数
• 省显存运行策略

你显卡型号是？显存多少？
我们可以直接调到最优解。

很好，你这张 RTX 4080 12GB 其实是一个“刚好卡在临界点”的配置——
既可以跑 SDXL，但必须精细控制显存策略，否则就会出现 OOM 或频繁清理显存导致卡顿。

我给你一个系统级的优化方案，不是零散参数，而是完整结构思路。

一、先确认你的目标类型

12GB 显存下的优先级建议：

• 🟢 SD1.5 → 完全无压力
• 🟡 SDXL → 可跑，但需要控制
• 🔴 Flux / 大型 LoRA 叠加 → 必须优化

如果你是长期使用 ComfyUI 做生产工作，建议做下面这几层优化。

二、ComfyUI 启动层优化

推荐启动参数（4080 12GB 稳定版）

1

python main.py --force-fp16 --use-pytorch-cross-attention --disable-smart-memory

参数解释

• --force-fp16
  强制半精度，直接节省 40~50% 显存

• --use-pytorch-cross-attention
  让 attention 走 torch 原生 kernel（对 40 系列更稳定）

• --disable-smart-memory
  禁止 ComfyUI 频繁卸载模型（12GB 下反而更稳定）

三、PyTorch 层优化

1️⃣ 开启 TF32（非常重要）

在 main.py 顶部加：

1
2
3

import torch
torch.backends.cuda.matmul.allow_tf32 = True
torch.backends.cudnn.allow_tf32 = True

这对 RTX 40 系列有明显提升。

2️⃣ 开启 cudnn benchmark

1

torch.backends.cudnn.benchmark = True

前提是你分辨率固定（例如 1024×1024）。

四、模型加载策略优化

1️⃣ 不要同时加载多个 checkpoint

12GB 下：

• 一次只加载一个大模型
• LoRA 不超过 2~3 个

2️⃣ 使用 8-bit 或 4-bit LoRA

如果你使用大量 LoRA：

• 转成 8bit
• 或用 nvfp4（ComfyUI 新 backend 已支持）

可以节省 1~2GB。

五、分辨率控制建议

不要一开始就 1344×1344。

六、Windows 系统层优化

1️⃣ 关闭 Defender 对模型目录扫描

把：

1

D:\AI Models\

加入排除列表。

会明显减少 IO 卡顿。

2️⃣ 设置电源模式为“最佳性能”

控制面板 → 电源选项。

3️⃣ NVIDIA 控制面板

• 电源管理模式 → Prefer Maximum Performance
• 低延迟模式 → Off

七、内存和缓存优化

1️⃣ 增加 Pagefile（很重要）

12GB GPU + 16GB RAM 时建议：

虚拟内存设置为：

1
2

最小 32768 MB
最大 65536 MB

避免 SDXL 爆内存崩溃。

八、性能预期（给你一个心理模型）

RTX 4080 12GB + SDXL：

如果明显慢于这个，多半是：

• 没开 fp16
• torch 没走 CUDA
• 被 Defender 拖慢

九、是否要安装 Triton？

你日志显示：

1

ImportError: No module named 'triton'

是否值得装？

结论：

• 对 40 系列提升有限
• 容易增加依赖冲突
• 不建议现在装

等环境稳定再考虑。

十、终极稳定方案（推荐结构）

1
2
3
4
5
6

D:\AI\
   ├── ComfyUI\
   │     ├── .venv
   │     ├── models
   │     ├── output
   │     └── custom_nodes

• 每个 AI 项目一个独立 venv
• 不共享 torch
• 不全局安装 CUDA Toolkit

十一、如果你想进一步压榨性能

可以：

• 使用 xFormers（节省 10~15% 显存）
• 使用 Flash Attention 2（需要编译）
• 使用 nvfp4 quantization

但这些属于“进阶实验优化”，不是稳定优先方案。

总结给你一句话

你的 RTX 4080 12GB 是一个“必须精细管理显存”的卡。

优化关键只有三件事：

1. 强制 FP16
2. 控制模型数量
3. 关闭 Windows IO 干扰

做到这三点，ComfyUI 会非常稳定。

如果你告诉我：

• 你主要跑 SDXL 还是 1.5？
• 会不会用 ControlNet？
• 会不会叠多个 LoRA？

我可以给你一个完全针对你使用模式的最优组合。

1

HKEY_CURRENT_USER\SOFTWARE\SolidWorks\AllowList\Current

在右侧窗口找到 Renderer 项，双击并复制其”Value”（例如：NVIDIA GeForce RTX 4080 Laptop GPU/PCIe/SSE2）

定位 Gl2Shaders：导航至：

1

HKEY_CURRENT_USER\SOFTWARE\SolidWorks\AllowList\Gl2Shaders

根据显卡品牌（NVIDIA 选 NV40，AMD 选 R420，Intel 选 Other），在对应文件夹下新建项（key），重命名为刚才复制的名称。

在新文件夹内新建 DWORD (32位) 值，命名为 Workarounds，数值建议填入 30408 或 31408 (十六进制)(Hexadecimal)

在 2026 年的 React 生态系统中，Motion（原 Framer Motion）依然是声明式动画的事实标准。然而，根据不同的项目需求，如物理特性、复杂时间轴、包体积或自动布局动画，以下是几个主要的同类竞争产品调研。

React Spring

React Spring 是一个基于弹簧物理（Physics-based）原理的动画库，它不再依赖固定的持续时间，而是通过模拟质量、张力和阻力来创建自然的运动效果。

• 核心优势：动画效果极其流畅且符合直觉，能很好地处理中断和交互。
• 适用场景：需要高度自然感、有机交互的 UI，或者涉及复杂物理反馈的场景。
• 关键特性：支持 Hooks API（如 useSpring, useTransition），兼容 SSR 环境。

GSAP (GreenSock Animation Platform)

GSAP 是网页动画领域的工业级标准。虽然它不是专门为 React 设计的，但其强大的插件生态（如 ScrollTrigger）使其在复杂动画开发中不可替代。

• 核心优势：极高的高性能和跨浏览器兼容性。其时间轴（Timeline）控制能力远超其他声明式库。
• 适用场景：复杂的营销页面、滚动驱动的叙事动画、涉及数百个元素同步运动的场景。
• 关键特性：ScrollTrigger 插件可以轻松实现复杂的滚动联动效果。

AutoAnimate

由 FormKit 团队开发的 AutoAnimate 走的是零配置路线，它通过一行代码就能为列表和布局变动添加平滑过渡。

• 核心优势：极低的学习成本，不需要编写具体的动画帧或过渡逻辑。
• 适用场景：快速提升后台管理系统、动态列表或网格布局的视觉质感。
• 关键特性：通过单个 Hook 或指令即可自动识别 DOM 变化并应用动画。

React Transition Group

这是 React 官方推荐过的底层库，它本身不提供动画逻辑，而是管理组件进入和离开 DOM 的状态。

• 核心优势：体积小巧，完全控制生命周期，可配合原生 CSS 或任何 JavaScript 动画引擎使用。
• 适用场景：基础的模态框显隐、简单的淡入淡出，以及对包体积有极致要求的项目。
• 关键特性：CSSTransition 和 TransitionGroup 组件。

性能与特性对比表

选择建议

1. 如果追求与 React 的深度集成、极致的声明式体验和丰富的手势支持，Motion 仍是首选。
2. 如果项目侧重于物理驱动的响应式动效，React Spring 在表现力上更具优势。
3. 面对需要精密编排、长序列动画或大规模 DOM 节点的情况，GSAP 的性能和调试工具更为可靠。
4. 仅需为列表增加简单的添加/删除动画，AutoAnimate 是投入产出比最高的方案。

我可以为您对比其中某两个库的具体代码实现，或者根据您的项目规模推荐最适合的配置方案，您希望我深入介绍哪一个？

Summary: TypeScript + package.json exports in monorepo

Why the error occurred

Your tsconfig.base.json has composite: true, which implies all source files must be under rootDir (defaults to the tsconfig’s directory). When TypeScript resolves @package/ui/Navigation via the exports field → ./src/Navigation/index.ts, that file lives in package/ui/, which is outside package/app/‘s rootDir. Hence the error.

Additionally, include: ["../ui/**/*.ts"] was directly pulling ui source into app’s program — a double violation.

How TypeScript resolves package.json exports

With moduleResolution: "Bundler" (your base config), TypeScript fully supports the exports field:

1. import {RouterLink} from '@package/ui/Navigation'
2. TS finds @package/ui → reads package.json
3. Matches exports["./Navigation"] → uses types condition → ./src/Navigation/index.ts
4. Resolution succeeds

The issue was never about exports compatibility — it was about composite‘s rootDir enforcement.

What was changed

package/app/tsconfig.json:

• Overrode composite: false, declaration: false, declarationMap: false, emitDeclarationOnly: false — app is a leaf Vite application, not a library, so it doesn’t need these
• Removed "../ui/**/*.ts", "../ui/**/*.tsx" from include — app should only compile its own source; cross-package types come through exports resolution
• Removed outDir since app doesn’t emit anything (Vite handles bundling)

Root tsconfig.json:

• Removed app from references — without composite, it can’t participate in tsc -b

The pattern for extensionless cross-package imports

Your current package/ui/package.json exports setup is correct for this:

1
2
3
4
5
6
7
8

"./*": {
  "types": "./src/*",
  "import": "./src/*"
},
"./Navigation": {
  "types": "./src/Navigation/index.ts",
  "import": "./src/Navigation/index.ts"
}

• Wildcard ./* — handles extensionless file imports like @package/ui/SomeFile
• Explicit ./Navigation — needed for directory-based exports (where the actual file is index.ts inside a folder), because the wildcard won’t automatically append /index.ts

The rule: for any directory with an index.ts, add an explicit exports entry. Wildcards only work for direct file-to-file mapping.

有，而且这是一个典型 Windows + Git + 大小写重命名的工程问题。你这个 monorepo 规模下，确实值得用“工程级解法”一次性清干净。

我给你按安全程度从低风险到高风险分层讲清楚。

✅ 方案一（推荐）：强制 Git 重新识别当前大小写状态

这个是最干净、最可控的方法。

第一步：关闭 ignorecase

Windows 默认：

1
2

git config core.ignorecase
# 大概率是 true

改为：

1

git config core.ignorecase false

这一步非常关键。

第二步：强制 Git 重新扫描 index

让 Git 重新对比磁盘文件和 index：

1
2

git rm -r --cached .
git add .

然后：

1

git status

如果大小写有差异，你会看到 rename 或 delete/add。

最后：

1

git commit -m "chore: normalize file casing"

为什么这招有效？

因为：

• --cached 只清 index，不删物理文件
• 再 git add . 会根据当前磁盘真实大小写重新建 index
• Git 被强制重新建立大小写映射

这是最安全方案。

✅ 方案二：强制大小写重命名（更精确）

如果你只想修一个目录，比如：

1

component/navigation

想统一成：

1

component/Navigation

做法：

1
2
3

git mv component/navigation component/__tmp__
git mv component/__tmp__ component/Navigation
git commit -m "fix: normalize Navigation directory casing"

✅ 方案三：暴力重建 index（偏工程化）

如果你怀疑整个仓库 casing 混乱，可以：

1
2

rm -f .git/index
git reset

或者：

1

git read-tree --reset -u HEAD

这个会完全重建 index。

⚠️ 只建议在工作区 clean 时使用。

🚨 千万不要做的事

不要：

1

删除文件 → 手动重建

不要：

1

直接 rename 文件夹大小写（Windows 会忽略）

因为 NTFS 默认大小写不敏感，直接改大小写 Git 不一定感知。

🧠 为什么会发生？

你的项目：

1

Library.Book/package/app/src/component

如果你：

• 曾在 Linux/WSL 操作
• 或从 Mac clone
• 或 IDE 自动修正大小写
• 或做过 git mv 但 ignorecase=true

都会导致：

Git index 认为：

1

Navigation

但磁盘是：

1

navigation

TypeScript 再结合 path alias 就会触发 TS1149。

🛡 工程级预防方案（强烈建议）

1️⃣ tsconfig 打开

1

"forceConsistentCasingInFileNames": true

2️⃣ 团队 Git 强制大小写敏感

在仓库级别执行：

1

git config core.ignorecase false

甚至可以写进：

1

.git/config

3️⃣ ESLint 规则

1

import/no-unresolved

并开启 caseSensitive 选项。

🎯 给你最稳的一套操作顺序

如果我是你，现在这样做：

1
2
3
4

git config core.ignorecase false
git rm -r --cached .
git add .
git commit -m "chore: rebuild git index to normalize casing"

然后：

• 重启 TS server
• 重启 IDE
• 再跑一遍 typecheck

基本 99% 解决。

💬 说一句实话

你这个 monorepo 规模（Library.Book）已经到了：

“路径规范必须制度化”的阶段。

否则以后 CI 上 Linux 一跑，直接炸。

如果你愿意，我可以给你：

• 一套跨平台命名规范
• 一套 React + TS + Bun monorepo 的 casing 规范模板
• 一套 pre-commit 自动检测大小写冲突脚本

这类问题属于工程成熟度问题，而不是单纯 bug。

你现在踩到的是正常进阶门槛。

为什么 Git 默认不追踪大小写变更？

• Git 默认大小写敏感，但会根据文件系统类型决定是否追踪大小写变化。
• Linux：默认大小写敏感（EXT4）。
• macOS/Windows：默认大小写不敏感（HFS+ / NTFS）。

如何让 Git 追踪大小写变化？

• 执行以下命令强制 Git 不忽略大小写：

  1	git config core.ignorecase false

如何解决已有的大小写更改未被识别？

• 使用中间临时名来实现大小写变更：

  1. 重命名为临时名：

     1	git mv foo temp_name

  2. 重命名为目标名：

     1	git mv temp_name Foo

  3. 提交更改：

     1	git commit -m "fix: rename foo → Foo (大小写更正)"

总结

• 跨系统协作时：

  • 确保所有开发者统一 Git 设置：git config core.ignorecase false
  • 规范文件命名，避免随意更改大小写（例如，统一小写或使用下划线）。、

• 检查当前设置：

  • 使用 git config core.ignorecase 查看当前的配置，确保其为 false。

问题

Few Hooks error

因为 babel-plugin-react-compiler 会优化 Hooks，但是只会优化以use开头的useXXX函数，理论上未使用use开头的函数是会跳过？

然而实际上这可能触发非常严重的问题，会导致完全无法调试的Few Hooks error。

推荐调试的时候先禁用插件，然后确定问题是不是由于babel-plugin-react-compiler导致的。

简介

Generate by AI

babel-plugin-react-compiler 本质上是 React Compiler 的 Babel 接入层：它把你的函数组件与自定义 Hook（以及部分相关函数）在“构建期”改写成带有自动缓存与细粒度失效的代码，让你在不大量手写 useMemo / useCallback / React.memo 的前提下，尽量把“更新时真正需要重算/重渲染的部分”压到最小，同时还会基于同一套核心逻辑去验证你是否违反了 React 的基本规则（纯渲染、Hooks 规则等）。这套方向在官方设计目标里写得很直白：希望应用默认就快、启动时间不要倒退、并且尽量“移除概念而不是引入概念”（减少对手动 memo 的依赖）。(GitHub)

从产物形态上看，这个 Babel 插件干的事并不神秘：它会在编译后的输出里插入一个“memo cache”数组，并以一个哨兵值 Symbol.for("react.memo_cache_sentinel") 来判断缓存是否已填充，然后复用上一次渲染计算出来的 JSX 或中间值。官方安装文档给了一个最小例子：编译后会出现 import { c as _c } from "react/compiler-runtime";，随后用 _c(n) 初始化缓存槽位并在命中时直接取回。(React) 这也是你判断“插件是否真的在跑”的最硬证据之一（另一个是 DevTools 里出现 “Memo ✨” 标记）。(React)

再往里一层，React 团队公开的编译器架构描述解释了“为什么它能做到更细粒度”：Babel 插件先决定哪些函数要编译（取决于选项与局部指令），随后把 Babel AST lowering 成编译器自己的高层中间表示 HIR（保留高层语义、并以控制流图组织），再进入 SSA 形式、跑一系列校验（检测条件式 Hook、无条件 setState 等）、做基础优化（DCE、常量传播）、做保守类型推断，然后推断并构造所谓“reactive scopes”（把会一起创建/变更、以及相关指令聚成组），最后 codegen 回 Babel AST 替换原函数。(GitHub) 这段描述里有两个对使用者非常关键的含义：第一，它强依赖“遵守 React 规则”来保证变换安全；第二，它明确把“完全零冗余重算”列为非目标，因为额外追踪与代码膨胀可能反噬启动性能。(GitHub) 也因此你会看到它不支持类组件、也不会承诺支持 100% JS 语法角落（例如 eval() 等）。(GitHub)

落到 babel-plugin-react-compiler 的实操层面，有三件事决定你能否顺利落地。第一是插件顺序：官方明确要求它必须在 Babel 插件流水线里最先运行，因为它需要尽可能“原始”的源码信息做分析，后置变换会破坏这些信息。(React) 第二是接入方式：React 官方文档直接给了 Babel 与 Vite 的推荐配置（Vite 既可以走 @vitejs/plugin-react 的 babel.plugins，也可以用 vite-plugin-babel 单独挂载）。(React) 第三是版本目标：React 19 默认就能工作；如果你在 React 17/18 上用编译产物，则需要安装 react-compiler-runtime 并在配置里设置 target: '17' | '18'，否则运行期会缺少相应 runtime。(React)

下面给你一个“工程里最常见、也最不容易踩坑”的 Babel 配置骨架，你只需要把它合并进现有配置即可（注意它要放在插件数组最前）：

1
2
3
4
5
6
7
8
9
10
11
12

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      // 生产建议：遇到问题的组件跳过优化，不要直接炸构建
      panicThreshold: 'none',
      // React 19 默认即可；React 17/18 需要显式 target + 安装 react-compiler-runtime
      // target: '18',
    }],
    // ...other plugins
  ],
};

这里出现的 panicThreshold 来自官方配置参考，它决定“编译遇到错误时是失败构建还是跳过问题组件”；文档里把 panicThreshold: 'none' 标为推荐的生产配置（跳过出问题的组件，继续优化其他部分）。(React) 同一份配置参考还给了调试与灰度手段：你可以用 logger.logEvent(filename, event) 捕获编译成功/失败等事件，用于定位到底哪些文件被编译、哪里被跳过。(React) 如果你需要做 A/B 或渐进灰度，gating 允许你指定一个 feature-flag 模块与导出函数名，让编译产物在运行期根据开关选择是否走优化路径。(React)

另一个经常被忽略、但会直接影响“为什么我感觉没生效”的开关，是 compilationMode。默认是 'infer'：编译器靠启发式识别组件与 Hook（比如 PascalCase 组件名、use 前缀 Hook、并且确实创建 JSX 或调用 Hook），你不需要写任何额外标注；如果你想极其稳妥地逐步接入，可以改为 'annotation'，此时只有显式写了 "use memo" 指令的函数才会被编译；而 "use no memo" 则永远是强制跳过。(React) 这套机制的价值在于：当你接入初期遇到少数库/组件不兼容或行为异常时，你可以先用 "use no memo" 把它们隔离出来，让整体构建与大部分页面继续享受优化，然后再用 lint/日志去逐个消化。官方安装页把这点写得非常明确："use no memo" 是临时逃生舱。(React)

关于“手写 memo 还要不要存在”，官方立场其实很一致：目标是让绝大多数场景下你不需要再为了性能去写 useMemo/useCallback/React.memo，但它并不追求把所有重算都消到零，也不会为了极限最优引入高额追踪成本或显著膨胀代码体积。(GitHub) 这意味着你的工程实践会变成“默认不写，只有在行为语义需要（比如你就是要一个稳定引用参与外部系统协议）或某些特殊性能剖析结论明确时再写”，而不是过去那种“先写一堆 memo 再说”。

最后说一下配套的“保证你不会盲用”的部分：官方推荐同时启用 ESLint 的相关规则，用来提示哪些组件/Hook 因为违反 Rules of React 而无法被优化。更重要的是，文档强调这是安全的：当 ESLint 报错时，编译器会跳过该组件/Hook 的优化，但不会影响其它代码的优化，你可以按自己的节奏逐步修。(React) 接入完成后，最直接的验收方法就是打开 React DevTools，看看组件名旁边是否出现 “Memo ✨” 标记；或者直接在构建输出里搜 react/compiler-runtime 与 react.memo_cache_sentinel。(React)

如果你愿意把你当前的构建栈（Vite/Next/Rspack 等）、React 版本（17/18/19）、以及是否存在“必须保留稳定引用语义”的场景（例如订阅系统、第三方表单库、可视化库）贴出来，我可以按你的工程形态给一份更贴合的推荐配置（compilationMode/target/panicThreshold/logger/gating 该怎么组合、以及最小化风险的渐进接入路径）。