anything-cli

# Anything Graph - 策略即代码层 **Anything Graph** 是一个面向 AI 智能体的语义数据层。它解决了当前 AI 智能体中最令人沮丧的问题： ``` 🤝 如何确保智能体答案在不同团队之间的一致性？ 🏢 如何让智能体在不同部门之间协同工作？ 🔍 如何提高 RAG 中的检索质量？ 🔒 如何强制执行权限和访问控制？ 📋 如何提高可审计性？ 🎯 如何避免幻觉？ 💸 如何让智能体在不消耗大量令牌的情况下读取数百万条记录？ 📖 如何阻止智能体使用错误的术语定义？ 🔗 如何让智能体理解多个系统中的数据？ ``` **我们认为答案不是另一个 LLM 或另一个 AI 编排系统 — 而是你的数据。** 你需要在 AI 智能体和你的记录系统之间添加一个轻量级的语义层。它不会移动你的数据，不会是另一个 ETL 项目，也不会依赖于转储提示。 ## 它给你： 1. **比基于模式的提示少 90% 的令牌** 2. **跨系统联合查询** 3. **可审计的证明** 4. **策略即代码，不在提示中** 5. **Git 原生本体 — 版本控制的剧本和绑定在存储库中；联合访问实时数据，无需建立 ETL 团队或数据湖** <b>在这里观看我们的演示 <a href="https://anythinggraph.com/demo.html" target="_blank">演示</a></b> 你的数据保留在原处 — Postgres、Salesforce、CSV 文件等。AnythingGraph 为 Cursor、Claude 等智能体提供了一种 **有管理的理解和查询** 数据的方式，其答案可以追溯到源头。 --- ## 为什么智能体和 AI 开发人员喜欢它 1. **稳定的词汇** — 当 IT 部门重命名列时，“客户”和“拥有账户”不会更改（更新绑定，而不是每个提示）。 2. **联合** — 一个剧本，多个系统；无需将所有内容强制放入一个数据库。 3. ** onboarding 循环** — 你的智能体可以读取你的模式，提出绑定，测试它，然后保存 — 在智能体执行繁琐的映射时，你可以保持在循环中。 4. **策略即代码** — 查询通过一个受管理的路径（剧本 → 计划 → 源），而不是来自聊天的原始 SQL。 --- ## 它是如何工作的 ### 1. 快速安装 ```bash npm install -g @anythinggraph/cli@latest anythinggraph onboard --install-daemon anythinggraph start ``` ### 2. 设置数据连接 ```bash anythinggraph start anythinggraph source add ``` `source add` 是一个四步向导：选择适配器（Postgres、MySQL、SQL Server、MongoDB、Salesforce、CSV、REST）、选择配置文件名（`source_id`）、输入凭证，然后在保存 `profiles/local.yaml` 和 `.env` 之前进行验证。 Git 克隆贡献者可以使用与 `npm install -g @anythinggraph/cli` 相同的流程，或者手动编辑文件： ```bash cp .env.example .env # 编辑 profiles/local.yaml 和 .env，然后： chmod +x start-all.sh # 仅第一次执行 ./start-all.sh ``` 我们支持 SQL 数据库、MongoDB、Salesforce SOQL、CSV 和 REST/HTTP JSON API 作为数据源。参见 [连接你的数据](https://anythinggraph.github.io/getting-started/connect-your-data/) 和 [完整文档](https://anythinggraph.github.io/)。 ### 3. 在你喜欢的 AI 智能体中连接 MCP ```json { "mcpServers": { "anythinggraph-cli": { "url": "http://127.0.0.1:3334/mcp" } } } ``` 在你的智能体工作空间中使用 [AGENTS.md](https://github.com/AnythingGraph/anything-cli/blob/main/AGENTS.md) — 它列出了 MCP 工具和紧凑的剧本/绑定格式。 ### 4. 浏览你的数据并创建自然语言本体剧本 这一步影响最大。使用你的 AI 智能体浏览数据，定义实体和关系，并设置基于角色的访问控制 — 所有操作都使用自然语言。 参见剧本指南：[剧本文档](https://anythinggraph.github.io/playbooks/)。 Anything Graph 引擎负责大部分繁重的工作，以生成你的 [本体剧本和数据绑定](https://anythinggraph.github.io/playbooks/)。 ### 5. 将你的本体剧本投入生产 生产剧本提供范围限定数据访问、AI 推理和治理。示例提示： - *谁是该人员或角色？* - *他们负责哪些记录？* - *他们可以看到哪些相关数据？* - *Alex 拥有多少个账户？* - *显示 Alex 的工资历史记录数* - *Alex Anderson 有多少条工资记录？* --- ## 数据适配器 适配器将配置文件连接到实时系统。**目前已有七种适配器**；更多适配器共享相同的剧本和绑定模型。 [查看如何连接你的数据源](https://anythinggraph.github.io/getting-started/connect-your-data/) | 适配器 | 配置文件密钥 | 典型源 | 状态 | | -------------- | --------------- | ------------------------------- | ------------- | | SQL | `sql` | PostgreSQL | **可用** | | CSV | `csv` | 本地 CSV / 平面文件 | **可用** | | SOQL | `soql` | Salesforce | **可用** | | MySQL | `mysql` | MySQL, MariaDB | **可用** | | SQL Server | `mssql` | Microsoft SQL Server, Azure SQL | **可用** | | MongoDB | `mongodb` | MongoDB 集合 | **可用** | | REST / OpenAPI | `rest` | HTTP JSON API | **可用** | | BigQuery | `bigquery` | Google BigQuery | 计划中 | | Snowflake | `snowflake` | Snowflake | 计划中 | | Databricks | `databricks` | Databricks SQL | 计划中 | | Elasticsearch | `elasticsearch` | Elasticsearch / OpenSearch | 计划中 | | S3 / Parquet | `s3` | 对象存储，Parquet 文件 | 计划中 | | GraphQL | `graphql` | GraphQL 端点 | 计划中 | | Google Sheets | `google_sheets` | 电子表格 | 计划中 | | HubSpot | `hubspot` | HubSpot CRM | 计划中 | --- ## 剧本和绑定 如何编写剧本 JSON 和绑定 YAML： **[playbooks/README.md](playbooks/README.md)** — 或 [剧本文档](https://anythinggraph.github.io/playbooks/) 中的网络演练（使用演示剧本作为示例）。 --- ## 技术参考 ### 安装和运行 **要求：** Rust、Node.js、Postgres（用于 CRM 演示），可选 CSV 用于工资演示。 ```bash cargo build --release cd mcp && npm install && cd .. cp .env.example .env # 编辑 .env 文件，包含连接字符串 ./start-all.sh ``` | 服务 | URL | | --------------------- | --------------------------- | | 推理 API | `http://127.0.0.1:8787` | | MCP（Cursor / Claude） | `http://127.0.0.1:3334/mcp` | `start-all.sh` 停止任何现有的进程，然后启动这两个服务。按 Ctrl+C 停止。 `start-all.sh` 自动设置工作区路径和服务 URL。在 `.env` 文件中覆盖任何值 — 参见下面的 [环境参考](#环境参考)。 ### 样本 Postgres 模式（CRM 演示） ```sql CREATE TABLE users ( user_id TEXT PRIMARY KEY, full_name TEXT NOT NULL ); CREATE TABLE accounts ( account_name TEXT PRIMARY KEY, industry TEXT, owner_user_id TEXT NOT NULL REFERENCES users(user_id) ); INSERT INTO users VALUES ('alex.ae', 'Alex Anderson'); INSERT INTO accounts VALUES ('Northwind Traders', '零售', 'alex.ae'), ('Contoso Ltd', '技术', 'alex.ae'); ``` 工资样本数据：`data/payroll.csv`（列 `user` 链接到 `users.user_id`）。 ### 验证剧本 ```bash cargo run -p anythinggraph-ag -- validate --playbooks playbooks ``` 参见 **[playbooks/README.md](playbooks/README.md)** 了解完整的创作演练。 ### 凭证和配置文件 1. `**cp .env.example .env`** — 将机密放入 `.env`（gitignored）。`start-all.sh` 自动加载它。 2. `**profiles/local.yaml**` — 使用 `env:AG_*` 引用注册命名源（此文件中不包含机密）。 参见 `.env.example` 了解所有支持的变量。详情参见剧本指南。 ### 认证角色（一个 MCP + 持有者令牌） 本地开发：`start-all.sh` 默认设置 `AG_AUTH_DISABLED=1`（无需持有者令牌）。要启用身份验证，请在 `.env` 文件中设置： ```bash AG_AUTH_DISABLED=0 AG_ADMIN_TOKENS=admin-secret-change-me AG_USER_TOKENS=user-secret-change-me ``` 客户端在 MCP HTTP 请求上发送 `Authorization: Bearer <token>`。令牌映射到： | 角色 | MCP 工具 | 推理 HTTP | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | **用户** | `health_check`, `list_playbooks`, `get_playbook_context`, `list_entity`, `sample_entity`, `plan_query`, `execute_plan`, `query_graph`, `list_allowed_rows` | `/query`, `/plan`, `/execute`, `/rebac/`*, 读取剧本上下文 | | **管理员** | 所有用户工具 **加** `list_sources`, `get_adapter_guide`, `list_bindings`, `get_binding`, `introspect_source`, `sample_source`, `suggest_bindings`, `propose_binding`, `test_binding`, `save_binding`, `propose_playbook`, `save_playbook` | 所有端点 | 当 `AG_AUTH_DISABLED=1` 或未配置令牌时，身份验证被禁用（仅限本地开发）。 **配置文件永远不会通过 MCP 编写** — 手动编辑 `profiles/local.yaml`。管理员代理使用 `list_sources` → `get_adapter_guide(source_id)` → `introspect_source` 在创作绑定之前。 **实时数据是只读的** — 绑定拒绝非 SELECT 查询；MCP 没有插入/更新/删除工具。 **代理创作：** 参见 **[AGENTS.md](AGENTS.md)** 了解紧凑的剧本/绑定格式。MCP `propose_binding` 默认不再返回扩展 SQL — `save_binding` 写入您提交的 YAML **逐字**（验证仅在内存中编译）。 标准输入 MCP：为 `AG_MCP_AUTH_TOKEN` 设置管理员或用户令牌。 ### 完整的 MCP 工具列表 | 工具 | 角色 | 目的 | | ---------------------- | ----- | ---------------------------------------------------------------------------------------- | | `health_check` | 用户 | 乒乓 Rust 推理服务 | | `list_playbooks` | 用户 | 列出从 `playbooks/` 加载的剧本 ID | | `get_playbook_context` | 用户 | 加载剧本模式摘要（实体和关系） | | `list_entity` | 用户 | 列出剧本实体的行（有界浏览；默认限制 1000） | | `sample_entity` | 用户 | 返回剧本实体的少量样本（默认限制 5） | | `plan_query` | 用户 | 将结构化联合查询编译为计划 IR | | `execute_plan` | 用户 | 通过只读适配器执行编译的计划 IR | | `query_graph` | 用户 | 编译并执行联合只读查询，一步到位（证明信封） | | `list_allowed_rows` | 用户 | 列出主题在强制 ReBAC 规则下可以读取的行标识符 | | `list_sources` | 管理员 | 列出 `profiles/local.yaml` 中的已配置数据源（无机密） | | `get_adapter_guide` | 管理员 | 每个适配器的绑定创作指南，用于 `source_id` — 在 `propose_binding` 之前调用 | | `list_bindings` | 管理员 | 列出 `bindings/` 中加载的绑定文件茎 | | `get_binding` | 管理员 | 按茎加载一个已保存的绑定 YAML | | `introspect_source` | 管理员 | 读取代理映射的源模式（表/列 — 只读） | | `sample_source` | 管理员 | 从源表/集合/对象读取几个原始行（无需剧本） | | `suggest_bindings` | 管理员 | 从内省模式建议剧本实体到表映射 | | `propose_binding` | 管理员 | 验证声明性绑定 YAML（无 SQL） | | `test_binding` | 管理员 | 编译针对提议或已保存绑定的样本查询；可选执行只读 | | `save_binding` | 管理员 | 将声明性绑定 YAML 保存到 `bindings/{playbook_id}.{adapter_suffix}.yaml` | | `propose_playbook` | 管理员 | 验证紧凑的剧本 JSON | | `save_playbook` | 管理员 | 将紧凑的剧本 JSON 保存到 `playbooks/{playbook_id}.json` | ### 手动启动（替代） ```bash # 终端 1 export AG_SQL_DSN="postgres://..." export AG_ADMIN_TOKENS="admin-secret" export AG_USER_TOKENS="user-secret" cargo run -p reasoning-service # 终端 2 cd mcp && AG_REASONING_URL=http://127.0.0.1:8787 AG_ADMIN_TOKENS=admin-secret AG_USER_TOKENS=user-secret npm run dev:http ``` ### 环境参考 复制 `.env.example` 到 `.env` 并在本地编辑 — 永远不要提交 `.env`。`profiles/local.yaml` 以 `env:AG_*` 引用凭证；仅在 `.env` 中保留机密。 **数据源凭证** （由 `profiles/local.yaml` 使用）： | 变量 | 示例 / 默认 | 目的 | | --------------------- | -------------------------------------------- | --------------------------------------------- | | `AG_SQL_DSN` | `postgres://user:pass@localhost:5432/yourdb` | Postgres — 配置文件密钥 `warehouse_pg` | | `AG_PAYROLL_CSV_PATH` | `./data/payroll.csv` | 本地 CSV — 配置文件密钥 `payroll_csv` | | `AG_MONGODB_DSN` | `mongodb://localhost:27017` | MongoDB 连接 — 配置文件密钥 `mongo_main` | | `AG_MONGODB_DATABASE` | `mydb` | MongoDB 默认数据库 | | `AG_SF_INSTANCE_URL` | `https://your-instance.my.salesforce.com` | Salesforce 实例 URL | | `AG_SF_ACCESS_TOKEN` | — | Salesforce OAuth 访问令牌 | | `AG_REST_BASE_URL` | `https://api.example.com` | REST/HTTP JSON API 基 URL（可选） | | `AG_REST_TOKEN` | — | REST API 持有者令牌（可选） | **路径和工作区** (`start-all.sh` 将 `AG_WORKSPACE_ROOT` 设置为存储库根目录)： | 变量 | 默认 | 目的 | | ------------------- | --------------------------------- | ---------------------------------------------------- | | `AG_WORKSPACE_ROOT` | 存储库根目录 | 剧本、绑定和配置文件的_workspace 根目录 | | `AG_PLAYBOOKS_DIR` | `{workspace}/playbooks` | 剧本 JSON 目录 | | `AG_BINDINGS_DIR` | `{workspace}/bindings` | 绑定 YAML 文件 | | `AG_PROFILE_PATH` | `{workspace}/profiles/local.yaml` | 命名源配置文件（引用 `env:AG_`*） | **服务** （可选 — 默认值适用于本地开发）： | 变量 | 默认 | 目的 | | ------------------- | ----------------------- | ---------------------------- | | `AG_REASONING_HOST` | `127.0.0.1` | 推理服务绑定主机 | | `AG_REASONING_PORT` | `8787` | 推理服务端口 | | `AG_REASONING_URL` | `http://127.0.0.1:8787` | MCP → 推理 API 基 URL | | `AG_MCP_HOST` | `127.0.0.1` | MCP HTTP 绑定主机 | | `AG_MCP_PORT` | `3334` | MCP HTTP 端口 | **身份验证**: | 变量 | 默认 | 目的 | | ------------------- | --------------------- | -------------------------------------- | | `AG_AUTH_DISABLED` | `1` 在 `start-all.sh` | 设置为 `0` 以需要持有者令牌 | | `AG_ADMIN_TOKENS` | — | 以逗号分隔的管理员持有者令牌 | | `AG_USER_TOKENS` | — | 以逗号分隔的用户持有者令牌 | | `AG_MCP_AUTH_TOKEN` | — | stdio MCP 的默认令牌（可选） | **调试**: | 变量 | 默认 | 目的 | | ------------------- | ------- | ----------------------------------------------------------------------------------------------- | | `AG_DEBUG_COMPILED` | 未设置 | 将 `debug_compiled_binding_yaml` 设置为 `propose_binding` 响应（仅限调试） | ### HTTP API 推理服务在 **8787** 端口暴露 `/health`, `/playbooks/{id}/context`, `/playbooks/{id}/propose-playbook`, `/playbooks/{id}/save-playbook`, `/query`, 绑定上线端点等。受保护的路由在配置身份验证令牌时需要 `Authorization: Bearer <token>`。 --- ## 许可证 Apache-2.0 版权所有 (C) 2026 — EdwardDeBon, AnythingGraph.