@hddz/plugin-harness 0.1.19 → 0.2.1

package/README.md

@@ -1,45 +1,46 @@
 # @hddz/plugin-harness
 
-> **Harness Engineering 插件** - 为 AI Agent 构建约束、反馈与控制系统  
-> **版本**: 0.1.17  
-> **作者**: 蓝山  
-> **许可**: MIT
+> OpenClaw Harness Engineering 插件 - 为 AI Agent 构建约束、反馈与控制系统
+
+**最新版本**: v0.2.0 (2026-03-24)
 
 ---
 
-## 🎯 功能特性
+## 🎯 功能
 
-| 功能 | 说明 | 状态 |
-|------|------|------|
-| **配置验证** | 修改 `openclaw.json` 前自动验证，防止无效配置导致系统崩溃 | ✅ |
-| **Skill 审核** | 安装 Skill 前自动扫描安全风险 | ✅ |
-| **循环检测** | 检测 AI 对同一文件反复修改，防止死循环 | ✅ |
-| **文件保护** | 保护关键文件（SOUL.md 等）不被误删 | ✅ |
-| **操作审计** | 记录所有关键操作（编辑/删除/命令） | ✅ |
-| **Trace 追踪** | 完整的工具调用链路追踪 | ✅ |
+- ✅ **配置验证**：修改 `openclaw.json` 前自动验证
+- ✅ **Skill 审核**：安装 Skill 前自动安全扫描
+- ✅ **循环检测**：防止 AI 反复修改同一文件
+- ✅ **文件保护**：保护关键文件（SOUL.md 等）不被误删
+- ✅ **操作审计**：记录所有关键操作
+- ✅ **Trace 追踪**：完整的工具调用链路
+- ✅ **文件监听器** (v0.2.0 新增)：实时监听配置文件变化，用户手动编辑也能触发验证
 
 ---
 
 ## 🚀 快速开始
 
-### 方式一：使用 OpenClaw CLI（推荐）
+### 安装
 
 ```bash
-# 安装插件
-openclaw plugins install @hddz/plugin-harness@0.1.13
-
-# 重启 Gateway
-openclaw gateway restart
+# 从 npm 安装（推荐）
+npm install @hddz/plugin-harness@0.2.0
 
-# 验证安装
-openclaw plugins list
+# 本地开发版
+cd /Users/hzl/.openclaw/extensions/harness
+npm link
 ```
 
-**配置**：编辑 `~/.openclaw/openclaw.json`，添加：
+### 配置
+
+编辑 `~/.openclaw/openclaw.json`：
 
 ```json
 {
   "plugins": {
+    "installs": [
+      "@hddz/plugin-harness@0.2.0"
+    ],
     "entries": {
       "harness": {
         "enabled": true,
@@ -55,7 +56,7 @@ openclaw plugins list
             "MEMORY.md",
             "openclaw.json"
           ],
-          "logsDir": "workspace/logs/harness"
+          "logsDir": "logs/harness"
         }
       }
     }
@@ -63,13 +64,9 @@ openclaw plugins list
 }
 ```
 
-### 方式二：从本地目录安装（开发用）
+然后重启 gateway：
 
 ```bash
-# 链接本地插件目录
-openclaw plugins install -l /Users/hzl/.openclaw/workspace/harness-plugin
-
-# 重启 Gateway
 openclaw gateway restart
 ```
 
@@ -79,17 +76,35 @@ openclaw gateway restart
 
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `autoValidateConfig` | boolean | `true` | 自动验证配置变更 |
-| `autoAuditSkill` | boolean | `true` | 自动审核 Skill 安装 |
-| `loopDetectionEnabled` | boolean | `true` | 启用循环检测 |
-| `protectedFiles` | string[] | `[SOUL.md, ...]` | 保护文件列表 |
-| `logsDir` | string | `workspace/logs/harness` | 日志目录 |
+| `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
 # 查看最近的配置变更
@@ -97,112 +112,80 @@ harness get-config-changes -l 10
 
 # 查看操作日志
 harness get-operations -l 20
+
+# 查看循环检测统计
+harness loop-stats
 ```
 
 ---
 
-## 🏗️ 架构设计
+## 🛡️ 安全机制
 
-### Hook 系统
+### 保护文件
 
-| Hook | 触发时机 | 功能 |
-|------|----------|------|
-| `onConfigChange` | 修改 `openclaw.json` 前 | 验证配置有效性 |
-| `onSkillInstall` | 安装 Skill 前 | 扫描安全风险 |
-| `onFileEdit` | 编辑文件时 | 循环检测 + 保护文件监控 |
-| `onFileDelete` | 删除文件前 | 拦截保护文件删除 |
-| `onExecCommand` | 执行命令前 | 记录审计日志 |
+以下文件默认受保护，修改/删除前会告警：
 
-### 目录结构
+- `SOUL.md` - 身份定义
+- `USER.md` - 用户信息
+- `AGENTS.md` - Agent 指南
+- `TOOLS.md` - 工具配置
+- `MEMORY.md` - 长期记忆
+- `openclaw.json` - 核心配置
 
-```
-harness-plugin/
-├── src/
-│   └── index.ts          # 插件核心逻辑
-├── dist/                 # 编译输出
-├── docs/                 # 文档
-├── openclaw.plugin.json  # OpenClaw 插件元数据
-├── package.json          # NPM 配置
-├── tsconfig.json         # TypeScript 配置
-└── README.md             # 本文件
-```
+### 风险等级
 
----
+| 等级 | 标识 | 处理 |
+|------|------|------|
+| LOW | 🟢 | 允许 |
+| MEDIUM | 🟡 | 警告，但允许 |
+| HIGH | 🟠 | 阻止，需人工确认 |
+| CRITICAL | 🔴 | 阻止，禁止操作 |
 
-## 🐛 常见问题
+---
 
-### Q: 插件加载失败？
+## 📚 文档
 
-**A**: 检查：
-1. 确认安装成功：`openclaw plugins list`
-2. 查看日志：`openclaw gateway status`
-3. 确认 `openclaw.json` 配置了 `plugins.entries.harness`
-4. 检查 manifest：`cat ~/.openclaw/extensions/harness/openclaw.plugin.json`
+- [使用指南](./docs/使用指南.md)
+- [开发文档](./docs/开发文档.md)
+- [API 参考](./docs/API.md)
 
-### Q: 配置验证不工作？
+---
 
-**A**: 检查 `openclaw.json` 中：
-```json
-{
-  "plugins": {
-    "entries": {
-      "harness": {
-        "enabled": true,
-        "config": {
-          "autoValidateConfig": true
-        }
-      }
-    }
-  }
-}
-```
+## 🔧 开发
 
-### Q: 如何禁用某个功能？
+```bash
+# 安装依赖
+npm install
 
-**A**: 修改 `openclaw.json` 配置：
-```json
-{
-  "plugins": {
-    "entries": {
-      "harness": {
-        "config": {
-          "autoValidateConfig": false,
-          "loopDetectionEnabled": false
-        }
-      }
-    }
-  }
-}
-```
+# 构建
+npm run build
 
-### Q: 如何卸载？
+# 测试
+npm test
 
-**A**: 
-```bash
-openclaw plugins uninstall harness
-openclaw gateway restart
+# 链接到 OpenClaw
+npm link
 ```
 
 ---
 
-## 📚 更多文档
+## 📝 变更日志
+
+### v0.1.0 (2026-03-19)
 
-- [Harness 插件开发完整教程](./docs/Harness 插件开发完整教程.md)
-- [发布与安装指南](./docs/发布与安装指南.md)
+- ✅ 初始版本
+- ✅ 配置验证
+- ✅ Skill 审核
+- ✅ 循环检测
+- ✅ 操作日志
+- ✅ Trace 追踪
 
 ---
 
-## 📦 发布历史
+## 📄 许可证
 
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| 0.1.10 | 2026-03-24 | 添加 `openclaw.plugin.json` manifest，支持 `openclaw plugins install` |
-| 0.1.9 | 2026-03-24 | 提供 `install.sh` 一键安装脚本 |
-| 0.1.8 | 2026-03-24 | 修复 Skill 审核路径问题 |
-| 0.1.7 | 2026-03-23 | 初始发布到 npm |
+MIT
 
 ---
 
-**许可证**: MIT  
-**仓库**: https://github.com/hddz/plugin-harness  
-**npm**: https://www.npmjs.com/package/@hddz/plugin-harness
+_@openclaw/plugin-harness | 蓝山 | 2026-03-19_

package/dist/core/auditors/index.d.ts

@@ -0,0 +1,2 @@
+export { SkillAuditor } from './skill-auditor';
+export type { SkillAuditResult, Warning, SkillMetadata } from './skill-auditor';

package/dist/core/auditors/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// src/auditors/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillAuditor = void 0;
+var skill_auditor_1 = require("./skill-auditor");
+Object.defineProperty(exports, "SkillAuditor", { enumerable: true, get: function () { return skill_auditor_1.SkillAuditor; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvY29yZS9hdWRpdG9ycy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsd0JBQXdCOzs7QUFFeEIsaURBQStDO0FBQXRDLDZHQUFBLFlBQVksT0FBQSIsInNvdXJjZXNDb250ZW50IjpbIi8vIHNyYy9hdWRpdG9ycy9pbmRleC50c1xuXG5leHBvcnQgeyBTa2lsbEF1ZGl0b3IgfSBmcm9tICcuL3NraWxsLWF1ZGl0b3InO1xuZXhwb3J0IHR5cGUgeyBTa2lsbEF1ZGl0UmVzdWx0LCBXYXJuaW5nLCBTa2lsbE1ldGFkYXRhIH0gZnJvbSAnLi9za2lsbC1hdWRpdG9yJztcbiJdfQ==

package/dist/core/auditors/skill-auditor.d.ts

@@ -0,0 +1,72 @@
+export interface SkillAuditResult {
+    skillName: string;
+    skillPath: string;
+    source: string;
+    riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    passed: boolean;
+    warnings: Warning[];
+    recommendations: string[];
+    metadata: SkillMetadata;
+}
+export interface Warning {
+    type: 'dangerous_code' | 'permission' | 'dependency' | 'network' | 'other';
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    message: string;
+    file?: string;
+    line?: number;
+}
+export interface SkillMetadata {
+    hasSkillMd: boolean;
+    hasScripts: boolean;
+    hasPackageJson: boolean;
+    declaredPermissions: string[];
+    dependencies: string[];
+    devDependencies: string[];
+    lastModified?: Date;
+}
+export declare class SkillAuditor {
+    private workspacePath;
+    constructor(workspacePath: string);
+    /**
+     * 审核 Skill
+     */
+    audit(skillPath: string, source?: string): Promise<SkillAuditResult>;
+    /**
+     * 检查来源
+     */
+    private checkSource;
+    /**
+     * 检查权限声明
+     */
+    private checkPermissions;
+    /**
+     * 扫描危险代码
+     */
+    private scanDangerousCode;
+    /**
+     * 扫描脚本文件
+     */
+    private scanScripts;
+    /**
+     * 检查依赖
+     */
+    private checkDependencies;
+    /**
+     * 获取 Skill 元数据
+     */
+    private getSkillMetadata;
+    /**
+     * 获取所有 JS 文件
+     */
+    private getJsFiles;
+    /**
+     * 计算风险等级
+     */
+    private calculateRiskLevel;
+    /**
+     * 生成审计报告
+     */
+    generateReport(result: SkillAuditResult): string;
+    private getRiskEmoji;
+    private getSeverityEmoji;
+}