Project Basanos

巴萨诺斯项目

一个参考实现，探索人工智能代理如何在企业系统中发现、推广和执行规则——基于ServiceNow构建。

Basanos （βάσανος）是希腊语，用于测试黄金纯度的试金石。Mike Carey的 *路西法*，Basanos是一个活生生的塔罗牌，可以阅读关系、预测后果并理解深层架构。它没有为主人服务。

这是什么

Basanos是一项应用研究，而不是产品。它探讨了一个具体的问题：当人工智能代理在多个企业系统中运行时，应该如何发现、审查和执行跨系统规则？

这项研究是针对ServiceNow的ITSM生态系统进行的，因为这是我所知道的。ServiceNow连接器是真实的，适用于实时实例。模拟Jira集成演示了如何跨系统边界扩展执行。这些概念适用于任何多系统环境，但其实现植根于ServiceNow。

这是一个单独的开源项目。MCP网关和代理治理正成为受资助团队（Cerbos、TrojAI、SAFE-MCP、Red Hat）的一个活跃类别。Basanos没有与他们竞争。这是一个探索模式并记录所学内容的工作原型。

问题

ServiceNow有业务规则。Jira有自动化。Salesforce有流量。每个系统都在自己的边界内执行规则。但没有一个系统能看到其他系统在做什么。ServiceNow业务规则无法检查Jira是否在同一服务上有活动部署。Jira自动化无法检查ServiceNow是否已冻结更改。

当人工智能代理在这些系统中运行时，谁来执行跨越边界的规则？

Basanos探索了一个答案：位于代理和目标系统之间的MCP代理网关，拦截工具调用，丰富来自多个来源的上下文，并返回 BLOCK 或 ALLOW 在行动执行之前做出判决。被阻止的动作永远不会到达目标系统。这是运行时强制执行，而不是上下文注入——Basanos不会将规则转储到系统提示符中，并希望LLM遵循这些规则。

代码的作用是什么

ServiceNow连接器 -通过REST API连接到活动实例。从以下位置导入表架构 sys_dictionary，同步活动实体，并充当MCP代理网关，在转发到ServiceNow的本机MCP服务器之前拦截工具调用、丰富上下文并执行规则。

规则引擎 -由YAML驱动。规则在启动时加载到内存中，并根据实时系统状态对每个请求进行评估。仅检查与预期操作匹配的升级规则。退货 BLOCK 或 ALLOW 有证据和审计追踪。

规则发现 -启发式模式分析（不是机器学习或人工智能推理）。编码算法扫描您的数据以查找已知的反模式：更改冻结、SLA违规、P1重新打开率、CI故障模式。输出是规则候选，而不是强制规则。

人在循环生命周期 -发现的规则从候选规则开始。在执行之前，人类会对其进行审查和推广。未经人类批准，任何规则都不会生效。随时降级或禁用。

跨系统演示 -模拟Jira数据演示了如何跨系统边界执行。ServiceNow数据是实时的；Jira数据是模拟的。演示显示了两个方向：ServiceNow捕捉Jira错过的内容，Jira捕捉ServiceNow错过的内容。

当前范围

• ServiceNow 是实现的连接器（REST API、模式导入、实体同步、MCP代理）。Jira是跨系统演示的模拟数据。其他连接器遵循相同的模式。
• 规则发现 使用启发式模式匹配编码算法，扫描已知的反模式（更改冻结、SLA违规、P1重新打开）。
• MCP服务器 运行并可由任何MCP客户端调用。特定于代理的集成（Claude Desktop配置等）留给操作员。
• 跨系统语义对齐 （跨平台映射等效概念）是一个尚未解决的开放问题。

建筑

flowchart TD
    subgraph Agents["AI Agents"]
        A1[Claude]
        A2[GPT]
        A3[ServiceNow Agent]
        A4[Custom Agents]
    end

    subgraph Basanos["project-basanos"]
        OE[Entity Model
How things connect across systems]
        CE[Rules Engine
Discover, promote, enforce]
        AC[Agent Card
A2A capability discovery]
        DS[(Domain Config
YAML rules + entity definitions)]
        OE --- DS
        CE --- DS
    end

    subgraph Systems["Enterprise Systems"]
        SN[ServiceNow
Implemented]
        JR[Jira
Demo/Mock]
        SF[Salesforce
Planned]
    end

    Agents -->|MCP / A2A| Basanos
    Basanos -->|REST Connectors| Systems

运作原理

Basanos连接到一个实时系统，导入其结构，并发现规则。今天，ServiceNow实现了此管道：

flowchart LR
    subgraph Operator
        U[Operator
Dashboard or CLI]
    end

    subgraph Pipeline["Basanos Pipeline"]
        C[Connect
Verify credentials]
        I[Import Schemas
Read sys_dictionary]
        S[Sync Entities
Query live tables]
        D[Discover Constraints
Analyze data patterns]
    end

    subgraph ServiceNow["ServiceNow Instance"]
        SD[sys_dictionary
Field definitions]
        SC[sys_choice
Dropdown values]
        TA[Table API
Live records]
    end

    subgraph Artifacts["Generated Artifacts"]
        OY[ontology.yaml
Entity definitions]
        CY[discovered-constraints.yaml
Rules from data]
        PJ[provenance.json
Proof of origin]
    end

    U --> C
    C --> I
    I -->|For each table| SD
    I -->|For each enum field| SC
    I --> S
    S -->|Query ITSM tables| TA
    S --> D
    D -->|Analyze patterns| TA
    D --> OY
    D --> CY
    D --> PJ

每一步的作用

sequenceDiagram
    participant Operator
    participant Basanos
    participant ServiceNow

    Operator->>Basanos: Credentials (URL, user, pass)

    rect rgba(200, 200, 255, 0.15)
    Note over Basanos,ServiceNow: Step 1: Connect
    Basanos->>ServiceNow: GET /api/now/table/incident?limit=1
    ServiceNow-->>Basanos: 200 OK
    Basanos-->>Operator: Connected
    end

    rect rgba(200, 255, 200, 0.15)
    Note over Basanos,ServiceNow: Step 2: Import Schemas
    loop For each table (incident, cmdb_ci, cmdb_ci_service, ...)
        Basanos->>ServiceNow: GET /api/now/table/sys_dictionary?name={table}
        ServiceNow-->>Basanos: Field definitions (type, mandatory, references)
        Basanos->>ServiceNow: GET /api/now/table/sys_choice?name={table}
        ServiceNow-->>Basanos: Enum values (priority, state, category)
    end
    Note over Basanos: Map types, detect relationships, write entity definitions
    end

    rect rgba(255, 200, 200, 0.15)
    Note over Basanos,ServiceNow: Step 3: Sync Entities
    loop For each ITSM table
        Basanos->>ServiceNow: GET /api/now/table/{table}?limit=100
        ServiceNow-->>Basanos: Live records
    end
    Note over Basanos: Convert to entities, wire cross-references
    end

    rect rgba(255, 255, 200, 0.15)
    Note over Basanos,ServiceNow: Step 4: Discover Constraints
    Basanos->>ServiceNow: Query change_request, task_sla
    ServiceNow-->>Basanos: Change freezes, SLA breaches
    Note over Basanos: Analyze P1 patterns, group workload, SLA breaches
    Basanos-->>Operator: 3 rules discovered with evidence
    end

进口后代理商看到了什么

sequenceDiagram
    participant Agent as AI Agent
    participant Basanos

    Agent->>Basanos: What is INC0099001?
    Basanos-->>Agent: P1 incident on mail-server-prod-01
affects Corporate Email Service
assigned to Infrastructure Operations

    Agent->>Basanos: Can I resolve this incident?
    Basanos-->>Agent: BLOCKED: Active change freeze
Evidence: 1 scheduled change request
Source: your-instance.service-now.com
Imported: 2026-02-17T00:28:57Z

    Agent->>Basanos: What else does this CI affect?
    Basanos-->>Agent: mail-server-prod-01 supports
3 business services, 2 with SLA penalties

每个答案都可以追溯到真实的API调用、真实的记录和真实的时间戳。出处已确定。

演示

仪表板有两个演示选项卡：

单系统演示

浏览Basanos针对实时ServiceNow实例的完整叙述：

1. 发现 -Basanos分析数据模式和曲面约束候选。虽然这可以通过ServiceNow中的业务规则或其他系统中的等效机制来实现，但同样的概念适用于多个系统和代理平台。
2. 促进 -人类会审查候选人并提拔重要的候选人。没有人工审查，任何规则都不会生效。
3. 执行 -任何MCP客户端都可以通过Basanos调用工具。Basanos丰富了上下文，评估约束，并阻止或允许调用。

多系统演示

使用实时ServiceNow数据和 模拟Jira数据 （不需要Jira凭据）。Basanos从两个来源丰富了上下文，然后评估了跨越两个系统的规则：

• 公司0025428 -ServiceNow冻结了更改，Jira没有部署。 此 路 不通。 只有Jira工具才能让这一切通过。
• 公司0025729 -ServiceNow没有更改冻结，但Jira有一个活动部署。 此 路 不通。 ServiceNow的业务规则本应允许这种情况发生。
• INC0018834 -两个系统都清楚。允许。

这两个方向都得到了证明：ServiceNow捕捉到Jira错过的内容，Jira捕捉到ServiceNow错过的内容。没有一个系统能同时看到这两种风险。

Docker快速入门（推荐）

经营Basanos最简单的方法。无需安装Node.js或TypeScript。

第一步：安装Docker桌面

Docker桌面是唯一的先决条件。

• macOS：下载 ，拖动到“应用程序”，启动
• 视窗：下载 ，运行安装程序，重新启动
• Linux: curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh

验证： docker --version

第二步：使用Docker Compose运行

git clone https://github.com/leojacinto/project-basanos.git
cd project-basanos
docker compose up

打开 http://localhost:3001 -仪表板加载了一个模拟的ServiceNow实例、示例ITSM数据和11条发现规则。

Docker Hub镜像: leofrancia08489/project-basanos:v0.2.0

步骤3：连接到真实的ServiceNow实例（可选）

创建一个 .env 项目根目录中的文件：

# Schema import (basic auth or OAuth)
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_USERNAME=admin
SERVICENOW_PASSWORD=your-password

# MCP Proxy Gateway (OAuth client_credentials)
SERVICENOW_MCP_SERVER_URL=https://your-instance.service-now.com/sncapps/mcp-server/mcp/sn_mcp_server_default
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET='your-client-secret'

然后重新启动： docker compose up

仪表板将使用您的真实凭据。去 连接 选项卡导入模式并发现约束，然后使用 演示 选项卡，用于测试对实时数据的约束执行。

开发者

• 利奥·弗朗西亚 -创建者、架构师、维护者
• 克劳德（人类学） -AI配对程序员和开发伙伴。为插件架构、连接器重构、仪表板UI、约束引擎、文档和CI/CD自动化做出了贡献。

快速入门（开发人员）

git clone https://github.com/leojacinto/project-basanos.git
cd project-basanos
npm install && npm run build

# Run the MCP server (hand-crafted ITSM ontology)
npm start

# Explore visually (multi-domain, light/dark mode, auto port scan)
npm run dashboard

# Inspect with MCP Inspector
npm run inspect

连接到实时ServiceNow实例

cp .env.example .env          # Configure credentials
npm run cli -- full            # Full pipeline: connect > import > sync > discover

# Or step by step
npm run cli -- connect         # Test connection
npm run cli -- import          # Import table schemas to YAML
npm run cli -- sync            # Sync live entities
npm run cli -- discover        # Discover constraints from data patterns

或者使用 “连接”选项卡 在仪表板中从浏览器运行管道。

使用模拟服务器进行测试

npm run mock-snow              # Starts mock at http://localhost:8090
npm run cli -- full            # In another terminal

项目结构

src/
├── index.ts                 # MCP server entry point (6 tools, dynamic resources)
├── cli.ts                   # CLI: connect, import, sync, discover
├── dashboard.ts             # Web UI: rules engine dashboard, demos, light/dark mode
├── loader.ts                # YAML schema/constraint loader
├── ontology/
│   ├── engine.ts            # Entity model resolution and traversal
│   ├── types.ts             # Core type system
│   └── schema.ts            # Schema loading and validation
├── constraints/
│   ├── engine.ts            # Rules evaluation engine with audit trail
│   ├── types.ts             # Rule type definitions
│   └── rule-evaluator.ts    # Declarative rule evaluator (YAML conditions)
├── connectors/
│   ├── types.ts             # ConnectorPlugin interface (the plugin contract)
│   ├── registry.ts          # Plugin registry (auto-discovers configured connectors)
│   ├── servicenow/          # ServiceNow plugin
│   │   └── index.ts         # Plugin entry point (wraps SN-specific code)
│   ├── jira/                # Jira plugin (mock, demonstrates the pattern)
│   │   └── index.ts         # Plugin entry point (mock data, cross-system constraint)
│   ├── servicenow.ts        # ServiceNow REST API client
│   ├── servicenow-mcp.ts    # ServiceNow MCP proxy (OAuth, tool exec, context enrichment)
│   ├── schema-importer.ts   # sys_dictionary -> entity definitions
│   ├── entity-sync.ts       # Live table data -> Basanos entities
│   └── constraint-discovery.ts  # Data pattern analysis -> suggested rules
├── a2a/
│   └── types.ts             # A2A agent card types and generation
├── mock/
│   └── servicenow-server.ts # Mock ServiceNow REST API for testing
├── server/
│   ├── resources.ts         # MCP resource handlers
│   └── tools.ts             # MCP tool handler reference
└── test/
    ├── smoke.ts             # 32-assertion engine test suite
    ├── yaml-loader.ts       # 23-assertion YAML loader tests
    └── scenario-autonomous.ts  # 3am incident demo (with vs without Basanos)
domains/
├── itsm/                    # Hand-crafted ITSM domain (YAML, promoted)
│   ├── ontology.yaml
│   └── constraints.yaml
├── servicenow-demo/         # Auto-imported from mock server (committed)
│   ├── ontology.yaml
│   ├── discovered-constraints.yaml  # status: candidate
│   └── provenance.json
└── servicenow-live/         # Auto-imported from real instance (gitignored)
    ├── ontology.yaml
    ├── discovered-constraints.yaml  # status: candidate
    └── provenance.json
docs/
└── DIFFERENTIATORS.md       # Critical analysis: why Basanos vs Claude Desktop

连接器插件架构

Basanos使用插件系统连接到外部系统。每个连接器都是自包含的，并实现了一个强制性合同。核心引擎（规则评估器、仪表板、CLI）从不直接导入特定于系统的代码——它与 ConnectorPlugin 界面。

添加新连接器

1. 创建 src/connectors/yourconnector/index.ts
2. 出口A createPlugin() 返回a的函数 ConnectorPlugin

就是这样。注册表通过扫描自动发现插件 src/connectors/*/index.ts 在启动时。不更改CLI、仪表板、注册表或规则引擎。

强制性合同

每个连接器 必须 执行以下所有操作。看 src/connectors/types.ts 对于完整的TypeScript接口。

身份

配置

管道（进口流量）

运行时（在执行过程中按请求调用）

可选的

每个发现的约束必须包括什么

约束由返回 discoverConstraints() 是人工审核的候选者。每个人都必须具备：

• ID -唯一的、前缀有域（例如。， "servicenow-live:discovered:change_freeze")
• 适用范围 -该规则检查实体类型（例如。， ["incident"])
• 相关行动 -触发该规则的动作（例如。， ["resolve", "close"])
• 严重性 - block, warn，或 info
• 证据 -数据证明这种模式存在
• 违规信息 -被阻止时该告诉代理什么
• 满意的消息 -清楚后该告诉代理人什么

如果没有所有这些，约束对规则引擎或审查它的人都没有用。

现有连接器

示例：最小连接器

// src/connectors/yourconnector/index.ts
import type { ConnectorPlugin } from "../types.js";

class YourPlugin implements ConnectorPlugin {
  readonly id = "yourconnector";
  readonly label = "Your System";
  readonly description = "Connects to Your System via REST API.";

  getRequiredEnvVars() {
    return [
      { name: "YOUR_API_URL", description: "Base URL", required: true },
      { name: "YOUR_API_KEY", description: "API key", required: true, secret: true },
    ];
  }

  configureFromEnv() {
    return !!(process.env.YOUR_API_URL && process.env.YOUR_API_KEY);
  }

  async testConnection() { /* ... */ }
  getDefaultTables() { return ["issues", "projects"]; }
  async importSchemas(tables, outputDir) { /* ... */ }
  async syncEntities(ontologyEngine, options) { /* ... */ }
  async discoverConstraints(domainName, outputPath) { /* ... */ }
  async enrichContext(entityRef, action) { /* ... */ }
}

export function createPlugin(): ConnectorPlugin {
  return new YourPlugin();
}

注册表将在启动时自动找到它，不需要注册步骤。

起始域：ITSM

erDiagram
    Incident ||--o{ Business_Service : "affects"
    Incident ||--o{ Configuration_Item : "on CI"
    Incident ||--o{ Assignment_Group : "assigned to"
    Incident ||--o{ SLA_Contract : "governed by"
    Change_Request ||--o{ Configuration_Item : "impacts"
    Change_Request ||--o{ Assignment_Group : "owned by"
    Problem ||--o{ Incident : "causes"
    Business_Service ||--o{ SLA_Contract : "bound by"
    Business_Service ||--o{ Configuration_Item : "supported by"

ITSM是第一个领域，因为关系丰富，规则明确，影响可衡量。Basanos的代理可以做出更好的决策：更少的错误升级、对变化冻结的认识和准确的影响评估。

协议

MCP代理网关

Basanos可以充当 强制代理的规则 在ServiceNow的原生MCP服务器之前。任何MCP客户端（Claude、Copilot、Google ADK、人类）都会连接到Basanos，而不是直接连接到ServiceNow。Basanos拦截工具调用，通过实时API查询（不是缓存或静态数据）丰富目标系统的上下文，评估规则，并阻止或转发调用。规则在启动时从YAML加载到内存中，并根据请求进行评估。仅检查与预期操作匹配的升级规则，而不是系统中的所有规则。

Any MCP Client (Claude, Copilot, Google ADK, human)
  -> Basanos MCP Server (constraint gateway)
    -> ServiceNow MCP Server (execution)

在中配置 .env:

SERVICENOW_MCP_SERVER_URL=https://your-instance.service-now.com/sncapps/mcp-server/mcp/sn_mcp_server_default
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET='your-client-secret'

在评估规则之前，代理使用实时上下文（事件优先级、CI、活动更改请求、SLA违规）丰富每个工具调用。这意味着同一个“解决事件”工具可以针对一个事件被阻止（其CI上的活动更改冻结），并允许针对另一个事件（无更改）——基于真实的系统状态，而不是静态配置。

为什么不直接使用ServiceNow业务规则？

无论请求如何到达，ServiceNow的服务器端规则（业务规则、数据策略、ACL）都会保护ServiceNow数据。它们已经成熟，能够很好地覆盖自己的表面。对于单一系统场景，它们是正确的答案。

Basanos探索了上面的一层——当规则需要跨越系统边界时会发生什么：

• 跨系统意识 -“如果Jira中存在同一服务的开放部署，则不要解决此事件。”ServiceNow规则看不到Jira。
• 发现 -启发式分析，将数据中已知的反模式作为规则候选者，供人类审查。
• 协议网关 -MCP工具调用的单一执行点，无论调用哪个代理或系统。

这不是业务规则的替代品。这是一项关于互补层可能是什么样子的研究。

安全和身份验证

身份验证模式

连接器会根据您的喜好自动检测使用哪种模式 .env:

推荐设置

将OAuth client_credentials用于本地测试之外的任何事情。 为了方便起见，模拟服务器支持基本身份验证，但不应用于真实实例。

1. 创建专用OAuth客户端 在ServiceNow中：系统OAuth>应用程序注册表>创建OAuth API端点。
2. 范围权限为只读 在Basanos需要的桌子上(sys_dictionary, sys_choice, incident, cmdb_ci, cmdb_ci_service, change_request, task_sla, sys_user_group).
3. 使用服务帐户，不是个人管理员帐户。Basanos不需要管理员权限进行架构导入或实体同步。
4. 对于MCP代理网关，OAuth客户端需要访问MCP服务器范围。代理在规则评估后转发工具调用，将客户端范围限定为您打算公开的工具。

如何使用凭据

• 架构导入 从ServiceNow的表API读取。它从不回信。
• MCP代理 仅在规则通过后转发工具调用（包括“resolve incident”等写入）。代理通过OAuth client_credentials进行身份验证。
• 进口后，Basanos从本地YAML文件提供服务，与ServiceNow没有连接。凭据仅在导入和实时代理调用期间使用。

静态数据

• 生成的 ontology.yaml 和 provenance.json 包含表结构、字段名和记录计数。没有凭据，但有结构元数据。在敏感环境中相应地处理这些文件。
• 这 .env 文件被标记为无效。不要将凭据提交到版本控制。

相关工作

代理治理的问题已经得到很好的识别。Anthropic称之为“情境工程”(构建高效代理).空间正在快速移动。

MCP治理和政策执行

这些是建立生产级解决方案的资助团队。Basanos作为一项研究而非竞争对手探索了类似的领域。

企业知识与本体

Basanos探索的不同之处

Basanos将MCP代理、YAML规则引擎、启发式规则发现和跨系统执行结合在一个开源代码库中。各个部分存在于其他地方（通常在资源更充足的项目中）。这项研究的价值在于将它们与真实的ServiceNow实例连接在一起，并记录它们如何交互。

探索的概念

设计选择

• 深度大于广度。 一个域（ITSM/ServiceNow）做得很好，而不是对许多域的浅覆盖。
• 运行时强制执行，而不是上下文注入。 在执行操作之前返回判决。规则不会注入到提示中。
• 商业逻辑，而非安全。 正确性的护栏（更改冻结、SLA感知），而不是威胁检测。
• 互补，而非竞争。 现有的系统规则（业务规则、自动化、流）是其边界内的正确答案。这探讨了上面的内容。

规则生命周期

发现的规则不会自动执行。他们遵循深思熟虑的晋升工作流程：

candidate  --->  promoted  --->  disabled
   ^                |               |
   |                v               |
   +----------  demoted  <----------+

• 候选人：从数据中发现或手工制作但尚未审查。在仪表板中可见，但不由代理强制执行。
• 晋升：由人审查并积极执行。代理商来电 basanos_check_constraints 将收到来自这些机构的阻止/警告判决。
• 残疾：明确暂停。已晋升，现在已关闭（例如，在维护窗口期间）。

80/20控制

仪表板根据规则显示两个控件：

1. 状态 （候选人/晋升/残疾）
2. 严重性 （阻止/警告/信息）

深度规则逻辑（条件、运算符、实体作用域）存在于版本控制下的YAML文件中。仪表板用于操作决策，而不是规则编写。

贡献

basanos项目是开源的。“项目”前缀是有意的——这是一种探索，而不是一种成品。

如果你对这里的概念感兴趣，欢迎投稿。看 贡献.md 作为指导方针。

许可证

麻省理工学院