核心优势功能

Orchidea Guard

工业 AI 安全防护平台

工业 AI 交互防护与确定性治理平台（TriGuard），守护 AI Agent 与工具、系统、生产设备的交互链路。

核心能力

  • A 层对话防护（Conversation Guard，@orchidea/guard-conversation）：提示注入 / 越狱 / 敏感数据检测，含离线启发式检测器与 Jev 决策模型接入点
  • B 层确定性执行防护（guard-core + guard-policy）：Plan JSON 解析校验（含 dry_run 模拟评估）、RBAC 策略引擎
  • C 层守护审批（guard-audit）：人工审批队列、审计事件写入 / 查询 / 重放 / 脱敏
  • 决策四态：allow / deny（含拒绝原因与策略引用）/ require_approval / require_more_evidence
  • 三份协议 Schema：Plan JSON（plan-v1）/ 工具调用（tool-call-v1）/ 审计事件（audit-event-v1）
  • guard-server：10 秒滑动窗口 MetricsCollector + AlertEngine（deny 率 / 延迟 P99 / 错误率 / 吞吐 / 审计写入失败 5 条内置规则）+ W3C traceparent + 服务间内部 token
  • 接口：/guard/decide · /guard/conversation · /guard/plan/validate · /guard/audit/events · /guard/audit/cases/:correlationId · /dashboard
  • 内置策略：denyUnknownAction / planGatedWriteControl（写操作与控制下发必须提供执行计划）/ 跨组织非管理员拒绝
  • guard-mcp-gateway 透明代理 6 后端（platform / vision / director / archive / llot / plex）；SDK 双语言（Python / Rust）；三端集成 Code / Desktop / Director

技术优势

  • 提示注入与越狱实时拦截，安全防线前置
  • 高风险操作必须人工审批，AI 越权零容忍
  • 行为全程审计，事后可追溯、可重放
  • 透明代理接入，现有系统零改造启用
应用场景 AI 高风险动作（写操作 / 控制下发）的审批与审计；实现「AI 可用、风险可控、行为可溯」
数据流转 交互请求 → 风险检测 → 策略裁决 → 审批放行 → 审计留存
数据存储 审计日志 · 策略库

Orchidea-Guard

Orchidea-Guard（TriGuard）是 Orchidea 生态的工业 AI 交互防护与确定性治理平台：在 AI Agent 与工具、系统、生产设备的交互链路上，提供对话防护、策略执行与人工审批三层递进式防护，并为每次决策生成可审计、可重放的证据链，面向工业场景实现”AI 可用、风险可控、行为可溯”。

工作区命名空间：@orchidea/guard-* ｜ 包管理：pnpm workspace（pnpm@10.13.1）｜ 运行时：Node.js ≥ 20

架构概览：TriGuard 三层防护

Orchidea-Guard 采用三层递进式防护模型，每一层独立可审计、可降级：

  • A 层 — 对话防护（Conversation Guard）：负责 AI 对话阶段的意图感知与输入/输出过滤，检测提示注入（Prompt Injection）、越狱尝试（Jailbreak）与敏感数据泄露。实现包：@orchidea/guard-conversation（含离线启发式检测器与 Jev 决策模型接入点，作为默认判定源，guard-mcp-gateway 的分类模块聚焦工具名分类）。
  • B 层 — 确定性执行防护（Deterministic Execution Guard）：AI Agent 工具调用/动作执行阶段的安全边界，作为策略执行点（PEP）对 Plan JSON 协议请求进行解析、校验与策略匹配。实现包：@orchidea/guard-core + @orchidea/guard-policy。
  • C 层 — 守护审批（Guardian Approval）：高风险动作的人类审批与事后审计，负责审批队列编排、证据链保全与合规审计。实现包：@orchidea/guard-audit。

策略引擎对每个请求返回决策四态之一：

决策状态含义
allow策略校验通过，允许执行
deny策略校验失败，拒绝执行（返回拒绝原因与策略引用）
require_approval需要人工审批，进入 C 层审批队列
require_more_evidence证据链不完整，需补充证据后重新提交

配套协议与产物：Plan JSON 协议（schemas/plan-v1.json）、工具调用协议（schemas/tool-call-v1.json）、审计事件协议（schemas/audit-event-v1.json）。

2026-11 能力更新（v1.2.0）

  • 具身安全案例（safety case）：把运行时真实证据组织为 claim / evidence 结构；缺失证据一律 unverified，任一 claim 违反即整体 violated
  • 诚实边界：仅汇总运行时证据，不生成合规证书，不替代 IEC 61508/61511 认证结论
  • 落地：guard-policy 与 guard-server 路由同步，附单元与路由测试

2026-10 能力更新（v1.1.0）

  • 写入确认单：绑定工具名、参数指纹与发起人，有效期 10 分钟；支持 pending/confirmed/expired/cancelled，确认时校验「已确认 + 未过期 + 参数未被掉包」，确认人须与发起人不同
  • 补偿与 Saga 落盘：FileCompensationStore 支持跨进程重启查询逆动作；审批、幂等键、Plan 事件账本、写入确认单四类状态均持久化
  • 确定性执行器：按幂等键去重，高风险动作（默认阈值 7）未经审批门不得执行，失败自动逆序补偿
  • MCP 透明代理网关：聚合 platform / vision / director / archive / llot / plex 6 个后端，内置审批与写入确认运维工具
  • 审计与告警：JSONL 审计与 correlationId 重放；10 秒滑动窗口指标（p50/p95/p99）；deny 率、延迟、错误率、吞吐告警
  • 序列保密：三区隔离、字段级 RBAC、N-of-M 会签、代号化、零宽水印

仓库结构

orchidea-guard/
├── packages/
│   ├── guard-core/        # 核心类型、Plan JSON Schema/解析、关联（correlation）与决策类型
│   ├── guard-policy/      # 策略规则引擎（RBAC）、内置策略（planGatedWriteControl / denyUnknownAction）
│   └── guard-audit/       # 审计日志：事件模型、日志器、关联重放（replay）、脱敏（sanitize）
├── services/
│   ├── guard-server/      # Fastify HTTP 服务：PDP 决策、Plan 校验、审计、指标、告警、设置、Dashboard 托管
│   ├── guard-mcp-gateway/ # MCP 透明代理网关：tools/call 拦截 → Guard 决策（classifier / session / proxy）
│   └── guard-dashboard/   # 监控面板 SPA（监控概览 / 审计日志查看器 / 告警中心 / 设置管理，纯静态）
├── sdks/
│   ├── sdk-py/            # Python SDK（orchidea-guard）
│   └── sdk-rust/          # Rust SDK（orchidea-guard-sdk）
├── integrations/          # 集成配置：code / desktop / director 的 MCP 接入
├── schemas/               # JSON Schema：plan-v1 / tool-call-v1 / audit-event-v1
├── policies/              # 默认策略文件（default.yaml）
├── deploy/                # Dockerfile + docker-compose.yml
├── package.json
├── pnpm-workspace.yaml
└── copy.md                # 工程规范（TriGuard 架构 / Plan JSON 协议 / 审计规范的唯一真相源）

核心包

包说明
@orchidea/guard-core核心领域模型：Plan 等类型定义、Plan JSON Schema 校验、决策请求/响应类型、关联（correlation）追踪，基于 Zod
@orchidea/guard-policy策略决策引擎（Policy Decision Engine）：RBAC 规则匹配、内置策略 planGatedWriteControl（write/control 的 plan 门控放行，无 plan 时由引擎升级为需审批）与 denyUnknownAction（拒绝未知动作）、策略 bundle 与求值器
@orchidea/guard-audit审计事件写入与查询：事件模型、JSONL 审计日志器、按关联 ID 重放（replay）、事件脱敏（sanitize）

服务

guard-server（HTTP 服务）

基于 Fastify 5 的策略决策与治理服务，默认监听 0.0.0.0:4001。提供：

  • 决策与校验：PDP 决策、Plan JSON 校验（含 dry_run 模拟评估）
  • 审计：审计事件写入、按关联 ID 查询事件链、审计事件查询
  • 可观测性：指标采集（10 秒滑动窗口 MetricsCollector）、告警引擎（AlertEngine，内置规则：deny 率 / 延迟 P99 / 错误率 / 吞吐 / 审计写入失败）
  • 管理：告警规则与活跃告警、设置管理（策略 / 后端 / 分类覆盖）、/dashboard 静态 Dashboard、/health 健康检查
  • 中间件：W3C traceparent 分布式追踪注入、服务间认证（GUARD_INTERNAL_TOKEN）

主要接口（路径来自服务源码 services/guard-server/src/routes/）：

接口说明
POST /api/v1/guard/decide策略决策（PDP）
POST /api/v1/guard/conversationA 层对话防护判定（提示注入/越狱/敏感数据）
POST /api/v1/guard/plan/validatePlan JSON 校验（支持 dry_run）
POST /api/v1/guard/audit/events审计事件写入
GET /api/v1/guard/audit/events审计事件查询
GET /api/v1/guard/audit/cases/:correlationId按关联 ID 重放事件链
GET /health健康检查
GET /dashboardGuard Dashboard SPA

环境变量：GUARD_PORT（默认 4001）、GUARD_HOST（默认 0.0.0.0）、GUARD_INTERNAL_TOKEN。

guard-mcp-gateway（MCP 透明代理网关）

基于 @modelcontextprotocol/sdk 的 MCP 网关：将 tools/call 等请求拦截后交给 Guard 决策，再转发至目标后端。后端清单见 services/guard-mcp-gateway/backends.yaml，当前配置了 platform / vision / director / archive / llot / plex 六个后端（HTTP 或 stdio 传输）。

guard-dashboard（监控面板）

纯静态 SPA（services/guard-dashboard/public/），由 guard-server 在 /dashboard 托管，覆盖监控概览、审计日志查看、告警中心与设置管理。

SDK

Python（sdks/sdk-py）

  • 包名 orchidea-guard，Python ≥ 3.11，依赖 httpx、pydantic
  • 模块：orchidea_guard/client.py（异步 GuardClient：decide / validate_plan / write_audit_events 等）、orchidea_guard/types.py（Plan、Decision、AuditEvent、DecideRequest/Response 等类型）

Rust（sdks/sdk-rust）

  • 包名 orchidea-guard-sdk，基于 reqwest / serde / uuid / tokio
  • 提供 GuardClient（new(base_url, internal_token)）与类型定义（src/lib.rs、src/types.rs），覆盖决策、Plan 校验、审计写入与审计案例重放

快速开始

本地开发

pnpm install        # 安装 workspace 依赖
pnpm dev            # 启动 guard-server（tsx watch，默认 http://localhost:4001）
pnpm build          # 构建所有包与服务（tsc）
pnpm test           # 运行测试（Vitest）
pnpm typecheck      # 全量类型检查（tsc --noEmit）

启动后可访问：

  • 健康检查：http://localhost:4001/health
  • Dashboard：http://localhost:4001/dashboard

Docker 部署

deploy/Dockerfile 为多阶段构建（Node.js 20 Alpine）：构建 packages/、services/ 与 schemas/ 后，以非 root 用户运行 guard-server，暴露 4001 端口并提供 /health 健康检查。

docker compose -f deploy/docker-compose.yml up -d --build

deploy/docker-compose.yml 映射 4001:4001 并注入 GUARD_INTERNAL_TOKEN（默认 changeme，生产环境务必修改）；文件内附有可选的 Redis sidecar 配置（用于审计事件持久化与分布式策略缓存，默认注释）。

策略与协议

  • 默认策略：policies/default.yaml 内置三条策略——拒绝未识别的操作类型（deny）、写操作/控制下发必须提供执行计划（require_approval）、非管理员跨组织操作拒绝（deny）
  • 协议 Schema：schemas/plan-v1.json（Plan JSON）、schemas/tool-call-v1.json（工具调用）、schemas/audit-event-v1.json（审计事件），与 copy.md 中的协议规范保持一致

集成

integrations/ 提供三端 MCP 接入配置：

目录内容
code/Code CLI 的 MCP 配置（guard-mcp-config.json）
desktop/Desktop 的 Guard MCP Provider（guard-provider.ts）
director/Director 的 MCP 配置（guard-mcp-config.yaml）

许可证

本仓库未包含独立的 LICENSE 文件，许可证信息见仓库声明（copy.md 中标注为 UNLICENSED 的私有项目）。

← 返回平台架构总览