1. 项目概述：为你的AI助手注入灵魂

如果你和我一样，是Claude Code的深度用户，每天都要和它进行大量的代码对话，那你一定对那个千篇一律的“Thinking...”提示符感到审美疲劳了。它就像一个永远面无表情的助手，无论你是深夜debug的焦头烂额，还是清晨灵光一现的兴奋，它都只会用同一个词告诉你：我在想。

这太无趣了。代码世界本应是充满创造力和个性的，为什么我们的AI伙伴不能更有“人味儿”一点？这就是我开发 Thinking Words 这个Claude Code技能插件的初衷。它不是一个复杂的开发工具，而是一个纯粹的“氛围组”神器，一个能让你在枯燥的编码过程中会心一笑的小玩意儿。

简单来说， Thinking Words 是一个专门用于切换Claude Code界面中“思考中”提示词（官方称之为 spinnerVerbs ）的工具。它内置了11种风格迥异的预设词组库，从“静思中、煮茶中”的古风雅韵，到“神经元同步中、数据流分析中”的赛博朋克，再到“debug中、祈祷中”的程序员自嘲梗，应有尽有。你不仅可以一键切换，还能创建自己的专属词库，甚至让它根据一天中的不同时段自动变换风格。

想象一下：早晨开工，你的Claude Code显示“晨思中、醒脑中”；下午茶时间，它变成“下午茶中、小憩中”；深夜赶工，它又切换为“夜思中、沉思中”。这种微小的、个性化的互动，能极大地提升你与AI协作时的愉悦感和沉浸感。它解决的，正是工具人性化体验中那个最容易被忽略，却又最能触动人的细节。

无论你是追求效率的极客，还是喜欢折腾的“美化党”，这个工具都能让你的开发环境瞬间变得与众不同。接下来，我将带你从零开始，深入拆解这个项目的设计思路、实现细节，并分享我在开发和长期使用中积累的所有实战经验与避坑指南。

2. 核心设计思路与架构解析

2.1 为什么是“思考词组”？

在深入代码之前，我们首先要理解Claude Code的技能机制和 spinnerVerbs 这个配置项的本质。Claude Code允许用户通过技能（Skills）来扩展其功能，技能本质上是一个遵循特定格式的Markdown文档（ SKILL.md ），其中可以定义命令、配置和交互逻辑。

spinnerVerbs 是Claude Code主配置文件（ ~/.claude/settings.json ）中的一个数组字段，它定义了AI在“思考”（即处理你的请求并生成回复）过程中，界面底部那个动态旋转的提示文字会随机显示哪些词语。默认值通常是 ["Thinking..."] 或 ["思考中..."] 这样的单一词组。

设计的核心挑战在于： 如何在不侵入Claude Code核心进程、不修改其源代码的前提下，动态、安全、便捷地修改这个配置项？我的设计目标很明确：

1. 无侵入性 ：必须作为一个纯外部技能运行，通过官方提供的配置接口操作。
2. 用户友好 ：提供多种安装和使用方式，覆盖从命令行高手到普通用户的所有场景。
3. 功能丰富 ：不仅仅是替换几个词，要提供预设、自定义、统计、自动化等进阶功能。
4. 数据持久化 ：用户的个性化配置（自定义词组、使用记录、自动切换规则）必须能安全保存和迁移。

基于这些目标，我选择了Node.js作为实现语言，因为它能很好地处理JSON文件操作、命令行交互，并且拥有庞大的生态系统，便于通过npm分发。

2.2 项目架构与模块划分

为了让项目清晰可维护，我将功能逻辑拆分到了几个核心模块中，目录结构如下：

thinking-words/
├── SKILL.md              # Claude Code技能入口文件
├── index.mjs             # 命令行主入口（CommonJS/ESM双模式）
├── src/
│   ├── presets.js        # 所有内置预设词库的定义
│   ├── commands.js       # 所有命令（list, add, mix等）的实现逻辑
│   ├── config.js         # 负责读写Claude配置和插件自身配置
│   └── utils.js          # 通用工具函数（如时间判断、随机选择）
├── package.json          # 项目元数据和npm脚本
└── examples/             # 示例配置文件

各模块职责解析：

• SKILL.md ：这是Claude Code技能的“门面”。它定义了用户如何在Claude Code界面内通过 /thinking-words 命令来调用我们的工具。其内部逻辑很简单：调用系统命令执行本工具的CLI。这实现了在Claude Code内部和外部的无缝调用体验。
• index.mjs ：作为命令行入口，它使用 mjs 扩展名以支持ES模块。它负责解析用户输入的命令行参数（如 wuxia , list ），然后将控制权交给 commands.js 中对应的处理函数。
• src/presets.js ：这是项目的“灵魂”所在，一个巨大的JSON对象，定义了所有内置预设。每个预设都是一个键值对，键名是预设ID（如 wuxia ），值是一个字符串数组，包含该风格下的所有思考词组。我花费了大量时间搜集和创作这些词组，确保它们既符合主题意境，又不会过于冗长影响阅读。
• src/commands.js ：这是“大脑”，包含了所有命令的业务逻辑。例如， list 命令负责格式化输出所有预设； add 命令负责验证用户输入并将新预设写入配置文件； mix 命令需要合并多个预设的词组并去重。
• src/config.js ：这是“双手”，负责所有IO操作。它需要做两件事：
  1. 读写Claude Code的 settings.json ，找到并修改 spinnerVerbs 字段。
  2. 管理插件自身的多个配置文件（如用户预设、使用统计、自动切换规则）。这里的关键是 错误处理 ，比如目标配置文件不存在、JSON格式损坏、权限不足等情况，都必须有优雅的降级方案。

这种架构分离了数据（presets）、逻辑（commands）和IO（config），使得代码测试、维护和功能扩展变得非常清晰。

2.3 配置文件策略：安全与兼容性

操作Claude Code的配置文件需要格外小心。一个错误的写入可能导致Claude Code无法启动。因此，在 config.js 中，我采用了以下策略：

1. 读取时备份 ：在修改 settings.json 前，先在内存中保留一份完整拷贝，并尝试在临时目录创建一个备份文件（如 settings.json.bak ）。
2. 原子化写入 ：不使用简单的 JSON.stringify 后覆盖写入。而是先将新的JSON内容写入一个临时文件（如 settings.json.tmp ），写入成功后再用重命名（ fs.rename ）操作替换原文件。这可以防止在写入过程中发生断电或崩溃导致配置文件损坏。
3. 格式保留 ：使用 JSON.stringify(data, null, 2) 进行格式化，确保生成的JSON文件具有良好的可读性，缩进与Claude Code原文件保持一致。
4. 自身配置隔离 ：插件的用户数据（自定义预设、统计等）完全存储在独立的文件（如 spinner-presets.json ）中，与Claude Code主配置隔离，避免污染和冲突。

踩坑实录：配置文件权限问题 在Linux和macOS上， ~/.claude/ 目录的权限可能很严格。最初版本中，当以非所有者用户运行或目录权限为755时，写入会失败。解决方案是在代码中增加了更详细的错误提示，引导用户检查目录权限，并提供了 --config-path 参数（虽然最终没暴露给基础用户）让高级用户可以指定备用配置路径。对于绝大多数用户，确保 ~/.claude/ 目录存在且有写入权限即可。

3. 核心功能实现与使用详解

3.1 多种安装方式的背后考量

我提供了三种安装方式，是为了覆盖不同用户的使用习惯和技术背景：

方式一：手动复制（最简单）

cp thinking-words/SKILL.md ~/.claude/skills/thinking-words/

这种方式最直接，适合任何用户。你只需要把项目的 SKILL.md 文件放到Claude Code的技能目录下即可。Claude Code会自动加载该目录下的所有技能。我 更推荐使用软链接 ，这样当你在本地更新项目代码时，Claude Code能立即生效，无需再次复制。

ln -s $(pwd)/thinking-words/SKILL.md ~/.claude/skills/thinking-words.md

方式二：使用NPX（无需安装）

npx thinking-words@latest wuxia

这是现代Node.js生态中最优雅的方式之一。 npx 会临时下载并运行指定版本的包，运行完毕后清理。对于只是想尝鲜或者偶尔使用的用户来说，零安装负担，体验最佳。我在 package.json 中正确配置了 bin 字段，使得 npx 可以直接调用。

方式三：全局安装CLI

cd thinking-words
npm install -g .

适合重度用户。全局安装后，你可以在系统的任何终端窗口直接使用 thinking-words 命令，无需关心当前工作目录。这对于想要集成到其他脚本或自动化流程中的用户非常方便。

实操心得： package.json 中的关键配置 为了让这三种方式都能工作， package.json 的配置至关重要：

• "bin": { "thinking-words": "./index.mjs" } : 这定义了全局命令 thinking-words 指向的入口文件。
• "files": ["SKILL.md", "index.mjs", "src/", "package.json"] : 定义了发布到npm时包含哪些文件，确保用户安装后所有必要文件都在。
• "engines": { "node": ">=18" } : 声明了所需的Node.js版本，避免低版本用户遇到不支持的语法（如ES模块）问题。

3.2 内置预设的艺术：如何打造有灵魂的词组

内置预设是吸引用户的第一步。我并没有随意堆砌词汇，而是为每种风格构建了独特的“词库宇宙”。

以 wuxia （武侠） 预设为例，它的词组不仅仅是“思考”的变体，而是试图构建一个完整的武侠叙事场景：

• 修炼视角 ：悟道中、参禅中、练气中、运功中。
• 行动视角 ：御剑中、踏雪中、寻踪中、破阵中。
• 意境视角 ：对弈中、听雨中、观云中、抚琴中。

再比如 cyberpunk （赛博朋克） 预设：

• 硬件层面 ：神经元同步中、义体校准中、芯片超频中。
• 数据层面 ：数据流分析中、矩阵解密中、防火墙渗透中。
• 意识层面 ：意识上传中、记忆检索中、幻境构建中。

设计原则：

1. 一致性 ：所有词组必须服务于同一个核心主题。
2. 简洁性 ：长度控制在2-4个汉字或3-6个英文单词，确保在Claude Code的UI中显示完整。
3. 动态感 ：使用“中”、“ing”等后缀，或具有进行时态意味的词汇，贴合“正在思考”的状态。
4. 趣味性 ：适当玩梗，如程序员预设中的“debug中、祈祷中、面向Stack Overflow编程中”。

用户可以通过 /thinking-words list 命令完整查看所有预设及其示例，快速找到自己的心头好。

3.3 自定义与混合：打造你的专属词库

内置预设再好，也比不上自己创造的独特。 add 和 mix 命令赋予了用户无限的创造力。

添加自定义预设 ( add )

/thinking-words add my-cat “喵喵思考中” “爪子敲键盘中” “打翻水杯前思考中”

这个命令会创建一个名为 my-cat 的新预设，并将这三个词组保存到 ~/.claude/spinner-presets.json 文件中。之后，你就可以像使用内置预设一样使用它： /thinking-words my-cat 。

技术细节：

• 命令会检查预设名是否已存在，避免覆盖。
• 会对输入词组进行简单的去空格和去重处理。
• 新增的预设会立即持久化，并同步到Claude Code的配置中（如果你在添加后执行了切换）。

混合多个预设 ( mix ) 这是我最喜欢的功能之一。它允许你将多个预设的词组合并成一个新的、更丰富的列表。

/thinking-words mix classical cyberpunk

这条命令会将“古风”和“赛博朋克”两个预设的所有词组合并、去重，然后立即应用。想象一下，“煮茶中”和“神经元同步中”交替出现，有种奇妙的穿越感和幽默感。混合后的结果并不会保存为一个新的预设，而是直接生效。如果你喜欢这个混合结果，可以用 add 命令将其保存下来。

注意事项：词组数量与性能 Claude Code的 spinnerVerbs 数组理论上可以很长，但经过测试，当数组元素超过500个时，UI轮播可能会稍有卡顿（尽管不影响核心功能）。因此，在 mix 命令的逻辑中，我虽然不做强制数量限制，但会在命令行给出一个友好提示：“当前混合词组共XX个，若感觉动画不流畅，可考虑精简。” 一般来说，100-200个词组是体验最佳的范围。

3.4 智能功能：统计、推荐与自动切换

为了让工具更有“智能感”，我加入了数据驱动的小功能。

使用统计 ( stats ) 每次用户切换预设，插件都会在 ~/.claude/thinking-words-stats.json 中记录一条日志，格式为 { preset: ‘wuxia‘, timestamp: 1743321600000 } 。 /thinking-words stats 命令会分析这些日志，计算出：

• 总切换次数
• 最常使用的预设 （Top 3）
• 最近一周的使用趋势

这不仅能满足用户的好奇心，也为“智能推荐”提供了数据基础。

智能推荐 ( recommend ) 这个命令的逻辑很简单，但效果不错：

1. 读取使用统计。
2. 找出用户 最不常用 的2-3个内置预设。
3. 随机选择一个推荐给用户，并附带一句推荐语，如：“你好像很少用‘赛博朋克’风格，要不要试试看‘神经元同步中’的感觉？” 这个设计的目的是鼓励用户探索和尝试不同的预设，打破使用习惯。

时间感知自动切换 ( auto ) 这是实现“氛围感”的终极功能。通过 /thinking-words auto on 开启后，插件会结合 thinking-words-auto.json 中的配置和当前系统时间，自动切换预设。

# 配置不同时段的预设
/thinking-words auto set morning simple    # 早晨用简洁风
/thinking-words auto set afternoon cute    # 下午用可爱风
/thinking-words auto set night cyberpunk  # 深夜用赛博风

其核心实现逻辑在 utils.js 的 getTimeBasedPreset 函数中：

1. 获取当前系统时间的小时数。
2. 根据预设规则（如6-12点为早晨）匹配时间段。
3. 返回该时间段配置的预设名称，如果未配置则返回 default 。
4. 当用户执行任何命令，或通过系统定时任务（如cron）触发时，如果自动切换已开启，则调用此函数获取应切换的预设并执行切换。

实操心得：实现“无感”自动切换 最初的设想是做一个常驻后台进程来定时切换，但这增加了复杂性，且可能带来资源占用和权限问题。现在的方案更巧妙： 利用现有触发点 。

1. 主动触发 ：用户每次运行 /thinking-words 命令（包括无参数随机切换）时，都会检查自动切换是否开启，如果是，则先根据时间执行一次自动切换。
2. 被动触发（推荐） ：在 SKILL.md 中，我引导用户设置一个系统的定时任务（cron job），例如每小时的0分运行一次 npx thinking-words@latest auto-check （这是一个隐藏的维护命令）。这样就能实现真正的全自动、无感知切换。这种“事件驱动+定时补偿”的混合模式，在简单性和可靠性之间取得了很好的平衡。

4. 高级技巧、问题排查与生态展望

4.1 开发者指南：参与贡献与自定义开发

这个项目是完全开源的，如果你有新的创意，欢迎深度参与。

如何添加一个新的内置预设？

1. 打开 src/presets.js 文件。
2. 在 PRESETS 对象中添加一个新的键值对，例如：

   const PRESETS = {
     // ... 其他预设
     scifi: [
       “曲率引擎预热中“,
       “跃迁坐标计算中“,
       “与地外文明通讯中“,
       “扫描未知星域中“,
     ]
   };
   

3. 确保你的词组数组长度适中（建议8-20个），风格统一。
4. 提交Pull Request。一个好的PR应该包含：清晰的预设名称、符合主题的词组、以及更新后的 README.md 中的预设列表。

如何修改现有预设的词组？ 同样在 src/presets.js 中直接修改对应的数组即可。但请注意，修改内置预设会影响所有用户。如果你只是想自己用，强烈建议使用 add 命令创建自定义预设，这样在项目更新时不会覆盖你的修改。

本地开发与测试 克隆项目后，你可以直接运行 node index.mjs [command] 进行测试。为了不污染你的真实Claude配置，我建议在测试时通过环境变量指定一个临时的配置目录：

export CLAUDE_CONFIG_DIR=”/tmp/test-claude-config“
node index.mjs wuxia

这样，所有配置操作都会发生在 /tmp/test-claude-config 目录下，与你的真实环境隔离。

4.2 常见问题排查（Q&A）

在实际使用中，你可能会遇到以下问题，这里提供完整的排查思路：

Q1: 运行命令后，Claude Code界面上的提示词没有变化？ A1: 这是最常见的问题。请按以下步骤排查：

1. 确认Claude Code已重启 ：技能配置修改后，需要重启Claude Code桌面应用才能生效。请完全退出并重新启动。
2. 检查配置文件路径 ：确保 ~/.claude/settings.json 文件存在且可写。可以手动打开该文件，查看 spinnerVerbs 字段是否已被修改。
3. 检查技能安装 ：确认 SKILL.md 文件已正确放置在 ~/.claude/skills/ 目录下，并且文件名无误。可以在Claude Code中输入 /help 查看技能列表里是否有 thinking-words 。
4. 查看命令输出 ：运行命令时，工具会打印日志。如果看到 “Configuration updated successfully” 则表示配置写入成功。如果看到权限错误，请检查 ~/.claude/ 目录的权限（应为 755 且所属用户正确）。

Q2: 使用 npx 安装或运行时网络很慢或失败？ A2: npx 需要从npm仓库下载包。如果网络不畅：

• 可以尝试使用 --registry 参数指定国内镜像，如 npx --registry=https://registry.npmmirror.com thinking-words@latest list 。
• 或者，直接采用“方式一：手动复制”，这是完全离线的。

Q3: 自定义预设不见了？ A3: 自定义预设存储在 ~/.claude/spinner-presets.json 。如果文件被误删或损坏，预设会丢失。请养成定期使用 /thinking-words export 命令备份配置的习惯。如果文件损坏，可以尝试删除该文件，然后重新添加预设。

Q4: 自动切换功能不工作？ A4: 首先用 /thinking-words auto 检查自动切换是否已开启和配置是否正确。然后，确认你理解其工作原理：它不是在后台持续运行的，而是在 每次你手动运行 /thinking-words 命令时 ，或 通过系统cron定时触发 时才会执行切换。如果你一整天没运行过任何命令，它自然不会切换。设置一个每小时运行的cron job是最可靠的方案。

Q5: 我想恢复成Claude Code最初的样子？ A5: 非常简单，运行 /thinking-words default 即可切换回原始的英文“Thinking...”词组。或者，你也可以手动编辑 ~/.claude/settings.json ，将 spinnerVerbs 字段改为 [“Thinking...“] 。

4.3 安全与隐私说明

这是一个纯本地化、无网络请求的工具，所有操作都在你的计算机上完成。

• 数据存储 ：所有配置、统计信息都仅保存在你本地 ~/.claude/ 目录下的JSON文件中。
• 无数据上传 ：工具不会收集或上传你的任何使用数据、预设内容或系统信息。
• 权限需求 ：只需要读写 ~/.claude/ 目录的权限，用于管理配置文件。

4.4 未来可能的扩展方向

虽然当前版本功能已经比较完善，但社区的力量是无穷的。这里抛砖引玉，列出几个我想到的、或有用户提议的扩展方向：

1. 动态词组生成 ：结合简单的模板或AI（本地小模型），根据当前项目语言（如检测到 package.json 则用Node.js梗）、天气、甚至系统负载动态生成思考词组。
2. 可视化配置界面 ：为不习惯命令行的用户开发一个简单的图形化界面（可能是基于Tauri或Electron的小应用），通过点击和拖拽来管理预设和配置自动切换。
3. 词组市场/分享 ：建立一个简单的在线平台（或通过Gist），让用户可以上传、分享和下载他人创作的有趣预设包。
4. 深度集成 ：探索能否通过Claude Code更底层的API，实现更动态的交互，例如思考词组的显示速度与系统CPU使用率关联，或者当代码编译出错时，显示特定的沮丧系词组。

这个项目的魅力在于它很小，但想象空间很大。它证明了，即使是在一个非常细分的点上，通过精心的设计和对用户体验的洞察，也能创造出让人愉悦的工具。