Skip to content

CursorGuard v1.0.0

Choose a tag to compare

View all tags
@Colliot2 Colliot2 released this 20 Oct 03:29
· 1 commit to master since this release
v1.0.0
42b950e

CursorGuard v1.0.0

🎉 首个正式版本发布

CursorGuard 是一个智能命令包装器，专门为 Cursor AI 设计，强制其在执行 grep、tail、head 命令时使用最佳实践，避免信息不足导致频繁重跑命令。

✨ 核心特性

🎯 智能检测

  • ✅ 精准识别：只在 Cursor AI 执行命令时生效
  • ✅ 用户透明：手动在 Cursor 终端执行完全正常，不受影响
  • ✅ 零性能开销：基于环境变量检测，无需进程树遍历

🔧 强制最佳实践

grep 命令

  • 自动添加 -C 20（显示上下文 20 行）
  • 保留原有参数（--color=auto、--exclude-dir 等）
  • 管道输入自动保存到临时文件

tail / head 命令

  • 强制最少 100 行（-n 100）
  • 管道输入自动保存到临时文件
  • 避免信息不足需要重跑

📁 临时文件管理

  • 自动保存管道输入到 /tmp/cursor_outputs/
  • 文件名包含时间戳和随机数，避免覆盖
  • 明确提示文件位置和用途

🚀 快速开始

安装（macOS arm64）

# 1. 下载并解压
wget https://github.com/Colliot2/CursorGuard/releases/download/v1.0.0/cursor-guard-v1.0.0-macos-arm64.tar.gz
tar -xzf cursor-guard-v1.0.0-macos-arm64.tar.gz

# 2. 复制到系统路径
mkdir -p ~/bin
mv grep tail head ~/bin/
chmod +x ~/bin/{grep,tail,head}

# 3. 配置 PATH（如果 ~/bin 不在 PATH 中）
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证安装

which grep  # 应该显示 ~/bin/grep
echo "test" | grep "test"  # Cursor AI 执行时会看到强制提示

📋 使用示例

Cursor AI 执行（强制规则）

# AI 执行：echo "error" | grep "error"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 [Cursor 强制最佳实践] 管道输入已自动保存
📁 文件位置: /tmp/cursor_outputs/grep_input_12345_20241019_120000.txt
💡 用途: 避免重复运行耗时命令，可直接读取此文件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  [Cursor 强制最佳实践] grep 参数不足，已强制改为 grep -C 20
💡 这样可以提供足够的信息，避免重复运行命令
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
error

用户手动执行（完全正常）

# 手动在 Cursor 终端：echo "test" | grep "test"
test  # 无任何包装，完全正常

🔍 技术细节

检测机制

  • 关键环境变量：CURSOR_AGENT=1
  • 只有 Cursor AI 执行时才存在此变量
  • 用户手动执行不会触发包装器

实现

  • 语言：Rust（零成本抽象，高性能）
  • 架构：三个独立二进制（grep、tail、head）+ 共享库（cursor_common）
  • 测试：完整的单元测试覆盖

文件结构

cursor_grep_wrapper/
├── src/
│   ├── common.rs    # 共享逻辑（检测、文件管理）
│   ├── grep.rs      # grep 包装器
│   ├── tail.rs      # tail 包装器
│   └── head.rs      # head 包装器
├── auto_install.sh  # 自动安装脚本
└── README.md        # 完整文档

📊 兼容性

平台 架构 支持
macOS arm64 (Apple Silicon) ✅ 此版本
macOS x86_64 (Intel) ⏳ 计划中
Linux x86_64 ⏳ 计划中
Linux arm64 ⏳ 计划中

🛠️ 从源码编译

# 1. 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. 克隆仓库
git clone https://github.com/Colliot2/CursorGuard.git
cd CursorGuard

# 3. 编译
cargo build --release

# 4. 安装
./auto_install.sh

📝 Changelog

v1.0.0 (2024-10-19)

新增

  • ✨ 首个正式版本
  • ✨ 基于 CURSOR_AGENT 的精准检测
  • ✨ grep 自动添加 -C 20 上下文
  • ✨ tail/head 强制最少 100 行
  • ✨ 管道输入自动保存到临时文件
  • ✨ 完整的单元测试

修复

  • 🐛 移除 CURSOR_TRACE_ID 检测（手动终端也有此变量）
  • 🐛 确保只有 AI 执行才触发包装器

改进

  • ⚡ 零性能开销的检测机制
  • 📦 自动安装脚本支持 ~/bin 降级
  • 📚 完整的中英文文档

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发指南

# 运行测试
cargo test

# 运行 linter
cargo clippy

# 格式化代码
cargo fmt

📄 许可证

MIT License

🙏 致谢

感谢所有为这个项目做出贡献的开发者！

安装指南 | 完整文档 | 报告问题

Assets 3
Loading