GraphJin：面向AI智能体的统一治理图
一个受治理的图，让AI智能体通过GraphQL+MCP安全访问数据库、文件、代码和API。
证据显示：SECURITY.md 详细描述了源模式下的最小权限原则，包括默认阻止写入/删除、账户/所有者作用域、系统根访问控制矩阵，以及内部保留角色。用户确认方面，存在预览/应用两步配置更新，但缺少明确的用户确认机制。数据流透明度：文档说明了数据流和审计日志，但未提供完整的执行账本细节。敏感数据处理：文档提到身份字段脱敏、不存储原始 JWT/密钥，但未提供具体实现。依赖安全：package.json 仅列出 tar 依赖，未提供依赖审计或漏洞扫描证据。外部影响：文档描述了外部系统（数据库、文件、API）的访问控制，但未提供回滚机制。回滚：配置更新有预览/应用，但未提供数据操作回滚。来源归属：未验证发布者身份，但文档提供了作者和维护者信息。扣分原因：用户确认、回滚、依赖安全证据不足。
证据显示：README 和 SECURITY.md 在模式、访问控制、系统根等方面保持一致。依赖可用性：提供多种安装方式（npm、Homebrew、Scoop、Docker），但未提供依赖可用性保证。失败消息：文档提到错误返回，但未提供具体失败消息示例。扣分原因：失败消息证据不足。
证据显示：README 描述了多种使用场景（数据库、文件、代码、API），并提供了多个演示。能力边界：文档明确区分了模式（dev/prod/agentic）和访问控制。触发精度：MCP 工具和 GraphQL 查询有明确说明。环境适配：支持多种数据库和部署方式。扣分原因：无重大扣分。
证据显示：README 结构清晰，包含安装、使用、配置、安全等章节。安装说明详细。命名稳定性：版本号明确，但未提供命名约定。示例和 FAQ：提供了多个示例，但未提供 FAQ。已知限制：文档提到一些限制（如 prod 模式禁用 agentic 表面），但未全面列出。许可证：Apache-2.0 许可证文件完整。版本变更日志：未提供 CHANGELOG，但版本号在 package.json 中。维护责任：文档提供了作者和维护者信息。扣分原因：缺少 FAQ 和完整已知限制。
证据显示：输出可用性：提供了多种输出格式（GraphQL、REST、MCP）。边际价值：提供了独特功能（如 CodeSQL、代理）。成本效益：文档声称高性能，但未提供基准测试。扣分原因：成本效益证据不足。
证据显示：声明可追溯性：README 中的声明与 SECURITY.md 和代码一致。跨来源佐证：文档之间一致，但缺乏独立验证。事实与推断分离：文档区分了功能描述和设计意图。扣分原因：跨来源佐证不足。
- 发布者身份未验证，应视为未知，不要基于品牌信任。
- 静态审查无法验证实际执行行为，所有安全声明需在部署前独立测试。
- 依赖安全证据不足，建议检查依赖漏洞。
- 缺少用户确认和回滚机制，操作需谨慎。
这个 Agent 能做什么，适合哪些场景？
GraphJin是一个编译器和运行时，将企业内部多种系统（数据库、数据仓库、文件、源代码、工作流、元数据和安全策略）抽象为一个统一且受治理的图，并通过GraphQL和MCP接口暴露给AI智能体。智能体在行动前进行发现、验证查询、执行已批准的操作，并观察运行时状态，所有回答都经过执行账本的检查。它同时也是一个高性能的GraphQL到数据库的编译器、Go库、独立API服务、REST/OpenAPI网关和实时订阅服务器。支持多种数据库（PostgreSQL、MySQL、MongoDB、SQLite、Oracle、MSSQL、Snowflake、Redshift、BigQuery、Cassandra等），以及文件系统和源代码索引。内置服务器端智能体，可接收指令并返回带证据的答案。
GraphJin读取数据库schema，自动发现外键关系，暴露内置的gj_*系统表（如gj_catalog、gj_code、gj_security、gj_runtime），并编译GraphQL查询为优化的SQL。它通过MCP工具（如query_catalog、graphql_help、validate_where_clause）指导AI智能体先发现再行动，通过查询白名单、只读边界和策略感知工具来限制操作。它还能索引源代码（CodeSQL），将语法树和数据库引用管理为SQLite数据库。内置服务器端智能体通过/api/v1/agent端点接收指令并返回结构化答案。它支持实时订阅、文件系统表（本地、S3、GCS）、文件上传以及Apollo Federation v2。
- 开发者使用GraphJin为现有数据库快速创建GraphQL API，无需编写resolver。
- AI编码助手（如Claude Code或Codex）通过MCP连接GraphJin，安全地查询和操作生产数据库。
- 数据分析师通过自然语言指令让服务器端智能体生成查询并返回带证据的结果。
- 运维团队通过查询白名单和read_only模式控制AI对数据库的写操作。
- 开发团队使用CodeSQL索引源代码，让智能体回答关于代码库的问题，例如哪些处理器涉及客户发票。
这个 Agent 有哪些优点和局限？
- 统一的治理层：一个图覆盖多个系统，智能体无需直接访问各种数据源，降低安全风险。
- 高性能查询编译：将GraphQL编译为单个优化SQL，避免N+1问题。
- 丰富的安全机制：查询白名单、只读边界、行级安全、策略感知MCP工具，确保操作可审计。
- 内置服务器端智能体：通过一个指令返回带证据的答案，简化集成。
- 支持广泛的数据库和数据源：包括主流关系型、NoSQL、数据仓库和文件系统。
- 对于小型项目可能过于复杂：需要配置和学习，适合企业级场景。
- 部分数据库（如Redshift、BigQuery）支持是实验性的，功能不完整。
- 订阅支持依赖于数据库方言，某些数据库（如Cassandra）仅支持轮询。
- 服务器端智能体需要额外的模型API密钥，且默认配置可能要求模型擅长代码生成。
- 从传统数据库模式迁移到source模式需要调整配置，存在学习曲线。
如何安装或部署这个 Agent？
安装GraphJin有多种方式：npm全局安装（npm install -g graphjin）、Homebrew（brew install dosco/graphjin/graphjin）、Scoop（Windows）、下载Linux的.deb/.rpm包，或使用Docker（docker pull dosco/graphjin）。然后通过graphjin serve new my-app创建新应用，使用graphjin serve --path ./my-app启动服务。
如何使用这个 Agent？
启动服务后，可以通过graphjin mcp add claude http://localhost:8080将GraphJin添加到Claude Code，或通过codex mcp add graphjin --url http://localhost:8080/api/v1/mcp添加到Codex。之后可以直接用自然语言提问，如'数据库里有哪些表？'，GraphJin会通过MCP工具处理。也可以直接调用GraphQL端点（POST /api/v1/graphql）或服务器端智能体（POST /api/v1/agent）。