1. 项目概述与核心价值

如果你和我一样，深度依赖像 Cursor 或 Windsurf 这类 AI 驱动的 IDE 进行开发，那你肯定遇到过这个痛点：每次切换项目，或者想尝试不同的 AI 助手角色（比如从“代码审查专家”切换到“架构设计顾问”），都得手动去改那个藏在配置文件里的提示词（Prompt）。更别提管理多个全局的、项目级的提示词有多混乱了。我之前的状态就是，桌面上散落着各种 prompt_for_code_review.txt 、 project_x_rules.md ，每次用的时候还得复制粘贴，效率低下不说，还容易出错。

直到我动手做了 Oh My Prompt 这个 VSCode 插件，才真正把这件事理顺了。简单来说，它就是一个专为 AI IDE 设计的、下一代提示词管理系统。它的核心价值，就是让你能像管理代码依赖一样，优雅地管理你的 AI 助手“人格”和“工作上下文”。你可以把它想象成 nvm （Node 版本管理器）之于 Node.js，或者 pyenv 之于 Python，但它是专门管 Prompt 的。

这个工具特别适合两类人：一是重度使用 Cursor/Windsurf 等工具的开发者，希望提升 AI 协作效率；二是团队技术负责人，需要为不同项目统一配置 AI 助手的行为规范，确保代码风格和质量的一致性。通过状态栏实时显示、一键切换和基于文件的同步机制，它把原本繁琐、隐性的 Prompt 管理，变成了一个可视、可控、可复用的工作流。

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

2.1 为什么选择“全局”与“项目”双模式？

在设计之初，我深入思考了开发者在不同场景下的需求差异，这直接决定了双模式架构。

全局提示词 对应的是你个人的、跨所有项目的通用偏好和角色设定。比如，我习惯让 AI 助手在写代码时优先考虑性能，注释写详细点，并且用英文变量名。这个设定不应该因为我从 A 项目切换到 B 项目而改变。它存储在用户主目录（如 ~/.neurora/oh-my-prompt ）下，跟随你的开发环境走。

项目提示词 则绑定到具体的代码仓库。不同的项目有不同的技术栈、代码规范和协作要求。例如，一个 React 前端项目可能要求组件使用函数式写法并遵循特定的 Props 接口规范；而一个 Go 后端项目则可能强调错误处理、并发模式和单元测试覆盖率。把这些规则写在项目级的 Prompt 里，并让插件自动应用，能确保 AI 助手生成的代码从一开始就符合项目要求，省去大量后期调整的功夫。

这种分离的设计，完美解决了“个人习惯”与“项目约束”之间的平衡问题。你可以拥有一个“严厉的代码审查员”作为全局角色，同时为某个快速原型项目临时切换到一个“创意实现者”的宽松模式，互不干扰。

2.2 同步机制：连接抽象仓库与具体 IDE

这是 Oh My Prompt 最精妙的部分，也是稳定性的关键。我设计了一个双向同步的“桥梁”架构。

核心思想是“单一事实来源” 。插件内部维护一个结构化的 Prompt 仓库（Store），所有 Prompt 的元数据（名称、描述、类型等）和内容都规整地存放在这里，格式是 TOML。这个仓库是你的“指挥中心”。

而 Cursor、Windsurf 这些 IDE，它们只认自己特定路径下的规则文件（比如 Windsurf 的 ~/.windsurf/global_prompt 或项目根目录的 .windsurfrules ）。这些文件通常是纯文本。

因此，同步流程是这样的：

1. 导出（Apply） ：当你在 Oh My Prompt 中选择激活某个全局 Prompt 时，插件会读取 TOML 中的 content 字段，将其内容写入到 IDE 预期的全局配置文件路径中。对于项目 Prompt，则写入（或创建）项目根目录下的 .windsurfrules 或 .cursorrules 文件。
2. 导入（Save） ：反之，如果你直接在 IDE 的配置界面里修改了 Prompt 文本，Oh My Prompt 的状态栏监控到文件变化后，可以提示你将更改保存回自己的结构化仓库，并更新对应的 TOML 元数据。

这个机制的好处是“非侵入式”。插件并不强行接管 IDE 的配置，而是作为一個智能的同步层和增强管理界面。即使插件暂时失效，IDE 依然能读取它最后写入的规则文件正常工作，保证了可用性。

2.3 为什么选用 TOML 作为存储格式？

在 JSON、YAML 和 TOML 之间，我最终选择了 TOML。原因很实际：

• 可读性优于 JSON ：TOML 的格式对人类更友好，特别是包含多行文本的 Prompt 内容时，不用处理一堆转义引号和换行符。
• 简洁性优于 YAML ：YAML 的缩进敏感有时会带来隐藏的解析错误，而 TOML 的语法更明确，键值对清晰。
• 原生多行字符串支持 ：TOML 的 """ 或 ''' 语法非常适合包裹大段的 Prompt 文本，保持内容原貌。
• 广泛的生态支持 ：作为 VSCode 插件（基于 Node.js），有成熟稳定的 @iarna/toml 等解析库，性能可靠。

一个完整的 Prompt TOML 文件示例：

# 提示词内容，放在最前面，因为这是核心
content = """
你是一位经验丰富的 TypeScript 全栈开发专家，专注于 Next.js 和 React。
请遵循以下规则：
1. 所有组件必须使用函数式组件和 TypeScript 接口定义 Props。
2. 优先使用 Tailwind CSS 进行样式编写。
3. 为复杂的业务逻辑添加清晰的 JSDoc 注释。
4. 确保所有导出的函数和组件都编写相应的单元测试。
"""

# 元数据区块，用于管理
[meta]
type = "project" # 或 "global"
id = "nextjs-ts-starter" # 唯一标识符，用于内部索引
name = "Next.js + TS 项目规范"
description = "适用于现代 Next.js 全栈项目的 AI 助手行为规范"
author = "YourName"
version = "1.0.0"
date = "2024-05-27"
license = "MIT"

meta 区块里的信息不仅是为了记录，未来还计划用于实现 Prompt 的搜索、分类和版本管理功能。

3. 详细使用指南与实操要点

3.1 安装与初次配置

安装很简单，在 VSCode、Cursor 或 Windsurf 的扩展商店里搜索 “Oh My Prompt” 点击安装即可。安装后，你会在状态栏最左侧看到插件的图标和文字，通常显示为 Global: [未设置] 和 Project: [未设置] 。

第一次使用的关键步骤：

1. 初始化仓库 ：点击状态栏的 Global: [未设置] ，会弹出一个快速选择菜单。如果这是首次使用，本地仓库是空的，你需要选择“创建新全局提示词”或“从现有文件导入”。
2. 建议先“导入” ：如果你已经在 Windsurf 的全局设置里配置过 Prompt，我强烈建议先选择“从当前 IDE 配置导入”。插件会自动读取 ~/.windsurf/global_prompt 或 Cursor 对应配置的内容，并为你生成一个包含基本元数据的 TOML 文件保存到仓库。这避免了手动拷贝粘贴。
3. 命名与保存 ：导入或创建时，系统会提示你为这个 Prompt 起一个名字和描述。起个好名字很重要，比如“代码审查-严格模式”、“快速原型助手”，方便日后快速识别。

注意 ：安装后如果状态栏没有立即显示，可以尝试重启一下 IDE。有些基于 VSCode 的 IDE 需要完全重启才能加载所有状态栏组件。

3.2 管理全局提示词

全局提示词是你的“默认皮肤”。管理它主要通过状态栏的 Global: 项目。

点击状态栏项目 ：会弹出操作菜单，通常包括：

• 切换提示词 ：列出仓库中所有 type = "global" 的 Prompt，点击即可切换。切换后，插件会立即将内容同步到 IDE 的全局配置。
• 编辑当前提示词 ：在编辑器中打开对应的 TOML 文件，你可以直接修改 content 或 meta 信息。保存后，插件通常会询问你是否立即应用更改。
• 创建新的全局提示词 ：打开一个预置了 TOML 模板的新文件，让你从头编写。
• 从文件导入 ：选择本地的 .txt 、 .md 或任何文本文件，将其内容导入为一个新的全局 Prompt。

实操心得： 我会为不同的工作流创建不同的全局 Prompt。比如：

• global_deep_work ：用于需要高度专注、编写复杂算法或架构时，Prompt 里会强调“逐步思考”、“提供多种方案并分析利弊”。
• global_refactor ：专门用于代码重构，强调“保持功能不变”、“优先提升可读性”、“识别代码坏味道”。 需要切换时，只需点两下状态栏，比改配置文件快得多。

3.3 管理项目提示词

项目提示词是“因地制宜”的关键。当你在一个已打开的项目根目录下操作时， Project: 状态栏项目才会激活。

核心机制：自动发现与关联

1. 打开一个项目文件夹。
2. 点击状态栏的 Project: [未设置] 。
3. 插件会做两件事：
   • 首先，扫描当前目录下是否已存在 .windsurfrules 或 .cursorrules 文件。如果存在，它会提示你“是否将现有规则导入为项目提示词？”。 一定要选“是” ，这能将现有投资无缝迁移到管理系统。
   • 如果不存在，则显示和全局提示词类似的操作菜单（创建、切换、导入等）。
4. 当你为一个项目选择或创建了 Prompt 后，插件会在项目根目录生成一个 .oh-my-prompt-project 的隐藏链接文件（或直接在 .vscode 文件夹里保存配置），记录当前项目关联的是仓库里的哪一个 Prompt ID。这样下次打开项目时，插件就能自动恢复关联。

一个高级技巧：共享项目提示词 假设你为“公司微服务项目模板”创建了一个优秀的项目 Prompt。当有新项目启动时，你不需要重新编写。只需：

1. 在新项目根目录，点击 Project: -> “切换提示词”。
2. 在列表里找到那个模板 Prompt，选择它。
3. 插件会将其内容同步到新项目的 .windsurfrules 文件中。 这样，团队的所有同类项目都能共享同一套高质量的 AI 协作规范。

3.4 状态栏的妙用

状态栏不仅仅是显示，它是控制中心。

• 实时反馈 ：一眼就能知道当前生效的全局和项目规则是什么，防止用错上下文。
• 快速切换 ：比打开设置页面查找要快好几个数量级。
• 编辑入口 ：点击状态栏项目名称旁边的编辑图标（如果设计有），可以直接跳转到 TOML 文件进行微调。

我个人的习惯是把 Oh My Prompt 的状态栏项目锁定在左侧显眼位置，确保随时可见、可点。

4. 高级技巧与最佳实践

4.1 编写高效的 Prompt

工具再好，Prompt 本身的质量是上限。结合 Oh My Prompt 的管理能力，这里有一些编写原则：

结构化你的 Prompt： 不要写成一整段巨长的文字。用清晰的标记和分段，帮助 AI 理解。

content = """
# 角色
你是一位资深 DevOps 工程师，精通 Kubernetes 和 CI/CD。

# 主要任务
帮我编写或审查 Kubernetes YAML 文件和 GitLab CI 配置。

# 具体规则
## 关于 Kubernetes
1. 所有资源必须包含 `app.kubernetes.io/name` 和 `app.kubernetes.io/instance` 标签。
2. Deployment 必须设置 `resources.requests/limits`。
3. 优先使用 `ConfigMap` 和 `Secret` 管理配置。

## 关于 GitLab CI
1. 使用 `docker-in-docker` 镜像时，必须声明 `services` 和 `variables`。
2. 流水线阶段应包括 `test`, `build`, `security-scan`, `deploy`。
3. 使用 `artifacts` 和 `cache` 优化性能。

# 输出格式
请以代码块形式输出，并附上关键解释。
"""

利用元数据管理版本： 当团队对 Prompt 进行优化迭代时，用好 meta.version 字段。可以在描述里写清变更日志，例如 description = "v1.2: 新增了关于错误处理的强制要求" 。这样在切换时，能清楚知道用的是哪个版本。

4.2 团队协作方案

Oh My Prompt 的仓库文件（ ~/.neurora/oh-my-prompt/prompts/ ）是纯文本文件。这意味着它可以被纳入版本控制（如 Git）进行团队共享。

推荐的工作流：

1. 团队维护一个内部的 Git 仓库，用于存放经过评审的、高质量的全局和项目 Prompt 模板（ .toml 文件）。
2. 开发者克隆这个仓库，将其中的 prompts/ 目录软链接或拷贝到本地的 ~/.neurora/oh-my-prompt/ 目录下（需要注意跨平台路径问题）。
3. 当模板更新时，开发者拉取更改即可获得最新的 Prompt 集合。

注意事项： 直接同步整个目录可能会覆盖个人的自定义 Prompt。一个更稳健的方案是只共享 prompts/project/ 下的团队模板，而 prompts/global/ 下的个人提示词由各自管理。插件本身未来也可能增加更完善的“同步与合并”功能。

4.3 与现有工作流集成

你很可能已经有了一些自己积累的 Prompt 文本文件。Oh My Prompt 的“导入”功能就是为此而生。

批量导入脚本（Linux/macOS 示例）： 假设你有一堆 *.prompt.txt 文件在 ~/my_prompts/ 目录下。

#!/bin/bash
STORE_DIR="$HOME/.neurora/oh-my-prompt/prompts/global"
mkdir -p "$STORE_DIR"
for file in ~/my_prompts/*.prompt.txt; do
  BASENAME=$(basename "$file" .prompt.txt)
  # 使用一个简单的模板，并读取文件内容
  cat > "$STORE_DIR/${BASENAME}.toml" <<EOF
content = """
$(cat "$file")
"""
[meta]
type = "global"
id = "$(uuidgen)" # 需要安装 uuidgen，或使用其他生成唯一ID的方法
name = "${BASENAME}"
description = "Imported from legacy file"
date = "$(date -I)"
EOF
done
echo "导入完成！请在 Oh My Prompt 中刷新列表。"

运行此脚本，就能将旧文件快速转换为插件可识别的 TOML 格式。Windows 用户可以用 PowerShell 实现类似功能。

5. 常见问题与故障排查

在实际使用和与社区交流中，我总结了一些常见问题及其解决方法。

问题现象	可能原因	解决方案
状态栏不显示或显示 [未设置]	1. 插件未正确激活。 2. 本地仓库路径不存在或无法读取。	1. 检查扩展是否已启用，尝试重启 IDE。 2. 检查 ~/.neurora/oh-my-prompt 目录是否存在且有读写权限。可以尝试通过命令面板运行 Oh My Prompt: Reset Configuration （如果插件提供）。
切换 Prompt 后，AI 助手行为未改变	1. 同步到 IDE 配置文件失败。 2. IDE 未及时重载配置。 3. Cursor/Windsurf 自身有缓存。	1. 检查 IDE 的全局配置路径（如 ~/.windsurf/global_prompt ）文件内容是否已更新。 2. 尝试在 IDE 内手动修改并保存一次 Prompt 设置，触发重载。 3. 重启 Cursor/Windsurf 是最彻底的方法。
项目提示词切换无效	1. 项目未正确关联。 2. 项目根目录的规则文件（.windsurfrules）被其他进程锁定或覆盖。	1. 确认当前文件夹是 IDE 的根工作区。检查项目根目录下是否有 .oh-my-prompt-project 文件。 2. 关闭可能编辑该文件的其他编辑器或工具。检查文件权限。
导入现有规则文件时出错	1. 文件格式不是纯文本或编码问题。 2. 文件路径包含插件无法处理的特殊字符。	1. 用文本编辑器（如 VSCode）打开源文件，确认其内容正常，另存为 UTF-8 编码。 2. 将文件移动到不含空格、中文等字符的路径下再尝试导入。
插件命令在命令面板中找不到	VSCode 扩展激活时机问题。	确保至少打开了一个文本文件或项目，因为很多插件是在“激活事件”触发后才完全加载。也可以尝试重新加载窗口（Ctrl/Cmd + Shift + P，输入 Developer: Reload Window ）。

调试锦囊： 如果遇到奇怪的问题，可以打开 VSCode 的输出面板（Output），选择 “Oh My Prompt” 通道，查看插件运行的详细日志。这里面通常会记录同步操作、文件读写是否成功等关键信息，是自我排查的第一手资料。

关于 Cursor 的特别说明： 截至当前版本，Oh My Prompt 对 Cursor 的集成可能仍在完善中。Cursor 的配置存储方式可能与 Windsurf 略有不同。如果发现对 Cursor 不生效，请关注项目的 GitHub Issues 页面，查看是否有针对 Cursor 的更新或配置说明。通常的解决思路是确认插件是否有权限写入 Cursor 的特定配置目录。