open-index/open-npm huggingface dataset:
npm package: @hddz/plugin-harness
Description: Harness Engineering plugin for OpenClaw - constraints, feedback loops, and control systems for AI agents
Author: 蓝山
Latest version: 0.2.13

# @hddz/plugin-harness

> OpenClaw Harness Engineering 插件 - 为 AI Agent 构建约束、反馈与控制系统

**最新版本**: v0.2.3 (2026-03-25) ✨ **安装即配置**

---

## 🎯 功能

- ✅ **配置验证**：修改 `openclaw.json` 前自动验证
- ✅ **Skill 审核**：安装 Skill 前自动安全扫描
- ✅ **循环检测**：防止 AI 反复修改同一文件
- ✅ **文件保护**：保护关键文件（SOUL.md 等）不被误删
- ✅ **操作审计**：记录所有关键操作
- ✅ **Trace 追踪**：完整的工具调用链路
- ✅ **文件监听器** (v0.2.0 新增)：实时监听配置文件变化，用户手动编辑也能触发验证
- ✅ **自动配置** (v0.2.3 新增)：安装时自动配置，无需手动编辑

---

## 🚀 快速开始

### 安装（一键完成）

```bash
# 从 npm 安装（推荐）- 自动配置！
npm install @hddz/plugin-harness@0.2.3

# 安装完成后重启 Gateway
openclaw gateway restart
```

**🎉 就这么简单！** 安装脚本会自动：
1. 将 harness 添加到允许插件列表
2. 配置默认安全选项
3. 备份原配置文件
4. 提示你重启 Gateway

### 手动配置（可选）

如果你想自定义配置，编辑 `~/.openclaw/openclaw.json`：

```json
{
  "plugins": {
    "allow": ["harness"],
    "entries": {
      "harness": {
        "enabled": true,
        "config": {
          "autoValidateConfig": true,
          "autoAuditSkill": true,
          "loopDetectionEnabled": true,
          "protectedFiles": [
            "SOUL.md",
            "USER.md",
            "AGENTS.md",
            "TOOLS.md",
            "MEMORY.md",
            "openclaw.json"
          ],
          "logsDir": "logs/harness"
        }
      }
    }
  }
}
```

然后重启 gateway：

```bash
openclaw gateway restart
```

---

## 📋 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `autoValidateConfig` | boolean | true | 配置修改前自动验证 |
| `autoAuditSkill` | boolean | true | Skill 安装前自动审核 |
| `loopDetectionEnabled` | boolean | true | 启用循环检测 |
| `protectedFiles` | string[] | 见上文 | 受保护的文件列表 |
| `logsDir` | string | logs/harness | 日志目录 |

---

## 🔍 使用示例

### 配置验证（自动）

```typescript
// 修改 openclaw.json 时自动触发
const result = await plugin.onConfigChange(newConfig);
// 如果验证失败，会抛出异常阻止修改
```

### Skill 审核（自动）

```typescript
// 安装 Skill 时自动触发
const auditResult = await plugin.onSkillInstall('/path/to/skill');
if (!auditResult.passed) {
  throw new Error(`Skill 审核未通过：${auditResult.riskLevel}`);
}
```

### 手动查询

```bash
# 查看最近的配置变更
harness get-config-changes -l 10

# 查看操作日志
harness get-operations -l 20

# 查看循环检测统计
harness loop-stats
```

---

## 🛡️ 安全机制

### 保护文件

以下文件默认受保护，修改/删除前会告警：

- `SOUL.md` - 身份定义
- `USER.md` - 用户信息
- `AGENTS.md` - Agent 指南
- `TOOLS.md` - 工具配置
- `MEMORY.md` - 长期记忆
- `openclaw.json` - 核心配置

### 风险等级

| 等级 | 标识 | 处理 |
|------|------|------|
| LOW | 🟢 | 允许 |
| MEDIUM | 🟡 | 警告，但允许 |
| HIGH | 🟠 | 阻止，需人工确认 |
| CRITICAL | 🔴 | 阻止，禁止操作 |

---

## 📚 文档

- [使用指南](./docs/使用指南.md)
- [开发文档](./docs/开发文档.md)
- [API 参考](./docs/API.md)

---

## 🔧 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test

# 链接到 OpenClaw
npm link
```

---

## 📝 变更日志

### v0.1.0 (2026-03-19)

- ✅ 初始版本
- ✅ 配置验证
- ✅ Skill 审核
- ✅ 循环检测
- ✅ 操作日志
- ✅ Trace 追踪

---

## 📄 许可证

MIT

---

_@openclaw/plugin-harness | 蓝山 | 2026-03-19_