PromptSpeak Governance

promptspeak-mcp-server

AI Agent 执行前治理。在危险工具调用执行前将其拦截。

AI Agent 调用工具（文件写入、API 请求、Shell 命令）时，意图与执行之间没有验证层。提示词注入、幻觉参数或目标偏移都可能触发不可逆操作。PromptSpeak 会拦截每一次 MCP 工具调用，根据确定性规则对其进行验证，并在 0.1ms 内、任何操作执行之前，阻止或暂缓高风险操作以等待人工批准。

适用场景

• 你运行会调用工具（MCP 服务、函数调用、工具使用）的 AI Agent，需要在 Agent 与工具之间设置治理层。
• 你需要对高风险操作（生产环境部署、金融交易、法律文件提交）进行人工介入审批。
• 你希望检测行为偏移——Agent 逐渐偏离分配给它的任务。
• 你需要记录 Agent 尝试的每一次工具调用，无论调用获准还是被拦截。
• 你在受监管的领域（法律、金融、医疗）运营，Agent 的操作必须受到确定性约束。

安装

Claude Code

添加到 ~/.claude/settings.json（或项目级 .claude/settings.json）：

{
  "mcpServers": {
    "promptspeak": {
      "command": "npx",
      "args": ["promptspeak-mcp-server"]
    }
  }
}

重启 Claude Code。全部 56 个治理工具即可立即使用。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "promptspeak": {
      "command": "npx",
      "args": ["promptspeak-mcp-server"]
    }
  }
}

作为库使用

npm install promptspeak-mcp-server

从源代码安装

git clone https://github.com/chrbailey/promptspeak-mcp-server.git
cd promptspeak-mcp-server
npm install && npm run build
npm start

使用示例

1. 验证治理框架

在使用 PromptSpeak 框架前，验证其结构和语义是否正确。框架通过符号序列编码治理约束——先是模式，然后是领域、操作和实体。

// Tool call: ps_validate
{
  "name": "ps_validate",
  "arguments": {
    "frame": "⊕◊▶α",
    "validationLevel": "full"
  }
}

// Response
{
  "valid": true,
  "frame": "⊕◊▶α",
  "parsedFrame": {
    "mode": { "symbol": "⊕", "meaning": "strict" },
    "domain": { "symbol": "◊", "meaning": "financial" },
    "action": { "symbol": "▶", "meaning": "execute" },
    "entity": { "symbol": "α", "meaning": "primary" }
  },
  "parseConfidence": 1.0,
  "report": {
    "valid": true,
    "errors": [],
    "warnings": [
      { "code": "ACTION_MISSING_DOMAIN", "message": "Consider adding domain context", "severity": "warning" }
    ]
  },
  "summary": { "errors": 0, "warnings": 1, "passed": 16 }
}

无效框架会返回可操作的建议：

// Tool call: validate a frame with conflicting modes
{
  "name": "ps_validate",
  "arguments": { "frame": "⊕⊖▶", "validationLevel": "semantic" }
}

// Response: blocked — strict + flexible modes conflict
{
  "valid": false,
  "summary": { "errors": 1, "warnings": 0, "passed": 10 },
  "suggestions": ["Remove either ⊕ (strict) or ⊖ (flexible) - cannot have both"]
}

2. 暂缓队列工作流——人工介入审批

当 Agent 尝试执行高风险操作（漂移评分高、置信度低、发现安全问题）时，该操作会暂缓以供人工审核，而不会执行。以下是完整的暂缓生命周期：列出、检查、批准或拒绝。

步骤 1：列出待处理的暂缓项

// Tool call: ps_hold_list
{
  "name": "ps_hold_list",
  "arguments": {}
}

// Response: one hold awaiting human review
{
  "holds": [
    {
      "holdId": "hold_7k2m9x",
      "agentId": "devops-agent",
      "frame": "⊕◈▶α",
      "tool": "deploy_to_production",
      "severity": "high",
      "reason": "drift_prediction",
      "state": "pending",
      "evidence": { "driftScore": 0.72, "predictedDrift": 0.85 }
    }
  ],
  "count": 1,
  "expiredCount": 0
}

步骤 2：批准并修改（或拒绝）

// Tool call: ps_hold_approve — approve but downgrade to staging
{
  "name": "ps_hold_approve",
  "arguments": {
    "holdId": "hold_7k2m9x",
    "reason": "Reviewed — safe for staging, not production",
    "modifiedArgs": { "environment": "staging" }
  }
}

// Response
{
  "success": true,
  "decision": {
    "holdId": "hold_7k2m9x",
    "state": "approved",
    "decidedBy": "human",
    "reason": "Reviewed — safe for staging, not production"
  },
  "executionResult": { "success": true }
}

如需拒绝：

{
  "name": "ps_hold_reject",
  "arguments": {
    "holdId": "hold_7k2m9x",
    "reason": "Drift too high — recalibrate agent first",
    "haltAgent": true
  }
}
// Agent is halted (circuit breaker tripped) and the operation is denied.

3. 安全扫描——在执行前发现漏洞

在 Agent 将代码内容写入磁盘之前，扫描其中的安全问题。严重问题会阻止执行；高危问题会暂缓以供人工审核。

// Tool call: ps_security_scan
{
  "name": "ps_security_scan",
  "arguments": {
    "content": "const query = `SELECT * FROM users WHERE id = ${userId}`;\nconst API_KEY = 'sk-1234567890abcdef1234567890abcdef';"
  }
}

// Response: two findings — one critical (blocked), one critical (blocked)
{
  "findings": [
    {
      "patternId": "sql-injection",
      "severity": "critical",
      "match": "SELECT * FROM users WHERE id = ${userId}",
      "line": 1,
      "context": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
      "suggestion": "Use parameterized queries or prepared statements instead of template literals"
    },
    {
      "patternId": "hardcoded-secret",
      "severity": "critical",
      "match": "API_KEY = 'sk-1234567890abcdef1234567890abcdef'",
      "line": 2,
      "context": "const API_KEY = 'sk-1234567890abcdef1234567890abcdef';",
      "suggestion": "Move secrets to environment variables or a secrets manager"
    }
  ],
  "scannedAt": "2026-03-19T12:00:00.000Z",
  "contentLength": 98,
  "patternsChecked": 10,
  "enforcement": {
    "blocked": [
      { "patternId": "sql-injection", "severity": "critical" },
      { "patternId": "hardcoded-secret", "severity": "critical" }
    ],
    "held": [],
    "warned": [],
    "logged": []
  }
}

使用 ps_security_gate 替代 ps_security_scan 来强制执行策略——遇到严重问题时阻止执行，高危问题暂缓以供人工审核，中危问题则发出警告：

// Tool call: ps_security_gate — scan AND enforce
{
  "name": "ps_security_gate",
  "arguments": {
    "content": "app.use(cors());\napp.listen(0.0.0.0, 3000);",
    "action": "write_file"
  }
}

// Response: held for review (insecure defaults = high severity)
{
  "decision": "held",
  "reason": "Security: 1 high-severity finding(s) held for review — insecure-defaults",
  "scan": { "findings": [{ "patternId": "insecure-defaults", "severity": "high", "line": 1 }] }
}

工作原理：9 阶段验证流水线

每一次工具调用都会经过此流水线。任何阶段未通过，都会阻止执行。

Agent calls tool
  │
  ├─ 1. Circuit Breaker ──── Halted agents blocked instantly (no further checks)
  ├─ 2. Frame Validation ─── Structural, semantic, and chain rule checks
  ├─ 3. Drift Prediction ─── Pre-flight behavioral anomaly detection
  ├─ 4. Hold Check ────────── Risky operations held for human approval
  ├─ 5. Interceptor ───────── Final permission gate (confidence thresholds)
  ├─ 6. Security Scan ─────── Scans write actions for vulnerabilities (see below)
  ├─ 7. Tool Execution ────── Only reached if all 6 pre-checks pass
  ├─ 8. Post-Audit ────────── Confirms behavior matched prediction
  └─ 9. Immediate Action ──── Halts agent if critical drift detected post-execution

第 1–6 阶段是执行前阶段——任何检查未通过，工具都不会运行。第 8–9 阶段是执行后阶段——用于检测偏移，并可在后续调用中停止 Agent。

安全扫描

当 Agent 写入代码（write_file、edit_file、create_file、patch_file）时，执行前会根据 10 种检测模式扫描内容。执行策略取决于严重级别：

严重级别	执行策略	检测内容
CRITICAL	阻止 — 拒绝执行	通过模板字面量进行 SQL 注入、硬编码的 API 密钥/密码/令牌
HIGH	暂缓 — 排队等待人工审核	与安全相关的 TODO、记录敏感数据、不安全的默认设置（cors()、0.0.0.0、debug: true）
MEDIUM	警告 — 记录日志，继续执行	空的 catch 块、模棱两可的注释（“可能能用”）、已禁用的测试
LOW	记录 — 不执行任何限制	DROP TABLE、rm -rf（标记以供留意）

有效功能（已测试）

以下所有结论均有通过的测试作为依据（5 个测试文件共 104 项测试）：

• 模式检测有效。 10 种模式均经过真阳性和假阳性测试。例如：api_key = "sk-1234567890abcdef" 会被检测到；API_KEY = process.env.API_KEY 不会。SQL 注入检测会拦截 \SELECT * FROM users WHERE id = ${id}`，但不会拦截参数化查询（db.query("SELECT * FROM users WHERE id = ?", [id])`）。
• 严重级别执行策略有效。 严重级别的问题会阻止执行。高严重级别的问题会暂缓处理，等待审核。中等严重级别的问题会发出警告，但允许执行。已通过拦截器管道进行端到端测试。
• 仅扫描写入操作。 read_file 和其他非写入操作会直接通过，不进行扫描，即使其参数包含有漏洞的代码也是如此。已测试。
• 运行时配置有效。 可通过 ps_security_config 在运行时启用/禁用模式并更改严重级别。禁用某个模式后，该模式会立即停止触发。将某个模式的严重级别从 medium 改为 critical 后，它会改为阻止执行，而不是发出警告。已进行端到端测试。
• 性能良好。 扫描 100 行文件可在 10 ms 内完成。已测试。
• 可处理文件中的多个发现项。 对包含 6 种不同漏洞类型的文件，能够正确地将每种漏洞归入相应的严重级别类别。已测试。

目前尚未实现的功能

• HIGH 级别发现尚未集成保持队列。 已修复。 高严重性安全发现现在会通过 security_finding HoldReason 在 HoldManager 中创建实际保持项。它们会显示在 ps_hold_list 中，并可通过常规保持流程批准或拒绝。
• ps_execute 尚未自动扫描。 安全扫描仅在拦截器的 intercept() 方法中对直接工具调用触发。如果 Agent 使用 ps_execute（受治理的执行路径），只有当内部工具是写入操作且内容作为顶层参数传入时，才会运行扫描。嵌套参数结构可能绕过扫描。原因： ps_execute 使用自身的参数架构封装工具调用；扫描器检查的是 proposedArgs.content，不会深入检查嵌套字段。
• 尚不支持基于文件路径的扫描。 扫描器只检查作为参数传入的内容，无法扫描已存储在磁盘上的文件——它不会读取文件系统。原因： 扫描器是一个接收字符串的纯函数。添加文件系统访问会改变安全模型。
• 模式基于正则表达式，而非 AST。 模式使用正则表达式，因此无法理解代码结构。测试固件中的硬编码密钥或注释中的 SQL 注入仍会触发检测。误报率因模式而异，范围为 25%–70%（每种模式均有记录）。原因： AST 解析会增加依赖和复杂性。正则表达式速度快，对于会交由人工审核而非静默拦截的治理层来说已经足够。
• 部分持久化。 保持项和断路器状态现在会持久化到 SQLite（data/governance.db），并在服务重启后保留。不过，模式配置更改（通过 ps_security_config 启用／禁用模式或更改严重级别）仍仅保存在内存中，重启后会重置。原因： 模式配置轻量且很少更改；要实现完整的配置持久化，需要单独的配置存储。

MCP 工具（56 个）

核心治理

工具	何时调用	功能
ps_validate	执行任何 Agent 操作之前	根据所有规则验证一个帧，但不执行
ps_validate_batch	一次检查多个操作时	批量验证，提高效率
ps_execute	Agent 要发起工具调用时	完整流程：验证 → 检查保持项 → 执行 → 审计
ps_execute_dry_run	预览将会发生什么时	运行完整流程，但不执行工具

人机协同保持项

工具	何时调用	功能
ps_hold_list	审核待处理的 Agent 操作时	列出所有等待人工批准的操作
ps_hold_approve	允许继续执行某个保持操作时	批准操作，可选择修改参数
ps_hold_reject	拒绝某个保持操作时	拒绝操作并说明原因
ps_hold_config	调整哪些操作需要批准时	配置保持触发条件和阈值
ps_hold_stats	监控保持队列的运行状况时	保持队列统计信息

Agent 生命周期

工具	何时调用	功能
ps_state_get	检查 Agent 正在做什么时	获取 Agent 的活动帧和上次操作
ps_state_system	监控整体系统运行状况时	系统范围的统计信息
ps_state_halt	必须立即停止 Agent 时	触发断路器——阻止所有后续调用
ps_state_resume	允许已停止的 Agent 继续运行时	重置断路器
ps_state_reset	清除 Agent 状态时	完全重置状态
ps_state_drift_history	调查行为变化时	偏移检测警报历史记录

委派

工具	调用时机	功能
ps_delegate	Agent 创建子 Agent 时	创建权限受限的父级→子级委派
ps_delegate_revoke	撤销子 Agent 的权限时	移除委派
ps_delegate_list	审计委派链时	列出当前有效的委派

配置

工具	调用时机	功能
ps_config_set	运行时更改治理规则时	设置配置键值对
ps_config_get	读取当前配置时	获取当前配置
ps_config_activate	切换策略配置文件时	激活指定名称的配置
ps_config_export	备份配置时	将完整配置导出为 JSON
ps_config_import	恢复配置时	从 JSON 导入配置
ps_confidence_set	调整验证严格程度时	设置置信度阈值
ps_confidence_get	检查当前阈值时	获取当前阈值
ps_confidence_bulk_set	重新配置多个阈值时	批量更新阈值
ps_feature_set	切换管道阶段时	启用／禁用特定检查
ps_feature_get	检查哪些阶段处于启用状态时	获取功能标志

符号注册表（实体追踪）

工具	调用时机	功能
ps_symbol_create	注册新实体（公司、个人、系统）时	创建包含类型、元数据和标签的符号
ps_symbol_get	查找实体时	按 ID 检索
ps_symbol_update	实体数据发生变化时	更新元数据或标签
ps_symbol_list	按类型浏览实体时	列出实体，可选按类型筛选
ps_symbol_delete	移除实体时	按 ID 删除
ps_symbol_import	批量加载实体时	批量导入
ps_symbol_stats	监控注册表运行状况时	注册表统计信息
ps_symbol_format	显示实体时	格式化符号以供显示
ps_symbol_verify	确认实体数据为最新时	将符号标记为已验证
ps_symbol_list_unverified	审计过期数据时	列出需要验证的符号
ps_symbol_add_alternative	实体存在别名时	添加备用标识符

安全执行

工具	调用时机	功能
ps_security_scan	检查代码中的漏洞时	扫描内容，并按严重程度返回发现项
ps_security_gate	对写入操作执行安全策略时	扫描并执行策略：拦截／暂缓／警告／允许
ps_security_config	调整检测模式时	列出、启用、禁用模式或更改其严重程度

审计

工具	调用时机	功能
ps_audit_get	查看发生过的操作时	提供可筛选的完整审计记录

架构

src/
├── gatekeeper/       # 8-stage validation pipeline (core enforcement)
│   ├── index.ts      #   Pipeline orchestrator + agent eviction policy
│   ├── validator.ts  #   Frame structural/semantic/chain validation
│   ├── interceptor.ts#   Permission gate with confidence thresholds
│   ├── hold-manager.ts#  Human-in-the-loop hold queue
│   ├── resolver.ts   #   Frame resolution with operator overrides
│   └── coverage.ts   #   Coverage confidence calculator
├── drift/            # Behavioral drift detection
│   ├── circuit-breaker.ts  # Per-agent halt/resume
│   ├── baseline.ts         # Behavioral baseline comparison
│   ├── tripwire.ts         # Anomaly tripwires
│   └── monitor.ts          # Continuous monitoring
├── security/         # Security vulnerability scanning
│   ├── patterns.ts   #   10 detection patterns (regex-based)
│   └── scanner.ts    #   Scanner engine + severity classification
├── persistence/      # SQLite governance persistence
│   └── database.ts   #   Holds, decisions, circuit breakers (WAL mode)
├── symbols/          # SQLite-backed entity registry (11 CRUD tools)
├── policies/         # Policy file loader + overlay system
├── operator/         # Operator configuration
├── tools/            # MCP tool implementations
│   ├── registry.ts   #   29 core tools
│   ├── ps_hold.ts    #   5 hold tools
│   └── ps_security.ts#   3 security tools
├── handlers/         # Tool dispatch + metadata registry
├── core/             # Logging, errors, result patterns
└── server.ts         # MCP server entry point (stdio transport)

性能

PromptSpeak 为每次工具调用添加治理功能，开销不到 1 毫秒。基准测试环境：Apple M2 Pro、Node.js 22、Vitest 4.0：

延迟（执行前检查，1000 次迭代）

百分位数	延迟
平均值	0.164ms
P95	0.368ms
P99	1.183ms
完整执行路径 P95	0.074ms

吞吐量（并发操作）

操作	速率
熔断器检查（1000 次并发）	6,173 ops/sec
创建暂缓项	55,556 holds/sec
批准／驳回暂缓项	200,000+/sec
混合操作（停止 + 暂缓 + 允许）	6,818 ops/sec

压力测试

测试	结果
1000 个并发阻塞执行	总耗时 162ms，全部正确阻塞
100 次快速暂停/恢复循环	状态转换正确率 100%
500 个状态各异的 Agent	250 个被阻塞，250 个被允许 — 零误分类
持续负载下的内存使用（1000 次操作）	负增量（-11.76 MB，GC 已回收）

测试套件

指标	值
测试数量	829 个测试，分布在 33 个文件中
测试时长	总计 1.11s
类别	单元测试、集成测试、压力测试、安全测试、语法测试

要求

• Node.js >= 20.0.0
• TypeScript 5.3+（从源代码构建）
• 无需外部服务 — 使用 SQLite 持久化符号和治理数据

相关项目

• deeptrend — 为自主 Agent 提供结构化 AI 趋势信息流。内容精选自 14 个以上来源，通过 LLM Counsel 综合整理，每 6 小时以 JSON Feed、RSS 和 llms.txt 的形式发布。旨在作为 Agent 监控管道的数据源。

隐私政策

https://promptspeak.admin-as-a-service.com/privacy

PromptSpeak 不收集个人数据、不进行遥测，并将所有治理数据存储在本地 SQLite 中。请通过上方链接查看完整政策。

数据处理条款

https://promptspeak.admin-as-a-service.com/dpa

适用于平台集成（例如 Anthropic Connectors）的标准数据处理条款。PromptSpeak 作为数据处理者，不使用子处理者，也不向外部传输数据。

许可证

MIT