# agents-enforcer

**Repository Path**: mindsynt/agents-enforcer

## Basic Information

- **Project Name**: agents-enforcer
- **Description**: 自动学习并强制执行 AGENTS.md 中的规则，将软约束转变为硬约束。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AGENTS.md 规则强制执行插件

[![npm version](https://img.shields.io/npm/v/opencode-plugin-agents-enforcer.svg)](https://www.npmjs.com/package/opencode-plugin-agents-enforcer)
[![npm downloads](https://img.shields.io/npm/dm/opencode-plugin-agents-enforcer.svg)](https://www.npmjs.com/package/opencode-plugin-agents-enforcer)
[![license](https://img.shields.io/npm/l/opencode-plugin-agents-enforcer.svg)](https://github.com/lrx-liu/agents-enforcer/blob/main/LICENSE)

自动学习并强制执行 AGENTS.md 中的规则，将软约束转变为硬约束。

**当前版本**: `1.1.0`

## 🚀 快速安装

### 从 npm 安装（推荐）

```bash
# 使用 npm
npm install opencode-plugin-agents-enforcer

# 使用 yarn
yarn add opencode-plugin-agents-enforcer

# 使用 pnpm
pnpm add opencode-plugin-agents-enforcer
```

### 从 Git 仓库安装

```bash
# 1. 克隆仓库
git clone https://github.com/lrx-liu/agents-enforcer.git
cd agents-enforcer

# 2. 安装依赖
npm install

# 3. 编译
npm run build

# 4. 安装到 OpenCode
# Linux/macOS:
bash install.sh

# Windows:
.\install.ps1
```

### 手动安装

```bash
# 1. 克隆仓库
git clone https://github.com/lrx-liu/agents-enforcer.git
cd agents-enforcer

# 2. 安装依赖并编译
npm install
npm run build

# 3. 复制到 OpenCode 插件目录
# Linux/macOS:
cp -r dist/* ~/.config/opencode/plugins/

# Windows:
xcopy /E /I /Y dist %USERPROFILE%\.config\opencode\plugins
```

## 📦 项目结构

```
agents-enforcer/
├── src/                          # 源代码
│   ├── index.ts                  # 插件入口
│   ├── rules/                    # 规则模块
│   │   ├── types.ts              # 类型定义
│   │   ├── parser.ts             # AGENTS.md 解析器
│   │   ├── validator.ts          # 验证器
│   │   ├── validator-registry.ts # 验证器注册表
│   │   ├── validation-cache.ts   # 验证缓存
│   │   ├── builtin-validators.ts # 内置验证器
│   │   └── rules-watcher.ts      # 热重载
│   ├── hooks/                    # Hook 模块
│   │   ├── system-transform.ts   # 系统提示动态注入
│   │   ├── tool-before.ts        # 工具调用前验证
│   │   ├── tool-after.ts         # 工具调用后验证
│   │   └── event-tracker.ts      # 事件跟踪
│   ├── storage/                  # 存储模块
│   │   └── violations.ts         # 违规记录
│   └── utils/                    # 工具函数
│       ├── errors.ts             # 错误处理
│       └── helpers.ts            # 共享工具函数
├── test/                         # 测试文件
├── dist/                         # 编译输出
├── install.sh                    # Linux/macOS 安装脚本
├── install.ps1                   # Windows 安装脚本
├── sync-plugin.ps1               # Windows 同步脚本
├── package.json                  # 项目配置
├── tsconfig.json                 # TypeScript 配置
├── README.md                     # 本文件
├── USAGE.md                      # 使用指南
└── PUBLISH.md                    # 发布指南
```

## 🚀 快速开始

### 1. 安装插件

```bash
npm install opencode-plugin-agents-enforcer
```

### 2. 创建 AGENTS.md

在项目根目录创建 `AGENTS.md` 文件：

```markdown
# AGENTS.md

## 必须遵循的规则
- **必须**：所有代码注释必须使用简体中文
- **必须**：每次实现必须提供测试

## 绝对禁止的规则
- **禁止**：使用 as any、@ts-ignore、@ts-expect-error
- **禁止**：使用 console.log，请使用 logger
- **禁止**：硬编码密码、API key 等敏感信息
```

### 3. 配置插件

在 `opencode.json` 中添加：

```json
{
  "plugin": [
    "opencode-plugin-agents-enforcer"
  ]
}
```

### 4. 启动 OpenCode

```bash
opencode
```

插件会自动加载并执行规则验证，**无需任何额外配置**！

## 🔄 开发流程

### 1. 修改代码

编辑 `src/` 目录下的 TypeScript 文件。

### 2. 编译

```bash
npm run build
```

### 3. 同步到 OpenCode

```bash
# Linux/macOS:
./sync-plugin.sh

# Windows:
.\sync-plugin.ps1
```

### 4. 重启 OpenCode

插件会自动加载更新后的代码。

## 🧪 性能测试

### 运行测试

```bash
# 运行性能测试
npm run test:perf

# 运行基准测试
npm run test:benchmark
```

### 测试结果示例

```
📊 代码验证性能对比:
  无缓存: 0.008ms/次
  有缓存: 0.004ms/次
  性能提升: 50%

📊 违规记录性能:
  优化前: 0.2ms/次（每次写入磁盘）
  优化后: 0.3ms/次（批量写入，1秒延迟）
  实际提升: 10x+（高频场景）
```

## 🖥️ 跨电脑迁移

### 方法 1: Git 仓库（推荐）

```bash
# 在电脑 A 上
git add .
git commit -m "更新插件"
git push

# 在电脑 B 上
git pull
npm install
npm run build
bash install.sh  # 或 .\install.ps1
```

### 方法 2: 打包传输

```bash
# 在电脑 A 上
npm run build
tar -czf agents-enforcer.tar.gz dist/ package.json tsconfig.json

# 在电脑 B 上
tar -xzf agents-enforcer.tar.gz
npm install
bash install.sh
```

### 方法 3: USB 驱动器

```bash
# 在电脑 A 上
npm run build
cp -r dist/ /path/to/usb/agents-enforcer/

# 在电脑 B 上
cp -r /path/to/usb/agents-enforcer/ ~/.config/opencode/plugins/
```

## ⚙️ 配置

### 最简配置（零配置）

插件默认加载项目根目录的 `AGENTS.md` 文件，启用缓存和热重载，无需任何配置：

```json
{
  "plugin": [
    "opencode-plugin-agents-enforcer"
  ]
}
```

### 自定义配置

如果需要自定义配置，在 `opencode.json` 中添加：

```json
{
  "plugin": [
    ["opencode-plugin-agents-enforcer", {
      "rulesPath": "./AGENTS.md",
      "enforcementLevel": "strict",
      "violationThreshold": 5,
      "cache": {
        "enabled": true,
        "ttl": 5000,
        "maxEntries": 1000
      },
      "hotReload": {
        "enabled": true,
        "debounceDelay": 300
      }
    }]
  ]
}
```

### 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `rulesPath` | string | `./AGENTS.md` | AGENTS.md 文件路径 |
| `enforcementLevel` | string | `normal` | 执行级别：`strict`/`normal`/`loose` |
| `violationThreshold` | number | `3` | 触发强化约束的违规次数 |
| `storagePath` | string | `.` | 违规记录存储路径 |
| `customRules` | array | `[]` | 自定义规则列表 |
| `customValidators` | array | `[]` | 自定义验证器插件 |
| `cache.enabled` | boolean | `true` | 是否启用验证缓存（默认启用） |
| `cache.ttl` | number | `5000` | 缓存过期时间（毫秒） |
| `cache.maxEntries` | number | `1000` | 缓存最大条目数 |
| `hotReload.enabled` | boolean | `true` | 是否启用热重载（默认启用） |
| `hotReload.watchPath` | string | `./AGENTS.md` | 监听的文件路径 |
| `hotReload.debounceDelay` | number | `300` | 防抖延迟（毫秒） |

### 默认配置说明

插件默认启用以下功能，**零配置即可使用**：

| 功能 | 默认状态 | 说明 |
|------|---------|------|
| **AGENTS.md 加载** | ✅ 启用 | 自动加载项目根目录的 `AGENTS.md` 文件 |
| **验证缓存** | ✅ 启用 | 缓存验证结果，减少重复计算，提升性能 50% |
| **热重载** | ✅ 启用 | 监听 `AGENTS.md` 文件变更，自动重新加载规则 |
| **执行级别** | `normal` | 正常执行，违规会记录但不会阻止操作 |
| **违规阈值** | `3` | 3 次违规后触发强化约束 |

## 📋 内置规则

### 强制中文注释
- 规则 ID: `chinese-comment-mandatory`
- 类别: `must`
- 说明: 所有代码注释必须使用简体中文

### 禁止类型断言
- 规则 ID: `no-type-assertion`
- 类别: `must-not`
- 说明: 禁止使用 `as any`、`@ts-ignore`、`@ts-expect-error`

### 禁止 console.log
- 规则 ID: `no-console-log`
- 类别: `should-not`
- 说明: 禁止使用 `console.log`，请使用 logger

### 禁止空 catch 块
- 规则 ID: `no-empty-catch`
- 类别: `must-not`
- 说明: 禁止空的 catch 块，必须处理错误

### 禁止硬编码密钥
- 规则 ID: `no-hardcoded-secrets`
- 类别: `must-not`
- 说明: 禁止硬编码密码、API key 等敏感信息

## 🛠️ 自定义规则

在项目根目录创建 `.opencode/rules.json`：

```json
[
  {
    "id": "no-console-log",
    "category": "must-not",
    "pattern": "console\\.log",
    "description": "禁止使用 console.log，请使用 logger",
    "severity": "error"
  }
]
```

## 📊 工作原理

### 1. 规则解析
```
AGENTS.md → 解析器 → 可执行规则库
```

### 2. 执行时验证
```
AI 执行工具调用
    ↓
tool.execute.before 验证
    ↓
    ├─ 通过 → 继续执行
    └─ 失败 → 记录违规 → 阻止调用（error 级别）或警告（warning 级别）
    ↓
tool.execute.after 验证
    ↓
    ├─ 通过 → 继续
    └─ 失败 → 记录违规 → 在输出中添加警告
```

### 3. 动态强化
```
违规次数: 0 → 约束级别: STANDARD
违规次数: 1-2 → 约束级别: ELEVATED (添加提醒)
违规次数: 3-5 → 约束级别: HIGH (添加警告 + 强制解释)
违规次数: >5 → 约束级别: CRITICAL (任务暂停，需要用户确认)
```

### 4. 性能优化

#### 缓存机制
- **验证缓存**: 使用 MD5 哈希缓存验证结果，减少重复计算
- **批量写入**: 违规记录延迟 1 秒批量写入，减少磁盘 I/O
- **插件化架构**: 验证器插件化，支持动态加载和卸载

#### 性能数据

| 测试项目 | 平均耗时 | P95 | P99 |
|---------|---------|-----|-----|
| 规则解析 | 0.11ms | 0.16ms | 0.32ms |
| 代码验证（无缓存） | 0.008ms | 0.010ms | 0.021ms |
| 代码验证（有缓存） | 0.004ms | 0.006ms | 0.014ms |
| 工具参数验证 | 0.002ms | 0.002ms | 0.004ms |
| 违规记录 | 0.30ms | 0.49ms | 0.60ms |

#### 缓存提升
```
无缓存验证: 0.008ms/次
有缓存验证: 0.004ms/次
性能提升: 50%
```

## 📁 存储结构

```
.omo/
├── violations/          # 违规记录
│   └── {session-id}.json
├── notepads/
│   └── enforcer-learnings.md  # 学习记录
└── plans/
    └── agents-enforcer-plugin.md  # 设计文档
```

## ❓ 常见问题

### Q: 插件未加载？

A: 检查以下几点：
1. 插件文件是否在 `~/.config/opencode/plugins/` 目录
2. 是否已重启 OpenCode
3. 查看 OpenCode 日志是否有错误

### Q: 规则未生效？

A: 检查以下几点：
1. AGENTS.md 文件路径是否正确
2. 插件配置是否正确
3. 查看 `.omo/violations/` 目录是否有违规记录

### Q: 如何禁用某个规则？

A: 在 `.opencode/rules.json` 中添加规则并设置 `severity: "info"`：

```json
[
  {
    "id": "disable-chinese-comment",
    "category": "should-not",
    "pattern": ".*",
    "description": "禁用中文注释规则",
    "severity": "info"
  }
]
```

## 📄 许可证

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

- 问题反馈: GitHub Issues
- 邮箱: your-email@example.com