AGENTS.md 规则强制执行插件

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

当前版本: 1.2.0

🚀 快速安装

从 npm 安装（推荐）

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

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

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

从 Git 仓库安装

# 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

手动安装

# 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. 安装插件

npm install opencode-plugin-agents-enforcer

2. 创建 AGENTS.md

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

# AGENTS.md

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

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

3. 配置插件

在 opencode.json 中添加：

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

4. 启动 OpenCode

opencode

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

🔄 开发流程

1. 修改代码

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

2. 编译

npm run build

3. 同步到 OpenCode

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

# Windows:
.\sync-plugin.ps1

4. 重启 OpenCode

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

🧪 性能测试

运行测试

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

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

测试结果示例

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

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

🖥️ 跨电脑迁移

方法 1: Git 仓库（推荐）

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

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

方法 2: 打包传输

# 在电脑 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 驱动器

# 在电脑 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 文件，启用缓存和热重载，无需任何配置：

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

自定义配置

如果需要自定义配置，在 opencode.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 | 防抖延迟（毫秒） | | logging.enabled | boolean | true | 是否启用日志文件输出 | | logging.logFile | string | .omo/enforcer.log | 日志文件路径 | | logging.level | string | info | 日志级别：debug/info/warn/error |

默认配置说明

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

| 功能 | 默认状态 | 说明 | |------|---------|------| | 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：

[
  {
    "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  # 设计文档
└── enforcer.log         # 日志文件（可选）

❓ 常见问题

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"：

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

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系方式

• 问题反馈: GitHub Issues
• 邮箱: [email protected]