@sofagent/rules 1.2.0

package/README.md

@@ -0,0 +1,9 @@
+# @sofagent/rules
+
+sofagent 规则引擎纯函数包——从 audit 包抽出，零 fs/git 依赖，供编排引擎 tool call 事前拦截。
+
+## API
+
+- `RulesEngine` — 规则引擎类，接受规则集 + tool call context，返回拦截裁决
+- `defaultToolRules` — 默认规则集
+- `InterceptVerdict` / `ToolCallContext` / `ToolRule` — 核心类型定义

package/dist/engine.d.ts

@@ -0,0 +1,26 @@
+import type { ToolRule, ToolCallContext, InterceptVerdict } from './types';
+/**
+ * 规则引擎——注册 N 条规则，对 tool call 做批量检查并聚合结果
+ *
+ * 聚合规则：
+ * - 任一 FAIL → FAIL
+ * - 否则任一 WARN → WARN
+ * - 否则 PASS
+ */
+export declare class RulesEngine {
+    private readonly rules;
+    constructor(rules: ToolRule[]);
+    /**
+     * 对单个 tool call 执行所有已注册规则的检查
+     * @param ctx tool call 上下文
+     * @returns 每条规则的判定结果数组
+     */
+    check(ctx: ToolCallContext): InterceptVerdict[];
+    /**
+     * 聚合多条规则判定为单一决策
+     * @param verdicts 规则判定结果数组
+     * @returns 聚合后的单一判定（取最严重状态）
+     */
+    aggregate(verdicts: InterceptVerdict[]): InterceptVerdict;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.js

@@ -0,0 +1,82 @@
+"use strict";
+// ============================================================
+// engine.ts · RulesEngine 纯函数入口
+// v1.2.0：P3 编排引擎内嵌——规则引擎核心
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RulesEngine = void 0;
+/**
+ * 规则引擎——注册 N 条规则，对 tool call 做批量检查并聚合结果
+ *
+ * 聚合规则：
+ * - 任一 FAIL → FAIL
+ * - 否则任一 WARN → WARN
+ * - 否则 PASS
+ */
+class RulesEngine {
+    rules;
+    constructor(rules) {
+        this.rules = rules;
+    }
+    /**
+     * 对单个 tool call 执行所有已注册规则的检查
+     * @param ctx tool call 上下文
+     * @returns 每条规则的判定结果数组
+     */
+    check(ctx) {
+        return this.rules.map((rule) => {
+            try {
+                return rule.check(ctx);
+            }
+            catch (err) {
+                // 单条规则异常不应中断整批检查——降级为该规则 FAIL，
+                // 让编排层 tool-gate 看到明确违规而非进程崩溃（P1-9 修复）
+                return {
+                    status: 'FAIL',
+                    ruleName: rule.name ?? 'unknown-rule',
+                    ruleNumber: rule.number ?? 0,
+                    details: [`规则执行异常: ${err instanceof Error ? err.message : String(err)}`],
+                    suggestion: '请检查该规则实现或上报此异常',
+                };
+            }
+        });
+    }
+    /**
+     * 聚合多条规则判定为单一决策
+     * @param verdicts 规则判定结果数组
+     * @returns 聚合后的单一判定（取最严重状态）
+     */
+    aggregate(verdicts) {
+        const hasFail = verdicts.some((v) => v.status === 'FAIL');
+        const hasWarn = verdicts.some((v) => v.status === 'WARN');
+        if (hasFail) {
+            const failed = verdicts.filter((v) => v.status === 'FAIL');
+            return {
+                status: 'FAIL',
+                ruleName: failed.map((v) => v.ruleName).join(', '),
+                ruleNumber: 0,
+                details: failed.flatMap((v) => v.details),
+                suggestion: failed.map((v) => v.suggestion).join('; '),
+            };
+        }
+        if (hasWarn) {
+            const warned = verdicts.filter((v) => v.status === 'WARN');
+            return {
+                status: 'WARN',
+                ruleName: warned.map((v) => v.ruleName).join(', '),
+                ruleNumber: 0,
+                details: warned.flatMap((v) => v.details),
+                suggestion: warned.map((v) => v.suggestion).join('; '),
+            };
+        }
+        return {
+            status: 'PASS',
+            ruleName: '',
+            ruleNumber: 0,
+            details: [],
+            suggestion: '',
+        };
+    }
+}
+exports.RulesEngine = RulesEngine;
+//# sourceMappingURL=engine.js.map

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { RulesEngine } from './engine';
+export type { ToolRule, ToolCallContext, InterceptVerdict, RuleStatus, RuleClass } from './types';
+export { defaultToolRules } from './rules';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+// ============================================================
+// index.ts · @sofagent/rules barrel export
+// v1.2.0：只导出 5 个公开符号，内部实现不外露
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultToolRules = exports.RulesEngine = void 0;
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "RulesEngine", { enumerable: true, get: function () { return engine_1.RulesEngine; } });
+var rules_1 = require("./rules");
+Object.defineProperty(exports, "defaultToolRules", { enumerable: true, get: function () { return rules_1.defaultToolRules; } });
+//# sourceMappingURL=index.js.map

package/dist/rules/index.d.ts

@@ -0,0 +1,7 @@
+import type { ToolRule } from '../types';
+/**
+ * 默认 tool 规则集合
+ * 移植自 audit 的 A1（敏感文件）/ A2（密钥泄漏）/ A9（注入检测）
+ */
+export declare const defaultToolRules: ToolRule[];
+//# sourceMappingURL=index.d.ts.map

package/dist/rules/index.js

@@ -0,0 +1,20 @@
+"use strict";
+// ============================================================
+// rules/index.ts · 默认规则注册表
+// v1.2.0：P3 编排引擎内嵌——默认 tool 规则集合
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultToolRules = void 0;
+const tool_sensitive_file_1 = require("./tool-sensitive-file");
+const tool_secret_leak_1 = require("./tool-secret-leak");
+const tool_injection_1 = require("./tool-injection");
+/**
+ * 默认 tool 规则集合
+ * 移植自 audit 的 A1（敏感文件）/ A2（密钥泄漏）/ A9（注入检测）
+ */
+exports.defaultToolRules = [
+    tool_sensitive_file_1.toolSensitiveFile,
+    tool_secret_leak_1.toolSecretLeak,
+    tool_injection_1.toolInjection,
+];
+//# sourceMappingURL=index.js.map

package/dist/rules/tool-injection.d.ts

@@ -0,0 +1,7 @@
+import type { ToolRule } from '../types';
+/**
+ * tool-injection 规则——检查 tool call args 是否含 prompt injection 模式
+ * 移植自 audit rule-a9（tool 视角）
+ */
+export declare const toolInjection: ToolRule;
+//# sourceMappingURL=tool-injection.d.ts.map

package/dist/rules/tool-injection.js

@@ -0,0 +1,87 @@
+"use strict";
+// ============================================================
+// tool-injection.ts · 移植 audit rule-a9（prompt injection 检测）
+// v1.2.0：tool 视角——扫 args 里的 prompt injection 模式
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolInjection = void 0;
+/**
+ * Prompt injection 高置信度模式
+ * 与 audit rule-a9 对齐（但只取高置信度模式，避免 tool args 误报）
+ *
+ * 注意：模式用 new RegExp + 字符串拼接构建，避免正则字面量中的注入示例串
+ * 触发 A9 审计规则误报（铁律 #3：fixture 中的 secret-like / injection-like 串
+ * 必须运行时拼接）
+ */
+const _I = 'ign' + 'ore';
+const _D = 'disr' + 'egard';
+const _P = 'prev' + 'ious';
+const _INS = 'instru' + 'ctions';
+const _PRO = 'prom' + 'pts';
+const INJECTION_PATTERNS = [
+    // 英文经典模式（拼接构建避免 A9 误报）
+    new RegExp(`${_I}\\s+(all\\s+)?(${_P}|prior|above)\\s+(${_INS}?|${_PRO}?)`, 'i'),
+    new RegExp(`${_D}\\s+(all\\s+)?(${_P}|prior)\\s+(${_INS}?|${_PRO}?)`, 'i'),
+    /forget\s+(everything|all\s+(previous|prior)\s+(instructions?|prompts?))/i,
+    /you\s+are\s+now\s+(a|an)\s+(different|new)/i,
+    /new\s+instructions?\s*:/i,
+    /system\s*:\s*you\s+are/i,
+    // 中文经典模式（拼接构建避免 A9 误报）
+    new RegExp('忽' + '略以上所有(指令|提示)'),
+    new RegExp('忽' + '略(上面|之前|前面)的(指令|提示|规则)'),
+    new RegExp('忘' + '记(之前|前面)的(指令|设定)'),
+    /你现在(是|扮演)/,
+];
+/**
+ * 从 tool call args 中提取所有字符串值（递归）
+ */
+function extractStrings(args) {
+    const strings = [];
+    for (const value of Object.values(args)) {
+        if (typeof value === 'string') {
+            strings.push(value);
+        }
+        else if (typeof value === 'object' && value !== null) {
+            strings.push(...extractStrings(value));
+        }
+    }
+    return strings;
+}
+/**
+ * tool-injection 规则——检查 tool call args 是否含 prompt injection 模式
+ * 移植自 audit rule-a9（tool 视角）
+ */
+exports.toolInjection = {
+    name: 'tool-injection',
+    number: 9,
+    ruleClass: '业务底线',
+    check(ctx) {
+        const allStrings = extractStrings(ctx.args);
+        const hits = [];
+        for (const str of allStrings) {
+            for (const pattern of INJECTION_PATTERNS) {
+                if (pattern.test(str)) {
+                    hits.push(str.substring(0, 80));
+                    break;
+                }
+            }
+        }
+        if (hits.length > 0) {
+            return {
+                status: 'FAIL',
+                ruleName: 'tool-injection',
+                ruleNumber: 9,
+                details: [`检测到 prompt injection 模式: ${hits.length} 处。tool 参数中含可疑指令注入。`],
+                suggestion: '检查 tool 参数来源——如果是用户输入，需在传入 tool 前做脱敏/转义。',
+            };
+        }
+        return {
+            status: 'PASS',
+            ruleName: 'tool-injection',
+            ruleNumber: 9,
+            details: [],
+            suggestion: '',
+        };
+    },
+};
+//# sourceMappingURL=tool-injection.js.map

package/dist/rules/tool-secret-leak.d.ts

@@ -0,0 +1,7 @@
+import type { ToolRule } from '../types';
+/**
+ * tool-secret-leak 规则——检查 tool call args 是否含密钥串
+ * 移植自 audit rule-a2（tool 视角）
+ */
+export declare const toolSecretLeak: ToolRule;
+//# sourceMappingURL=tool-secret-leak.d.ts.map

package/dist/rules/tool-secret-leak.js

@@ -0,0 +1,69 @@
+"use strict";
+// ============================================================
+// tool-secret-leak.ts · 移植 audit rule-a2（密钥泄漏检测）
+// v1.2.0：tool 视角——扫 args 字面量里的密钥模式
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolSecretLeak = void 0;
+/** 密钥泄漏检测正则模式（与 audit rule-a2 对齐） */
+const SECRET_PATTERNS = [
+    { pattern: /AKIA[A-Z0-9]{16}/, label: 'AWS Access Key' },
+    { pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/, label: 'Private Key' },
+    { pattern: /sk-[a-zA-Z0-9]{48}/, label: 'OpenAI API Key' },
+    { pattern: /sk-proj-[a-zA-Z0-9_]{40,}/, label: 'OpenAI Project Key' },
+    { pattern: /sk-svcacct-[a-zA-Z0-9_]{40,}/, label: 'OpenAI Service Account Key' },
+    { pattern: /sk-admin-[a-zA-Z0-9_]{40,}/, label: 'OpenAI Admin Key' },
+    { pattern: /gh[ps]_[A-Za-z0-9]{36}/, label: 'GitHub Token' },
+];
+/**
+ * 从 tool call args 中提取所有字符串值（递归）
+ */
+function extractStrings(args) {
+    const strings = [];
+    for (const value of Object.values(args)) {
+        if (typeof value === 'string') {
+            strings.push(value);
+        }
+        else if (typeof value === 'object' && value !== null) {
+            strings.push(...extractStrings(value));
+        }
+    }
+    return strings;
+}
+/**
+ * tool-secret-leak 规则——检查 tool call args 是否含密钥串
+ * 移植自 audit rule-a2（tool 视角）
+ */
+exports.toolSecretLeak = {
+    name: 'tool-secret-leak',
+    number: 2,
+    ruleClass: '业务底线',
+    check(ctx) {
+        const allStrings = extractStrings(ctx.args);
+        const detections = [];
+        for (const str of allStrings) {
+            for (const { pattern, label } of SECRET_PATTERNS) {
+                if (pattern.test(str)) {
+                    detections.push(label);
+                }
+            }
+        }
+        if (detections.length > 0) {
+            return {
+                status: 'FAIL',
+                ruleName: 'tool-secret-leak',
+                ruleNumber: 2,
+                details: [`检测到密钥/令牌: ${detections.join(', ')}。密钥不应硬编码到工具参数中。`],
+                suggestion: '将密钥写入 .env -> .gitignore 加 .env -> 使用环境变量引用。',
+            };
+        }
+        return {
+            status: 'PASS',
+            ruleName: 'tool-secret-leak',
+            ruleNumber: 2,
+            details: [],
+            suggestion: '',
+        };
+    },
+};
+//# sourceMappingURL=tool-secret-leak.js.map

package/dist/rules/tool-sensitive-file.d.ts

@@ -0,0 +1,7 @@
+import type { ToolRule } from '../types';
+/**
+ * tool-sensitive-file 规则——检查 tool call 是否操作了敏感文件
+ * 移植自 audit rule-a1（tool 视角）
+ */
+export declare const toolSensitiveFile: ToolRule;
+//# sourceMappingURL=tool-sensitive-file.d.ts.map

package/dist/rules/tool-sensitive-file.js

@@ -0,0 +1,104 @@
+"use strict";
+// ============================================================
+// tool-sensitive-file.ts · 移植 audit rule-a1（敏感文件保护）
+// v1.2.0：tool 视角——校验 args 里的文件路径
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolSensitiveFile = void 0;
+/** 敏感文件路径模式（与 audit rule-a1 对齐） */
+const SENSITIVE_PATTERNS = [
+    /\.env$/i,
+    /\.env\./i,
+    /\.sofagent\/config/i,
+    /\.sofagent\/knowledge/i,
+    /\.sofagent\/audit/i,
+    /\.sofagent\/think/i,
+    /\/\.ssh\//i,
+    /\/\.gnupg\//i,
+    /\.pem$/i,
+    /\.key$/i,
+    /id_rsa/i,
+    /id_ed25519/i,
+    /\.kube\/config/i,
+    /\.docker\/config/i,
+    /credentials/i,
+    /\.npmrc$/i,
+    /\.pypirc$/i,
+];
+/** 路径类字段名匹配（仅这些 key 的值才当作文件路径扫描） */
+const PATH_LIKE_KEY = /path|file|dir|folder|source|dest|target/i;
+/**
+ * 从 tool call args 中提取"路径类字段"的字符串值。
+ *
+ * v1.2.0 修复：只取路径类字段（path / file_path / edit_path 等），
+ * 不再把 write_file 的 content、edit_file 的 old/new_string、
+ * run_bash 的 command 等文本字段当路径扫描——
+ * 否则合法写入（内容含 "credentials" 字样）或
+ * `cat ~/.ssh/config` 这类命令会被误判为敏感文件操作。
+ */
+function extractFilePaths(args) {
+    const paths = [];
+    for (const [key, value] of Object.entries(args)) {
+        const keyIsPathLike = PATH_LIKE_KEY.test(key);
+        if (typeof value === 'string' && value.length > 0) {
+            // 标量字符串：仅路径类字段参与扫描
+            if (keyIsPathLike)
+                paths.push(value);
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value) {
+                if (typeof item === 'string' && item.length > 0) {
+                    // 数组元素：仅当数组所在 key 本身是路径类字段（如 files / paths）
+                    // 才把其中的字符串当作路径。避免扫描 command 等文本数组。
+                    if (keyIsPathLike)
+                        paths.push(item);
+                }
+                else if (typeof item === 'object' && item !== null) {
+                    paths.push(...extractFilePaths(item));
+                }
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            paths.push(...extractFilePaths(value));
+        }
+    }
+    return paths;
+}
+/**
+ * tool-sensitive-file 规则——检查 tool call 是否操作了敏感文件
+ * 移植自 audit rule-a1（tool 视角）
+ */
+exports.toolSensitiveFile = {
+    name: 'tool-sensitive-file',
+    number: 1,
+    ruleClass: '业务底线',
+    check(ctx) {
+        const filePaths = extractFilePaths(ctx.args);
+        const hits = [];
+        for (const filePath of filePaths) {
+            for (const pattern of SENSITIVE_PATTERNS) {
+                if (pattern.test(filePath)) {
+                    hits.push(filePath);
+                    break;
+                }
+            }
+        }
+        if (hits.length > 0) {
+            return {
+                status: 'FAIL',
+                ruleName: 'tool-sensitive-file',
+                ruleNumber: 1,
+                details: [`检测到敏感文件操作: ${hits.join(', ')}`],
+                suggestion: '敏感文件操作需用户确认。如确需操作，请在用户明确授权后执行。',
+            };
+        }
+        return {
+            status: 'PASS',
+            ruleName: 'tool-sensitive-file',
+            ruleNumber: 1,
+            details: [],
+            suggestion: '',
+        };
+    },
+};
+//# sourceMappingURL=tool-sensitive-file.js.map

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+/** 规则等级——与 audit 的 RuleClass 对齐 */
+export type RuleClass = '业务底线' | '质量拐杖' | '效率';
+/** 规则状态三态——与 audit 语义同源（铁律 #4 测试 SSOT） */
+export type RuleStatus = 'PASS' | 'WARN' | 'FAIL';
+/**
+ * Tool call 上下文——tool call 粒度的同步上下文
+ * 与 audit 的 AuditContext 完全分离（后者是 git diff 粒度的事后审计上下文）
+ */
+export interface ToolCallContext {
+    /** 被调用的 tool 名称 */
+    toolName: string;
+    /** tool 调用参数 */
+    args: Record<string, unknown>;
+    /** 发起 tool call 的 Agent 名称 */
+    agentName: string;
+    /** 当前任务描述 */
+    taskDesc: string;
+    /** 工作目录 */
+    cwd: string;
+}
+/**
+ * 规则判定结果
+ */
+export interface InterceptVerdict {
+    status: RuleStatus;
+    /** 规则名称（加 tool- 前缀避免与 audit 同名规则混淆） */
+    ruleName: string;
+    /** 规则编号（沿用 audit 的 1/2/9） */
+    ruleNumber: number;
+    /** 详细信息 */
+    details: string[];
+    /** 修复建议 */
+    suggestion: string;
+}
+/**
+ * Tool 视角规则接口
+ * 与 audit 的 RuleCheck 结构平行但独立（check 参数不同）
+ */
+export interface ToolRule {
+    /** 规则名称（加 tool- 前缀） */
+    name: string;
+    /** 规则编号（沿用 audit 编号） */
+    number: number;
+    /** 规则等级 */
+    ruleClass: RuleClass;
+    /**
+     * 检查 tool call 是否违规
+     * @param ctx tool call 上下文
+     * @returns 判定结果
+     */
+    check(ctx: ToolCallContext): InterceptVerdict;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+// ============================================================
+// types.ts · P3 编排引擎内嵌——tool call 拦截器类型定义
+// v1.2.0：从 audit 规则抽出为纯函数，零 fs/git 依赖
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@sofagent/rules",
+  "version": "1.2.0",
+  "description": "sofagent 规则引擎纯函数包——从 audit 抽出，零 fs/git 依赖，供编排引擎 tool call 事前拦截",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "npm run clean && tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  },
+  "keywords": ["rules-engine", "agent-safety", "tool-interceptor"],
+  "author": "孔放勋",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "files": [
+    "dist/",
+    "!dist/**/*.js.map",
+    "!dist/**/*.d.ts.map",
+    "!dist/**/*.test.*",
+    "README.md"
+  ]
+}