ByteBuddy

简体中文

English

简体中文

English

深色模式

规则配置 ​

ByteBuddy 提供了强大的规则系统，支持多种配置方式来定义 AI 助手的行为准则，确保生成的代码符合项目标准和团队规范。

规则配置方式 ​

ByteBuddy 支持以下三种主要的规则配置方式：

1. 配置文件中的规则（config.yaml） ​

在项目根目录的 config.yaml 中直接定义规则。

2. 规则文件夹（.bytebuddy/rules/） ​

在 .bytebuddy/rules/ 目录中放置 Markdown 格式的规则文件。

3. 代码库中的规则文件（rules.md） ​

在代码库的任何目录中放置 rules.md 文件，规则会自动应用到该目录及其子目录。

配置文件规则格式 ​

字符串规则 ​

简单的规则定义，直接描述要求：

yaml
# config.yaml
name: My ByteBuddy Config
version: 0.0.1
schema: v1

rules:
  - "始终包含类型注解"
  - "遵循现有代码风格"
  - "为复杂逻辑添加注释"

对象规则 ​

带名称和描述的详细规则：

yaml
rules:
  - name: "comment-complex"
    rule: "为复杂逻辑添加注释"
    description: "为超过5行的复杂函数添加注释"
  - name: "test-coverage"
    rule: "确保测试覆盖率不低于 80%"
    globs: ["**/*.ts", "**/*.js"]

Markdown 规则文件格式 ​

基本 Markdown 规则 ​

在 .bytebuddy/rules/ 目录或代码库中的 rules.md 文件：

markdown
---
name: "typescript-style"
globs: ["**/*.ts", "**/*.tsx"]
description: "TypeScript 编码规范"
---

# TypeScript 编码规范

所有 TypeScript 文件必须遵循以下规范：

1. 使用 2 个空格进行缩进
2. 所有函数参数必须包含类型注解
3. 优先使用 interface 而不是 type
4. 避免使用 any 类型

带高级配置的 Markdown 规则 ​

markdown
---
name: "component-rules"
globs: ["src/components/**/*.{js,jsx,ts,tsx}"]
regex: ["^[A-Z]"]
alwaysApply: true
invokable: false
---

# React 组件规则

React 组件必须遵循以下规范：

- 组件名必须以大写字母开头
- 使用函数组件而非类组件
- 每个组件文件包含对应的样式文件

规则字段说明 ​

基本字段 ​

  • name：规则名称（推荐设置，用于标识和引用）
  • rule：规则内容，Markdown 格式
  • description：规则描述（可选）

应用控制字段 ​

  • globs：文件匹配模式，字符串或数组格式
  • regex：正则表达式模式，用于文件内容匹配
  • alwaysApply：是否总是应用该规则（默认：false）
  • invokable：是否允许用户主动触发该规则（默认：false）
  • sourceFile：规则源文件路径（自动设置）

文件匹配模式 ​

Glob 模式示例 ​

yaml
# 匹配特定文件类型
globs: ["**/*.ts", "**/*.tsx"]

# 匹配特定目录
globs: ["src/components/**/*"]

# 排除特定文件
globs: ["**/*.ts", "!**/*.test.ts"]

# 多种模式组合
globs: ["src/**/*.{js,ts}", "!src/**/*.d.ts"]

Regex 模式示例 ​

yaml
# 匹配文件内容
regex: ["console\\.log", "TODO|FIXME"]

# 复杂正则表达式
regex: ["^\\s*function\\s+\\w+", "class\\s+\\w+.*extends"]

规则目录结构 ​

全局规则目录 ​

.bytebuddy/
├── rules/
│   ├── global-style.md      # 全局样式规则
│   ├── security.md          # 安全规则
│   └── performance.md       # 性能规则
└── prompts/
    ├── code-review.md       # 代码审查提示
    └── debugging.md         # 调试提示

代码库规则示例 ​

src/
├── components/
│   ├── Button.tsx
│   └── rules.md            # 组件特定规则
├── utils/
│   ├── helper.ts
│   └── rules.md            # 工具函数规则
└── rules.md                # src 目录规则

规则示例 ​

1. 配置文件规则 ​

yaml
# config.yaml
name: My ByteBuddy Config
version: 0.0.1
schema: v1

models:
  - name: "gpt-4"
    provider: "openai"
    model: "gpt-4"
    apiKey: "${OPENAI_API_KEY}"
    roles: ["chat"]

rules:
  - "始终包含类型注解"
  - "遵循现有代码风格"
  - name: "typescript-strict"
    rule: "TypeScript 代码必须严格模式"
    globs: ["**/*.ts", "**/*.tsx"]
    alwaysApply: true

2. Markdown 规则文件 ​

markdown
---
name: "react-components"
globs: ["src/components/**/*.{js,jsx,ts,tsx}"]
alwaysApply: true
invokable: false
---

# React 组件开发规范

所有 React 组件必须遵循以下规范：

## 组件结构

- 使用函数组件而非类组件
- 组件名必须以大写字母开头
- 导出使用默认导出

## 类型定义

- 所有 props 必须定义 TypeScript 接口
- 使用 React.FC 或显式返回类型
- 避免使用 any 类型

## 样式处理

- 优先使用 CSS Modules 或 styled-components
- 避免内联样式
- 响应式设计考虑

3. 特定目录规则 ​

markdown
---
name: "test-coverage"
globs: ["**/*.test.{js,ts}", "**/*.spec.{js,ts}"]
regex: ["test|it\\("]
---

# 测试文件规范

测试文件必须包含：

1. **描述性测试名称**
2. **Arrange-Act-Assert 结构**
3. **边界情况测试**
4. **错误处理测试**

每个测试函数必须有清晰的断言，确保测试覆盖率不低于 80%。

高级功能 ​

可调用规则（Invokable Rules） ​

设置 invokable: true 的规则可以在聊天中主动触发：

markdown
---
name: "code-review"
invokable: true
description: "对代码进行全面审查"
---

# 代码审查规则

请对提供的代码进行全面审查，检查：

1. **代码质量**：可读性、可维护性
2. **安全性**：潜在的安全漏洞
3. **性能**：性能优化建议
4. **测试**：测试覆盖情况
5. **文档**：文档完整性

提供具体的改进建议和最佳实践。

规则优先级 ​

  1. Colocated 规则：代码库中与文件同目录的 rules.md
  2. 全局 Markdown 规则：.bytebuddy/rules/ 目录中的规则
  3. 配置文件规则：config.yaml 中定义的规则

条件匹配规则 ​

markdown
---
name: "production-safety"
globs: ["src/**/*.{js,ts}"]
regex: ["console\\.(log|warn|error)", "debugger"]
---

# 生产环境安全检查

以下内容不应该出现在生产代码中：

- ❌ console.log(), console.warn(), console.error()
- ❌ debugger 语句
- ❌ 硬编码的 API 密钥
- ❌ 注释掉的调试代码

请使用适当的日志系统和环境变量管理。

规则管理最佳实践 ​

1. 规则组织 ​

  • 按功能模块组织规则文件
  • 使用清晰的命名约定
  • 定期审查和更新规则

2. 团队协作 ​

markdown
---
name: "team-standards"
globs: ["**/*.{js,ts,jsx,tsx}"]
description: "团队编码标准"
---

# 团队编码标准

本规则定义了团队的所有编码标准，请确保所有新代码都符合这些规范。

## 命名约定

- 组件：PascalCase
- 变量/函数：camelCase
- 常量：UPPER_SNAKE_CASE
- 文件名：kebab-case

## 代码组织

- 按功能模块组织文件
- 保持文件大小合理（< 300 行）
- 使用 index.ts 导出公共接口

3. 规则测试 ​

  • 使用示例代码验证规则效果
  • 定期审查规则的实际应用情况
  • 根据团队反馈调整规则内容

故障排除 ​

常见问题 ​

规则不生效

  1. 检查文件路径和 glob 模式
  2. 验证 YAML frontmatter 格式
  3. 确认规则文件位置正确

规则冲突

  1. 规则按优先级应用，后应用的规则可能覆盖前面的
  2. 使用 alwaysApply: true 确保规则始终生效
  3. 检查 globs 和 regex 的匹配逻辑

性能问题

  1. 避免过于复杂的 regex 模式
  2. 合理使用 globs 限制规则应用范围
  3. 定期清理不需要的规则文件 rule: "严格模式 TypeScript 开发" description: "启用严格类型检查，避免 any 类型" globs: ["/*.ts", "/*.tsx"] alwaysApply: true

测试要求 ​

  • name: "test-coverage" rule: "确保测试覆盖率不低于 80%" description: "新功能必须包含相应测试" globs: ["src/**/*.{js,ts}"]

## 高级配置

### 条件规则
```yaml
rules:
  - name: "production-only"
    rule: "生产环境必须启用严格模式"
    description: "仅在生产构建时应用此规则"
    globs: ["src/**/*.{js,ts}"]
    alwaysApply: true
    # 可以通过环境变量控制

规则组合 ​

yaml
rules:
  # 基础代码风格
  - "使用一致的代码格式"
  - "遵循项目命名约定"

  # 特定场景规则
  - name: "api-validation"
    rule: "API 参数必须包含验证"
    description: "所有 API 端点必须有参数验证"
    globs: ["src/api/**/*.{js,ts}"]
    alwaysApply: true

最佳实践 ​

1. 规则设计原则 ​

  • 具体明确：规则描述应该清晰具体
  • 可操作性：规则应该是可以被执行的
  • 逐步实施：从简单的规则开始，逐步增加复杂度

2. 团队协作 ​

  • 团队共识：确保团队成员都理解并同意规则
  • 文档同步：保持规则文档与实际配置同步
  • 定期审查：定期评估规则的有效性

3. 规则维护 ​

  • 版本控制：将规则配置纳入版本控制
  • 渐进式应用：新规则先在部分文件中测试
  • 反馈循环：收集开发者的反馈并调整规则

故障排除 ​

常见问题 ​

  1. 规则不生效

    • 检查文件路径是否匹配 globs 或 regex
    • 确认配置文件语法正确
    • 验证模型是否正确加载了规则

  2. 规则冲突

    • 检查是否存在矛盾的规则
    • 调整规则的应用顺序
    • 使用 alwaysApply 优先级

  3. 性能影响

    • 优化复杂的正则表达式
    • 减少规则的文件匹配范围
    • 合理使用 alwaysApply 和 invokable

调试技巧 ​

yaml
# 开发时可以添加调试规则
rules:
  - name: "debug-rule"
    rule: "调试规则：显示当前文件信息"
    description: "帮助调试规则应用情况"
    globs: ["**/*.{js,ts}"]
    invokable: true

通过合理配置规则，可以让 ByteBuddy 更好地适应项目需求，生成符合团队标准的代码。记住在聊天会话中，配置好的规则会自动指导 AI 的行为，确保生成的内容符合你的要求。

Copyright © 2025 ByteBuddy