npm package: @openclaw-harness/guardrails
Description: OpenClaw Harness Guardrails - Comprehensive safety and security layer for Agent interactions
Author: OpenClaw Harness Team
Latest version: 0.1.0

# @openclaw-harness/guardrails

[![npm version](https://badge.fury.io/js/@openclaw-harness%2Fguardrails.svg)](https://www.npmjs.com/package/@openclaw-harness/guardrails)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[English](./README.md) | 中文

> 用于 Agent 交互的全面安全和防护护栏

## 特性

- 🔒 **输入验证** - PII 检测、毒性过滤、注入防护
- ✅ **输出审查** - 幻觉检测、策略合规
- 🛡️ **执行控制** - 工具权限、速率限制、成本追踪
- 📊 **违规追踪** - 全面的审计日志

## 安装

```bash
npm install @openclaw-harness/guardrails
```

## 快速开始

```typescript
import { HarnessGuardrailsPlugin } from '@openclaw-harness/guardrails';

const plugin = new HarnessGuardrailsPlugin();

// 初始化
await plugin.init(openClawContext);

// 获取护栏服务
const guardrailsService = openClawContext.api.getService('harness:guardrails');

// 验证输入
const result = await guardrailsService.validateInput(
  'Contact me at john@example.com'
);

if (!result.valid) {
  console.log('检测到 PII:', result.violations);
  console.log('脱敏后:', result.sanitized);
}
```

## 检测类型

### 输入护栏
- **PII 检测** - 邮箱、电话、身份证号、信用卡等
- **毒性检测** - 侮辱性语言、威胁、仇恨言论
- **注入检测** - 提示词注入、越狱尝试

### 输出护栏
- **幻觉检测** - 识别不确定的陈述
- **策略合规** - 检查是否符合使用策略

### 执行护栏
- **工具权限** - 控制可访问的工具
- **速率限制** - 防止过度使用
- **成本追踪** - 监控 API 调用成本

## CLI 命令

```bash
# 查看护栏状态
openclaw harness:guardrails:status

# 查看违规记录
openclaw harness:guardrails:violations --limit 10

# 验证输入
openclaw harness:guardrails:validate "需要验证的文本"

# 审查输出
openclaw harness:guardrails:review "AI 生成的响应"
```

## HTTP API

```bash
# 查看状态
curl http://localhost:3000/harness/guardrails/status

# 验证输入
curl -X POST http://localhost:3000/harness/guardrails/validate \
  -H "Content-Type: application/json" \
  -d '{"input": "Contact me at john@example.com"}'

# 审查输出
curl -X POST http://localhost:3000/harness/guardrails/review \
  -H "Content-Type: application/json" \
  -d '{"output": "AI response here"}'

# 查看违规记录
curl "http://localhost:3000/harness/guardrails/violations?limit=10&type=pii"
```

## 配置示例

```json
{
  "enabled": true,
  "layers": {
    "input": {
      "enabled": true,
      "onViolation": "block",
      "guardrails": [
        { "id": "input-pii", "type": "pii", "enabled": true },
        { "id": "input-toxicity", "type": "toxicity", "enabled": true },
        { "id": "input-injection", "type": "injection", "enabled": true }
      ]
    },
    "output": {
      "enabled": true,
      "onViolation": "warn",
      "guardrails": [
        { "id": "output-hallucination", "type": "hallucination", "enabled": true }
      ]
    },
    "execution": {
      "enabled": true,
      "onViolation": "block",
      "guardrails": [
        { "id": "exec-permission", "type": "permission", "enabled": true },
        { 
          "id": "exec-rate-limit", 
          "type": "rate-limit", 
          "enabled": true,
          "config": {
            "strategies": [
              {
                "id": "global",
                "scope": "global",
                "limit": 1000,
                "window": 60000
              }
            ]
          }
        }
      ]
    }
  }
}
```

## 文档

查看 [完整文档](https://github.com/your-username/harness-guardrails#readme) 获取更多详情。

## 许可证

MIT © [OpenClaw Harness Team](https://github.com/your-username)