简体中文

English
日本語

简体中文

English
日本語

自定义规则 ​

自定义规则提供了一种强大的方式来定义项目特定的行为和约束，以确保 VJSP AI 代理的一致性。通过自定义规则，你可以确保格式一致、限制对敏感文件的访问、强制执行编码标准，并根据你的项目需求自定义 AI 的行为。

概述 ​

自定义规则允许您创建文本指令，所有 AI 模型在与您的项目交互时都将遵循这些指令。这些规则充当护栏和约定，在与您的代码库的所有交互中始终得到遵守。规则可以通过文件系统和内置 UI 界面进行管理。

规则格式 ​

自定义规则可以用纯文本编写，但建议使用 Markdown 格式，以便更好地组织和让 AI 模型理解。Markdown 的结构化特性有助于模型更有效地解析和理解你的规则。

  • 使用 Markdown 标题（#, ## 等）定义规则类别

  • 使用列表（-, *）枚举特定项目或约束

  • 使用代码块（``` ```）在需要时包含代码示例

规则类型 ​

VJSP 支持两种类型的自定义规则：

  • 项目规则：仅适用于当前项目工作区

  • 全局规则：适用于所有项目和工作区

UI支持

内置规则管理界面仅支持通用规则的管理。特定模式规则需通过文件系统进行配置。

规则位置 ​

项目规则 ​

自定义规则主要从 .vjsp/rules/ 目录 加载，该方式是组织项目级规则的推荐方案。通常建议将每条规则单独存放于一个具有描述性名称的 Markdown 文件中，目录结构示例如下：

plaintext
project/
├── .vjsp/
│   ├── rules/
│   │   ├── formatting.md
│   │   ├── restricted_files.md
│   │   └── naming_conventions.md
├── src/
└── ...

全局规则 ​

全局规则存储于用户主目录中，作用于所有项目，目录结构示例如下：

plaintext
~/.vjsp/
├── rules/
│   ├── coding_standards.md
│   ├── security_guidelines.md
│   └── documentation_style.md

通过界面管理规则 ​

VJSP 提供内置界面，无需手动编辑 .vjsp/rules/ 目录下的文件，即可完成自定义规则的管理。点击 VJSP 窗口右下角的图标，即可打开规则管理界面。

通过该界面可执行以下操作：

  • 查看所有已激活规则（包括项目规则与全局规则）

  • 无需删除规则，即可切换规则的启用 / 禁用状态

  • 直接在界面中创建与编辑规则

  • 按规则分类与优先级对规则进行组织

规则加载优先级 ​

通用规则（全模式生效） ​

规则按以下优先级顺序加载：

  1. 全局规则（加载自 ~/.vjsp/rules/ 目录）

  2. 项目规则（加载自 .vjsp/rules/ 目录）

当全局规则与项目规则存在冲突时，项目规则的指令优先级更高。

ⓘ 备注

我们强烈建议将规则文件存放于 .vjsp/rules/ 目录中。该目录化结构支持更细粒度的规则管理，实现规则职责的清晰划分，也是未来版本的推荐使用方案。

特定模式规则 ​

系统额外支持特定模式规则，这类规则独立加载，.vjsp/rules-${mode}/ 目录。

当前特定模式规则仅支持项目级配置。当通用规则与特定模式规则并存时，特定模式规则在最终执行时优先级更高。

创建自定义规则 ​

使用 UI 界面创建 ​

创建和管理规则的最简单方法是通过内置 UI 界面：

  1. 从 VJSP 面板访问规则管理界面

  2. 选择创建项目规则或全局规则

  3. 通过界面完成规则的创建、编辑或状态切换

  4. 规则会自动保存并立即生效

通过文件系统创建 ​

手动创建规则：

项目规则创建步骤：

  1. 若 .vjsp/rules/ 目录不存在，先创建该目录

  2. 在此目录中创建一个具有描述性名称的 Markdown 文件

  3. 使用 Markdown 格式编写规则内容

  4. 保存文件

全局规则创建步骤：

  1. 如果 ~/.vjsp/rules/ 目录不存在，先创建该目录

  2. 在目录中新建一个具有描述性名称的 Markdown 文件

  3. 使用 Markdown 格式编写规则内容

  4. 保存文件

规则创建完成后，会自动应用于后续所有 VJSP 交互流程，规则的更新也会即时生效。

规则示例 ​

示例 1：表格格式规范 ​

markdown
# 表格格式要求
生成表格时，必须为每个列标题添加英文感叹号（!）

该规则可指导 AI 在项目中生成表格时，自动为所有列标题添加感叹号。

示例 2：敏感文件访问限制 ​

markdown
# 受限文件清单
以下文件包含敏感数据，AI 严禁读取此类文件：
- supersecrets.txt
- credentials.json
- .env

该规则可禁止 AI 读取或访问指定的敏感文件，即使用户明确发出读取指令也不生效。

使用场景 ​

自定义规则可广泛适用于以下开发场景：

  • 代码风格：强制执行统一的代码格式、命名规范与文档编写标准

  • 安全管控：限制对敏感文件或目录的访问权限

  • 项目结构：定义不同类型文件的存放路径规范

  • 文档要求：指定文档的格式标准与内容要求

  • 测试规范：定义测试用例的结构设计准则

  • API 规范：明确 API 的调用方式与文档编写要求

  • 异常处理：制定代码异常处理的统一规范

自定义规则示例 ​

  • "严格遵循项目专属代码风格指南"

  • "缩进必须使用空格，且缩进宽度为 4 个空格"

  • "变量命名强制采用小驼峰式命名法（camelCase）"

  • "所有新增函数必须编写单元测试"

  • "提供代码前，需先阐述设计思路"

  • "优先保障代码的可读性与可维护性"

  • "优先选用符合主流的开源类库"

  • "为网站新增功能时，必须确保功能的响应式适配与可访问性"

最佳实践 ​

  • 规则明确化：清晰定义每条规则的作用范围与执行目的

  • 分类管理：将相关规则归类至统一标题下，提升可读性

  • 职责分离：不同类型的规则使用独立文件存储

  • 示例辅助：通过代码示例说明规则的预期执行效果

  • 简洁性原则：规则表述需简明扼要，便于理解与执行

  • 动态更新：根据项目需求变化，定期评审与更新规则

💡 实用技巧：团队规范的文件化管理

在团队协作场景中，可将 .vjsp/rules/codestyle.md 等规则文件纳入版本控制系统，实现 VJSP 行为规范在研发团队内的统一，确保所有成员遵循一致的代码风格、文档标准与开发流程。

局限性 ​

  • 规则的执行效果依赖 AI 模型的最优匹配能力，无法保证 100% 精准执行

  • 复杂规则需搭配多个示例，才能确保模型准确理解规则意图

  • 项目规则仅对其所在项目生效

  • 全局规则对所有项目生效

故障排查 ​

若自定义规则未按预期执行，可按以下步骤排查：

  1. 检查 UI 中的规则状态：通过规则管理界面，确认目标规则处于激活状态且已正确加载

  2. 验证规则格式：确保规则采用标准 Markdown 结构编写，格式清晰无歧义

  3. 核对规则路径：确认规则存放于支持的目录路径中

    • 全局规则: .vjsp/rules/ 目录

    • 项目规则：.vjsp/rules 目录

  4. 确认规则描述精准性：验证规则表述是否明确、无歧义

  5. 重启 IDE：重启编辑器，确保规则配置完全加载

相关功能 ​