@shindou/rules-cli

v0.1.13

Published

7 days ago

Manage and sync AI Agent rules across 30+ coding assistants via symlink

0High
0Medium
0Low

⚡ Rules CLI (@shindou/rules-cli)

Rules CLI 是一个为多种 AI 编码助手设计的规则管理工具。它可以把同一套 Rules 指令集统一存放在本地 store 中，并一键同步到 Cursor、Claude Code、Codex、Gemini CLI、Antigravity 等助手，减少重复维护不同配置文件的成本。

✨ 特性

🖥️ 沉浸式图形化 Web UI：内置基于现代化 Vue 3 SFC 与 Tailwind CSS 构筑的 Web 控制台 (rules ui)，支持零配置服务拉起与系统默认浏览器自启交互管理。
🚀 一键创建与应用：快速创建规则模板，并应用到指定 AI 助手。
📦 多助手适配：支持目录型规则和单文件注入型规则两种模式。
🗺️ 地图式规则入口：单文件型助手只写入精简入口地图，详细内容同步到 docs/ 等引用目录。
🔗 智能共享：目录型助手默认使用符号链接（Symlink），一份规则多处共享。
🔍 远程搜索与下载：支持 GitHub owner/repo、任意 Git URL 规则源，也支持从 cursor.directory 搜索和下载规则。
☁️ 远程仓库发布：支持将本地 store 中的规则发布到 GitHub、GitLab、Gitee 或自建 Git 仓库，并保留远程仓库内其他文件。
🧭 作用域清晰：支持项目级和全局级 store / applied rules。
🧾 手写规则可见：rules list 会显示已有的手写单文件规则，并标记为 manual。
🗑️ 交互式移除：支持从已应用规则或 store 中交互式选择并删除；引用文件删除后会自动清理空目录。
🛠️ 高度可配置：支持 .rulesrc 配置默认 agents、scope 和远程 sources。

🚀 安装

推荐使用 pnpm 进行全局安装：

pnpm add -g @shindou/rules-cli

本地开发：

pnpm install
pnpm build

安装完成后，通过 rules 命令调用。

💡 快速上手

1. 初始化配置

rules init
rules init --project

2. 创建规则

rules create use-chinese
rules c use-pnpm --project

3. 应用规则到助手

rules apply use-chinese
rules a use-chinese --agent cursor,claude-code
rules a use-chinese --project

4. 搜索规则

搜索本地 store：

rules search vue

同时搜索远程源：

rules search react --remote

搜索 cursor.directory：

rules search angular --cursor

5. 下载远程规则

从 .rulesrc 配置的 sources 下载：

rules install react
rules i react --project

从 cursor.directory 下载：

rules install angular-cursor-rules --cursor
rules i nextjs-react-typescript-cursor-rules --source cursor.directory

也可以不带 --cursor。当配置的 sources 找不到规则时，CLI 会自动尝试从 cursor.directory 下载同名规则。

从任意 Git 仓库下载：

rules install vue --source [email protected]:owner/rules.git
rules install react --source https://gitlab.com/owner/rules.git --project

6. 发布本地规则到远程仓库

发布当前作用域 store 中的全部规则：

rules publish --repo [email protected]:owner/rules.git --branch main --path rules
rules publish --source team-rules --message "chore: sync rules"

仅预检发布计划，不提交、不推送：

rules publish --repo [email protected]:owner/rules.git --dry-run

7. 查看规则

rules list
rules ls --global
rules ls --store

rules list 会展示已应用规则；对于 ~/.gemini/GEMINI.md、~/.codex/AGENTS.md 这类已有但不是由 rules-cli 注入的手写规则，会显示为：

📄 GEMINI.md — 语言要求 所有回复、思考过程及任务清单，均须使用中文 (manual, not managed by rules-cli)

8. 移除规则

rules remove use-chinese
rules rm use-chinese --store
rules rm -i
rules rm -i --store --global

9. 图形化 Web UI 沉浸式管理控制台

通过单条终端指令即可拉起全链条组件化架构的现代化控制台，并在默认浏览器中实现自启：

rules ui
rules ui --port 8080

全域 Store 融合接驳：同屏呈现全局与当前项目独立规则空间。
作用域双向链路同步下发：支持将跨域单据一键绑定挂载至指定助手通道的项目或全局环境。
高保真即时落盘源码编辑器：支持在线实时修改 rule.md 主体结构及 Frontmatter 并自动回写磁盘。
规则库批量选择：本地规则库支持筛选后全选、清空选择、多助手批量下发，并使用项目/全局规则路径精确匹配。
远程仓库管理：支持在 UI 中编辑项目或全局 .rulesrc 的 sources，保存 Git 仓库地址、source 名称、分支和目录；进入页面或切换仓库时自动读取远程 rules，并使用 24 小时本地缓存加速重复加载。
远程发布与删除：支持从 UI 上传本地规则到远程 Git 仓库、读取远程 rules、下载到本地和删除远程规则；删除类操作均需要二次确认。
Icon 化操作控件：关键操作统一使用图标按钮，并提供悬停提示与 aria-label。
映射嗅探与批量解绑：直观展示已生效的软链接与注入配置，支持多选解绑，解绑时同步清理 agent 入口和引用文件。
组件化二次确认：删除 store 规则、单条解绑、批量解绑均使用内置确认弹窗，不依赖浏览器原生确认框。

🛠️ 指令一览

📂 支持的 AI 助手

⚙️ 配置 (.rulesrc)

你可以通过 rules init 创建配置文件。

{
  "defaultAgents": ["cursor", "claude-code"],
  "scope": "global",
  "sources": [
    {
      "name": "github-rules",
      "repo": "owner/rules-repo",
      "subPath": "rules"
    },
    {
      "type": "git",
      "name": "team-rules",
      "url": "[email protected]:owner/rules.git",
      "subPath": "rules"
    }
  ]
}

字段说明

📌 作用域规则

| 命令组 | 默认作用域 | 切换到项目作用域 | | :--- | :--- | :--- | | create / install / apply / remove / init | 全局 | --project | | list | 同时显示项目 + 全局 | --project 或 --global |

🧩 规则文件结构

本地 store 中每条规则是一个目录，核心文件为 rule.md：

.rules/store/
└── use-chinese/
    └── rule.md

推荐在 rule.md 顶部写入 frontmatter：

---
name: use-chinese
description: 所有回复均须使用中文
tags: [language, i18n]
referencesDir: docs
references: []
---

所有回复、思考过程及任务清单，均须使用中文。

地图式引用管理

一条规则可以只把主规则文件作为入口地图，并把详细说明拆到同一规则目录下的引用文件中：

.rules/store/agent-map/
├── rule.md
└── docs/
    ├── architecture.md
    ├── development.md
    └── design-docs/
        └── ref-cli.md

在 rule.md frontmatter 中声明引用文件：

---
name: agent-map
description: AGENTS.md 地图入口
tags: [agent]
referencesDir: docs
references:
  - path: docs/architecture.md
    title: 分层架构详细说明
  - path: docs/development.md
    title: 开发环境搭建
  - path: docs/design-docs/ref-*.md
    title: 参考项目架构说明
---

# AGENTS.md

- [架构说明](./docs/architecture.md)
- [开发环境](./docs/development.md)
- [参考架构](./docs/design-docs/ref-cli.md)

执行 rules apply agent-map --agent codex --project 后，AGENTS.md 会写入入口地图，引用文件会同步到目标规则文件所在目录的相对路径下。

单文件型助手的注入区会保持精简，例如：

<!-- rules-cli:start -->
## agent-map
- [架构说明](./docs/architecture.md)
- [开发环境](./docs/development.md)
<!-- rules-cli:end -->

rules-cli:start/end 是用于可靠增删托管区的边界标记；每条规则不再额外写入  包裹。

如果规则没有声明 references，单文件型助手也会自动采用引用模式：入口文件只写入 docs/<rule>.md 链接，原规则正文会落盘到目标项目的 docs/<rule>.md，避免把长正文全部写进 AGENTS.md / CLAUDE.md / GEMINI.md。

移除规则时，rules-cli 只会删除内容仍与 store 源文件一致的引用文件；如果你手动改过目标文件，会保留它以避免误删。引用文件删除后会继续清理空目录，例如 docs/design-docs/ 为空时会删除该目录；如果 docs/ 也为空，会一并删除。

referencesDir 用于设置引用文件在目标项目中的统一落盘目录，默认值为 docs。设置为 ai-rules 等目录时，引用文件会写入对应目录下，地图链接也会指向该目录。如果源文件路径本身已经以 docs/ 开头，切换目录时会去掉这层源目录前缀，例如 docs/architecture.md 会落到 ai-rules/architecture.md。

📄 开源协议

基于 MIT 协议开源。