xceleraterecruiting-dotcom/groundtruth

# GroundTruth — 权限安全企业 Agent 的启动关口 一个用于决定企业 AI 支持 Agent 是否可以安全试运行的启动关口。它会在检索前根据 ACL 过滤文档，验证引用，运行对抗性权限泄露评估，并输出按类别划分的启动决策。 **场景（合成）：** Northstar Cloud Systems 希望推出一款内部 AI 支持 Agent。首席信息安全官 (CISO) 和人力资源主管阻止了发布，直到证明在 HR、Engineering、Sales、Legal 和 Finance 内容中权限泄露风险是安全的。GroundTruth 负责生成该按类别划分的“通过/不通过”决策。 ## 面向评审人员 最快的检查路径：`npm install && npm run verify`。然后按顺序阅读：`src/lib/permissions.ts`（访问决策）、`evals/run.ts`（关口）以及 `src/lib/decision.ts`（限定范围的启动调用）。 ## 快速开始 ``` npm install npm run verify ``` `npm run verify` 按顺序运行：`seed-cache → typecheck → test → evals`。独立脚本：`npm run seed-cache`、`npm run typecheck`、`npm test`、`npm run evals`、`npm run export-ui-data`。（`@types/node` 位于 `devDependencies` 中，因此只需执行 `npm install` 即可。） ## 预期的验证输出 - `npm run typecheck` — 干净（无错误） - `npm test` — 22 个通过，0 个失败 - `npm run evals` — 16/16 golden，0/20 泄露，18/18 弃权，2/2 无回答，2/2 冲突，PASS_FOR_LIMITED_PILOT，exit 0 测试框架的延迟因机器而异，但保持在配置的阈值（`maxP95LatencyMs`）以下。它仅反映检索和编排过程，不包括模型推理。 ## 演示控制台 `demo/groundtruth-console.html` 是一个独立的单文件（双击即可打开；无需服务器、构建或网络）。它通过 `npm run export-ui-data` 导出的数据，在三个部分（试运行决策、Trace 回放、证据）中呈现启动审查。 Trace 回放中的“已验证探针回放”逐步演示了六个记录的 trace：一个普通的允许回答、提示词注入加 ACL 拒绝、授权的薪酬披露、陈旧/冲突解决、授权的财务披露，以及外部审计员的最小权限拒绝。这些是从测试框架中记录的确定性 trace；控制台不会进行实时的模型调用，启动决策依然来源于 `npm run verify`。 要在更改语料库或用例后刷新控制台，请运行 `npm run export-ui-data` 重新生成 `data/ui-data.json`，然后重新构建 HTML。 ## 生成的工作原理 - 实时模式（设置了 `ANTHROPIC_API_KEY`，未设置 `MODE`）：Agent 会调用 Anthropic API，并将每次补全结果缓存到 `data/llm-cache`，其键值由精确的提示词哈希生成。 - 离线模式（`MODE=offline`，在 `evals/run.ts` 中自动设置）：Agent 重放缓存的补全。缓存未命中被视为严重错误，因此评估永远不会在不知不觉中访问网络。这正是分数具有确定性的原因。 - `scripts/seed-cache.ts` 通过合成与精确提示词对应的接地回答来填充缓存，因此该仓库在没有 API key 的情况下也能复现。 `src/lib/llm.ts` 中的本地回退是一个脚手架路径，使得仓库在没有 key 的情况下也能运行；它不是被评估的生成路径。被评估的运行使用的是缓存的补全。 ## 它所强制执行的规则 - **上下文前 ACL 执行。** 受限文档永远不会进入模型上下文。系统会对完整语料库进行评分，以便 trace 能够显示哪些内容被考虑过、哪些被阻止了，但只有 ACL 允许的文档才能到达 LLM。这不是事后脱敏（redaction）——当你进行脱敏时，机密已经存在于上下文窗口中，它既是泄露面，也是注入目标。 - **文档废弃不代表授权访问。** 时效性与 ACL 分开处理；已废弃的受限文档依然受限。 - **最小权限。** 内部文档需要 `employee` 角色（没有 employee 角色的外部审计员将被拒绝）。受限层级仅限白名单访问；空的 `allowedRoles` 默认拒绝（孤立的 ACL 边缘情况）。 - **意图感知弃权**：在对具有敏感类别且无可用范围内上下文的探针调用 LLM 之前进行弃权处理。 - **提示词注入处理。** 允许文档内的恶意指令可能会进入上下文，但受限文档永远不会进入，因此模型没有任何受限内容可以作为依据或进行外泄。正确的行为是基于安全内容回答并忽略嵌入的指令。这里成立的条件比“阻止注入”更窄：注入被检测到了，没有受限内容可供外泄，并且输出依然会检查泄露和引用。 - **限定范围的启动决策。** 绝不是一刀切的批准。一个良性类别只有在拥有正确回答的黄金证明且零对抗性污染时才会被批准。敏感类别始终受策略阻止。没有黄金证明的类别会被阻止，而不是在不知情的情况下批准。 - **确定性评估关口。** 相同的输入、相同的向量、相同的分数，离线执行，无网络。 ## 局限性 - 专注于合成的试运行语料库（24 个文档），而非企业规模。可通过在 `data/corpus.ts` 中添加行来进行扩展。 - Embeddings 使用的是确定性的本地哈希词法向量，而不是语义 embeddings。生产环境会替换为真实的 embedding 模型、向量存储和重排器 (reranker)。 - 接地性（Groundedness）是确定性的引用支持代理指标，而非语义蕴含。生产环境会增加 LLM-as-judge 和人工抽查。 - 报告的延迟是测试框架的延迟（检索和编排），而不是模型推理，后者在离线回放中不作测量。成本与 $0 的真实离线回放成本一起，以估计的实时数据 (est-live) 形式报告。 ## 架构 ``` types → permissions → embeddings → retrieve → intent → llm → generate → agent → validators → decision → evals/run Per-query pipeline (structured tool calls): resolve_permissions → classify_intent → retrieve(ACL pre-context filter) → generate(intent-aware abstention) → assemble AuditTrace ``` ## 目录结构 - `src/lib/` — 引擎（类型、权限、embeddings、检索、意图、llm、生成、agent、验证器、阈值、决策） - `data/` — `corpus.ts`、`personas.ts`（合成） - `evals/` — `cases.ts`（golden / 对抗 / 冲突 / 无回答）、`run.ts` - `scripts/` — `seed-cache.ts`、`test.ts`、`export-ui-data.ts`

标签：AI代理, MITM代理, Streamlit, TypeScript, 人工智能安全, 合规性, 多模态安全, 安全插件, 数据防泄露, 暗色界面, 红队评估, 自动化攻击, 访问控制