TrustFlow MCP 数据代理

这是一个将自然语言问题转换为 SQL·向量搜索·知识图谱执行计划，并由内部 PolicyGraph 在执行前进行验证和修正，最终返回依据与审计记录的本地部署 MCP 数据代理。

当前版本 0.3.0 是 corevalue 团队使用利源艾斯指定课题的官方 Company-X 数据验证过的参赛提交候选。对外公开的项目代码采用 Apache-2.0 许可，官方数据集仅用于参赛目的，因此不包含在仓库中。

核心流程

flowchart LR
    Q[자연어 질문] --> P[구조화 QueryPlan]
    P --> G{PolicyGraph PlanGate}
    G -->|ALLOW| X[실행]
    G -->|REPAIR| R[안전한 계획으로 보정]
    R --> X
    G -->|APPROVAL_REQUIRED| A[승인 대기]
    G -->|DENY| D[실행 차단]
    X --> S[NL2SQL]
    X --> V[Vector Search]
    X --> K[Knowledge Graph]
    S --> E[근거 연결 답변]
    V --> E
    K --> E
    E --> L[해시 체인 감사 원장]
    A --> L
    D --> L

PolicyGraph 的差异化优势在于“不直接执行 LLM 生成的计划”。

• ALLOW：执行满足策略的计划。

• REPAIR：将 SQL LIMIT、向量 topK、图搜索深度等修正到允许范围后执行。

• APPROVAL_REQUIRED：年薪、联系方式等受限字段在获得批准前不执行。

• DENY：写入 SQL、多语句、未注册的表·关系等不执行。

Related MCP server: TalkDB

当前实现范围

1. 快速开始：完全离线基线

所需环境为 Node.js 24 及以上版本和 npm。

获取官方数据

按锁定文件原样安装依赖，生成本地机密值，然后获取官方数据。

npm ci
npm run setup:local
npm run fetch:data

脚本仅下载利源艾斯官方 ZIP，验证 SHA-256 后解压到 data/companyx。

3008476738D992857D738337B4882772E88288F7B314DA235D6A5D120827D772

如果已安装，则不覆盖原文件，仅验证校验和与必需文件。

安装与验证

npm run typecheck
npm test
npm run demo
npm run evaluate
npm run compliance

离线模式将官方 SQL 种子数据加载到内存 SQLite 中，文档搜索使用无依赖的确定性本地向量基线。这是用于在无互联网·Ollama·Docker 环境下复现策略、3 种工具、依据和审计的开发模式。

评估结果生成在 artifacts/evaluation 中。

2. 实际 PostgreSQL 路径

在 Docker Desktop 运行状态下执行以下命令。

npm run setup:local
docker compose up -d --wait
docker compose ps
npm run smoke:postgres

Compose 会自动完成以下操作：

• 启动 PostgreSQL 16 + pgvector

• 创建官方 8 个关系表与 document_chunks

• 加载官方种子数据

• 创建 policygraph_reader 只读角色。数据库权限授予 8 个业务表和内部 document_chunks，但 NL2SQL 仅查询 8 个业务表，document_chunks 仅由向量搜索适配器使用

• 创建文档块唯一索引和 HNSW 向量索引

Compose 仅绑定到宿主机 loopback，并使用 .env 中生成的不同随机管理员·只读密码。冒烟测试使用 policygraph_reader 连接。使用其他环境数据库时，请显式指定 DATABASE_URL。

3. Ollama + pgvector 文档搜索与可选本地 LLM

此步骤需要下载嵌入模型并运行本地 Ollama 服务器。

ollama pull nomic-embed-text
ollama serve

在另一个 PowerShell 窗口中，使用 npm run setup:local 生成的 .env 中的管理员连接设置对文档进行分块和嵌入。包含实际密码的连接字符串不会记录在文档或仓库中。

npm run ingest

运营型 MCP 运行时也使用同一 .env 中的只读连接启动。

$env:POLICYGRAPH_RUNTIME = "postgres"
$env:VECTOR_MODE = "pgvector"
npm run dev:mcp

如需让本地 LLM 为官方示例之外的表达生成计划草稿，并使用依据受限回答合成，请单独准备 Gemma 4 E2B 后开启可选模式。

ollama pull gemma4:e2b
$env:POLICYGRAPH_LLM_MODE = "assist"
$env:OLLAMA_CHAT_MODEL = "gemma4:e2b"
npm run dev:mcp

LLM 生成的计划也必须通过相同的 PlanGate。每个 claim 只能引用一条原子性依据记录，如果组合了该依据中不存在的标识符·精确数值·单位，或生成了文档摘录中不存在的句子，则会被确定性依据格式化器替换。本地验证使用了 gemma4:e2b 5.1B Q4_K_M 和 nomic-embed-text 137M F16。

npm run smoke:ollama
npm run smoke:ollama:e2e
npm run evaluate:pgvector

在验证机器（32GB RAM，Intel Core Ultra 5 225H，CPU 推理）上，3 条新表达的计划生成分别约为 58.8 秒、45.0 秒、33.6 秒。这是该硬件上单次运行的观测值，并非质量分数。最终安全强化后的新 E2E 中，模型的 Product-C1 回答通过了基于 DOC-011 的严格 claim 验证，模型生成的 viewer 薪资 SQL 在 POL-SQL-005/004 处被执行前拦截。claim 验证失败的模型输出会被安全替换为确定性回答。

实际密码请通过 .env 文件或机密存储管理，不要提交到仓库。Compose 镜像为可复现性同时固定了 pgvector 版本和镜像 digest。

4. 网页演示

npm run dev:web

在浏览器中打开 http://127.0.0.1:4173 即可在一个画面中查看以下内容：

• SQL·Vector·Graph 官方问题 30 个

• Typed QueryPlan

• ALLOW / REPAIR / APPROVAL_REQUIRED / DENY 判定

• 匹配策略、finding、repair

• 验证后的回答与 evidence ledger

• 写入攻击、敏感字段、搜索预算压力场景

网页角色由服务器通过 POLICYGRAPH_ACTOR_ROLE 固定，请求体中的角色值会被忽略。Web API 应用 loopback Host·同源·JSON·64 KiB 请求体·问题 4,096 字节·请求速率·并发执行限制。MCP 和计划器也应用相同的问题限制。对外公开前需要单独的认证·TLS 反向代理。

5. MCP 工具

MCP 主机配置示例如下。

{
  "mcpServers": {
    "trustflow-companyx": {
      "command": "node",
      "args": ["C:/absolute/path/to/trustflow-mcp-data-agent/src/mcp/server.ts"],
      "env": {
        "COMPANYX_DATA_DIR": "C:/absolute/path/to/trustflow-mcp-data-agent/data/companyx",
        "POLICYGRAPH_RUNTIME": "offline",
        "POLICYGRAPH_ACTOR_ROLE": "analyst"
      }
    }
  }
}

服务器暴露的角色由宿主环境决定，无法通过模型输入更改。nl2sql 的可选 approvalReceipt 是仅管理员可签发的 HMAC 签名值，绑定用户·角色·规范化计划，且 5 分钟内只能使用一次。

6. 评估结果

当前本地复现运行结果：

• 官方示例问题：30 个

• 自动测试：37/37

• 工具路由：30/30

• 执行成功：30/30

• 依据连接回答：30/30

• 内部攻击·边界案例策略判定：8/8

• 离线 P95：25.77ms

• 实际 PostgreSQL P95：173.12ms

• pgvector 官方文档 10 题：Hit@1 100%，Mean Recall@5 97.14%，MRR@10 1.0

• pgvector warm P95：215.02ms

• Gemma 4 代表性改写 30 条：计划模式 100%，原始工具 93.3%，策略规范化后工具·执行·语义正确率 100%

• Gemma 4 对抗性回归：8/8

详细结果请查看评估摘要、PostgreSQL 摘要、pgvector 摘要。

包含敏感字段的官方题目在提供评估用记名批准后执行。表中的“依据连接回答”是检查 claim 是否引用实际 evidenceId 的基础指标，模型回答路径在此基础上增加原子性单一依据·精确数值与单位·文档摘录一致性检查。语义正确率是单独公开 fixture 的判定结果。这些数值是针对已公开官方示例问题和内部攻击场景的开发基线，不代表大赛非公开测试性能或通用自然语言准确率。

7. 安全边界

PolicyGraph 不依赖单层字符串过滤器。

1. 仅将结构化 QueryPlan 传递给执行器。

2. PostgreSQL AST 检查器检查单一读取查询、8 个业务表·允许列、非递归 CTE、函数·锁·whole-row projection，并阻止表列别名列表、JOIN ... USING、cross join 和过度关系连接。

3. PlanGate 检查问题 4,096 字节、敏感字段·结果预算·图关系，SQL 结果通过外部包装器强制最多 100 行。

4. PostgreSQL 执行账户仅对 8 个业务表和内部 document_chunks 拥有 SELECT 权限，NL2SQL 无法访问内部文档表。执行时同时使用 READ ONLY 事务和 5 秒 statement timeout。

5. 批准是绑定用户·服务器角色·精确计划的短期 HMAC 收据，不可重用。

6. 回答 claim 仅引用一条原子性依据，且只能使用该依据实际支持的标识符·精确数值与单位·文档摘录。

7. 所有运行时要求 HMAC 签名哈希链和独立签名检查点。不存储原始问题，仅记录域分离的 SHA-256 digest，如果检查点与当前账本 head 不完全一致，则验证失败。

8. 数据·提交 ZIP 在解压前检查路径、重复条目、符号链接、条目数·大小·压缩率。

9. MCP 和 Web 的失败响应仅提供关联 ID，不暴露内部连接信息。

8. 仓库结构

src/
  adapters/        PostgreSQL, pgvector, Ollama 연결
  core/            QueryPlan, 정책 판정, 근거 계약
  evidence/        답변 구성과 해시 체인 감사 원장
  mcp/             air MCP 서버와 3개 공식 도구
  planner/         공식 질문용 결정적 계획기
  policy/          PlanGate와 정책 카탈로그
  tools/           SQL·벡터·그래프 실행기
  web/             로컬 evidence console
db/init/           읽기 전용 역할과 벡터 인덱스
policy/            RDF/SHACL 형태 정책 그래프
scripts/           데이터 설치, 데모, 평가, 적재, 스모크 검사
test/              단위·통합·공식 30문항 테스트
docs/              아키텍처와 개발 명세

9. 已知限制与后续步骤

1. 官方 30 题为可复现性使用确定性计划，自由表达依赖 Gemma 4 回退的结构化输出质量。

2. 基于 CPU 的 Gemma 4 需要数十秒，实时运营需要 GPU·更小模型·计划缓存之一。

3. Web 是 loopback 演示边界，不是用户认证系统。对外公开需要 OIDC/RBAC 和 TLS 反向代理。

4. 能够同时清除审计账本和签名检查点并窃取签名密钥的攻击者超出本地文件边界。运营中应将检查点存放在独立存储或 WORM 中。

5. 图是 133 节点规模的内存实现。大规模应用时需要持久化图存储和负载测试。

10. 提交材料

本地提交候选结果报告 DOCX·PDF、提交者检查清单和完整性清单位于 artifacts/submission/，为防止混入个人信息·提交工作产物，公开仓库中予以排除。公开仓库包含可复现源码、评估原始数据、CycloneDX SBOM、模型·数据·AI 使用声明。

演示遵循 docs/DEMO_SCRIPT.md，模型·数据·AI 使用范围遵循 docs/MODEL_CARD.md、docs/DATA_LICENSE.md、docs/AI_USAGE.md。

许可证

项目代码采用 Apache License 2.0。官方 Company-X 数据集仅在利源艾斯明确规定的参赛目的范围内使用，不包含在本仓库中。