# Jarvis 规则系统（Rules）介绍

## 1. 概述

### 1.1 什么是规则系统

Jarvis 规则系统是一套基于 Markdown 的规范化指令集合，用于指导 Agent 在代码生成、代码审查、重构等任务中遵循统一的标准和最佳实践。规则系统是 Jarvis 实现"行为规范"和"知识复用"的核心机制。

### 1.2 规则系统的价值

- **统一标准**：确保不同 Agent 的输出风格一致
- **质量保证**：内置检查清单，减少代码缺陷
- **知识传承**：将最佳实践文档化，便于团队共享
- **灵活扩展**：可根据项目需求自定义规则
- **动态渲染**：支持 Jinja2 模板语法，实现规则内容的动态化
- **极强的扩展性**：规则系统是一套扩展性极强的系统，skill 支持、rules 支持、spec 等都可以通过这套系统扩展出来

### 1.3 规则系统的工作原理

规则系统通过以下机制工作：

1. **规则加载**：从多个来源加载规则文件（项目规则、全局规则、内置规则等）
2. **规则合并**：按照优先级顺序合并规则内容
3. **规则注入**：将规则内容注入到 Agent 的系统提示词中
4. **动态注入**：支持在用户输入中动态引用特定规则

### 1.4 规则系统的扩展性

规则系统是一套扩展性极强的系统，不仅用于代码规范，还可以通过规则扩展出各种功能：

- **Skill 支持**：通过规则系统可以定义和集成各种技能（skill），扩展 Agent 的能力
- **Rules 支持**：规则系统本身支持通过规则来定义新规则，实现规则的递归扩展
- **Spec 支持**：通过规则系统可以定义和生成项目规范（spec），指导项目开发
- **Jarvis 配置**：Jarvis 自身的配置也可以通过规则系统进行，实现配置的智能化和自动化管理
- **规则扩充**：对规则的扩充和增强也可以通过规则系统进行，实现规则的自我完善和迭代
- **其他扩展**：任何需要指导 Agent 行为的场景都可以通过规则系统来实现

这种设计使得 Jarvis 系统具有极强的可扩展性，用户可以根据自己的需求灵活扩展功能，甚至可以通过规则系统来扩展规则系统本身。

---

## 2. 规则的类型和来源

### 2.1 规则树状结构

规则系统采用树状结构组织，有 3 个根节点作为索引：

1. **内置规则索引**（`builtin_rules.md`）：Jarvis 内置规则的索引文件，列出了所有内置规则的分类和路径
2. **项目规则目录**（`.jarvis/rules/`）：项目特定的规则文件目录
3. **全局规则目录**（`~/.jarvis/rules/`）：全局共享的规则文件目录

**灵活引用**：用户可以从任何一个节点引入规则，支持以下方式：

- **通过索引引用**：使用规则名称，系统会从索引文件中查找（如 `clean_code`）。无前缀时优先从内置规则查找，因此不需要使用 `builtin:` 前缀
- **通过前缀引用**：使用前缀明确指定来源，支持相对路径（如 `project:architecture_design/solid`、`global:python_style`）

### 2.2 规则共享

规则支持共享机制，可以将规则分享到中心规则仓库，供多个项目使用。

#### 中心规则仓库

通过配置 `central_rules_repo` 指定中心规则仓库，支持：

- **Git 仓库 URL**：系统会自动克隆到 `~/.jarvis/central_rules_repo`
- **本地目录路径**：直接使用本地目录

中心规则仓库具有最高优先级，如果存在同名规则，以中心仓库为准。系统会自动执行每日更新检查。

#### 规则分享流程

可以通过命令行工具将本地规则分享到中心规则仓库：

1. **使用方式**：运行 `jca --share-rule` 启动规则分享流程

2. **来源**：可以从以下位置选择规则进行分享
   - 项目规则目录（`.jarvis/rules/`）
   - 内置规则目录（`builtin/rules/`）
   - 配置的规则加载目录（`rules_load_dirs`）

3. **分享**：选中的规则会被复制到中心规则仓库，保持原有的目录结构

4. **索引更新**：共享的规则不会自动更新索引。如果需要更新全局规则的索引文件（`~/.jarvis/rule`），可以在交互式会话中请求 Jarvis 扫描规则目录并更新索引文件

#### 规则加载目录优先级

规则系统按以下优先级顺序查找规则：

1. **中心规则仓库**（`central_rules_repo`）：最高优先级
2. **项目规则目录**（`.jarvis/rules/`）
3. **配置的规则目录**（`rules_load_dirs`）：通过配置项指定，支持多个目录
4. **全局规则目录**（`~/.jarvis/rules/`）
5. **内置规则**（`builtin/rules/`）：最低优先级

### 2.3 规则类型

Jarvis 规则系统支持以下类型的规则：

#### 全局规则

- **位置**：`~/.jarvis/rule`
- **作用范围**：所有项目
- **用途**：个人通用编码规范、全局最佳实践

#### 项目规则

- **位置**：`<项目根目录>/.jarvis/rule`
- **作用范围**：当前项目
- **用途**：项目特定的编码规范、业务逻辑约束

#### 命名规则

命名规则可以从多个来源加载，按优先级从高到低：

1. **中心规则仓库**（最高优先级）
   - 位置：通过配置 `central_rules_repo` 指定
   - 支持本地目录或 Git 仓库 URL
   - 支持自动克隆和每日更新

2. **项目 `rules/` 目录**
   - 位置：`<项目根目录>/.jarvis/rules/`
   - 存储项目特定的规则文件（`.md` 格式）

3. **配置的规则目录**
   - 位置：通过 `rules_load_dirs` 配置项指定
   - 支持多个目录，按配置顺序加载

4. **全局规则目录**
   - 位置：`~/.jarvis/rules/`
   - 全局共享的规则文件目录

5. **内置规则**（最低优先级）
   - 位置：`builtin/rules/` 和 `builtin/rules/testing/`
   - Jarvis 自带的规则集

### 2.4 规则引用方式

规则系统支持多种引用方式，可以从树状结构的任何节点引入规则：

#### 通过索引引用（推荐）

使用规则名称，系统会自动从索引文件中查找：

```bash
jca --rule-names clean_code,security
```

系统会按优先级顺序查找：中心规则仓库 → 项目规则目录 → 配置的规则目录 → 全局规则目录 → 内置规则索引。

#### 通过前缀明确指定来源

使用前缀明确指定规则来源，避免歧义。规则名称不需要包含 `.md` 后缀，系统会自动添加。前缀引用支持相对路径：

- **`project:`**：项目规则目录（如 `project:api_standard` 或 `project:architecture_design/solid`）
- **`global:`**：全局规则目录（如 `global:python_style`）
- **`central:`**：中心规则仓库（如 `central:team_rule`）
- **`config1:`, `config2:`**：配置的规则目录（按配置顺序编号）

**注意**：

- 无前缀时系统会优先从内置规则查找，因此不需要使用 `builtin:` 前缀
- 无前缀时不支持相对路径引用，相对路径只在有前缀时支持

**示例**：

```bash
# 从项目规则引用（根节点规则）
jca --rule-names project:api_standard

# 从项目规则引用（子节点规则，使用相对路径）
jca --rule-names project:architecture_design/solid

# 从全局规则引用
jca --rule-names global:python_style

# 从中心规则仓库引用
jca --rule-names central:team_rule

# 组合使用（内置规则无需前缀）
jca --rule-names clean_code,project:api_standard
```

### 2.5 规则加载优先级

当指定多个规则来源时，系统按以下顺序合并规则：

1. **全局规则文件**（`~/.jarvis/rule`）
2. **项目规则文件**（`.jarvis/rule`）
3. **通过 `--rule-names` 指定的规则**

查找指定规则时（无前缀时），按以下顺序查找：

1. 中心规则仓库
2. 项目规则目录（`.jarvis/rules/`）
3. 配置的规则目录
4. 全局规则目录（`~/.jarvis/rules/`）
5. 内置规则索引（`builtin_rules.md`）
6. 内置规则目录（最低优先级）

**注意**：使用前缀引用时，会直接到指定的来源查找，不遵循上述优先级顺序。

---

## 3. 内置规则概览

Jarvis 内置了丰富的规则集，涵盖架构设计、开发流程、代码质量、安全规范、性能优化等多个方面。

### 3.1 架构设计规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `solid.md` | SOLID 设计原则 | 面向对象设计 |
| `clean_architecture.md` | 整洁架构 | 架构设计 |
| `clean_code.md` | 整洁代码规范 | 代码生成、重构 |
| `code-reverse-design.md` | 代码反向设计规则 | 代码重构 |
| `architecture-diagram-generation.md` | 架构图生成规则 | 架构文档生成 |

### 3.2 开发流程规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `sdd.md` | Spec 驱动开发 | 设计文档编写 |
| `tdd.md` | 测试驱动开发 | 测试代码生成 |
| `refactoring.md` | 重构指南 | 代码重构任务 |
| `c2rust_transpiler.md` | C2Rust 转译 | C 代码转 Rust |
| `go2rust_transpiler.md` | Go2Rust 转译 | Go 代码转 Rust |

### 3.3 代码质量规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `code_review.md` | 代码审查标准 | 代码审查任务 |
| `documentation.md` | 文档编写规范 | 文档生成 |
| `refactor-checker.md` | 重构检查专家 | 重构质量检查 |

### 3.4 安全规范规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `security.md` | 安全编码标准 | 安全相关代码 |
| `vulnerability-analysis.md` | 安全漏洞分析规则 | 安全审计 |

### 3.5 性能优化规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `performance.md` | 性能优化指南 | 性能敏感代码 |
| `rust_performance.md` | Rust 性能优化 | Rust 代码优化 |

### 3.6 UI 设计规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `dark-theme-design.md` | 暗色主题设计规则 | 前端界面开发 |
| `light-theme-design.md` | 亮色主题设计规则 | 前端界面开发 |
| `macos-web-design.md` | macOS Web 设计规范 | Web 界面开发 |

### 3.7 开发工具规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `script-generation.md` | 脚本生成规则 | 脚本代码生成 |
| `skill-development.md` | 技能开发规则 | 技能开发 |
| `mcp-integration.md` | MCP 集成规则 | MCP 工具集成 |

### 3.8 测试规范规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `cpp_test.md` | C/C++ 测试指南 | C/C++ 代码测试 |
| `go_test.md` | Go 测试指南 | Go 代码测试 |
| `javascript_test.md` | JavaScript/TypeScript 测试指南 | JS/TS 代码测试 |
| `java_test.md` | Java 测试指南 | Java 代码测试 |
| `php_test.md` | PHP 测试指南 | PHP 代码测试 |
| `python_test.md` | Python 测试指南 | Python 代码测试 |
| `ruby_test.md` | Ruby 测试指南 | Ruby 代码测试 |
| `rust_test.md` | Rust 测试指南 | Rust 代码测试 |

### 3.9 工具配置规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `add_rule.md` | 新增规则规范 | 创建新规则时 |
| `alert-management.md` | 告警管理规则 | 告警处理 |
| `self_config.md` | 自助配置规则 | 配置文件修改 |
| `add_builtin_rule.md` | 新增内置规则规范 | 添加内置规则 |

### 3.10 部署规范规则

| 规则文件 | 用途 | 适用场景 |
|---------|------|---------|
| `opensource-deployment.md` | 开源部署规则 | 开源项目部署 |

---

## 4. 规则的使用方式

### 4.1 通过命令行参数指定

使用 `--rule-names` 参数指定要使用的规则：

```bash
# 使用单个规则
jca --rule-names clean_code "创建用户模块"

# 使用多个规则（逗号分隔）
jca --rule-names clean_code,security,performance "创建 API"

# 组合使用项目规则和内置规则
jca --rule-names my_project_rule,clean_code "创建功能"
```

### 4.2 通过项目规则文件

创建 `.jarvis/rule` 文件，内容将自动加载：

```markdown
# .jarvis/rule

# 这是一个全局规则，对所有任务生效

你必须遵守以下原则：

- 代码必须符合 PEP 8 规范
- 所有公共函数必须有类型注解
- 必须编写单元测试
```

### 4.3 通过全局规则文件

创建 `~/.jarvis/rule` 文件，对所有项目生效：

```markdown
# ~/.jarvis/rule

# 全局默认规则

使用 Python 编写代码时：

- 必须使用 `f-strings` 进行字符串格式化
- 禁止使用 `print()` 语句（使用 logging 模块）
```

### 4.4 使用 @ 交互式增加规则

在交互式输入中输入 `@` 符号即可触发规则补全功能，快速选择并插入所需的规则。

**使用步骤**：

1. **触发补全**：在交互式输入过程中输入 `@` 符号
2. **浏览规则**：系统自动显示所有可用的规则列表
3. **选择规则**：使用上下键或鼠标选择所需的规则
4. **自动注入**：确认选择后，规则内容自动插入到输入中

**补全优先级**：

规则按以下顺序显示和查找：

1. 中心规则仓库（最高优先级）
2. 项目规则目录（`.jarvis/rules/`）
3. 配置的规则目录
4. 全局规则目录（`~/.jarvis/rules/`）
5. 内置规则目录（`builtin/rules/`）

**使用场景**：

- ✅ 需要快速切换不同规则集时
- ✅ 不记得规则具体名称时
- ✅ 想要组合多个规则使用时
- ✅ 临时需要添加额外规则时
- ✅ 交互式开发调试过程中

---

## 5. 规则注入机制

### 5.1 系统提示词注入

规则（包括全局、项目、`--rule-names` 指定的规则）会被合并成一个字符串，使用 `<rules>...</rules>` 标签包裹，注入到 Agent 的系统提示词中。

**重要特性**：规则会在上下文压缩中保持。由于规则是系统提示词的一部分，而系统提示词在上下文压缩过程中始终保留（不参与压缩），因此规则内容在整个对话过程中都会保持有效，不会因为上下文压缩而丢失。这确保了 Agent 在整个任务执行过程中始终遵循规则约束。

### 5.2 用户输入动态注入

用户可以在其输入中使用 `'<rule:rule_name>'` 标记动态注入特定规则。系统会拦截此标记，查找对应的规则内容，并将其替换为 `<rule>...</rule>` 标签包裹的格式，直接插入到用户输入中。

**示例**：

```
> 创建用户模块 '<rule:clean_code>'
```

会被转换为：

```
> 创建用户模块 <rule>
# 整洁代码规范
...
</rule>
```

---

## 6. 规则文件格式

### 6.1 基本结构

规则文件采用 Markdown 格式，推荐以下结构：

```markdown
# 规则标题

## 引言/背景

简要说明规则的用途和适用场景。

## 核心原则

### 原则名称

**执行要求：**

- **必须**：强制要求
- **禁止**：禁止行为

## 详细规范

### 子章节

**检查项：**

- [ ] 检查点 1
- [ ] 检查点 2

## 代码示例

### ❌ 不好的实践

```python
# 错误示例代码
```

### ✅ 好的实践

```python
# 正确示例代码
```

## 检查清单

在完成任务前，你必须确认：

- [ ] 检查项 1
- [ ] 检查项 2

```

### 6.2 格式要求

1. **标题层级**：使用 `##` 作为顶级章节，`###` 作为子章节
2. **强调标记**：
   - **必须**：强制要求，使用粗体
   - **禁止**：禁止行为，使用粗体
   - 建议：推荐做法，使用粗体
3. **检查清单**：使用 `- [ ]` 格式，便于 Agent 逐项确认
4. **代码示例**：使用明确的标题区分好/坏实践，如 `❌ 不好的实践`、`✅ 好的实践`

---

## 7. 规则占位符（Jinja2 模板）

### 7.1 可用的占位符变量

| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| `{{ current_dir }}` | 当前工作目录（绝对路径） | `/home/user/myproject` |
| `{{ script_dir }}` | 脚本所在目录 | `/path/to/jarvis/...` |
| `{{ jarvis_data_dir }}` | jarvis 数据目录 | `~/.jarvis` |
| `{{ jarvis_src_dir }}` | jarvis 源码目录 | `/path/to/jarvis` |
| `{{ git_root_dir }}` | Git 仓库根目录 | `/home/user/myproject` |
| `{{ rule_file_dir }}` | 规则文件所在目录 | `/home/user/...` |

### 7.2 使用示例

```markdown
# 项目文件组织规范

**必须遵守的目录结构：**

配置文件：`{{ git_root_dir }}/config/`
源代码：`{{ git_root_dir }}/src/`
测试代码：`{{ git_root_dir }}/tests/`

**要求：**

- 所有源代码文件必须放在 `{{ git_root_dir }}/src/` 目录下
- 测试文件必须放在 `{{ git_root_dir }}/tests/` 目录下
```

---

## 8. 规则系统的最佳实践

### 8.1 规则编写原则

1. **明确性原则**：使用清晰、无歧义的语言
2. **可操作性原则**：每条规则都应该是可验证的
3. **结构化原则**：按照逻辑层次组织内容
4. **示例驱动**：每条关键规范都应配有示例

### 8.2 规则使用建议

1. **项目规则**：为项目创建专属规则文件，确保代码风格一致
2. **规则组合**：根据任务类型组合使用多个规则
3. **规则优先级**：理解规则加载优先级，避免冲突
4. **规则更新**：定期审查和更新规则，保持最佳实践
