RoboSystems

RoboSystems

RoboSystems 是一个开源、AI 原生的金融智能平台，面向会计、财务报告和投资管理。它将您的财务数据建模为知识图谱——交易、事实、报告要素以及将它们关联起来的计算结构都是节点和边，并保留其语义，而不是将其扁平化为供您查询的行。基于这个图谱，它为 AI Agent 和分析师提供了一个具备账本级可靠性的记录系统，供双方查询和操作——结账、生成报告，并分析您自己的账本、持仓以及可同时查询的 SEC 公开文件中的投资组合。为 RoboLedger 和 RoboInvestor 提供支持。

每个租户都有自己的图谱。 不是共享表中的行级切片，而是运行在独立实例上的专用图数据库，后端配有专用 OLTP 架构。您的本体、分类体系和计算结构都以资源的形式保存在其中，您可以读取、导出并带走。

平台

平台提供所有扩展所依赖的核心基础设施：

• 专用基础设施：分层的 LadybugDB 图基础设施，配备专用实例和可配置的内存分配
• AI 操作员系统：自主的财务操作员（Claude/MCP 执行器），支持自动信用额度跟踪和 SSE 进度流式传输。
• 共享存储库：用于上下文挖掘和基准比较的 SEC XBRL 文件知识图谱
• 文档管理：通过 OpenSearch 上传、索引和搜索文档，支持全文和语义搜索
• 基于信用额度的计费：根据令牌用量为 AI 操作提供灵活的信用额度
• 子图（工作区）：用于开发和团队协作的 AI 记忆图谱和隔离环境
• Web 应用：主要 Web 界面——图谱管理、AI 查询控制台（通过 MCP 使用自然语言 + Cypher）、架构浏览器、文档搜索、共享存储库访问和计费——robosystems-app

核心平台 API 位于 /v1——包括身份验证、组织、计费、图谱生命周期（子图、备份、物化、层级变更）、Cypher 和 MCP——读取操作使用 REST GET。所有写入操作——无论是在核心 API 还是扩展 API 中——都是具名的 OperationEnvelope 操作，支持 Idempotency-Key、审计日志，以及通过 /v1/operations/{id}/stream 进行的 SSE 进度流式传输。

扩展

扩展是特定领域的子系统，各自提供自己的架构、OLTP 表、API 路由、数据管道和专用前端应用。它们共享一个 PostgreSQL 数据库，并通过每个租户独立的架构实现隔离；数据会物化到图谱中以供分析查询。领域内容以区块分子的形式编写——自描述信封将原子事实与其结构、规则和验证捆绑在一起，绝不是裸行。

扩展 API 在 URL 层面按图谱限定——graph_id 始终是路径参数，而不是查询参数——并按传输方式将读取和写入分开：

• 读取 → POST /extensions/{graph_id}/graphql — Strawberry GraphQL，开发环境中提供 GraphiQL，架构根据已启用的领域动态组合
• 写入 → POST /extensions/{roboledger|roboinvestor}/{graph_id}/operations/{operation_name} — 具名 REST 命令
• 分析视图 → POST /extensions/{domain}/{graph_id}/operations/{view_name} — 只读分析操作（例如 build-fact-grid、live-financial-statement），使用与写入操作相同的信封

API 后端是一个 CQRS 操作内核（每个领域下的 reads/ + commands/，以及由图谱支持的 views/），它是业务逻辑的唯一事实来源——GraphQL 解析器、REST 操作路由和 MCP 工具都委托给相同的函数。各领域的功能标志（ROBOLEDGER_ENABLED、ROBOINVESTOR_ENABLED）同时控制路由器和 GraphQL 架构组合。

RoboLedger

会计与财务报告扩展——一个账簿级记录系统，AI 和分析师都能查询和操作。写入的数据以自描述的 molecule 形式落地：将原子事实与其结构连接、规则和验证打包到一个类型化封装中，绝不只是裸行。三种块 molecule 是创作基础：

• Information Blocks — 可报告内容的封装：将明细表、报表、指标和文本块披露，与其按期间和版本管理的事实集、类型化机制及规则打包在一起。evaluate-rules 会对物化事实运行算术检查（EqualTo、RollUp、RollForward、SumEquals、Exists、CoExists）；固定事实集可将实时结账账簿与冻结报告分开。
• Event Blocks — REA 事件采集：调用方通过结构化的动作动词词汇记录现实世界中发生的事情（销售、付款、资产处置等），处理器注册表则在三级账簿（Transaction → Entry → LineItem）中推导借方和贷方。预览处理器解析结果，执行操作以原子方式过账到 GL，并按需提升已到期义务（AR/AP、明细表分录）。
• Taxonomy Blocks — 将会计框架作为数据而非代码：在一次原子写入中包含 Elements、linkbase Associations（presentation / calculation / mapping）、Structures 和自动生成的结构规则。内置 fac（基础）和 rs-gaap（约 2,000 个精选 US-GAAP 概念），通过两级公共→租户库提供，并以 calc-DAG 叶节点为锚点进行 CoA→GAAP 映射。

基于这些块构建：

• Close lifecycle — 财政日历、关闭目标追赶排序，以及由余额方程、QuickBooks 同步陈旧状态和未结明细表义务共同控制的期间关闭/重新开启；每个阻止项都会说明阻碍关闭的原因
• Mapping — CoA→GAAP 映射关联，以及通过 MappingOperator 进行 AI 辅助批量映射（按置信度分级：自动批准 / 审核 / 跳过）
• Reporting — 通过 Reporting Style 基于共享事实呈现多期间报告；报告生命周期（draft → under_review → filed → archived），并提供用于分发的发布列表
• Forecasting — 通过相同报表结构投影运营计划场景：基于规则的预测、逐行增长轨迹和手动行断言；读取报表时会将预测期间与实际期间一并返回
• Analytical operations — live-financial-statement 可直接从 OLTP 账簿呈现报表（无需物化）；build-fact-grid 和 financial-statement-analysis 可查询图中的物化 XBRL 超立方体
• Serialization — 报告以 holon 形式发布（数据集形式的 JSON-LD，是存储锚点，也是唯一承载完整报告的形式），并提供 XBRL International Tavi 编译模型和首次下载时构建的、达到申报级标准的 XBRL 2.1 包（经 Arelle 验证）；三者都是同一份组装后报告的投影
• Pipelines & data — 通过 dbt/Dagster 和可配置的 write_policy 实现 QuickBooks ELT，以及 SEC XBRL 财务报告

专用前端应用：roboledger-app。

RoboInvestor

投资组合管理与投资跟踪扩展——跟踪私营公司的持仓，并将其关联回发行这些持仓的企业。

• 投资组合区块 — 沿用 RoboLedger 的分子化设计规范：投资组合及其持仓与证券经过验证后，会作为一个整体写入；成本基础和当前价值以整数美分存储，美元总额则在边界处计算。持仓会经历 active / disposed / archived 生命周期；读取时会返回 portfolios、positions、holdings（按发行方汇总）以及组装好的 portfolioBlock。
• 证券 — 注册并维护所有权工具（普通股、认股权证、可转换票据……），并通过可扩展的 terms 数据块记录工具特定的详情（行权价、清算优先权、归属情况）。
• 跨图谱研究 — 如果发行证券的公司也在该平台上运行，证券可以指向该公司的图谱。投资者会预先记录发行方的 source_graph_id，作为预关联；当发行方之后将已发布的报告共享到投资者的图谱时，发行方实体会在该图谱中实例化，任何等待此 source_graph_id 的证券都会链接到该实体。随后，持仓即可遍历至发行方自身报告的事实：Portfolio → Position → Security → Entity → Report → Fact——授权在报告共享边界执行，而非在 OLTP 层执行。

专用前端应用：roboinvestor-app。

快速开始

Docker 开发环境

# Install uv and just
brew install uv just

# Start robosystems backend
just start

# Start frontend apps - robosystems-app, roboledger-app, roboinvestor-app
just start apps

# Refresh images and recreate the containers that changed (after a git pull)
just upgrade

# Local builds: restart to pick up code changes; rebuild after dependency changes
just restart
just rebuild

此操作会初始化 .env 文件，并启动完整的 RoboSystems 技术栈，包括：

• 使用 LadybugDB 和 DuckDB 后端的 Graph API
• 用于数据管道编排的 Dagster
• 用于 IAM、图谱元数据、扩展和 Dagster 的 PostgreSQL
• 用于缓存、SSE 消息传递和速率限制的 Valkey
• 用于全文和语义文档搜索的 OpenSearch
• 用于模拟 S3 和 DynamoDB 的 Localstack

服务 URL：

服务	URL
主 API	http://localhost:8000
Graph API	http://localhost:8001
Dagster UI	http://localhost:8002

使用 just start apps（前端应用）时：

应用	URL
RoboSystems App	http://localhost:3000
RoboLedger App	http://localhost:3001
RoboInvestor App	http://localhost:3002

本地开发

just start 会按发布时的状态运行已发布的镜像，因此检出内容仅提供配置，不包含代码。若要运行自己的更改，请在 .env 中注释掉 image 行：此时技术栈会从检出内容构建，并挂载其源代码，因此编辑后执行 just restart 即可生效。

# Setup Python environment (uv automatically handles Python versions)
just init

示例

通过可运行的演示了解 RoboSystems 的实际运行情况：使用 robosystems-client 创建图谱、加载数据并执行查询：

just demo-sec               # Loads NVIDIA's SEC XBRL data via Dagster pipeline
just demo-roboledger        # End-to-end RoboLedger demo: bulk OLTP, schedules, FY 2025 filed report, AI close
just demo-custom-graph      # Builds custom graph schema with relationship networks
just demo-coffee-roaster    # Synthetic manufacturing scenario
just demo-saas-startup      # Synthetic SaaS scenario
just demo-roboinvestor      # Cross-graph traversal from a private holding to its issuer's filed report (run demo-saas-startup first)

每个演示都有对应的文档页面，其中包含详细指南。

开发命令

测试

just test-all               # Tests with code quality
just test                   # Default test suite
just test adapters          # Test specific module
just test-cov               # Tests with coverage

代码质量

just test-code              # Lint, format, and typecheck (what the git hooks run)
just lint fix               # Auto-fix lint issues
just typecheck              # Type checking

日志监控

just logs api                 # View API logs (last 100 lines by default)
just logs graph-api           # View Graph API logs
just logs dagster-webserver   # View Dagster Webserver logs
just logs dagster-daemon      # View Dagster Daemon logs

请参阅 justfile，了解 100 多条开发命令，包括数据库迁移、CloudFormation 检查、图谱操作、管理等。

前置条件

系统要求

• Docker 和 Docker Compose
• 至少 8GB RAM
• 20GB 可用磁盘空间

所需工具

• 用于 Python 包和版本管理的 uv
• 用于项目命令运行的 just

已在 macOS 和 Linux 上开发并测试。在 Windows 上，请使用 WSL2，并将仓库克隆到 Linux 文件系统中——请参阅 Windows Setup (WSL2) Guide。

部署要求

• Fork 此仓库
• 配备 IAM Identity Center（SSO）的 AWS 账户
• 运行 just bootstrap 配置 OIDC 和 GitHub 变量

完整说明请参阅 Bootstrap 指南。

架构

完全基于开源引擎构建——PostgreSQL、LadybugDB、DuckDB、LanceDB、OpenSearch 和 Valkey——将它们组合成事务核心，并配备物化分析图和集成式向量搜索，不会被专有数据库锁定。

这种开放性不仅贯穿底层，也延伸到整个技术栈：会计本体、报告分类体系和计算结构都是可检查、可移植、由你拥有的制品，而不是被困在供应商平台配置中的内容——为你的财务数据实现语义自主权。

多租户与隔离

只有一条规则：每种隔离机制都以 graph_id 为键，而非以组织为键——会话 search_path、缓存键、幂等键、速率限制桶和额度核算都以图为命名空间。同一组织中的两张图使用与隔离两个互不相关的客户完全相同的机制；没有绕过边界的“内部”路径。

• 每个租户使用一个图数据库——每个层级都设为 databases_per_instance: 1，因此层级的差异在于实例大小，而非共享同一实例的租户数量。
• 按图划分 Schema 的 OLTP——每张图都有自己的 PostgreSQL Schema；每次请求都会重新设置 search_path，而不是从连接池中的连接继承。CI 结构测试会固定此约定。
• 两个数据库，两套迁移历史——平台状态（身份、组织、计费）与扩展 OLTP 相互独立；对其中一个的迁移绝不会影响另一个。
• 图是派生投影——OLTP 行是系统记录的事实来源，分析图则通过蓝绿方式从中重建，因此重建是常规操作，而非高风险操作。
• 子图是租户内彼此隔离的环境，共享父图的额度和权限——用于 AI 记忆、开发和团队工作区。
• 共享存储库（SEC XBRL）是唯一可由多个读取者访问的界面：只读、单独复制，可与自己的图一同查询，但绝不能通过它写入。

由于租户隔离是在图层而非应用谓词中强制执行，同一代码库无需 Fork，即可用于托管式 SaaS、专用单租户部署和完全可自托管的安装。详情：图与多租户。

身份与访问

程序化访问使用 X-API-Key；浏览器应用使用短期 JWT。用户的 登录 方式由部署决定——密码、WebAuthn 通行密钥或企业身份提供商。可通过 GET /v1/auth/providers 获取此配置，因此一个前端构建版本即可根据后端配置呈现相应的认证方式。

仓库中包含企业 SSO（OIDC）和 SCIM 2.0 配置，默认关闭——任何 Fork 都可以使用，无需许可证审核。配置仅支持关联：SCIM 创建账户，OIDC 仅解析已配置的账户，因此身份提供商可双向管理账户生命周期。

详情：企业 SSO 与 SCIM · 身份验证与 API 密钥 · SECURITY.md

组件

应用层：

• FastAPI REST API，提供带版本号的端点
• Extension GraphQL 读取 API，以及命名的 REST 命令操作（CQRS）
• 用于 AI 驱动的图数据库访问的 MCP 服务——每个图都支持 MCP Streamable HTTP 传输，并通过 OAuth 或 API 密钥进行身份验证
• AI Operator System，用于自主财务操作并自动跟踪信用额度
• Dagster，用于数据管道编排和后台任务

LadybugDB 图数据库：

• 专为财务分析打造的嵌入式列式图数据库
• 基础架构 + 扩展架构：扩展定义领域模型
• 原生 DuckDB 集成，用于高性能暂存和数据摄取
• LanceDB 作为语义模态引擎——每个图对应一个磁盘上的向量存储（IVF-PQ，384 维嵌入），用于 AI 记忆（记住/回忆）和向量搜索卸载
• 分层基础设施，支持配置内存、速率限制和子图分配
• 共享层托管公共存储库，并提供只读副本

数据层：

• PostgreSQL（RDS），用于 IAM、图元数据、Dagster 和扩展 OLTP 数据库（每个租户一个架构）
• OpenSearch，用于全文和语义文档搜索（BM25 + KNN）
• Valkey（ElastiCache），用于缓存、SSE 消息传递和速率限制
• S3，用于数据湖存储和静态资源
• DynamoDB，用于实例/图/卷注册表

基础设施：

• 通过 GitHub Actions 和 OIDC 部署 CloudFormation
• ECS Fargate 用于 API 和 Dagster
• EC2（ASG）用于 LadybugDB 写入集群；EC2（ALB + ASG）用于共享副本集群

AI

Model Context Protocol（MCP）

• 财务分析：使用自然语言查询企业数据和公共基准数据
• 跨数据库查询：将用户图数据与 SEC 共享存储库数据进行比较
• 工具：丰富的工具集，支持图查询、架构自省、事实发现、财务分析、文档搜索和 AI 记忆操作
• 处理程序池：受资源限制管理的 MCP 处理程序实例

AI Operator System

• 统一架构：无状态 Operators（Claude/MCP 执行器），通过基于协议的方式注入服务
• 双重执行方式：API（同步/SSE）和后台工作器（Valkey 队列 + SSE 进度）
• 自动跟踪每次 AI 调用的信用额度——Operators 不会遗漏计费
• 可扩展：为新的 AI 工作流添加 Operators；它们会自动继承执行、信用额度跟踪和进度流式传输功能

信用额度系统

• 仅限 AI 操作：信用额度仅在调用 AI Operator 时消耗（通过 AWS Bedrock 调用 Anthropic Claude）
• 基于 Token 的计费：根据实际 Token 用量和模型成本计算信用额度
• MCP 工具访问：调用 MCP 或执行数据库操作不消耗信用额度

SEC 共享仓库

基于 SEC EDGAR XBRL 文件整理的美国上市公司财务数据知识图谱。运行在共享 LadybugDB 层，可通过 MCP 工具、Cypher 查询和 AI Operator 访问。

完整语料每月也会以一个 LadybugDB 文件的形式发布到 Hugging Face — robosystems/sec-xbrl-knowledge-graphs（下载需要数十 GiB，磁盘占用远超 100 GiB；数据集说明页会列出每个快照的确切大小）。just sec-dump 会将其下载到 data/lbug-dbs，无需运行流水线即可在本地使用 Cypher、API 和 MCP；请参阅 SEC XBRL Pipeline 指南。

• 流水线：EDGAR → 下载 → 处理（Parquet）→ 暂存（DuckDB）→ 丰富（Icebug+fastembed）→ 实例化（LadybugDB）→ 索引 + 嵌入（OpenSearch）
• 图谱：基础架构加上 roboledger 扩展 — 20 种节点类型和 41 种关系类型，用于建模完整的 XBRL 报告层级
• 提取：每份文件都由 xbrlkit 解析 — 这是 disclosures 和 information-block 工具、holon 查看器及其自有 MCP 服务背后的同一个开源库
• 搜索：针对叙述性章节和 iXBRL 披露内容的 BM25 + KNN 混合向量搜索
• 丰富：在共享仓库的披露内容中进行语义元素映射、报表分类和披露标记

详细文档请参阅 SEC Adapter。

客户端库

RoboSystems 提供全面的客户端库，用于构建应用程序：

MCP（模型上下文协议）

每个图谱都是一个 MCP 服务，连接时首选使用图谱的 URL — Claude、Claude Code、Cursor 或任何支持 HTTP 传输的 MCP 客户端均可使用，无需安装。URL 用于选择图谱（公共 SEC 仓库使用 sec，自有图谱使用其图谱 ID）；使用 OAuth 登录，或将 API 密钥放入 X-API-Key 标头 — 切勿将密钥放在 URL 中。

OAuth — 登录并选择图谱。 与图谱无关的端点 https://api.robosystems.ai/v1/mcp 仅接受 OAuth：支持 OAuth 的客户端（claude.ai、Claude Code、ChatGPT、VS Code、Cursor）会从该端点发现授权服务器，你登录后选择此连接所涵盖的图谱，客户端会持有绑定到该图谱且可撤销的令牌 — 无需粘贴密钥。每个图谱的 URL 也接受 OAuth，同时支持密钥标头。（部署标志：MCP_OAUTH_ENABLED。）

RoboLedger 端点。 https://api.robosystems.ai/v1/mcp/roboledger 提供相同的 OAuth 流程，但仅适用于 RoboLedger 图谱：登录时只会显示你的 RoboLedger 图谱；该连接提供会计工具集，不包含工作区和平台管理工具（子图、备份、实例化、写入策略）。这是 RoboLedger 目录列表使用的端点，每个 URL 固定对应一份工具列表。

claude mcp add --transport http robosystems https://api.robosystems.ai/v1/mcp

使用 API 密钥连接 Claude Code — 只需一条命令：

claude mcp add --transport http robosystems-sec \
  https://api.robosystems.ai/v1/graphs/sec/mcp \
  --header "X-API-Key: <your key>"

Cursor / VS Code — 添加到 mcp.json：

"robosystems-sec": {
  "url": "https://api.robosystems.ai/v1/graphs/sec/mcp",
  "headers": { "X-API-Key": "<your key>" }
}

Claude（claude.ai / Desktop） — 依次选择“设置”→“连接器”→“添加自定义连接器”，并填写 https://api.robosystems.ai/v1/mcp（或每个图谱的 URL）：Claude 会检测到 OAuth，你可在登录时选择图谱。应用中的 MCP 页面（/connect）会为所选图谱填好所有代码片段，并为仅支持标头的客户端生成图谱范围密钥。

• 文档：AI Operators and MCP | stdio bridge（代理模式），适用于不支持 HTTP 传输的客户端

TypeScript/JavaScript 客户端

面向 Web 和 Node.js 应用的全功能 SDK，支持 TypeScript。

npm install @robosystems/client

• 功能：类型安全的 API 调用、自动重试逻辑、连接池、流式传输支持
• 使用场景：Web 应用、Node.js 后端、React/Vue/Angular 前端
• 文档：npm | GitHub

Python 客户端

适用于后端服务和数据科学工作流的原生 Python SDK。

pip install robosystems-client

• 功能：支持 Async/await、集成 pandas、兼容 Jupyter、批量操作
• 使用场景：数据管道、ML 工作流、后端服务、分析
• 文档：PyPI | GitHub

文档

技术文档

入门与平台：

• 主页 / 概览 · 快速入门 · 核心概念 · 架构概览 · 引导指南 · Windows 设置（WSL2） · 安全与合规

运营层：

• 图与多租户 · 身份验证与 API 密钥 · 企业 SSO 与 SCIM · 查询分析图 · 图操作 · AI 操作器与 MCP · 共享仓库 · 额度与账单 · 管道指南

扩展层：

• 扩展功能概览 · GraphQL 读取 · RoboLedger 操作 · RoboInvestor 操作 · 在本地连接 QuickBooks

内容与贡献体系：

• 信息块 · 分类体系与框架 · 事件驱动型账本 · 报告与渲染 · 序列化与导出

文档与搜索：

• 搜索与 AI 检索 · 文档管理 · 文件上传

演示：

• RoboLedger 演示导览 · SEC XBRL 管道 · 自定义图架构

代码库文档

每个包都有自己的文档——在目录中开展工作前，请先阅读该目录的 README。

核心服务：

• 适配器 - 外部服务集成
• 运维 - 业务工作流编排、用于扩展的 CQRS 查询／命令内核
• AI 操作器 - AI 操作器框架：Claude/MCP 执行器、额度跟踪、SSE 流式传输
• 模式 - 图模式定义
• 扩展 GraphQL - Strawberry GraphQL 读取接口、Pydantic 自动推导、解析器模式
• 配置 - 配置管理
• Dagster - 数据管道与任务编排

数据库模型：

• 平台模型 - 平台数据库的 SQLAlchemy 模型
• 扩展模型 - 扩展数据库的 SQLAlchemy 模型，采用每个图一个模式的租户管理方式
• API 模型 - 核心平台和扩展接口的 Pydantic 请求／响应模型

图数据库系统：

• 图 API - 图 API 概览
• 客户端工厂 - 客户端工厂系统
• 核心服务 - 核心服务层

中间件组件：

• 身份验证 - 身份验证与授权
• 图路由 - 图路由层
• MCP - MCP 工具与池化
• 计费 - 订阅与计费管理
• 可观测性 - OpenTelemetry 可观测性
• 健壮性 - 断路器与重试策略

基础设施：

• CloudFormation - AWS 基础设施模板
• 设置脚本 - 引导与配置脚本

开发资源：

• 示例 - 可运行的演示和集成示例
• 测试 - 测试策略与组织方式
• 管理工具 - 管理实用工具和命令行

安全与合规：

• SECURITY.md - 安全控制目录及实现参考
• 合规 - 合规体系、开关和 SOC 2 状况
• 信任中心 - 实时合规状况与审计材料

API 参考

• API 参考 — 所有端点及其参数、模式和调用示例
• 交互式 API 控制台 — Swagger UI，可使用你自己的密钥向线上 API 发起调用
• OpenAPI 规范 — 机器可读的源文件，SDK 生成器会读取此文件

支持

• 问题
• 文档
• 项目
• 讨论
• CONTRIBUTING.md — 分支约定、编码标准和拉取请求流程

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

Apache-2.0 © 2026 RFS LLC