跳转至

2026-04-21 学习日志

今日主题

  • Claude Code 配置来源与启动参数
  • TypeScript shim 与三方组件类型错配
  • Tailwind v4 的 @theme 机制
  • Tailwind v3 与 v4 的主题配置映射
  • 飞书画板 DSL + OpenAPI + Yoga 引擎原理

新增认知

Claude Code 配置来源与启动参数

  • 不会替换默认 ，而是作为单独的 配置层加入合并链，优先级高于 user/project/local。
  • 只控制 、、integer 10 readonly !=0 integer 10 readonly '#'=0 integer 10 readonly '$'=64122 array readonly ''=( ) readonly -=569X 0=/bin/zsh integer 10 readonly '?'=127 array readonly @=( ) integer 10 readonly ARGC=0 tied cdpath CDPATH='' CODEX_CI=1 CODEX_SANDBOX=seatbelt CODEX_SANDBOX_NETWORK_DISABLED=1 CODEX_THREAD_ID=019daad6-7a68-7101-8cad-42cf4aef5e0e COLORFGBG='15;0' COLORTERM=truecolor integer 10 COLUMNS=0 COMMAND_MODE=unix2003 CPUTYPE=arm64 integer 10 EGID=20 integer 10 EUID=501 tied fignore FIGNORE='' tied fpath FPATH=/usr/local/share/zsh/site-functions:/usr/share/zsh/site-functions:/usr/share/zsh/5.9/functions integer 10 FUNCNEST=700 GH_PAGER=cat integer 10 GID=20 GIT_PAGER=cat GOOGLE_CLOUD_PROJECT=soy-reporter-269419 HISTCHARS='!^#' integer 10 readonly HISTCMD=0 integer 10 HISTSIZE=30 HOME=/Users/Yungyu HOMEBREW_API_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles HOMEBREW_BREW_GIT_REMOTE=https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git HOMEBREW_CELLAR=/opt/homebrew/Cellar HOMEBREW_CORE_GIT_REMOTE=https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git HOMEBREW_PREFIX=/opt/homebrew HOMEBREW_REPOSITORY=/opt/homebrew HOST=Yungyu-Mac.local IFS=$' \t\n\C-@' INFOPATH=/opt/homebrew/share/info:/opt/homebrew/share/info: ITERM_INJECT_SHELL_INTEGRATION=1 ITERM_PROFILE=Home ITERM_SESSION_ID=w2t0p0:B6627FF4-03D4-4254-8691-E89CC5865893 JAVA_HOME=/Users/Yungyu/.jenv/versions/8 JAVA_TOOL_OPTIONS='-DJM.LOG.PATH=/tmp -DJM.SNAPSHOT.PATH=/tmp' JDK_HOME=/Users/Yungyu/.jenv/versions/8 JENV_FORCEJAVAHOME=true JENV_FORCEJDKHOME=true JENV_LOADED=1 JENV_SHELL=zsh KEYBOARD_HACK='' integer KEYTIMEOUT=40 KUBE_EDITOR='code --wait' LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 LC_CTYPE=C.UTF-8 LC_TERMINAL=iTerm2 LC_TERMINAL_VERSION=3.6.9 LESS=-R integer 10 readonly LINENO=1 integer 10 LINES=0 integer LISTMAX=100 LOGNAME=Yungyu LSCOLORS=Gxfxcxdxbxegedabagacad LS_COLORS='di=1;36:ln=35:so=32:pi=33:ex=31:bd=34;46:cd=34;43:su=30;41:sg=30;46:tw=30;42:ow=30;43' LaunchInstanceID=9D1A24E1-6341-4010-B393-AF09863F3F78 MACHTYPE=x86_64 integer MAILCHECK=60 tied mailpath MAILPATH='' tied manpath MANPATH='' tied module_path MODULE_PATH=/usr/lib/zsh/5.9 NO_COLOR=1 NULLCMD=cat NVM_BIN=/Users/Yungyu/.nvm/versions/node/v24.13.0/bin NVM_CD_FLAGS=-q NVM_DIR=/Users/Yungyu/.nvm NVM_INC=/Users/Yungyu/.nvm/versions/node/v24.13.0/include/node OLDPWD=/Users/Yungyu/Agent OPTARG='' integer 10 OPTIND=1 OSTYPE=darwin24.0 PAGER=less tied path PATH='/Users/Yungyu/.codex/tmp/arg0/codex-arg0icqwPc:/Users/Yungyu/Library/pnpm:/Users/Yungyu/.krew/bin:/Users/Yungyu/.jenv/shims:/Users/Yungyu/.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/Users/Yungyu/.local/bin:/opt/homebrew/opt/ruby/bin:/Users/Yungyu/.jenv/bin:/Users/Yungyu/.go/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/usr/local/corplink/mdm/opt/corplink-mdm/bin:/Users/Yungyu/.cargo/bin:/Applications/iTerm.app/Contents/Resources/utilities:/Users/Yungyu/Library/Application Support/JetBrains/Toolbox/scripts:/Users/Yungyu/.orbstack/bin' PNPM_HOME=/Users/Yungyu/Library/pnpm integer 10 readonly PPID=67468 PROMPT='' PROMPT2='' PROMPT3='?# ' PROMPT4='+%N:%i> ' PS1='' PS2='' PS3='?# ' PS4='+%N:%i> ' tied psvar PSVAR='' PWD=/Users/Yungyu/Agent integer 10 RANDOM=23721 READNULLCMD=more integer 10 SAVEHIST=0 integer 10 SECONDS=0 SECURITYSESSIONID=186a2 SHELL=/bin/zsh integer 10 SHLVL=1 SPROMPT='zsh: correct '\''%R'\'' to '\''%r'\'' [nyae]? ' SSH_AUTH_SOCK=/private/tmp/com.apple.launchd.RSSRUXqkGp/Listeners TERM=xterm-256color TERMINFO_DIRS=/Applications/iTerm.app/Contents/Resources/terminfo:/usr/share/terminfo TERM_FEATURES=T3CwLrMSc7UUw9Ts3BFGsSyHNoSxFP TERM_PROGRAM=iTerm.app TERM_PROGRAM_VERSION=3.6.9 TERM_SESSION_ID=w2t0p0:B6627FF4-03D4-4254-8691-E89CC5865893 TIMEFMT='%J %U user %S system %P cpu %E total' TMPDIR=/var/folders/tx/vp1nbzn79q9cn2t1rxdmjlc0000gn/T/ TMPPREFIX=/tmp/zsh integer 10 TRY_BLOCK_ERROR=-1 integer 10 TRY_BLOCK_INTERRUPT=-1 TTY='' integer 10 readonly TTYIDLE=-1 integer 10 UID=501 USER=Yungyu USERNAME=Yungyu VENDOR=apple undefined WATCH WORDCHARS='*?-.[]~=/&;!#$%^(){}<>' XPC_FLAGS=0x0 XPC_SERVICE_NAME=0 ZED_ALLOW_ROOT=true ZSH=/Users/Yungyu/.oh-my-zsh ZSH_ARGZERO=/bin/zsh readonly tied zsh_eval_context ZSH_EVAL_CONTEXT=cmdarg:cmdsubst ZSH_EXECUTION_STRING='python3 /Users/Yungyu/Agent/learning-log/scripts/append_learning_entry.py --source codex --topic "Claude Code 配置来源与启动参数" --insight "--settings 不会替换默认 ~/.claude/settings.json，而是作为单独的 flagSettings 配置层加入合并链，优先级高于 user/project/local。" --insight "--setting-sources 只控制 user、project、local 三类文件来源；flagSettings 和 policySettings 会被源码强制保留，所以把它设为空也不等于完全禁用所有配置。" --insight "状态页里的 Setting sources 显示的是实际读取到且内容非空的 source，不是命令行允许的 source 列表；某个来源缺席，通常说明对应文件不存在、为空或校验失败。" --insight "源码里的 project 专指 .claude/settings.json，而 .claude/settings.local.json 属于 local；因此看到 Project local settings 只说明加载了 local，并不代表存在 project settings。"' ZSH_NAME=zsh ZSH_PATCHLEVEL=zsh-5.9-0-g73d3173 integer 10 readonly ZSH_SUBSHELL=1 ZSH_VERSION=5.9 _=local __CFBundleIdentifier=com.googlecode.iterm2 __CF_USER_TEXT_ENCODING=0x1F5:0:0 undefined aliases array argv=( ) undefined builtins array tied CDPATH cdpath=( ) undefined commands undefined dirstack undefined dis_aliases undefined dis_builtins undefined dis_functions undefined dis_functions_source undefined dis_galiases undefined dis_patchars undefined dis_reswords undefined dis_saliases array tied FIGNORE fignore=( ) array tied FPATH fpath=( /usr/local/share/zsh/site-functions /usr/share/zsh/site-functions /usr/share/zsh/5.9/functions ) undefined funcfiletrace undefined funcsourcetrace undefined funcstack undefined functions undefined functions_source undefined functrace undefined galiases histchars='!^#' undefined history undefined historywords undefined jobdirs undefined jobstates undefined jobtexts undefined keymaps array tied MAILPATH mailpath=( ) array tied MANPATH manpath=( ) array tied MODULE_PATH module_path=( /usr/lib/zsh/5.9 ) undefined modules undefined nameddirs undefined options undefined parameters undefined patchars array tied PATH path=( /Users/Yungyu/.codex/tmp/arg0/codex-arg0icqwPc /Users/Yungyu/Library/pnpm /Users/Yungyu/.krew/bin /Users/Yungyu/.jenv/shims /Users/Yungyu/.nvm/versions/node/v24.13.0/bin /opt/homebrew/bin /opt/homebrew/sbin /Users/Yungyu/.local/bin /opt/homebrew/opt/ruby/bin /Users/Yungyu/.jenv/bin /Users/Yungyu/.go/bin /usr/local/bin /usr/bin /bin /usr/sbin /sbin /var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin /var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin /var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin /usr/local/corplink/mdm/opt/corplink-mdm/bin /Users/Yungyu/.cargo/bin /Applications/iTerm.app/Contents/Resources/utilities '/Users/Yungyu/Library/Application Support/JetBrains/Toolbox/scripts' /Users/Yungyu/.orbstack/bin ) array pipestatus=( 0 ) prompt='' array tied PSVAR psvar=( ) undefined reswords undefined saliases array signals=( EXIT HUP INT QUIT ILL TRAP ABRT EMT FPE KILL BUS SEGV SYS PIPE ALRM TERM URG STOP TSTP CONT CHLD TTIN TTOU IO XCPU XFSZ VTALRM PROF WINCH INFO USR1 USR2 ZERR DEBUG ) integer 10 readonly status=127 undefined termcap undefined terminfo undefined userdirs undefined usergroups undefined watch undefined widgets array readonly tied ZSH_EVAL_CONTEXT zsh_eval_context=( cmdarg cmdsubst ) undefined zsh_scheduled_events 三类文件来源； 和 会被源码强制保留，所以把它设为空也不等于完全禁用所有配置。
  • 状态页里的 显示的是实际读取到且内容非空的 source，不是命令行允许的 source 列表；某个来源缺席，通常说明对应文件不存在、为空或校验失败。
  • 源码里的 专指 ，而 属于 integer 10 readonly !=0 integer 10 readonly '#'=0 integer 10 readonly '$'=64122 array readonly ''=( ) readonly -=569X 0=/bin/zsh integer 10 readonly '?'=127 array readonly @=( ) integer 10 readonly ARGC=0 tied cdpath CDPATH='' CODEX_CI=1 CODEX_SANDBOX=seatbelt CODEX_SANDBOX_NETWORK_DISABLED=1 CODEX_THREAD_ID=019daad6-7a68-7101-8cad-42cf4aef5e0e COLORFGBG='15;0' COLORTERM=truecolor integer 10 COLUMNS=0 COMMAND_MODE=unix2003 CPUTYPE=arm64 integer 10 EGID=20 integer 10 EUID=501 tied fignore FIGNORE='' tied fpath FPATH=/usr/local/share/zsh/site-functions:/usr/share/zsh/site-functions:/usr/share/zsh/5.9/functions integer 10 FUNCNEST=700 GH_PAGER=cat integer 10 GID=20 GIT_PAGER=cat GOOGLE_CLOUD_PROJECT=soy-reporter-269419 HISTCHARS='!^#' integer 10 readonly HISTCMD=0 integer 10 HISTSIZE=30 HOME=/Users/Yungyu HOMEBREW_API_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles HOMEBREW_BREW_GIT_REMOTE=https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git HOMEBREW_CELLAR=/opt/homebrew/Cellar HOMEBREW_CORE_GIT_REMOTE=https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git HOMEBREW_PREFIX=/opt/homebrew HOMEBREW_REPOSITORY=/opt/homebrew HOST=Yungyu-Mac.local IFS=$' \t\n\C-@' INFOPATH=/opt/homebrew/share/info:/opt/homebrew/share/info: ITERM_INJECT_SHELL_INTEGRATION=1 ITERM_PROFILE=Home ITERM_SESSION_ID=w2t0p0:B6627FF4-03D4-4254-8691-E89CC5865893 JAVA_HOME=/Users/Yungyu/.jenv/versions/8 JAVA_TOOL_OPTIONS='-DJM.LOG.PATH=/tmp -DJM.SNAPSHOT.PATH=/tmp' JDK_HOME=/Users/Yungyu/.jenv/versions/8 JENV_FORCEJAVAHOME=true JENV_FORCEJDKHOME=true JENV_LOADED=1 JENV_SHELL=zsh KEYBOARD_HACK='' integer KEYTIMEOUT=40 KUBE_EDITOR='code --wait' LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 LC_CTYPE=C.UTF-8 LC_TERMINAL=iTerm2 LC_TERMINAL_VERSION=3.6.9 LESS=-R integer 10 readonly LINENO=1 integer 10 LINES=0 integer LISTMAX=100 LOGNAME=Yungyu LSCOLORS=Gxfxcxdxbxegedabagacad LS_COLORS='di=1;36:ln=35:so=32:pi=33:ex=31:bd=34;46:cd=34;43:su=30;41:sg=30;46:tw=30;42:ow=30;43' LaunchInstanceID=9D1A24E1-6341-4010-B393-AF09863F3F78 MACHTYPE=x86_64 integer MAILCHECK=60 tied mailpath MAILPATH='' tied manpath MANPATH='' tied module_path MODULE_PATH=/usr/lib/zsh/5.9 NO_COLOR=1 NULLCMD=cat NVM_BIN=/Users/Yungyu/.nvm/versions/node/v24.13.0/bin NVM_CD_FLAGS=-q NVM_DIR=/Users/Yungyu/.nvm NVM_INC=/Users/Yungyu/.nvm/versions/node/v24.13.0/include/node OLDPWD=/Users/Yungyu/Agent OPTARG='' integer 10 OPTIND=1 OSTYPE=darwin24.0 PAGER=less tied path PATH='/Users/Yungyu/.codex/tmp/arg0/codex-arg0icqwPc:/Users/Yungyu/Library/pnpm:/Users/Yungyu/.krew/bin:/Users/Yungyu/.jenv/shims:/Users/Yungyu/.nvm/versions/node/v24.13.0/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/Users/Yungyu/.local/bin:/opt/homebrew/opt/ruby/bin:/Users/Yungyu/.jenv/bin:/Users/Yungyu/.go/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin:/usr/local/corplink/mdm/opt/corplink-mdm/bin:/Users/Yungyu/.cargo/bin:/Applications/iTerm.app/Contents/Resources/utilities:/Users/Yungyu/Library/Application Support/JetBrains/Toolbox/scripts:/Users/Yungyu/.orbstack/bin' PNPM_HOME=/Users/Yungyu/Library/pnpm integer 10 readonly PPID=67468 PROMPT='' PROMPT2='' PROMPT3='?# ' PROMPT4='+%N:%i> ' PS1='' PS2='' PS3='?# ' PS4='+%N:%i> ' tied psvar PSVAR='' PWD=/Users/Yungyu/Agent integer 10 RANDOM=23721 READNULLCMD=more integer 10 SAVEHIST=0 integer 10 SECONDS=0 SECURITYSESSIONID=186a2 SHELL=/bin/zsh integer 10 SHLVL=1 SPROMPT='zsh: correct '\''%R'\'' to '\''%r'\'' [nyae]? ' SSH_AUTH_SOCK=/private/tmp/com.apple.launchd.RSSRUXqkGp/Listeners TERM=xterm-256color TERMINFO_DIRS=/Applications/iTerm.app/Contents/Resources/terminfo:/usr/share/terminfo TERM_FEATURES=T3CwLrMSc7UUw9Ts3BFGsSyHNoSxFP TERM_PROGRAM=iTerm.app TERM_PROGRAM_VERSION=3.6.9 TERM_SESSION_ID=w2t0p0:B6627FF4-03D4-4254-8691-E89CC5865893 TIMEFMT='%J %U user %S system %P cpu %E total' TMPDIR=/var/folders/tx/vp1nbzn79q9cn2t1rxdmjlc0000gn/T/ TMPPREFIX=/tmp/zsh integer 10 TRY_BLOCK_ERROR=-1 integer 10 TRY_BLOCK_INTERRUPT=-1 TTY='' integer 10 readonly TTYIDLE=-1 integer 10 UID=501 USER=Yungyu USERNAME=Yungyu VENDOR=apple undefined WATCH WORDCHARS='*?-.[]~=/&;!#$%^(){}<>' XPC_FLAGS=0x0 XPC_SERVICE_NAME=0 ZED_ALLOW_ROOT=true ZSH=/Users/Yungyu/.oh-my-zsh ZSH_ARGZERO=/bin/zsh readonly tied zsh_eval_context ZSH_EVAL_CONTEXT=cmdarg:cmdsubst ZSH_EXECUTION_STRING='python3 /Users/Yungyu/Agent/learning-log/scripts/append_learning_entry.py --source codex --topic "Claude Code 配置来源与启动参数" --insight "--settings 不会替换默认 ~/.claude/settings.json，而是作为单独的 flagSettings 配置层加入合并链，优先级高于 user/project/local。" --insight "--setting-sources 只控制 user、project、local 三类文件来源；flagSettings 和 policySettings 会被源码强制保留，所以把它设为空也不等于完全禁用所有配置。" --insight "状态页里的 Setting sources 显示的是实际读取到且内容非空的 source，不是命令行允许的 source 列表；某个来源缺席，通常说明对应文件不存在、为空或校验失败。" --insight "源码里的 project 专指 .claude/settings.json，而 .claude/settings.local.json 属于 local；因此看到 Project local settings 只说明加载了 local，并不代表存在 project settings。"' ZSH_NAME=zsh ZSH_PATCHLEVEL=zsh-5.9-0-g73d3173 integer 10 readonly ZSH_SUBSHELL=1 ZSH_VERSION=5.9 _=local __CFBundleIdentifier=com.googlecode.iterm2 __CF_USER_TEXT_ENCODING=0x1F5:0:0 undefined aliases array argv=( ) undefined builtins array tied CDPATH cdpath=( ) undefined commands undefined dirstack undefined dis_aliases undefined dis_builtins undefined dis_functions undefined dis_functions_source undefined dis_galiases undefined dis_patchars undefined dis_reswords undefined dis_saliases array tied FIGNORE fignore=( ) array tied FPATH fpath=( /usr/local/share/zsh/site-functions /usr/share/zsh/site-functions /usr/share/zsh/5.9/functions ) undefined funcfiletrace undefined funcsourcetrace undefined funcstack undefined functions undefined functions_source undefined functrace undefined galiases histchars='!^#' undefined history undefined historywords undefined jobdirs undefined jobstates undefined jobtexts undefined keymaps array tied MAILPATH mailpath=( ) array tied MANPATH manpath=( ) array tied MODULE_PATH module_path=( /usr/lib/zsh/5.9 ) undefined modules undefined nameddirs undefined options undefined parameters undefined patchars array tied PATH path=( /Users/Yungyu/.codex/tmp/arg0/codex-arg0icqwPc /Users/Yungyu/Library/pnpm /Users/Yungyu/.krew/bin /Users/Yungyu/.jenv/shims /Users/Yungyu/.nvm/versions/node/v24.13.0/bin /opt/homebrew/bin /opt/homebrew/sbin /Users/Yungyu/.local/bin /opt/homebrew/opt/ruby/bin /Users/Yungyu/.jenv/bin /Users/Yungyu/.go/bin /usr/local/bin /usr/bin /bin /usr/sbin /sbin /var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin /var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin /var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin /usr/local/corplink/mdm/opt/corplink-mdm/bin /Users/Yungyu/.cargo/bin /Applications/iTerm.app/Contents/Resources/utilities '/Users/Yungyu/Library/Application Support/JetBrains/Toolbox/scripts' /Users/Yungyu/.orbstack/bin ) array pipestatus=( 0 ) prompt='' array tied PSVAR psvar=( ) undefined reswords undefined saliases array signals=( EXIT HUP INT QUIT ILL TRAP ABRT EMT FPE KILL BUS SEGV SYS PIPE ALRM TERM URG STOP TSTP CONT CHLD TTIN TTOU IO XCPU XFSZ VTALRM PROF WINCH INFO USR1 USR2 ZERR DEBUG ) integer 10 readonly status=127 undefined termcap undefined terminfo undefined userdirs undefined usergroups undefined watch undefined widgets array readonly tied ZSH_EVAL_CONTEXT zsh_eval_context=( cmdarg cmdsubst ) undefined zsh_scheduled_events；因此看到 只说明加载了 local，并不代表存在 project settings。
  • 参数 --settings 不会替换默认的用户配置文件，而是作为 flagSettings 配置层加入合并链，优先级高于 user、project、local。
  • 参数 --setting-sources 只控制 user、project、local 三类文件来源；flagSettings 和 policySettings 在源码里会被强制保留。
  • 状态页里的 Setting sources 显示的是实际读取到且内容非空的来源，不是命令行允许的来源列表。
  • 源码里的 project 专指 .claude/settings.json，而 .claude/settings.local.json 属于 local；看到 Project local settings 只说明 local 被加载。

TypeScript shim 与三方组件类型错配

  • 当三方组件运行时实际接受 string，但 .d.ts 声明要求 UserInfo 时，报错根因是实现与类型声明不一致，而不是业务表单模型一定错误。
  • 判断是否可以用 shim，关键不是能不能强转，而是先核对运行时代码；只有确认组件真实使用的 value 就是字符串时，本地兼容层才是在修正错误声明，而不是掩盖真实 bug。
  • shim 之所以能解决问题，是因为它不改变运行时逻辑，只重写 TypeScript 看到的组件签名，让类型系统与真实行为重新对齐。
  • 排查这类问题要分清两层：运行时吃什么值，TypeScript 以为它吃什么值。只有这两层分离开，才能判断该改业务代码，还是该修库类型或加本地适配层。

Tailwind v4 的 @theme 机制

  • Tailwind v4 中，@import "tailwindcss"; 是框架入口写法，用来引入 Tailwind 本身；没有它，@theme、@layer、@apply 以及相关工具类都不会生效。
  • @theme 不是普通样式块，而是向 Tailwind 注册设计 token 的声明区；只有放在约定命名空间下的变量，例如 --color-、--spacing-、--breakpoint-*，才会转换成可用的工具类或变体。
  • 项目里把 --foreground 这类业务 CSS 变量映射为 --color-foreground，本质上是在把自定义主题体系接入 Tailwind 的命名体系，因此后续才能使用 text-foreground、bg-background 这类类名。
  • @theme inline 适合右侧直接引用现有 CSS 变量的场景，它会让 Tailwind 生成的工具类直接使用这些值，减少中间变量层级，更适合已有主题变量体系的项目。

Tailwind v3 与 v4 的主题配置映射

  • 可以把 Tailwind v4 的 @theme 理解为把 v3 的 theme.extend 从 JavaScript 对象改写成有命名空间的 CSS 变量声明；核心职责没变，都是向 Tailwind 注册设计 token。
  • v3 中 theme.extend.colors.background = "var(--background)" 这类写法，在 v4 中对应为 --color-background: var(--background)；本质上仍是在注册 background 这个颜色 token，只是注册介质从 JS 变成了 CSS。
  • v3 的常见配置项与 v4 命名空间存在稳定映射关系，例如 colors 对应 --color-，fontFamily 对应 --font-，borderRadius 对应 --radius-，screens 对应 --breakpoint-。
  • 不是整个 tailwind.config.js 都会迁移到 @theme；只有 theme 或 extend 里的设计 token 适合这样迁移，而 content 这类配置在 v4 中属于自动检测或 @source 的职责。

飞书画板 DSL + OpenAPI + Yoga 引擎原理

  • 飞书画板的完整链路：DSL JSON → @larksuite/whiteboard-cli 编译（Yoga 布局计算 + 格式转换）→ lark-cli POST 到飞书 OpenAPI。布局计算在客户端完成，飞书服务端只接收算好坐标的节点。
  • Yoga 是 Meta 开源的跨平台 Flexbox 布局引擎（C 实现），whiteboard-cli 用 Yoga JS binding 做布局计算。DSL 的 layout: 'vertical'、gap、fit-content 等语义被 Yoga 编译成精确的 x、y、width、height。
  • DSL 是声明式的（不用写坐标），OpenAPI 格式是精确的（每个节点必须有 x、y 坐标和像素尺寸）。两者差异：rect → composite_shape/round_rect、borderWidth: 2 → border_width: 'narrow'、fit-content → 45px 等。
  • lark-cli 本身没有 whiteboard 服务，画板操作通过 lark-cli docs +whiteboard-update 完成。whiteboard-cli 负责渲染（PNG）和格式转换（--to openapi），两者职责不同但可管道串联。
  • Java 调飞书画板 OpenAPI 有三种方案：1) ProcessBuilder 调 whiteboard-cli 最简单；2) 手算坐标直接写 OpenAPI JSON 适合简单图；3) Java 集成 Yoga binding + 自己转格式最完整也最复杂。