[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-intellectronica--ruler":3,"tool-intellectronica--ruler":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160784,2,"2026-04-19T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":76,"owner_location":77,"owner_email":76,"owner_twitter":73,"owner_website":78,"owner_url":79,"languages":80,"stars":89,"forks":90,"last_commit_at":91,"license":92,"difficulty_score":32,"env_os":93,"env_gpu":94,"env_ram":94,"env_deps":95,"category_tags":99,"github_topics":100,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":110,"updated_at":111,"faqs":112,"releases":142},9733,"intellectronica\u002Fruler","ruler","Ruler — apply the same rules to all coding agents","Ruler 是一款专为统一 AI 编程助手指令而设计的开源工具。随着开发团队引入 GitHub Copilot、Claude Code、Cursor 等多种 AI 代理，维护各自独立的配置文件往往导致指令不一致、重复劳动以及项目上下文漂移等问题。Ruler 通过建立单一的“真理来源”，巧妙解决了这一痛点：开发者只需在项目的 `.ruler\u002F` 目录中用 Markdown 编写一套规则，Ruler 即可自动将这些指令分发并同步到各个 AI 工具对应的配置文件中。\n\n该工具特别适合需要同时使用多种 AI 编码辅助的开发者和技术团队，尤其是那些拥有复杂目录结构、需要针对不同模块定制特定指令的大型项目。Ruler 的核心亮点在于支持嵌套规则加载，允许在不同子目录中定义局部规则，从而灵活适应多层次的项目架构。此外，它还具备 MCP（模型上下文协议）服务器配置的自动传播能力，并能智能管理 `.gitignore` 以避免生成的配置文件污染版本控制。通过简单的命令行操作，Ruler 让多 AI 环境的协作变得规范、高效且易于维护，帮助团队将精力重新聚焦于代码本身。","# Ruler: Centralise Your AI Coding Assistant Instructions\n\n\u003Ctable style=\"width:100%\">\n \u003Ctr>\n \u003Ctd style=\"vertical-align: top;\">\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\u003C\u002Fa>\n \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@intellectronica\u002Fruler\">\u003Cimg src=\"https:\u002F\u002Fbadge.fury.io\u002Fjs\u002F%40intellectronica%2Fruler.svg\" alt=\"npm version\">\u003C\u002Fa>\n \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg\" alt=\"License: MIT\">\n \u003C\u002Fp>\n \u003Cul>\n \u003Cli>\u003Cstrong>GitHub\u003C\u002Fstrong>: \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\">intellectronica\u002Fruler\u003C\u002Fa>\u003C\u002Fli>\n \u003Cli>\u003Cstrong>NPM\u003C\u002Fstrong>: \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@intellectronica\u002Fruler\">@intellectronica\u002Fruler\u003C\u002Fa>\u003C\u002Fli>\n \u003C\u002Ful>\n \u003Chr \u002F>\n \u003Cp>\n \u003Cem>Animation by \u003Ca href=\"https:\u002F\u002Fisaacflath.com\u002F\">Isaac Flath\u003C\u002Fa> of \u003Cstrong>\u003Ca href=\"https:\u002F\u002Felite-ai-assisted-coding.dev\u002F\">Elite AI-Assisted Coding\u003C\u002Fa>\u003C\u002Fstrong>\u003C\u002Fem> ➡︎\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003Ctd style=\"vertical-align: top; width:33%;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fintellectronica_ruler_readme_4eb82d0447a4.gif\" alt=\"Ruler demo\" style=\"width:300px; height:auto; display:block;\" \u002F>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n---\n\n> **Beta Research Preview**\n>\n> - Please test this version carefully in your environment\n> - Report issues at https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues\n\n## Why Ruler?\n\nManaging instructions across multiple AI coding tools becomes complex as your team grows. Different agents (GitHub Copilot, Claude, Cursor, Aider, etc.) require their own configuration files, leading to:\n\n- **Inconsistent guidance** across AI tools\n- **Duplicated effort** maintaining multiple config files\n- **Context drift** as project requirements evolve\n- **Onboarding friction** for new AI tools\n- **Complex project structures** requiring context-specific instructions for different components\n\nRuler solves this by providing a **single source of truth** for all your AI agent instructions, automatically distributing them to the right configuration files. With support for **nested rule loading**, Ruler can handle complex project structures with context-specific instructions for different components.\n\n## Core Features\n\n- **Centralised Rule Management**: Store all AI instructions in a dedicated `.ruler\u002F` directory using Markdown files\n- **Nested Rule Loading**: Support complex project structures with multiple `.ruler\u002F` directories for context-specific instructions\n- **Automatic Distribution**: Ruler applies these rules to configuration files of supported AI agents\n- **Targeted Agent Configuration**: Fine-tune which agents are affected and their specific output paths via `ruler.toml`\n- **MCP Server Propagation**: Manage and distribute Model Context Protocol (MCP) server settings\n- **`.gitignore` Automation**: Keeps generated agent config files out of version control automatically\n- **Simple CLI**: Easy-to-use commands for initialising and applying configurations\n\n## Supported AI Agents\n\n| Agent | Rules File(s) | MCP Configuration \u002F Notes | Skills Support \u002F Location |\n| ---------------------- | ---------------------------------------------- | ------------------------------------------------ | ------------------------- |\n| AGENTS.md | `AGENTS.md` | (pseudo-agent ensuring root `AGENTS.md` exists) | - |\n| GitHub Copilot | `AGENTS.md` | `.vscode\u002Fmcp.json` | `.claude\u002Fskills\u002F` |\n| Claude Code | `CLAUDE.md` | `.mcp.json` | `.claude\u002Fskills\u002F` |\n| OpenAI Codex CLI | `AGENTS.md` | `.codex\u002Fconfig.toml` | `.codex\u002Fskills\u002F` |\n| Pi Coding Agent | `AGENTS.md` | - | `.pi\u002Fskills\u002F` |\n| Jules | `AGENTS.md` | - | - |\n| Cursor | `AGENTS.md` | `.cursor\u002Fmcp.json` | `.cursor\u002Fskills\u002F` |\n| Windsurf | `AGENTS.md` | `.windsurf\u002Fmcp_config.json` | `.windsurf\u002Fskills\u002F` |\n| Cline | `.clinerules` | - | - |\n| Crush | `CRUSH.md` | `.crush.json` | - |\n| Amp | `AGENTS.md` | - | `.agents\u002Fskills\u002F` |\n| Antigravity | `.agent\u002Frules\u002Fruler.md` | - | `.agent\u002Fskills\u002F` |\n| Amazon Q CLI | `.amazonq\u002Frules\u002Fruler_q_rules.md` | `.amazonq\u002Fmcp.json` | - |\n| Aider | `AGENTS.md`, `.aider.conf.yml` | `.mcp.json` | - |\n| Firebase Studio | `.idx\u002Fairules.md` | `.idx\u002Fmcp.json` | - |\n| Open Hands | `.openhands\u002Fmicroagents\u002Frepo.md` | `config.toml` | - |\n| Gemini CLI | `AGENTS.md` | `.gemini\u002Fsettings.json` | `.gemini\u002Fskills\u002F` |\n| Junie | `.junie\u002Fguidelines.md` | `.junie\u002Fmcp\u002Fmcp.json` | `.junie\u002Fskills\u002F` |\n| AugmentCode | `.augment\u002Frules\u002Fruler_augment_instructions.md` | - | - |\n| Kilo Code | `AGENTS.md` | `.kilocode\u002Fmcp.json` | `.claude\u002Fskills\u002F` |\n| OpenCode | `AGENTS.md` | `opencode.json` | `.opencode\u002Fskills\u002F` |\n| Goose | `.goosehints` | - | `.agents\u002Fskills\u002F` |\n| Qwen Code | `AGENTS.md` | `.qwen\u002Fsettings.json` | - |\n| RooCode | `AGENTS.md` | `.roo\u002Fmcp.json` | `.roo\u002Fskills\u002F` |\n| Zed | `AGENTS.md` | `.zed\u002Fsettings.json` (project root, never $HOME) | - |\n| Trae AI | `.trae\u002Frules\u002Fproject_rules.md` | - | - |\n| Warp | `WARP.md` | - | - |\n| Kiro | `.kiro\u002Fsteering\u002Fruler_kiro_instructions.md` | `.kiro\u002Fsettings\u002Fmcp.json` | - |\n| Firebender | `firebender.json` | `firebender.json` (rules and MCP in same file) | - |\n| Factory Droid | `AGENTS.md` | `.factory\u002Fmcp.json` | `.factory\u002Fskills\u002F` |\n| Mistral Vibe | `AGENTS.md` | `.vibe\u002Fconfig.toml` | `.vibe\u002Fskills\u002F` |\n| JetBrains AI Assistant | `.aiassistant\u002Frules\u002FAGENTS.md` | - | - |\n\n## Getting Started\n\n### Installation\n\nRequires Node.js `^20.19.0 || ^22.12.0 || >=23`.\n\n**Global Installation (Recommended for CLI use):**\n\n```bash\nnpm install -g @intellectronica\u002Fruler\n```\n\n**Using `npx` (for one-off commands):**\n\n```bash\nnpx @intellectronica\u002Fruler apply\n```\n\n### Project Initialisation\n\n1. Navigate to your project's root directory\n2. Run `ruler init`\n3. This creates:\n\n- `.ruler\u002F` directory\n- `.ruler\u002FAGENTS.md`: The primary starter Markdown file for your rules\n- `.ruler\u002Fruler.toml`: The main configuration file for Ruler (now contains sample MCP server sections; legacy `.ruler\u002Fmcp.json` no longer scaffolded)\n- (Optional legacy fallback) If you previously used `.ruler\u002Finstructions.md`, it is still respected when `AGENTS.md` is absent. (The prior runtime warning was removed.)\n\nAdditionally, you can create a global configuration to use when no local `.ruler\u002F` directory is found:\n\n```bash\nruler init --global\n```\n\nThe global configuration will be created to `$XDG_CONFIG_HOME\u002Fruler` (default: `~\u002F.config\u002Fruler`).\n\n## Core Concepts\n\n### The `.ruler\u002F` Directory\n\nThis is your central hub for all AI agent instructions:\n\n- **Primary File Order & Precedence**:\n 1. A repository root `AGENTS.md` (outside `.ruler\u002F`) if present (highest precedence, prepended)\n 2. `.ruler\u002FAGENTS.md` (new default starter file)\n 3. Legacy `.ruler\u002Finstructions.md` (only if `.ruler\u002FAGENTS.md` absent; no longer emits a deprecation warning)\n 4. Remaining discovered `.md` files under `.ruler\u002F` (and subdirectories) in sorted order\n- **Rule Files (`*.md`)**: Discovered recursively from `.ruler\u002F` or `$XDG_CONFIG_HOME\u002Fruler` and concatenated in the order above\n- **Concatenation Marker**: Each file's content is prepended with `\u003C!-- Source: \u003Crelative_path_to_md_file> -->` for traceability\n- **`ruler.toml`**: Master configuration for Ruler's behavior, agent selection, output paths, and MCP server settings\n- **`mcp.json`**: (Legacy, deprecated) Shared MCP server settings - no longer scaffolded but still supported for backward compatibility\n\nThis ordering lets you keep a short, high-impact root `AGENTS.md` (e.g. executive project summary) while housing detailed guidance inside `.ruler\u002F`.\n\n### Nested Rule Loading\n\nRuler now supports **nested rule loading** with the `--nested` flag, enabling context-specific instructions for different parts of your project:\n\n```\nproject\u002F\n├── .ruler\u002F # Global project rules\n│ ├── AGENTS.md\n│ └── coding_style.md\n├── src\u002F\n│ └── .ruler\u002F # Component-specific rules\n│ └── api_guidelines.md\n├── tests\u002F\n│ └── .ruler\u002F # Test-specific rules\n│ └── testing_conventions.md\n└── docs\u002F\n └── .ruler\u002F # Documentation rules\n └── writing_style.md\n```\n\n**How it works:**\n\n- Discover all `.ruler\u002F` directories in the project hierarchy\n- Load and concatenate rules from each directory in order\n- Decide whether nested mode is enabled using the following precedence:\n 1. `ruler apply --nested` (or `--no-nested`) takes top priority\n 2. `nested = true` in `ruler.toml`\n 3. Default to disabled when neither option is provided\n- When a run is nested, downstream configs are forced to keep `nested = true`. If a child config attempts to disable it, Ruler keeps nested processing active and emits a warning in the logs.\n- Nested processing carries forward each directory's own MCP bundle and configuration settings so that generated files remain scoped to their source directories while being normalized back to the project root.\n\n> [!CAUTION]\n> Nested mode is experimental and may change in future releases. The CLI logs this warning the first time a nested run is detected so you know the behavior may evolve.\n\n**Perfect for:**\n\n- Monorepos with multiple services\n- Projects with distinct components (frontend\u002Fbackend)\n- Teams needing different instructions for different areas\n- Complex codebases with varying standards\n\n### Best Practices for Rule Files\n\n**Granularity**: Break down complex instructions into focused `.md` files:\n\n- `coding_style.md`\n- `api_conventions.md`\n- `project_architecture.md`\n- `security_guidelines.md`\n\n**Example rule file (`.ruler\u002Fpython_guidelines.md`):**\n\n```markdown\n# Python Project Guidelines\n\n## General Style\n\n- Follow PEP 8 for all Python code\n- Use type hints for all function signatures and complex variables\n- Keep functions short and focused on a single task\n\n## Error Handling\n\n- Use specific exception types rather than generic `Exception`\n- Log errors effectively with context\n\n## Security\n\n- Always validate and sanitize user input\n- Be mindful of potential injection vulnerabilities\n```\n\n## Usage: The `apply` Command\n\n### Primary Command\n\n```bash\nruler apply [options]\n```\n\nThe `apply` command looks for `.ruler\u002F` in the current directory tree, reading the first match. If no such directory is found, it will look for a global configuration in `$XDG_CONFIG_HOME\u002Fruler`.\n\n### Options\n\n| Option | Description |\n| ------------------------------ | ---------------------------------------------------------------------- |\n| `--project-root \u003Cpath>` | Project root path (default: current directory). |\n| `--agents \u003Cagent1,agent2,...>` | Comma-separated agent names to target (see supported list below). |\n| `--config \u003Cpath>` | Custom `ruler.toml` path. |\n| `--mcp` \u002F `--with-mcp` | Enable applying MCP server configurations (default: true). |\n| `--no-mcp` | Disable applying MCP server configurations. |\n| `--mcp-overwrite` | Overwrite native MCP config instead of merging. |\n| `--gitignore` | Enable automatic .gitignore updates (default: true). |\n| `--no-gitignore` | Disable automatic .gitignore updates. |\n| `--gitignore-local` | Write managed ignore entries to `.git\u002Finfo\u002Fexclude` instead. |\n| `--nested` | Enable nested rule loading (default: inherit from config or disabled). |\n| `--no-nested` | Disable nested rule loading even if `nested = true` in config. |\n| `--backup` | Enable creation of `.bak` backup files (default: enabled). |\n| `--no-backup` | Disable creation of `.bak` backup files. |\n| `--skills` | Enable skills support (experimental, default: enabled). |\n| `--no-skills` | Disable skills support. |\n| `--dry-run` | Preview changes without writing files. |\n| `--local-only` | Skip `$XDG_CONFIG_HOME` when looking for configuration. |\n| `--verbose` \u002F `-v` | Display detailed output during execution. |\n\n### Common Examples\n\n**Apply rules to all configured agents:**\n\n```bash\nruler apply\n```\n\n**Apply rules only to GitHub Copilot and Claude:**\n\n```bash\nruler apply --agents copilot,claude\n```\n\n**Apply rules only to Firebase Studio:**\n\n```bash\nruler apply --agents firebase\n```\n\n**Apply rules only to Warp:**\n\n```bash\nruler apply --agents warp\n```\n\n**Apply rules only to Trae AI:**\n\n```bash\nruler apply --agents trae\n```\n\n**Apply rules only to RooCode:**\n\n```bash\nruler apply --agents roo\n```\n\n**Use a specific configuration file:**\n\n```bash\nruler apply --config .\u002Fteam-configs\u002Fruler.frontend.toml\n```\n\n**Apply rules with verbose output:**\n\n```bash\nruler apply --verbose\n```\n\n**Apply rules but skip MCP and .gitignore updates:**\n\n```bash\nruler apply --no-mcp --no-gitignore\n```\n\n## Usage: The `revert` Command\n\nThe `revert` command safely undoes all changes made by `ruler apply`, restoring your project to its pre-ruler state. It intelligently restores files from backups (`.bak` files) when available, or removes generated files that didn't exist before.\n\n### Why Revert is Needed\n\nWhen experimenting with different rule configurations or switching between projects, you may want to:\n\n- **Clean slate**: Remove all ruler-generated files to start fresh\n- **Restore originals**: Revert modified files back to their original state\n- **Selective cleanup**: Remove configurations for specific agents only\n- **Safe experimentation**: Try ruler without fear of permanent changes\n\n### Primary Command\n\n```bash\nruler revert [options]\n```\n\n### Options\n\n| Option | Description |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--project-root \u003Cpath>` | Path to your project's root (default: current directory) |\n| `--agents \u003Cagent1,agent2,...>` | Comma-separated list of agent names to revert (agentsmd, aider, amazonqcli, amp, antigravity, augmentcode, claude, cline, codex, copilot, crush, cursor, factory, firebase, firebender, gemini-cli, goose, jetbrains-ai, jules, junie, kilocode, kiro, mistral, opencode, openhands, pi, qwen, roo, trae, warp, windsurf, zed) |\n| `--config \u003Cpath>` | Path to a custom `ruler.toml` configuration file |\n| `--keep-backups` | Keep backup files (.bak) after restoration (default: false) |\n| `--dry-run` | Preview changes without actually reverting files |\n| `--verbose` \u002F `-v` | Display detailed output during execution |\n| `--local-only` | Only search for local .ruler directories, ignore global config |\n\n### Common Examples\n\n**Revert all ruler changes:**\n\n```bash\nruler revert\n```\n\n**Preview what would be reverted (dry-run):**\n\n```bash\nruler revert --dry-run\n```\n\n**Revert only specific agents:**\n\n```bash\nruler revert --agents claude,copilot\n```\n\n**Revert with detailed output:**\n\n```bash\nruler revert --verbose\n```\n\n**Keep backup files after reverting:**\n\n```bash\nruler revert --keep-backups\n```\n\n## Configuration (`ruler.toml`) in Detail\n\n### Location\n\nDefaults to `.ruler\u002Fruler.toml` in the project root. Override with `--config` CLI option.\n\n### Complete Example\n\n```toml\n# Default agents to run when --agents is not specified\n# Uses case-insensitive substring matching\ndefault_agents = [\"copilot\", \"claude\", \"aider\"]\n\n# --- Global MCP Server Configuration ---\n[mcp]\n# Enable\u002Fdisable MCP propagation globally (default: true)\nenabled = true\n# Global merge strategy: 'merge' or 'overwrite' (default: 'merge')\nmerge_strategy = \"merge\"\n\n# --- MCP Server Definitions ---\n[mcp_servers.filesystem]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fpath\u002Fto\u002Fproject\"]\n\n[mcp_servers.git]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol\u002Fserver-git\", \"--repository\", \".\"]\n\n[mcp_servers.remote_api]\nurl = \"https:\u002F\u002Fapi.example.com\"\n\n[mcp_servers.remote_api.headers]\nAuthorization = \"Bearer your-token\"\n\n# --- Global .gitignore Configuration ---\n[gitignore]\n# Enable\u002Fdisable automatic .gitignore updates (default: true)\nenabled = true\n# Write managed entries to .git\u002Finfo\u002Fexclude instead of .gitignore (default: false)\nlocal = false\n\n# --- Agent-Specific Configurations ---\n[agents.copilot]\nenabled = true\n\n[agents.claude]\nenabled = true\noutput_path = \"CLAUDE.md\"\n\n[agents.aider]\nenabled = true\noutput_path_instructions = \"AGENTS.md\"\noutput_path_config = \".aider.conf.yml\"\n\n# OpenAI Codex CLI agent and MCP config\n[agents.codex]\nenabled = true\noutput_path = \"AGENTS.md\"\noutput_path_config = \".codex\u002Fconfig.toml\"\n\n# Agent-specific MCP configuration for Codex CLI\n[agents.codex.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n[agents.firebase]\nenabled = true\noutput_path = \".idx\u002Fairules.md\"\n\n[agents.gemini-cli]\nenabled = true\n\n[agents.jules]\nenabled = true\n\n[agents.junie]\nenabled = true\noutput_path = \".junie\u002Fguidelines.md\"\n\n[agents.junie.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n# Agent-specific MCP configuration\n[agents.cursor.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n# Disable specific agents\n[agents.windsurf]\nenabled = false\n\n[agents.kilocode]\nenabled = true\noutput_path = \"AGENTS.md\"\n\n[agents.warp]\nenabled = true\noutput_path = \"WARP.md\"\n```\n\n### Configuration Precedence\n\n1. **CLI flags** (e.g., `--agents`, `--no-mcp`, `--mcp-overwrite`, `--no-gitignore`)\n2. **Settings in `ruler.toml`** (`default_agents`, specific agent settings, global sections)\n3. **Ruler's built-in defaults** (all agents enabled, standard output paths, MCP enabled with 'merge')\n\n## MCP (Model Context Protocol) Server Configuration\n\nMCP provides broader context to AI models through server configurations. Ruler can manage and distribute these settings across compatible agents.\n\n### TOML Configuration (Recommended)\n\nYou can now define MCP servers directly in `ruler.toml` using the `[mcp_servers.\u003Cname>]` syntax:\n\n```toml\n# Global MCP behavior\n[mcp]\nenabled = true\nmerge_strategy = \"merge\" # or \"overwrite\"\n\n# Local (stdio) server\n[mcp_servers.filesystem]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fpath\u002Fto\u002Fproject\"]\n\n[mcp_servers.filesystem.env]\nAPI_KEY = \"your-api-key\"\n\n# Remote server\n[mcp_servers.search]\nurl = \"https:\u002F\u002Fmcp.example.com\"\n\n[mcp_servers.search.headers]\nAuthorization = \"Bearer your-token\"\n\"X-API-Version\" = \"v1\"\n```\n\n### Legacy `.ruler\u002Fmcp.json` (Deprecated)\n\nFor backward compatibility, you can still use the JSON format; a warning is issued encouraging migration to TOML. The file is no longer created during `ruler init`.\n\n```json\n{\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@modelcontextprotocol\u002Fserver-filesystem\",\n \"\u002Fpath\u002Fto\u002Fproject\"\n ]\n },\n \"git\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-git\", \"--repository\", \".\"]\n }\n }\n}\n```\n\n### Configuration Precedence\n\nWhen both TOML and JSON configurations are present:\n\n1. **TOML servers take precedence** over JSON servers with the same name\n2. **Servers are merged** from both sources (unless using overwrite strategy)\n3. **Deprecation warning** is shown encouraging migration to TOML (warning shown once per run)\n\n### Server Types\n\n**Local\u002Fstdio servers** require a `command` field:\n\n```toml\n[mcp_servers.local_server]\ncommand = \"node\"\nargs = [\"server.js\"]\n\n[mcp_servers.local_server.env]\nDEBUG = \"1\"\n```\n\n**Remote servers** require a `url` field (headers optional; bearer Authorization token auto-extracted for OpenHands when possible):\n\n```toml\n[mcp_servers.remote_server]\nurl = \"https:\u002F\u002Fapi.example.com\"\n\n[mcp_servers.remote_server.headers]\nAuthorization = \"Bearer token\"\n```\n\nRuler uses this configuration with the `merge` (default) or `overwrite` strategy, controlled by `ruler.toml` or CLI flags.\n\n**Home Directory Safety:** Ruler never writes MCP configuration files outside your project root. Any historical references to user home directories (e.g. `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json` or `~\u002F.zed\u002Fsettings.json`) have been removed; only project-local paths are targeted.\n\n**Note for OpenAI Codex CLI:** To apply the local Codex CLI MCP configuration, set the `CODEX_HOME` environment variable to your project’s `.codex` directory:\n\n```bash\nexport CODEX_HOME=\"$(pwd)\u002F.codex\"\n```\n\n## Skills Support (Experimental)\n\n**⚠️ Experimental Feature**: Skills support is currently experimental. Skills are only propagated to agents with native skills support; other agents are skipped with a warning.\n\nRuler can manage and propagate skills to supported AI agents. Skills are stored in `.ruler\u002Fskills\u002F` and are automatically distributed to compatible agents when you run `ruler apply`.\n\n### How It Works\n\nSkills are specialized knowledge packages that extend AI agent capabilities with domain-specific expertise, workflows, or tool integrations. Ruler discovers skills in your `.ruler\u002Fskills\u002F` directory and propagates them to compatible agents:\n\n- **Agents with native skills support**: Skills are copied directly to each agent's native skills directory:\n - **Claude Code**: `.claude\u002Fskills\u002F`\n - **GitHub Copilot**: `.claude\u002Fskills\u002F` (shared with Claude Code)\n - **Kilo Code**: `.claude\u002Fskills\u002F` (shared with Claude Code)\n - **OpenAI Codex CLI**: `.codex\u002Fskills\u002F`\n - **OpenCode**: `.opencode\u002Fskills\u002F`\n - **Pi Coding Agent**: `.pi\u002Fskills\u002F`\n - **Goose**: `.agents\u002Fskills\u002F`\n - **Amp**: `.agents\u002Fskills\u002F` (shared with Goose)\n - **Antigravity**: `.agent\u002Fskills\u002F`\n - **Factory Droid**: `.factory\u002Fskills\u002F`\n - **Mistral Vibe**: `.vibe\u002Fskills\u002F`\n - **Roo Code**: `.roo\u002Fskills\u002F`\n - **Gemini CLI**: `.gemini\u002Fskills\u002F`\n - **Junie**: `.junie\u002Fskills\u002F`\n - **Cursor**: `.cursor\u002Fskills\u002F`\n - **Windsurf**: `.windsurf\u002Fskills\u002F`\n\n### Skills Directory Structure\n\nSkills can be organized flat or nested:\n\n```\n.ruler\u002Fskills\u002F\n├── my-skill\u002F\n│ ├── SKILL.md # Required: skill instructions\u002Fknowledge\n│ ├── helper.py # Optional: additional resources (scripts)\n│ └── reference.md # Optional: additional resources (docs)\n└── another-skill\u002F\n └── SKILL.md\n```\n\nEach skill must contain:\n\n- `SKILL.md` - Primary skill file with instructions or knowledge base\n\nSkills can optionally include additional resources like:\n\n- Markdown files with supplementary documentation\n- Python, JavaScript, or other scripts\n- Configuration files or data\n\n### Configuration\n\nSkills support is **enabled by default** but can be controlled via:\n\n**CLI flags:**\n\n```bash\n# Enable skills (default)\nruler apply --skills\n\n# Disable skills\nruler apply --no-skills\n```\n\n**Configuration in `ruler.toml`:**\n\n```toml\n[skills]\nenabled = true # or false to disable\n```\n\n### Non-native Agents\n\nIf you run Ruler for agents that do not support native skills, Ruler logs a warning and skips skills propagation for those agents.\n\n### `.gitignore` Integration\n\nWhen skills support is enabled and gitignore integration is active, Ruler automatically adds:\n\n- `.claude\u002Fskills\u002F` (for Claude Code, GitHub Copilot, and Kilo Code)\n- `.codex\u002Fskills\u002F` (for OpenAI Codex CLI)\n- `.opencode\u002Fskills\u002F` (for OpenCode)\n- `.pi\u002Fskills\u002F` (for Pi Coding Agent)\n- `.agents\u002Fskills\u002F` (for Goose and Amp)\n- `.agent\u002Fskills\u002F` (for Antigravity)\n- `.factory\u002Fskills\u002F` (for Factory Droid)\n- `.vibe\u002Fskills\u002F` (for Mistral Vibe)\n- `.roo\u002Fskills\u002F` (for Roo Code)\n- `.gemini\u002Fskills\u002F` (for Gemini CLI)\n- `.junie\u002Fskills\u002F` (for Junie)\n- `.cursor\u002Fskills\u002F` (for Cursor)\n- `.windsurf\u002Fskills\u002F` (for Windsurf)\n\nto your `.gitignore` file within the managed Ruler block.\n\n### Requirements\n\n- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Antigravity, Factory Droid, Mistral Vibe, Roo Code, Gemini CLI, Junie, Cursor, Windsurf): No additional requirements.\n\n### Validation\n\nRuler validates discovered skills and issues warnings for:\n\n- Missing required file (`SKILL.md`)\n- Invalid directory structures (directories without `SKILL.md` and no sub-skills)\n\nWarnings don't prevent propagation but help identify potential issues.\n\n### Dry-Run Mode\n\nTest skills propagation without making changes:\n\n```bash\nruler apply --dry-run\n```\n\nThis shows which skills would be copied.\n\n### Example Workflow\n\n```bash\n# 1. Add a skill to your project\nmkdir -p .ruler\u002Fskills\u002Fmy-skill\ncat > .ruler\u002Fskills\u002Fmy-skill\u002FSKILL.md \u003C\u003C 'EOF'\n# My Custom Skill\n\nThis skill provides specialized knowledge for...\n\n## Usage\n\nWhen working on this project, always follow these guidelines:\n- Use TypeScript for all new code\n- Write tests for all features\n- Follow the existing code style\nEOF\n\n# 2. Apply to all agents (skills enabled by default)\nruler apply\n\n# 3. Skills are now available to compatible agents:\n# - Claude Code, GitHub Copilot & Kilo Code: .claude\u002Fskills\u002Fmy-skill\u002F\n# - OpenAI Codex CLI: .codex\u002Fskills\u002Fmy-skill\u002F\n# - OpenCode: .opencode\u002Fskills\u002Fmy-skill\u002F\n# - Pi Coding Agent: .pi\u002Fskills\u002Fmy-skill\u002F\n# - Goose & Amp: .agents\u002Fskills\u002Fmy-skill\u002F\n# - Antigravity: .agent\u002Fskills\u002Fmy-skill\u002F\n# - Factory Droid: .factory\u002Fskills\u002Fmy-skill\u002F\n# - Mistral Vibe: .vibe\u002Fskills\u002Fmy-skill\u002F\n# - Roo Code: .roo\u002Fskills\u002Fmy-skill\u002F\n# - Gemini CLI: .gemini\u002Fskills\u002Fmy-skill\u002F\n# - Junie: .junie\u002Fskills\u002Fmy-skill\u002F\n# - Cursor: .cursor\u002Fskills\u002Fmy-skill\u002F\n# - Windsurf: .windsurf\u002Fskills\u002Fmy-skill\u002F\n```\n\n## `.gitignore` Integration\n\nRuler automatically manages your `.gitignore` file to keep generated agent configuration files out of version control.\n\n### How it Works\n\n- Creates or updates `.gitignore` in your project root\n- Adds paths to a managed block marked with `# START Ruler Generated Files` and `# END Ruler Generated Files`\n- Preserves existing content outside this block\n- Sorts paths alphabetically and uses relative POSIX-style paths\n\n### Example `.gitignore` Section (sample - actual list depends on enabled agents)\n\n```gitignore\n# Your existing rules\nnode_modules\u002F\n*.log\n\n# START Ruler Generated Files\n.aider.conf.yml\n.clinerules\nAGENTS.md\nCLAUDE.md\n# END Ruler Generated Files\n\ndist\u002F\n```\n\n### Control Options\n\n- **CLI flags**: `--gitignore`, `--no-gitignore`, `--gitignore-local`, `--no-gitignore-local`\n- **Configuration**: `[gitignore].enabled` and `[gitignore].local` in `ruler.toml`\n- **Default**: enabled\n\n## Practical Usage Scenarios\n\n### Scenario 1: Getting Started Quickly\n\n```bash\n# Initialize Ruler in your project\ncd your-project\nruler init\n\n# Edit the generated files\n# - Add your coding guidelines to .ruler\u002FAGENTS.md (or keep adding additional .md files)\n# - Customize .ruler\u002Fruler.toml if needed\n\n# Apply rules to all AI agents\nruler apply\n```\n\n### Scenario 2: Complex Projects with Nested Rules\n\nFor large projects with multiple components or services, enable nested rule loading so each directory keeps its own rules and MCP bundle:\n\n```bash\n# Set up nested .ruler directories\nmkdir -p src\u002F.ruler tests\u002F.ruler docs\u002F.ruler\n\n# Add component-specific instructions\necho \"# API Design Guidelines\" > src\u002F.ruler\u002Fapi_rules.md\necho \"# Testing Best Practices\" > tests\u002F.ruler\u002Ftest_rules.md\necho \"# Documentation Standards\" > docs\u002F.ruler\u002Fdocs_rules.md\n```\n\n```toml\n# .ruler\u002Fruler.toml\nnested = true\n```\n\n```bash\n# The CLI inherits nested mode from ruler.toml\nruler apply --verbose\n\n# Override from the CLI at any time\nruler apply --no-nested\n```\n\nThis creates context-specific instructions for different parts of your project while maintaining global rules in the root `.ruler\u002F` directory. Nested runs automatically keep every nested config enabled even if a child tries to disable it.\n\n> [!NOTE]\n> The CLI prints \"Nested mode is experimental and may change in future releases.\" the first time nested processing runs. Expect refinements in future versions.\n\n### Scenario 3: Team Standardization\n\n1. Create `.ruler\u002Fcoding_standards.md`, `.ruler\u002Fapi_usage.md`\n2. Commit the `.ruler` directory to your repository\n3. Team members pull changes and run `ruler apply` to update their local AI agent configurations\n\n### Scenario 4: Project-Specific Context for AI\n\n1. Detail your project's architecture in `.ruler\u002Fproject_overview.md`\n2. Describe primary data structures in `.ruler\u002Fdata_models.md`\n3. Run `ruler apply` to help AI tools provide more relevant suggestions\n\n### Integration with NPM Scripts\n\n```json\n{\n \"scripts\": {\n \"ruler:apply\": \"ruler apply\",\n \"dev\": \"npm run ruler:apply && your_dev_command\",\n \"precommit\": \"npm run ruler:apply\"\n }\n}\n```\n\n### Integration with GitHub Actions\n\n```yaml\n# .github\u002Fworkflows\u002Fruler-check.yml\nname: Check Ruler Configuration\non:\n pull_request:\n paths: ['.ruler\u002F**']\n\njobs:\n check-ruler:\n runs-on: ubuntu-latest\n steps:\n - uses: actions\u002Fcheckout@v4\n - uses: actions\u002Fsetup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n\n - name: Install Ruler\n run: npm install -g @intellectronica\u002Fruler\n\n - name: Apply Ruler configuration\n run: ruler apply --no-gitignore\n\n - name: Check for uncommitted changes\n run: |\n if [[ -n $(git status --porcelain) ]]; then\n echo \"::error::Ruler configuration is out of sync!\"\n echo \"Please run 'ruler apply' locally and commit the changes.\"\n exit 1\n fi\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Cannot find module\" errors:**\n\n- Ensure Ruler is installed globally: `npm install -g @intellectronica\u002Fruler`\n- Or use `npx @intellectronica\u002Fruler`\n\n**Permission denied errors:**\n\n- On Unix systems, you may need `sudo` for global installation\n\n**Agent files not updating:**\n\n- Check if the agent is enabled in `ruler.toml`\n- Verify agent isn't excluded by `--agents` flag\n- Use `--verbose` to see detailed execution logs\n\n**Configuration validation errors:**\n\n- Ruler now validates `ruler.toml` format and will show specific error details\n- Check that all configuration values match the expected types and formats\n\n### Debug Mode\n\nUse `--verbose` flag to see detailed execution logs:\n\n```bash\nruler apply --verbose\n```\n\nThis shows:\n\n- Configuration loading details\n- Agent selection logic\n- File processing information\n- MCP configuration steps\n\n## FAQ\n\n**Q: Can I use different rules for different agents?**\nA: Currently, all agents receive the same concatenated rules. For agent-specific instructions, include sections in your rule files like \"## GitHub Copilot Specific\" or \"## Aider Configuration\".\n\n**Q: How do I set up different instructions for different parts of my project?**\nA: Enable nested mode either by setting `nested = true` in `ruler.toml` or by passing `ruler apply --nested`. The CLI inherits the config setting by default, but `--no-nested` always wins if you need to opt out for a run. Nested mode keeps loading rules (and MCP settings) from every `.ruler\u002F` directory in the hierarchy, forces child configs to remain nested, and logs \"Nested mode is experimental and may change in future releases.\" if any nested processing occurs.\n\n**Q: How do I temporarily disable Ruler for an agent?**\nA: Set `enabled = false` in `ruler.toml` under `[agents.agentname]`, or use `--agents` flag to specify only the agents you want.\n\n**Q: What happens to my existing agent configuration files?**\nA: Ruler creates backups with `.bak` extension before overwriting any existing files.\n\n**Q: Can I run Ruler in CI\u002FCD pipelines?**\nA: Yes! Use `ruler apply --no-gitignore` in CI to avoid modifying `.gitignore`. See the GitHub Actions example above.\n\n**Q: How do I migrate from older versions using `instructions.md`?**\nA: Simply rename `.ruler\u002Finstructions.md` to `.ruler\u002FAGENTS.md` (recommended). If you keep the legacy file and omit `AGENTS.md`, Ruler will still use it (without emitting the old deprecation warning). Having both causes `AGENTS.md` to take precedence; the legacy file is still concatenated afterward.\n\n**Q: How does OpenHands MCP propagation classify servers?**\nA: Local stdio servers become `stdio_servers`. Remote URLs containing `\u002Fsse` are classified as `sse_servers`; others become `shttp_servers`. Bearer tokens in an `Authorization` header are extracted into `api_key` where possible.\n\n**Q: Where is Zed configuration written now?**\nA: Ruler writes a `settings.json` in the project root (not the user home dir) and transforms MCP server definitions to Zed's `context_servers` format including `source: \"custom\"`.\n\n**Q: What changed about MCP initialization?**\nA: `ruler init` now only adds example MCP server sections to `ruler.toml` instead of creating `.ruler\u002Fmcp.json`. The JSON file is still consumed if present, but TOML servers win on name conflicts.\n\n**Q: Is Kiro supported?**\nA: Yes. Kiro receives concatenated rules at `.kiro\u002Fsteering\u002Fruler_kiro_instructions.md`.\n\n## Development\n\n### Setup\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler.git\ncd ruler\nnpm install\nnpm run build\n```\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n### Code Quality\n\n```bash\n# Run linting\nnpm run lint\n\n# Run formatting\nnpm run format\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\nFor bugs and feature requests, please [open an issue](https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues).\n\n## License\n\nMIT\n\n---\n\n© Eleanor Berger \n[ai.intellectronica.net](https:\u002F\u002Fai.intellectronica.net\u002F)\n","# Ruler：集中管理您的 AI 编码助手指令\n\n\u003Ctable style=\"width:100%\">\n \u003Ctr>\n \u003Ctd style=\"vertical-align: top;\">\n \u003Cp>\n \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\u003C\u002Fa>\n \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@intellectronica\u002Fruler\">\u003Cimg src=\"https:\u002F\u002Fbadge.fury.io\u002Fjs\u002F%40intellectronica%2Fruler.svg\" alt=\"npm version\">\u003C\u002Fa>\n \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg\" alt=\"License: MIT\">\n \u003C\u002Fp>\n \u003Cul>\n \u003Cli>\u003Cstrong>GitHub\u003C\u002Fstrong>: \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\">intellectronica\u002Fruler\u003C\u002Fa>\u003C\u002Fli>\n \u003Cli>\u003Cstrong>NPM\u003C\u002Fstrong>: \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@intellectronica\u002Fruler\">@intellectronica\u002Fruler\u003C\u002Fa>\u003C\u002Fli>\n \u003C\u002Ful>\n \u003Chr \u002F>\n \u003Cp>\n \u003Cem>动画由\u003Cstrong>\u003Ca href=\"https:\u002F\u002Felite-ai-assisted-coding.dev\u002F\">Elite AI-Assisted Coding\u003C\u002Fa>\u003C\u002Fstrong> 的 \u003Ca href=\"https:\u002F\u002Fisaacflath.com\u002F\">Isaac Flath\u003C\u002Fa> 制作\u003C\u002Fem> ➡︎\n \u003C\u002Fp>\n \u003C\u002Ftd>\n \u003Ctd style=\"vertical-align: top; width:33%;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fintellectronica_ruler_readme_4eb82d0447a4.gif\" alt=\"Ruler 演示\" style=\"width:300px; height:auto; display:block;\" \u002F>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n---\n\n> **测试版研究预览**\n>\n> - 请在您的环境中仔细测试此版本\n> - 如发现问题，请前往 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues 报告\n\n## 为什么选择 Ruler？\n\n随着团队规模的扩大，跨多个 AI 编码工具管理指令会变得复杂。不同的 AI 助手（如 GitHub Copilot、Claude、Cursor、Aider 等）需要各自的配置文件，这会导致：\n\n- **AI 工具之间的指导不一致**\n- **维护多个配置文件的重复工作**\n- **项目需求变化时的上下文偏差**\n- **新 AI 工具的上手难度增加**\n- **复杂的项目结构需要针对不同组件的特定上下文指令**\n\nRuler 通过提供所有 AI 助手指令的**单一可信源**来解决这些问题，并自动将这些指令分发到相应的配置文件中。借助**嵌套规则加载**功能，Ruler 能够处理复杂的项目结构，为不同组件提供特定于上下文的指令。\n\n## 核心功能\n\n- **集中式规则管理**：使用 Markdown 文件将所有 AI 指令存储在一个专用的 `.ruler\u002F` 目录中\n- **嵌套规则加载**：支持复杂的项目结构，允许为不同上下文设置多个 `.ruler\u002F` 目录\n- **自动分发**：Ruler 会将这些规则应用到受支持的 AI 助手的配置文件中\n- **目标明确的助手配置**：通过 `ruler.toml` 文件精确控制受影响的助手及其特定的输出路径\n- **MCP 服务器传播**：管理和分发模型上下文协议（MCP）服务器设置\n- **`.gitignore` 自动化**：自动生成的助手配置文件会自动排除在版本控制之外\n- **简洁的命令行界面**：提供易于使用的命令来初始化和应用配置\n\n## 支持的 AI 代理\n\n| 代理 | 规则文件(s) | MCP 配置 \u002F 备注 | 技能支持 \u002F 位置 |\n| ---------------------- | ---------------------------------------------- | ------------------------------------------------ | ------------------------- |\n| AGENTS.md | `AGENTS.md` | （伪代理，确保根目录存在 `AGENTS.md`） | - |\n| GitHub Copilot | `AGENTS.md` | `.vscode\u002Fmcp.json` | `.claude\u002Fskills\u002F` |\n| Claude Code | `CLAUDE.md` | `.mcp.json` | `.claude\u002Fskills\u002F` |\n| OpenAI Codex CLI | `AGENTS.md` | `.codex\u002Fconfig.toml` | `.codex\u002Fskills\u002F` |\n| Pi 编码代理 | `AGENTS.md` | - | `.pi\u002Fskills\u002F` |\n| Jules | `AGENTS.md` | - | - |\n| Cursor | `AGENTS.md` | `.cursor\u002Fmcp.json` | `.cursor\u002Fskills\u002F` |\n| Windsurf | `AGENTS.md` | `.windsurf\u002Fmcp_config.json` | `.windsurf\u002Fskills\u002F` |\n| Cline | `.clinerules` | - | - |\n| Crush | `CRUSH.md` | `.crush.json` | - |\n| Amp | `AGENTS.md` | - | `.agents\u002Fskills\u002F` |\n| Antigravity | `.agent\u002Frules\u002Fruler.md` | - | `.agent\u002Fskills\u002F` |\n| Amazon Q CLI | `.amazonq\u002Frules\u002Fruler_q_rules.md` | `.amazonq\u002Fmcp.json` | - |\n| Aider | `AGENTS.md`, `.aider.conf.yml` | `.mcp.json` | - |\n| Firebase Studio | `.idx\u002Fairules.md` | `.idx\u002Fmcp.json` | - |\n| Open Hands | `.openhands\u002Fmicroagents\u002Frepo.md` | `config.toml` | - |\n| Gemini CLI | `AGENTS.md` | `.gemini\u002Fsettings.json` | `.gemini\u002Fskills\u002F` |\n| Junie | `.junie\u002Fguidelines.md` | `.junie\u002Fmcp\u002Fmcp.json` | `.junie\u002Fskills\u002F` |\n| AugmentCode | `.augment\u002Frules\u002Fruler_augment_instructions.md` | - | - |\n| Kilo Code | `AGENTS.md` | `.kilocode\u002Fmcp.json` | `.claude\u002Fskills\u002F` |\n| OpenCode | `AGENTS.md` | `opencode.json` | `.opencode\u002Fskills\u002F` |\n| Goose | `.goosehints` | - | `.agents\u002Fskills\u002F` |\n| Qwen Code | `AGENTS.md` | `.qwen\u002Fsettings.json` | - |\n| RooCode | `AGENTS.md` | `.roo\u002Fmcp.json` | `.roo\u002Fskills\u002F` |\n| Zed | `AGENTS.md` | `.zed\u002Fsettings.json`（项目根目录，不在 $HOME） | - |\n| Trae AI | `.trae\u002Frules\u002Fproject_rules.md` | - | - |\n| Warp | `WARP.md` | - | - |\n| Kiro | `.kiro\u002Fsteering\u002Fruler_kiro_instructions.md` | `.kiro\u002Fsettings\u002Fmcp.json` | - |\n| Firebender | `firebender.json` | `firebender.json`（规则和 MCP 在同一文件中） | - |\n| Factory Droid | `AGENTS.md` | `.factory\u002Fmcp.json` | `.factory\u002Fskills\u002F` |\n| Mistral Vibe | `AGENTS.md` | `.vibe\u002Fconfig.toml` | `.vibe\u002Fskills\u002F` |\n| JetBrains AI Assistant | `.aiassistant\u002Frules\u002FAGENTS.md` | - | - |\n\n## 开始使用\n\n### 安装\n\n需要 Node.js `^20.19.0 || ^22.12.0 || >=23`。\n\n**全局安装（推荐用于 CLI 使用）：**\n\n```bash\nnpm install -g @intellectronica\u002Fruler\n```\n\n**使用 `npx`（用于一次性命令）：**\n\n```bash\nnpx @intellectronica\u002Fruler apply\n```\n\n### 项目初始化\n\n1. 导航到您的项目根目录\n2. 运行 `ruler init`\n3. 这将创建：\n\n- `.ruler\u002F` 目录\n- `.ruler\u002FAGENTS.md`：您规则的主要入门 Markdown 文件\n- `.ruler\u002Fruler.toml`：Ruler 的主配置文件（现在包含示例 MCP 服务器部分；旧版 `.ruler\u002Fmcp.json` 不再自动生成）\n- （可选的旧版回退）如果您之前使用过 `.ruler\u002Finstructions.md`，在缺少 `AGENTS.md` 时仍会生效。（之前的运行时警告已被移除。）\n\n此外，您还可以创建一个全局配置，在未找到本地 `.ruler\u002F` 目录时使用：\n\n```bash\nruler init --global\n```\n\n全局配置将被创建到 `$XDG_CONFIG_HOME\u002Fruler`（默认：`~\u002F.config\u002Fruler`）。\n\n## 核心概念\n\n### `.ruler\u002F` 目录\n\n这是您所有 AI 代理指令的中央枢纽：\n\n- **主要文件顺序与优先级**：\n 1. 如果存在，仓库根目录下的 `AGENTS.md`（位于 `.ruler\u002F` 外部）（优先级最高，会前置插入）\n 2. `.ruler\u002FAGENTS.md`（新的默认起始文件）\n 3. 旧版的 `.ruler\u002Finstructions.md`（仅当 `.ruler\u002FAGENTS.md` 不存在时使用；不再发出弃用警告）\n 4. 在 `.ruler\u002F` 及其子目录中按排序顺序发现的其余 `.md` 文件\n- **规则文件（`*.md`）**：从 `.ruler\u002F` 或 `$XDG_CONFIG_HOME\u002Fruler` 中递归发现，并按照上述顺序拼接。\n- **拼接标记**：每个文件的内容前都会添加 `\u003C!-- Source: \u003Crelative_path_to_md_file> -->`，以便追踪来源。\n- **`ruler.toml`**：Ruler 行为、代理选择、输出路径以及 MCP 服务器设置的主配置文件。\n- **`mcp.json`**：（旧版，已弃用）共享的 MCP 服务器设置——不再自动生成，但仍为向后兼容而保留。\n\n这种顺序设计允许您在根目录下保留一份简短但极具影响力的 `AGENTS.md` 文件（例如项目高层概要），同时将详细指导内容存放在 `.ruler\u002F` 中。\n\n### 嵌套规则加载\n\nRuler 现在支持通过 `--nested` 标志进行**嵌套规则加载**，从而为项目的不同部分提供特定于上下文的指令：\n\n```\nproject\u002F\n├── .ruler\u002F # 全局项目规则\n│ ├── AGENTS.md\n│ └── coding_style.md\n├── src\u002F\n│ └── .ruler\u002F # 组件特定规则\n│ └── api_guidelines.md\n├── tests\u002F\n│ └── .ruler\u002F # 测试特定规则\n│ └── testing_conventions.md\n└── docs\u002F\n └── .ruler\u002F # 文档规则\n └── writing_style.md\n```\n\n**工作原理**：\n\n- 发现项目层级中的所有 `.ruler\u002F` 目录。\n- 按照顺序加载并拼接每个目录中的规则。\n- 是否启用嵌套模式由以下优先级决定：\n 1. `ruler apply --nested`（或 `--no-nested`）具有最高优先级。\n 2. `ruler.toml` 中的 `nested = true` 设置。\n 3. 如果两者均未指定，则默认禁用。\n- 当运行处于嵌套模式时，下游配置会被强制保持 `nested = true`。如果子配置尝试将其禁用，Ruler 仍会维持嵌套处理，并在日志中发出警告。\n- 嵌套处理会传递每个目录自身的 MCP 包和配置设置，从而使生成的文件始终限定在其源目录范围内，同时被规范化回项目根目录。\n\n> [!CAUTION]\n> 嵌套模式目前处于实验阶段，未来版本可能会发生变化。CLI 会在首次检测到嵌套运行时记录此警告，以提醒您该行为可能随时间演进。\n\n**适用场景**：\n\n- 包含多个服务的单体代码库。\n- 具有明确组件划分的项目（如前端\u002F后端）。\n- 需要针对不同领域制定不同指令的团队。\n- 规范要求各异的复杂代码库。\n\n### 规则文件的最佳实践\n\n**粒度化**：将复杂的指令拆分为专注的 `.md` 文件：\n\n- `coding_style.md`\n- `api_conventions.md`\n- `project_architecture.md`\n- `security_guidelines.md`\n\n**规则文件示例（`.ruler\u002Fpython_guidelines.md`）**：\n\n```markdown\n# Python 项目指南\n\n## 通用风格\n\n- 所有 Python 代码应遵循 PEP 8 规范。\n- 所有函数签名及复杂变量应使用类型注解。\n- 函数应尽量简短，专注于单一任务。\n\n## 错误处理\n\n- 应使用具体的异常类型，而非通用的 `Exception`。\n- 记录错误时需包含上下文信息。\n\n## 安全性\n\n- 始终对用户输入进行验证和清理。\n- 注意潜在的注入漏洞。\n```\n\n## 使用方法：`apply` 命令\n\n### 主命令\n\n```bash\nruler apply [options]\n```\n\n`apply` 命令会在当前目录树中查找 `.ruler\u002F`，并读取第一个匹配项。若未找到此类目录，则会搜索 `$XDG_CONFIG_HOME\u002Fruler` 中的全局配置。\n\n### 选项\n\n| 选项 | 描述 |\n| ------------------------------ | ---------------------------------------------------------------------- |\n| `--project-root \u003Cpath>` | 项目根目录路径（默认：当前目录）。 |\n| `--agents \u003Cagent1,agent2,...>` | 以逗号分隔的目标代理名称列表（参见下方支持列表）。 |\n| `--config \u003Cpath>` | 自定义 `ruler.toml` 路径。 |\n| `--mcp` \u002F `--with-mcp` | 启用应用 MCP 服务器配置（默认：开启）。 |\n| `--no-mcp` | 禁用应用 MCP 服务器配置。 |\n| `--mcp-overwrite` | 覆盖原生 MCP 配置，而非合并。 |\n| `--gitignore` | 启用自动更新 `.gitignore` 文件（默认：开启）。 |\n| `--no-gitignore` | 禁用自动更新 `.gitignore` 文件。 |\n| `--gitignore-local` | 将管理的忽略条目写入 `.git\u002Finfo\u002Fexclude` 文件中，而非 `.gitignore`。 |\n| `--nested` | 启用嵌套规则加载（默认：继承配置设置或禁用）。 |\n| `--no-nested` | 即使配置中设置了 `nested = true`，也禁用嵌套规则加载。 |\n| `--backup` | 启用创建 `.bak` 备份文件（默认：开启）。 |\n| `--no-backup` | 禁用创建 `.bak` 备份文件。 |\n| `--skills` | 启用技能支持（实验性功能，默认：开启）。 |\n| `--no-skills` | 禁用技能支持。 |\n| `--dry-run` | 预览更改而不实际写入文件。 |\n| `--local-only` | 查找配置时跳过 `$XDG_CONFIG_HOME`。 |\n| `--verbose` \u002F `-v` | 在执行过程中显示详细输出。 |\n\n### 常见示例\n\n**为所有已配置的代理应用规则：**\n\n```bash\nruler apply\n```\n\n**仅为 GitHub Copilot 和 Claude 应用规则：**\n\n```bash\nruler apply --agents copilot,claude\n```\n\n**仅为 Firebase Studio 应用规则：**\n\n```bash\nruler apply --agents firebase\n```\n\n**仅为 Warp 应用规则：**\n\n```bash\nruler apply --agents warp\n```\n\n**仅为 Trae AI 应用规则：**\n\n```bash\nruler apply --agents trae\n```\n\n**仅为 RooCode 应用规则：**\n\n```bash\nruler apply --agents roo\n```\n\n**使用特定配置文件：**\n\n```bash\nruler apply --config .\u002Fteam-configs\u002Fruler.frontend.toml\n```\n\n**以详细模式应用规则：**\n\n```bash\nruler apply --verbose\n```\n\n**应用规则但跳过 MCP 和 `.gitignore` 更新：**\n\n```bash\nruler apply --no-mcp --no-gitignore\n```\n\n## 使用方法：`revert` 命令\n\n`revert` 命令可以安全地撤销由 `ruler apply` 所做的所有更改，将您的项目恢复到应用规则之前的初始状态。它会智能地从备份文件（`.bak` 文件）中恢复文件（如果存在），或者移除那些原本不存在的生成文件。\n\n### 为什么需要使用 `revert`？\n\n在尝试不同的规则配置或切换不同项目时，您可能希望：\n\n- **清空所有内容**：移除所有由 Ruler 生成的文件，以便重新开始。\n- **恢复原始文件**：将被修改的文件恢复为它们的原始状态。\n- **选择性清理**：仅移除特定代理的配置。\n- **安全实验**：在不用担心永久性更改的情况下试用 Ruler。\n\n### 主要命令\n\n```bash\nruler revert [选项]\n```\n\n### 选项\n\n| 选项 | 描述 |\n| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--project-root \u003C路径>` | 指定项目的根目录路径（默认为当前目录） |\n| `--agents \u003Cagent1,agent2,...>` | 以逗号分隔的代理名称列表，用于指定要还原的代理（agentsmd、aider、amazonqcli、amp、antigravity、augmentcode、claude、cline、codex、copilot、crush、cursor、factory、firebase、firebender、gemini-cli、goose、jetbrains-ai、jules、junie、kilocode、kiro、mistral、opencode、openhands、pi、qwen、roo、trae、warp、windsurf、zed） |\n| `--config \u003C路径>` | 自定义 `ruler.toml` 配置文件的路径 |\n| `--keep-backups` | 在恢复后保留备份文件（`.bak` 文件）（默认为不保留） |\n| `--dry-run` | 预览将要执行的更改，但不会实际还原文件 |\n| `--verbose` \u002F `-v` | 在执行过程中显示详细输出 |\n| `--local-only` | 仅搜索本地 `.ruler` 目录，忽略全局配置 |\n\n### 常见示例\n\n**还原所有 Ruler 更改：**\n\n```bash\nruler revert\n```\n\n**预览将要还原的内容（模拟运行）：**\n\n```bash\nruler revert --dry-run\n```\n\n**仅还原特定代理：**\n\n```bash\nruler revert --agents claude,copilot\n```\n\n**以详细模式还原：**\n\n```bash\nruler revert --verbose\n```\n\n**在还原后保留备份文件：**\n\n```bash\nruler revert --keep-backups\n```\n\n## 配置文件 (`ruler.toml`) 详解\n\n### 位置\n\n默认位于项目根目录下的 `.ruler\u002Fruler.toml`。可以通过 `--config` CLI 选项进行覆盖。\n\n### 完整示例\n\n```toml\n# 当未指定 --agents 时，默认运行的代理\n# 使用不区分大小写的子字符串匹配\ndefault_agents = [\"copilot\", \"claude\", \"aider\"]\n\n# --- 全局 MCP 服务器配置 ---\n[mcp]\n# 全局启用或禁用 MCP 传播（默认：启用）\nenabled = true\n# 全局合并策略：'merge' 或 'overwrite'（默认：'merge'）\nmerge_strategy = \"merge\"\n\n# --- MCP 服务器定义 ---\n[mcp_servers.filesystem]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fpath\u002Fto\u002Fproject\"]\n\n[mcp_servers.git]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol\u002Fserver-git\", \"--repository\", \".\"]\n\n[mcp_servers.remote_api]\nurl = \"https:\u002F\u002Fapi.example.com\"\n\n[mcp_servers.remote_api.headers]\nAuthorization = \"Bearer your-token\"\n\n# --- 全局 .gitignore 配置 ---\n[gitignore]\n# 启用或禁用自动更新 .gitignore（默认：启用）\nenabled = true\n# 将受管理的条目写入 .git\u002Finfo\u002Fexclude 而不是 .gitignore（默认：不启用）\nlocal = false\n\n# --- 代理特定配置 ---\n[agents.copilot]\nenabled = true\n\n[agents.claude]\nenabled = true\noutput_path = \"CLAUDE.md\"\n\n[agents.aider]\nenabled = true\noutput_path_instructions = \"AGENTS.md\"\noutput_path_config = \".aider.conf.yml\"\n\n# OpenAI Codex CLI 代理及 MCP 配置\n[agents.codex]\nenabled = true\noutput_path = \"AGENTS.md\"\noutput_path_config = \".codex\u002Fconfig.toml\"\n\n# Codex CLI 的代理特定 MCP 配置\n[agents.codex.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n[agents.firebase]\nenabled = true\noutput_path = \".idx\u002Fairules.md\"\n\n[agents.gemini-cli]\nenabled = true\n\n[agents.jules]\nenabled = true\n\n[agents.junie]\nenabled = true\noutput_path = \".junie\u002Fguidelines.md\"\n\n[agents.junie.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n# 代理特定的 MCP 配置\n[agents.cursor.mcp]\nenabled = true\nmerge_strategy = \"merge\"\n\n# 禁用特定代理\n[agents.windsurf]\nenabled = false\n\n[agents.kilocode]\nenabled = true\noutput_path = \"AGENTS.md\"\n\n[agents.warp]\nenabled = true\noutput_path = \"WARP.md\"\n```\n\n### 配置优先级\n\n1. **CLI 标志**（例如 `--agents`、`--no-mcp`、`--mcp-overwrite`、`--no-gitignore`）\n2. **`ruler.toml` 中的设置**（`default_agents`、特定代理设置、全局部分）\n3. **Ruler 的内置默认值**（所有代理均启用、标准输出路径、MCP 默认启用且采用 `'merge'` 策略）\n\n## MCP（模型上下文协议）服务器配置\n\nMCP 通过服务器配置为 AI 模型提供更广泛的上下文信息。Ruler 可以管理和分发这些设置到兼容的代理中。\n\n### TOML 配置（推荐）\n\n现在您可以在 `ruler.toml` 中直接使用 `[mcp_servers.\u003Cname>]` 语法定义 MCP 服务器：\n\n```toml\n# 全局 MCP 行为\n[mcp]\nenabled = true\nmerge_strategy = \"merge\" # 或者 \"overwrite\"\n\n# 本地（stdio）服务器\n[mcp_servers.filesystem]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\", \"\u002Fpath\u002Fto\u002Fproject\"]\n\n[mcp_servers.filesystem.env]\nAPI_KEY = \"your-api-key\"\n\n# 远程服务器\n[mcp_servers.search]\nurl = \"https:\u002F\u002Fmcp.example.com\"\n\n[mcp_servers.search.headers]\nAuthorization = \"Bearer your-token\"\n\"X-API-Version\" = \"v1\"\n```\n\n### 旧版 `.ruler\u002Fmcp.json`（已弃用）\n\n为了向后兼容，您仍然可以使用 JSON 格式；系统会发出警告，鼓励迁移到 TOML 格式。该文件在执行 `ruler init` 时将不再创建。\n\n```json\n{\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@modelcontextprotocol\u002Fserver-filesystem\",\n \"\u002Fpath\u002Fto\u002Fproject\"\n ]\n },\n \"git\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-git\", \"--repository\", \".\"]\n }\n }\n}\n```\n\n### 配置优先级\n\n当同时存在 TOML 和 JSON 配置时：\n\n1. **TOML 服务器优先**于同名的 JSON 服务器。\n2. **服务器配置合并**自两个来源（除非使用覆盖策略）。\n3. **弃用警告**会提示您迁移至 TOML 格式（每运行一次显示一次警告）。\n\n### 服务器类型\n\n**本地\u002Fstdio 服务器**需要 `command` 字段：\n\n```toml\n[mcp_servers.local_server]\ncommand = \"node\"\nargs = [\"server.js\"]\n\n[mcp_servers.local_server.env]\nDEBUG = \"1\"\n```\n\n**远程服务器**需要 `url` 字段（头部信息可选；对于 OpenHands，如果可能的话，会自动提取 Bearer 授权令牌）：\n\n```toml\n[mcp_servers.remote_server]\nurl = \"https:\u002F\u002Fapi.example.com\"\n\n[mcp_servers.remote_server.headers]\nAuthorization = \"Bearer token\"\n```\n\nRuler 使用此配置，并根据 `ruler.toml` 或 CLI 标志控制的 `merge`（默认）或 `overwrite` 策略来处理。\n\n**主目录安全性：** Ruler 绝不会在您的项目根目录之外写入 MCP 配置文件。任何涉及用户主目录的历史引用（例如 `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json` 或 `~\u002F.zed\u002Fsettings.json`）已被移除；仅针对项目本地路径进行操作。\n\n**OpenAI Codex CLI 注意事项：** 若要应用本地 Codex CLI 的 MCP 配置，请将 `CODEX_HOME` 环境变量设置为您项目的 `.codex` 目录：\n\n```bash\nexport CODEX_HOME=\"$(pwd)\u002F.codex\"\n```\n\n## 技能支持（实验性）\n\n**⚠️ 实验性功能：** 技能支持目前处于实验阶段。技能只会传播到具有原生技能支持的代理；其他代理则会被跳过，并显示警告。\n\nRuler 可以管理和传播技能到受支持的 AI 代理。技能存储在 `.ruler\u002Fskills\u002F` 目录中，当您运行 `ruler apply` 时，它们会自动分发给兼容的代理。\n\n### 工作原理\n\n技能是专门的知识包，能够通过领域特定的专业知识、工作流程或工具集成来扩展 AI 代理的能力。Ruler 会在您的 `.ruler\u002Fskills\u002F` 目录中发现技能，并将其传播到兼容的代理：\n\n- **具有原生技能支持的代理：** 技能会直接复制到每个代理的原生技能目录中：\n - **Claude Code：** `.claude\u002Fskills\u002F`\n - **GitHub Copilot：** `.claude\u002Fskills\u002F`（与 Claude Code 共享）\n - **Kilo Code：** `.claude\u002Fskills\u002F`（与 Claude Code 共享）\n - **OpenAI Codex CLI：** `.codex\u002Fskills\u002F`\n - **OpenCode：** `.opencode\u002Fskills\u002F`\n - **Pi Coding Agent：** `.pi\u002Fskills\u002F`\n - **Goose：** `.agents\u002Fskills\u002F`\n - **Amp：** `.agents\u002Fskills\u002F`（与 Goose 共享）\n - **Antigravity：** `.agent\u002Fskills\u002F`\n - **Factory Droid：** `.factory\u002Fskills\u002F`\n - **Mistral Vibe：** `.vibe\u002Fskills\u002F`\n - **Roo Code：** `.roo\u002Fskills\u002F`\n - **Gemini CLI：** `.gemini\u002Fskills\u002F`\n - **Junie：** `.junie\u002Fskills\u002F`\n - **Cursor：** `.cursor\u002Fskills\u002F`\n - **Windsurf：** `.windsurf\u002Fskills\u002F`\n\n### 技能目录结构\n\n技能可以采用扁平化或嵌套式组织：\n\n```\n.ruler\u002Fskills\u002F\n├── my-skill\u002F\n│ ├── SKILL.md # 必需：技能说明\u002F知识\n│ ├── helper.py # 可选：附加资源（脚本）\n│ └── reference.md # 可选：附加资源（文档）\n└── another-skill\u002F\n └── SKILL.md\n```\n\n每个技能必须包含：\n\n- `SKILL.md` - 主要技能文件，包含说明或知识库。\n\n技能还可以选择性地包含以下附加资源：\n\n- 带有补充文档的 Markdown 文件\n- Python、JavaScript 或其他脚本\n- 配置文件或数据\n\n### 配置\n\n技能支持默认启用，但可以通过以下方式控制：\n\n**CLI 标志：**\n\n```bash\n# 启用技能（默认）\nruler apply --skills\n\n# 禁用技能\nruler apply --no-skills\n```\n\n**`ruler.toml` 中的配置：**\n\n```toml\n[skills]\nenabled = true # 或 false 以禁用\n```\n\n### 非原生代理\n\n如果您为不支持原生技能的代理运行 Ruler，Ruler 将记录警告，并跳过对这些代理的技能传播。\n\n### `.gitignore` 集成\n\n当技能支持启用且 `.gitignore` 集成生效时，Ruler 会自动将以下目录添加到您管理的 Ruler 区块内的 `.gitignore` 文件中：\n\n- `.claude\u002Fskills\u002F`（适用于 Claude Code、GitHub Copilot 和 Kilo Code）\n- `.codex\u002Fskills\u002F`（适用于 OpenAI Codex CLI）\n- `.opencode\u002Fskills\u002F`（适用于 OpenCode）\n- `.pi\u002Fskills\u002F`（适用于 Pi Coding Agent）\n- `.agents\u002Fskills\u002F`（适用于 Goose 和 Amp）\n- `.agent\u002Fskills\u002F`（适用于 Antigravity）\n- `.factory\u002Fskills\u002F`（适用于 Factory Droid）\n- `.vibe\u002Fskills\u002F`（适用于 Mistral Vibe）\n- `.roo\u002Fskills\u002F`（适用于 Roo Code）\n- `.gemini\u002Fskills\u002F`（适用于 Gemini CLI）\n- `.junie\u002Fskills\u002F`（适用于 Junie）\n- `.cursor\u002Fskills\u002F`（适用于 Cursor）\n- `.windsurf\u002Fskills\u002F`（适用于 Windsurf）\n\n### 要求\n\n- **对于具有原生技能支持的代理**（Claude Code、GitHub Copilot、Kilo Code、OpenAI Codex CLI、OpenCode、Pi Coding Agent、Goose、Amp、Antigravity、Factory Droid、Mistral Vibe、Roo Code、Gemini CLI、Junie、Cursor、Windsurf）：无需额外要求。\n\n### 验证\n\nRuler 会对发现的技能进行验证，并对以下情况发出警告：\n\n- 缺少必需文件（`SKILL.md`）\n- 目录结构无效（没有 `SKILL.md` 且没有子技能）\n\n警告不会阻止传播，但有助于识别潜在问题。\n\n### 模拟运行模式\n\n在不进行实际更改的情况下测试技能传播：\n\n```bash\nruler apply --dry-run\n```\n\n这将显示哪些技能会被复制。\n\n### 示例工作流程\n\n```bash\n# 1. 向您的项目添加一个技能\nmkdir -p .ruler\u002Fskills\u002Fmy-skill\ncat > .ruler\u002Fskills\u002Fmy-skill\u002FSKILL.md \u003C\u003C 'EOF'\n# 我的自定义技能\n\n此技能提供了关于...的专业知识。\n\n## 使用方法\n\n在处理该项目时，请始终遵循以下指南：\n- 所有新代码均使用 TypeScript\n- 为所有功能编写测试\n- 遵循现有代码风格\nEOF\n\n# 2. 应用到所有智能体（技能默认启用）\nruler apply\n\n# 3. 技能现在可供兼容的智能体使用：\n# - Claude Code、GitHub Copilot 和 Kilo Code：.claude\u002Fskills\u002Fmy-skill\u002F\n# - OpenAI Codex CLI：.codex\u002Fskills\u002Fmy-skill\u002F\n# - OpenCode：.opencode\u002Fskills\u002Fmy-skill\u002F\n# - Pi 编码智能体：.pi\u002Fskills\u002Fmy-skill\u002F\n# - Goose 和 Amp：.agents\u002Fskills\u002Fmy-skill\u002F\n# - Antigravity：.agent\u002Fskills\u002Fmy-skill\u002F\n# - Factory Droid：.factory\u002Fskills\u002Fmy-skill\u002F\n# - Mistral Vibe：.vibe\u002Fskills\u002Fmy-skill\u002F\n# - Roo Code：.roo\u002Fskills\u002Fmy-skill\u002F\n# - Gemini CLI：.gemini\u002Fskills\u002Fmy-skill\u002F\n# - Junie：.junie\u002Fskills\u002Fmy-skill\u002F\n# - Cursor：.cursor\u002Fskills\u002Fmy-skill\u002F\n# - Windsurf：.windsurf\u002Fskills\u002Fmy-skill\u002F\n```\n\n## `.gitignore` 集成\n\nRuler 会自动管理您的 `.gitignore` 文件，以确保生成的智能体配置文件不会被纳入版本控制。\n\n### 工作原理\n\n- 在项目根目录创建或更新 `.gitignore`\n- 将路径添加到由 `# START Ruler Generated Files` 和 `# END Ruler Generated Files` 标记的受管区域\n- 保留该区域之外的现有内容\n- 按字母顺序对路径进行排序，并使用相对的 POSIX 风格路径\n\n### 示例 `.gitignore` 部分（示例——实际列表取决于已启用的智能体）\n\n```gitignore\n# 您现有的规则\nnode_modules\u002F\n*.log\n\n# START Ruler Generated Files\n.aider.conf.yml\n.clinerules\nAGENTS.md\nCLAUDE.md\n# END Ruler Generated Files\n\ndist\u002F\n```\n\n### 控制选项\n\n- **CLI 标志**：`--gitignore`、`--no-gitignore`、`--gitignore-local`、`--no-gitignore-local`\n- **配置**：`ruler.toml` 中的 `[gitignore].enabled` 和 `[gitignore].local`\n- **默认值**：启用\n\n## 实际使用场景\n\n### 场景 1：快速入门\n\n```bash\n# 在您的项目中初始化 Ruler\ncd your-project\nruler init\n\n# 编辑生成的文件\n# - 将编码规范添加到 .ruler\u002FAGENTS.md（或继续添加其他 .md 文件）\n# - 如有必要，自定义 .ruler\u002Fruler.toml\n\n# 将规则应用到所有 AI 智能体\nruler apply\n```\n\n### 场景 2：具有嵌套规则的复杂项目\n\n对于包含多个组件或服务的大型项目，可以启用嵌套规则加载，使每个目录都保留自己的规则和 MCP 包：\n\n```bash\n# 设置嵌套的 .ruler 目录\nmkdir -p src\u002F.ruler tests\u002F.ruler docs\u002F.ruler\n\n# 添加组件特定的说明\necho \"# API 设计指南\" > src\u002F.ruler\u002Fapi_rules.md\necho \"# 测试最佳实践\" > tests\u002F.ruler\u002Ftest_rules.md\necho \"# 文档标准\" > docs\u002F.ruler\u002Fdocs_rules.md\n```\n\n```toml\n# .ruler\u002Fruler.toml\nnested = true\n```\n\n```bash\n# CLI 会从 ruler.toml 继承嵌套模式\nruler apply --verbose\n\n# 可随时通过 CLI 覆盖\nruler apply --no-nested\n```\n\n这样可以在保持根目录 `.ruler\u002F` 中全局规则的同时，为项目的不同部分创建特定于上下文的说明。嵌套运行会自动确保每个嵌套配置都处于启用状态，即使子目录尝试将其禁用。\n\n> [!NOTE]\n> 第一次执行嵌套处理时，CLI 会打印“嵌套模式为实验性功能，未来版本可能会更改。”预计在后续版本中会有进一步改进。\n\n### 场景 3：团队标准化\n\n1. 创建 `.ruler\u002Fcoding_standards.md`、`.ruler\u002Fapi_usage.md`\n2. 将 `.ruler` 目录提交到您的仓库\n3. 团队成员拉取更改并运行 `ruler apply` 来更新他们本地的 AI 智能体配置。\n\n### 场景 4：针对项目的特定上下文使用 AI\n\n1. 在 `.ruler\u002Fproject_overview.md` 中详细说明项目的架构\n2. 在 `.ruler\u002Fdata_models.md` 中描述主要的数据结构\n3. 运行 `ruler apply` 以帮助 AI 工具提供更相关的建议。\n\n### 与 NPM 脚本集成\n\n```json\n{\n \"scripts\": {\n \"ruler:apply\": \"ruler apply\",\n \"dev\": \"npm run ruler:apply && your_dev_command\",\n \"precommit\": \"npm run ruler:apply\"\n }\n}\n```\n\n### 与 GitHub Actions 集成\n\n```yaml\n# .github\u002Fworkflows\u002Fruler-check.yml\nname: 检查 Ruler 配置\non:\n pull_request:\n paths: ['.ruler\u002F**']\n\njobs:\n check-ruler:\n runs-on: ubuntu-latest\n steps:\n - uses: actions\u002Fcheckout@v4\n - uses: actions\u002Fsetup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n\n - name: 安装 Ruler\n run: npm install -g @intellectronica\u002Fruler\n\n - name: 应用 Ruler 配置\n run: ruler apply --no-gitignore\n\n - name: 检查是否有未提交的更改\n run: |\n if [[ -n $(git status --porcelain) ]]; then\n echo \"::error::Ruler 配置不同步！\"\n echo \"请在本地运行 'ruler apply' 并提交更改。\"\n exit 1\n fi\n```\n\n## 故障排除\n\n### 常见问题\n\n**“无法找到模块”错误：**\n\n- 确保已全局安装 Ruler：`npm install -g @intellectronica\u002Fruler`\n- 或者使用 `npx @intellectronica\u002Fruler`\n\n**权限拒绝错误：**\n\n- 在 Unix 系统上，全局安装可能需要 `sudo`\n\n**智能体文件未更新：**\n\n- 检查智能体是否在 `ruler.toml` 中已启用\n- 确认智能体未被 `--agents` 标志排除\n- 使用 `--verbose` 查看详细的执行日志\n\n**配置验证错误：**\n\n- Ruler 现在会验证 `ruler.toml` 的格式，并显示具体的错误信息\n- 检查所有配置值是否符合预期的类型和格式\n\n### 调试模式\n\n使用 `--verbose` 标志查看详细的执行日志：\n\n```bash\nruler apply --verbose\n```\n\n这将显示：\n\n- 配置加载详情\n- 智能体选择逻辑\n- 文件处理信息\n- MCP 配置步骤\n\n## 常见问题解答\n\n**问：我可以为不同的代理使用不同的规则吗？** \n答：目前，所有代理都会收到相同的拼接规则。如果需要针对特定代理的指令，请在规则文件中添加类似“## GitHub Copilot 特定”或“## Aider 配置”的部分。\n\n**问：如何为项目的不同部分设置不同的指令？** \n答：可以通过在 `ruler.toml` 中设置 `nested = true`，或者通过传递 `ruler apply --nested` 来启用嵌套模式。CLI 默认继承配置设置，但如果需要在某次运行中禁用嵌套模式，可以使用 `--no-nested` 选项。启用嵌套模式后，Ruler 会从目录层次结构中的每个 `.ruler\u002F` 目录加载规则（以及 MCP 设置），并强制子配置保持嵌套状态。如果发生任何嵌套处理，Ruler 还会记录一条警告：“嵌套模式处于实验阶段，未来版本可能会发生变化。”\n\n**问：如何临时禁用某个代理的 Ruler 功能？** \n答：可以在 `ruler.toml` 的 `[agents.agentname]` 下将 `enabled = false`，或者使用 `--agents` 标志来指定您希望启用的代理。\n\n**问：我现有的代理配置文件会怎样？** \n答：Ruler 在覆盖任何现有文件之前，会先创建带有 `.bak` 扩展名的备份文件。\n\n**问：我可以在 CI\u002FCD 管道中运行 Ruler 吗？** \n答：可以！在 CI 中使用 `ruler apply --no-gitignore` 可以避免修改 `.gitignore` 文件。请参阅上面的 GitHub Actions 示例。\n\n**问：如何从使用 `instructions.md` 的旧版本迁移？** \n答：只需将 `.ruler\u002Finstructions.md` 重命名为 `.ruler\u002FAGENTS.md`（推荐）。如果您保留了旧版文件而未提供 `AGENTS.md`，Ruler 仍会使用它（但不会发出旧版弃用警告）。如果同时存在两者，则优先使用 `AGENTS.md`；旧版文件的内容仍会在之后被拼接进来。\n\n**问：OpenHands MCP 传播如何对服务器进行分类？** \n答：本地标准输入输出服务器会被归类为 `stdio_servers`。包含 `\u002Fsse` 的远程 URL 被归类为 `sse_servers`；其他则被归类为 `shttp_servers`。如果可能的话，还会从 `Authorization` 头中提取 Bearer 令牌，并将其放入 `api_key` 字段中。\n\n**问：Zed 的配置现在写在哪里？** \n答：Ruler 会在项目根目录（而非用户主目录）下生成一个 `settings.json` 文件，并将 MCP 服务器定义转换为 Zed 的 `context_servers` 格式，其中包含 `source: \"custom\"`。\n\n**问：MCP 初始化有哪些变化？** \n答：`ruler init` 现在仅会在 `ruler.toml` 中添加示例 MCP 服务器部分，而不再创建 `.ruler\u002Fmcp.json` 文件。如果该 JSON 文件存在，仍然会被读取，但在名称冲突时，`ruler.toml` 中的服务器配置会优先生效。\n\n**问：Kiro 是否受支持？** \n答：是的。Kiro 会在 `.kiro\u002Fsteering\u002Fruler_kiro_instructions.md` 文件中接收到拼接后的规则。\n\n## 开发\n\n### 设置\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler.git\ncd ruler\nnpm install\nnpm run build\n```\n\n### 测试\n\n```bash\n# 运行所有测试\nnpm test\n\n# 运行带覆盖率的测试\nnpm run test:coverage\n\n# 以监听模式运行测试\nnpm run test:watch\n```\n\n### 代码质量\n\n```bash\n# 运行代码检查\nnpm run lint\n\n# 运行代码格式化\nnpm run format\n```\n\n## 贡献\n\n欢迎贡献！请按照以下步骤操作：\n\n1. 分支仓库\n2. 创建功能分支\n3. 进行更改\n4. 为新功能添加测试\n5. 确保所有测试通过\n6. 提交拉取请求\n\n如发现错误或有功能需求，请[提交问题](https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues)。\n\n## 许可证\n\nMIT\n\n---\n\n© 埃莉诺·伯格 \n[ai.intellectronica.net](https:\u002F\u002Fai.intellectronica.net\u002F)","# Ruler 快速上手指南\n\nRuler 是一个用于集中管理 AI 编程助手指令的工具。它允许你将所有 AI Agent（如 GitHub Copilot、Claude Code、Cursor 等）的配置规则统一存储在 `.ruler\u002F` 目录中，并自动分发到各个工具对应的配置文件中，解决多工具配置不一致和维护繁琐的问题。\n\n## 环境准备\n\n- **操作系统**：支持 Windows、macOS、Linux\n- **运行时依赖**：需要安装 Node.js\n - 版本要求：`^20.19.0` 或 `^22.12.0` 或 `>=23`\n- **前置检查**：确保终端中可以正常执行 `node -v` 和 `npm -v`\n\n> **提示**：国内用户建议使用 [Node.js 国内镜像](https:\u002F\u002Fnpmmirror.com\u002Fmirrors\u002Fnode\u002F) 安装，或使用 `nvm` 进行版本管理。\n\n## 安装步骤\n\n你可以选择全局安装（推荐）或按需使用 `npx`。\n\n### 方式一：全局安装（推荐）\n\n适用于频繁使用 CLI 命令的场景。\n\n```bash\nnpm install -g @intellectronica\u002Fruler\n```\n\n> **加速建议**：国内用户可配置 npm 镜像源加速安装：\n> ```bash\n> npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n> npm install -g @intellectronica\u002Fruler\n> ```\n\n### 方式二：使用 npx（免安装）\n\n适用于临时试用或单次执行场景。\n\n```bash\nnpx @intellectronica\u002Fruler apply\n```\n\n## 基本使用\n\n### 1. 初始化项目\n\n在项目根目录下运行以下命令，生成默认的配置文件结构：\n\n```bash\nruler init\n```\n\n执行后将创建：\n- `.ruler\u002F` 目录：存放所有 AI 指令的中心仓库\n- `.ruler\u002FAGENTS.md`：主要的规则文件（Markdown 格式）\n- `.ruler\u002Fruler.toml`：Ruler 的主配置文件，用于定义目标 Agent 和 MCP 设置\n\n### 2. 编写规则\n\n编辑 `.ruler\u002FAGENTS.md` 文件，填入你希望 AI 助手遵守的通用指令。例如：\n\n```markdown\n# 项目规范\n- 请使用 TypeScript 编写代码\n- 所有函数必须包含 JSDoc 注释\n- 禁止使用任何已废弃的 API\n```\n\n你也可以在 `.ruler\u002F` 下创建多个 `.md` 文件（如 `coding_style.md`、`security_rules.md`），Ruler 会自动按顺序合并它们。\n\n### 3. 应用配置\n\n运行以下命令，将规则自动分发到项目中已检测到的 AI 工具配置文件中：\n\n```bash\nruler apply\n```\n\nRuler 会根据项目中的工具类型（如 Cursor、Copilot、Aider 等），自动更新对应的配置文件（如 `AGENTS.md`、`.clinerules`、`.cursor\u002Fmcp.json` 等）。\n\n### 4. 进阶：嵌套规则（可选）\n\n对于大型项目，可以在子目录中创建局部的 `.ruler\u002F` 文件夹以定义特定上下文的规则：\n\n```bash\n# 在 src\u002F 目录下创建特定规则\nmkdir -p src\u002F.ruler\necho \"API 层专用规范...\" > src\u002F.ruler\u002Fapi_guidelines.md\n\n# 启用嵌套模式应用规则\nruler apply --nested\n```\n\n此功能允许不同模块拥有独立的 AI 行为指导，同时保持全局规则的一致性。","某中型电商团队在重构支付模块时，需同时协调后端、前端及测试人员使用 GitHub Copilot、Claude Code 和 Cursor 等多种 AI 编程助手进行开发。\n\n### 没有 ruler 时\n- **规则维护繁琐**：团队需在 `.vscode\u002F`、根目录及各子模块中手动维护多份重复的 `AGENTS.md` 或 `CLAUDE.md` 文件，一旦安全规范变更，修改工作量巨大。\n- **输出风格割裂**：由于缺乏统一约束，Copilot 生成的代码偏向简洁，而 Claude 倾向于详细注释，导致合并后的代码库风格混乱，增加 Review 成本。\n- **上下文配置易错**：针对不同微服务组件的特定指令（如“支付模块严禁硬编码密钥”）容易遗漏配置到某个工具的专属文件中，引发合规风险。\n- **新人接入困难**：新成员配置本地 AI 环境时，常因漏配某个代理的规则文件或 MCP 服务器地址，导致 AI 产出不符合项目标准。\n\n### 使用 ruler 后\n- **单一事实来源**：团队只需在 `.ruler\u002F` 目录下编写一套 Markdown 规则，ruler 即可自动将其分发同步至所有支持的 AI 工具配置文件中。\n- **标准化输出**：通过中央化指令，确保所有代理生成的代码均遵循统一的命名规范、注释风格及安全策略，显著提升代码一致性。\n- **精准上下文控制**：利用 ruler 的嵌套规则加载功能，可在支付子目录单独定义特定约束，自动覆盖全局规则，确保敏感模块的指令精准生效。\n- **一键环境初始化**：新成员仅需运行 ruler 初始化命令，即可自动完成所有 AI 代理的配置与 `.gitignore` 设置，实现分钟级无缝接入。\n\nruler 通过将分散的 AI 指令收敛为单一真理源，彻底解决了多代理协作中的配置碎片化难题，让团队能专注于业务逻辑而非工具维护。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fintellectronica_ruler_0be033e4.png","intellectronica","Eleanor Berger","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fintellectronica_6b3cec31.jpg",null,"Zürich","https:\u002F\u002Fintellectronica.net\u002F","https:\u002F\u002Fgithub.com\u002Fintellectronica",[81,85],{"name":82,"color":83,"percentage":84},"TypeScript","#3178c6",98.8,{"name":86,"color":87,"percentage":88},"JavaScript","#f1e05a",1.2,2646,137,"2026-04-19T07:03:57","MIT","Linux, macOS, Windows","未说明",{"notes":96,"python":94,"dependencies":97},"该工具是一个基于 Node.js 的命令行界面 (CLI)，用于集中管理 AI 编码助手的指令。它不需要 GPU 或大量内存，主要通过 npm 安装。支持全局配置和本地项目配置，并具备嵌套规则加载功能（实验性）。",[98],"Node.js ^20.19.0 || ^22.12.0 || >=23",[13,15,35,14],[101,102,103,104,105,106,107,108,109],"agents","ai","aider","claude-code","codex","cursor","github-copilot","vibe-coding","windsurf","2026-03-27T02:49:30.150509","2026-04-20T04:05:07.833792",[113,118,123,128,133,138],{"id":114,"question_zh":115,"answer_zh":116,"source_url":117},43708,"如何为 Copilot 或 Cursor 应用特定文件的规则？","不需要单独为每个文件应用规则，直接使用“技能（skills）”进行匹配即可。对于 Cursor，最新版本已原生支持 `.mdc` frontmatter（包括 globs 和 alwaysApply），规则会自动复制到 `.cursor\u002Frules\u002F` 目录并转换为 Claude 技能。其他代理会将 globs 附加到技能描述中。","https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues\u002F5",{"id":119,"question_zh":120,"answer_zh":121,"source_url":122},43709,"如何禁用 skillz MCP 服务器以使用代理的原生技能支持？","请尝试使用最新版本的 Ruler。目前 Copilot 和 Cursor 都已原生支持技能，不再需要 skillz MCP 服务器。如果您在配置了多个代理（如 `default_agents = [\"copilot\", \"cursor\", \"claude\"]`）时仍然看到 skillz MCP 被注册，这可能是旧版本的遗留行为或 Bug，升级后若问题依旧存在请提交 Bug 报告。如果仅使用 Claude 作为代理，默认不会添加此 MCP 配置。","https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues\u002F344",{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},43710,"Cursor 是否支持使用 AGENTS.md 文件？","是的，Cursor 现已列出在 https:\u002F\u002Fagents.md\u002F 的支持列表中。测试表明，当生成 AGENTS.md 文件时，Cursor 能够读取并遵循其中的指令。如果 Cursor 未读取该文件，这通常是 Cursor 自身的问题而非 Ruler 的问题，建议向 Cursor 提交 Bug 报告。此外，也可以保留 CURSOR.md 用于 Cursor 特有规则，同时使用 AGENTS.md 作为多代理通用规则。","https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues\u002F130",{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},43711,"能否同时使用全局指令和项目本地指令？","用户普遍希望将全局指令（位于 `~\u002F.config\u002Fruler`）与项目本地指令（位于 `.ruler`）合并应用到 `AGENTS.md` 或 `CLAUDE.md` 中。这种级联行为是常见的（类似于 Claude 加载 `CLAUDE.md` 的方式），高层级的文件提供基础，更具体的文件在其上构建。虽然早期版本可能未完全实现自动合并，但这是社区强烈需求的功能，用于统一风格指南和错误处理策略等通用规则。","https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues\u002F51",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},43712,"是否支持合并多个 MCP 配置文件（如全局和个人配置）？","目前官方尚未完全支持自动合并子目录中的 MCP 文件（例如将 `.ruler\u002Flocal\u002Fmcp.json` 与主 `.ruler\u002Fmcp.json` 合并）。维护者表示愿意审查设计方案，但担心增加复杂性。当前实际上只能有效使用一个主要的 MCP 文件。如果有具体且不增加过多复杂度的设计方案，可以提交 PR 供考虑。","https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fissues\u002F91",{"id":139,"question_zh":140,"answer_zh":141,"source_url":127},43713,"Amazon Q 是否支持特定的指令文件格式？","是的，Amazon Q 现在支持 `AmazonQ.md` 文件。除了通用的 `AGENTS.md` 外，建议保留特定代理的文件（如 `CURSOR.md`, `GEMINI.md`, `QWEN.md`）以处理特定于该代理的规则，同时使用 `AGENTS.md` 处理跨代理的通用规则。",[143,148,153,158,163,168,173,178,183,188,193,198,203,208,213,218,223,228,233,238],{"id":144,"version":145,"summary_zh":146,"released_at":147},350509,"v0.3.38","## 变更内容\n* （功能）由 @CNTRS 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F405 中添加了 Windsurf 原生技能支持\n\n## 新贡献者\n* @CNTRS 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F405 中完成了首次贡献\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.37...v0.3.38","2026-03-30T05:48:44",{"id":149,"version":150,"summary_zh":151,"released_at":152},350510,"v0.3.37","## 变更内容\n* 添加 Junie 原生技能传播至 `.junie\u002Fskills`，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F396 中完成。\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.36...v0.3.37","2026-03-11T10:13:31",{"id":154,"version":155,"summary_zh":156,"released_at":157},350511,"v0.3.36","## 变更内容\n* 修复（README）：添加缺失的 `jetbrains-ai`，以恢复 `--agents` 列表，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F390 中完成\n* 从 README 中移除 Junie MCP 的实现细节，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F394 中完成\n\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.35...v0.3.36","2026-03-11T08:43:50",{"id":159,"version":160,"summary_zh":161,"released_at":162},350512,"v0.3.35","## 变更内容\n* 添加可配置的本地忽略目标（`.git\u002Finfo\u002Fexclude`），用于忽略由 @Copilot 生成的 Ruler 条目，详见 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F389\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.34...v0.3.35","2026-02-19T15:45:16",{"id":164,"version":165,"summary_zh":166,"released_at":167},350513,"v0.3.34","## 变更内容\n* 修复：由 @teszerrakt 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F383 中将 OpenCode 技能路径从 .opencode\u002Fskill 修正为 .opencode\u002Fskills\n\n## 新贡献者\n* @teszerrakt 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F383 中完成了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.33...v0.3.34","2026-02-11T14:41:26",{"id":169,"version":170,"summary_zh":171,"released_at":172},350514,"v0.3.33","## 变更内容\n* 由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F381 中将技能传播范围限定为选定的代理\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.32...v0.3.33","2026-02-09T12:58:19",{"id":174,"version":175,"summary_zh":176,"released_at":177},350515,"v0.3.32","## 变更内容\n* 修复 `.ruler\u002F` 目录中符号链接的 `.md` 文件在使用 @Copilot 时被静默跳过的问题，详见 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F378\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.31...v0.3.32","2026-02-07T07:17:47",{"id":179,"version":180,"summary_zh":181,"released_at":182},350516,"v0.3.31","## 变更内容\n* 文档补充了 --skills CLI 选项，并由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F372 中澄清了 MCP 配置状态。\n* 由 @Codex 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F374 中实现了在发现 .ruler 目录时跳过嵌套的 Git 仓库。\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.30...v0.3.31","2026-02-05T11:33:20",{"id":184,"version":185,"summary_zh":186,"released_at":187},350517,"v0.3.30","## 变更内容\n* 由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F371 中实现了 Codex CLI 的远程 MCP 支持以及 TOML 配置合并功能。\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.29...v0.3.30","2026-02-04T08:23:07",{"id":189,"version":190,"summary_zh":191,"released_at":192},350518,"v0.3.29","## 变更内容\n* 在 README 中添加 Document Factory Droid 代理，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F364 中完成\n* 修复 GitHub Actions 示例中的 Node.js 版本，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F368 中完成\n* 添加对 JetBrains AI Assistant 规则输出的支持，由 @Copilot 在 https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F369 中完成\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.28...v0.3.29","2026-01-30T16:04:48",{"id":194,"version":195,"summary_zh":196,"released_at":197},350519,"v0.3.28","## What's Changed\r\n* Align Node engine support with yargs v18 for CLI runtime by @Copilot in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F362\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.27...v0.3.28","2026-01-19T13:39:48",{"id":199,"version":200,"summary_zh":201,"released_at":202},350520,"v0.3.27","## What's Changed\r\n* Add Factory Droid agent support for MCP and skills propagation by @Copilot in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F359\r\n* Use AGENTS.md as Kilo Code rules output by @Copilot in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F360\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.26...v0.3.27","2026-01-19T12:10:45",{"id":204,"version":205,"summary_zh":206,"released_at":207},350521,"v0.3.26","## What's Changed\r\n* Add native skills support for Antigravity by @Copilot in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F357\r\n* Remove Skillz MCP server functionality and update documentation by @Copilot in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F358\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.25...v0.3.26","2026-01-19T09:14:01",{"id":209,"version":210,"summary_zh":211,"released_at":212},350522,"v0.3.25","## What's Changed\r\n* Scope Skillz MCP injection to MCP-only agents; make Skillz config portable by @Copilot in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F356\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.24...v0.3.25","2026-01-18T13:28:16",{"id":214,"version":215,"summary_zh":216,"released_at":217},350523,"v0.3.24","## What's Changed\r\n* Add MCP timeout parsing and OpenCode support with warnings for other agents by @Codex in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F350\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.23...v0.3.24","2026-01-14T15:17:46",{"id":219,"version":220,"summary_zh":221,"released_at":222},350524,"v0.3.23","## What's Changed\r\n* Implement native skills support for agents by @intellectronica in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F347\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.22...v0.3.23","2026-01-09T18:16:48",{"id":224,"version":225,"summary_zh":226,"released_at":227},350525,"v0.3.22","## What's Changed\r\n* Add Pi Coding Agent support by @elyase in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F345\r\n\r\n## New Contributors\r\n* @elyase made their first contribution in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F345\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.21...v0.3.22","2026-01-09T16:36:49",{"id":229,"version":230,"summary_zh":231,"released_at":232},350526,"v0.3.21","## What's Changed\n* Fix #337: Strip type field from Gemini CLI MCP configurations by @Claude in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F338\n* Guard against running Ruler from inside a .ruler directory by @Codex in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F339\n\n## New Contributors\n* @Codex made their first contribution in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F339\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.20...v0.3.21","2025-12-27T16:32:39",{"id":234,"version":235,"summary_zh":236,"released_at":237},350527,"v0.3.20","## What's Changed\r\n* Add Mistral Vibe CLI support by @intellectronica in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F334\r\n* Implement native skills support for Mistral Vibe by @intellectronica in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F335\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.19...v0.3.20","2025-12-25T16:48:40",{"id":239,"version":240,"summary_zh":241,"released_at":242},350528,"v0.3.19","## What's Changed\r\n* Add native skills support for OpenCode and Goose by @Claude in https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fpull\u002F332\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fintellectronica\u002Fruler\u002Fcompare\u002Fv0.3.18...v0.3.19","2025-12-24T08:33:04"]