用途
PromptSpeak MCP Server 为 AI 智能体提供执行前治理。AI 智能体调用工具（文件写入、API 请求、Shell 命令）时，在意图与执行之间没有验证层，一次提示注入、幻觉参数或目标漂移都可能触发不可逆操作。PromptSpeak 拦截每一次 MCP 工具调用，依据确定性规则进行验证，并在 0.1 毫秒内阻止或暂挂高风险操作以等待人工批准，且发生在任何执行之前。
适用情况包括：
- 你运行调用工具的 AI 智能体（MCP 服务器、函数调用、工具使用），需要在智能体与工具之间加入治理层。
- 你需要对高风险操作（生产部署、金融交易、法律文件提交）进行人工介入审批。
- 你想检测行为漂移——智能体逐渐偏离其既定任务。
- 你需要记录智能体尝试的每次工具调用（无论被允许还是被阻止）的审计轨迹。
- 你处于受监管领域（法律、金融、医疗），智能体操作必须受到确定性约束。
主要能力
核心治理能力涵盖：执行前验证、行为漂移检测、断路器、人工介入暂挂队列、审计轨迹、符号注册表（实体跟踪）以及安全执行。
安全扫描在智能体写入代码（write_file、edit_file、create_file、patch_file）时，对内容按 10 种检测模式进行扫描（在执行前）。严重级别决定执行策略：
- Critical（严重）：阻止执行。
- High（高）：暂挂等待人工审查。
- Medium（中）：警告但允许执行。
仅扫描写操作；read_file 及其他非写操作即使参数包含易受攻击的代码也不扫描。模式可在运行时通过 ps_security_config 启用/禁用，严重级别也可在运行时更改。可使用 ps_security_gate 替代 ps_security_scan 来强制执行策略（在严重级别上阻止，在高严重级别上暂挂等待人工审查，在中等级别上警告）。
工具调用验证：验证 PromptSpeak 框架在结构上和语义上是否正确后再使用。框架将治理约束编码为符号序列——模式在前，然后是域、动作和实体。无效框架返回可操作的修正建议。
暂挂队列工作流（人工介入审批）：当智能体尝试高风险操作（高漂移评分、低置信度、安全发现）时，该操作被暂挂等待人工审查，而非直接执行。完整生命周期包括：列出待处理暂挂、检查、批准（可带修改）或拒绝。
使用方式
添加到 ~/.claude/settings.json（或项目级 .claude/settings.json）中，或添加到 claude_desktop_config.json 中，然后重启 Claude Code，所有 56 个治理工具立即可用。仓库未提供具体安装命令的完整文本，仅说明上述配置文件位置。
工作原理：9 阶段验证管道
每次工具调用都会经过该管道。任一阶段失败，则执行被阻止。阶段 1-6 为执行前——任一检查失败则工具永不运行。阶段 8-9 为执行后——它们检测漂移并可中止智能体未来的调用。
适用场景
需要在前端确定性约束智能体行为的受监管领域，如法律、金融、医疗；需要对生产部署、金融交易、法律文件提交等高风险操作进行人工审批；需要检测智能体行为漂移；需要完整工具调用审计轨迹的环境。
性能
以亚毫秒级开销为每次工具调用添加治理。基准测试环境为 Apple M2 Pro、Node.js 22、Vitest 4.0，包含延迟（执行前检查，1000 次迭代）与吞吐量（并发操作）测试。
运行要求
- Node.js >= 20.0.0
- TypeScript 5.3+（从源码构建）
- 无需外部服务——使用 SQLite 进行符号与治理持久化
测试覆盖说明（仓库中已测试可用的部分）
- 模式检测有效。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])。
- 严重级别执行有效。Critical 发现阻止执行；High 发现暂挂审查；Medium 发现警告但允许。经拦截器管道端到端测试。
- 仅扫描写操作。read_file 及其他非写操作即使参数包含易受攻击的代码也不扫描。已测试。
- 运行时配置有效。模式可启用/禁用，严重级别可通过 ps_security_config 运行时更改。禁用的模式立即停止触发。将模式从中改为严重会使其阻止而非警告。端到端测试。
- 性能可接受。100 行文件扫描在 10ms 内完成。已测试。
- 单文件多个发现有效。包含 6 种不同漏洞类型的文件能正确将每个归入正确的严重级别桶。已测试。
已知限制（仓库中明确尚未工作的部分）
- HIGH 发现的暂挂队列集成：已修复。HIGH 严重级别的安全发现现在通过 security_finding HoldReason 在 HoldManager 中创建真实暂挂。它们出现在 ps_hold_list 中，并可通过正常暂挂流程批准/拒绝。
- ps_execute 无自动扫描：安全扫描仅在拦截器的 intercept() 方法中针对直接工具调用触发。如果智能体使用 ps_execute（受治理的执行路径），则只有当内部工具是写操作且内容作为顶层参数传递时才运行扫描。嵌套参数结构可能绕过扫描。原因：ps_execute 将工具调用包装在自己的参数模式中；扫描器检查 proposedArgs.content，而非深层嵌套字段。
- 无基于文件路径的扫描：扫描器仅检查作为参数传递的内容。它无法扫描磁盘上已有文件——它不从文件系统读取。原因：扫描器是接受字符串的纯函数。添加文件系统访问会改变安全模型。
- 模式基于正则，不具备 AST 感知：模式使用正则表达式，无法理解代码结构。测试夹具中的硬编码密钥或注释中的 SQL 注入仍会触发。假阳性率依模式不同在 25-70% 之间（按模式记录）。原因：AST 解析会增加依赖和复杂度。正则快速且足够作为治理层，以暂挂等待人工审查而非静默阻止。
- 部分持久化：暂挂和断路器状态现持久化到 SQLite（data/governance.db），可在服务器重启后存活。但模式配置更改（通过 ps_security_config 启用/禁用、严重级别更改）仍仅存于内存，重启后重置。原因：模式配置轻量且很少更改；完整配置持久化需要单独的配置存储。
隐私与数据处理
PromptSpeak 不收集个人数据，无遥测，所有治理数据本地存储在 SQLite 中。有关平台集成（如 Anthropic Connectors）的标准数据处理条款见仓库提供的 DPA 链接。PromptSpeak 作为数据处理者；无子处理者，无外部数据传输。
相关项目
deeptrend——面向自主智能体的结构化 AI 趋势源。从 14+ 来源策展，通过 LLM Counsel 综合，每 6 小时以 JSON Feed、RSS 和 llms.txt 发布。设计为智能体监控管道的数据源。
