AI智能体基础设施

QBrain.AI

Workspace-scoped AI agent infrastructure for .NET: context retrieval, TODO orchestration, session logging, durable agent memory, repository operations, GitHub automation, GraphRAG, host-local Products for shared requirements, and agent orchestration over HTTP and MCP STDIO transports.

Versioning: GitVersion.yml sets the next version to 1.4.39. The deployed service version is reported by /health; a source checkout may be ahead of or behind that deployment. /health echoes a caller nonce for liveness and reports storage as reachable or unreachable.

Key Features

• Three transports - HTTP REST with Swagger UI, MCP Streamable HTTP at /mcp-transport, and MCP-over-STDIO for direct agent integration
• QuadBrain - four-role multi-model decision engine (Creativity, Logic, CuriosityEngine, ArbiterOfTruth) behind an OpenAI-compatible chat-completions endpoint
• Multi-tenant workspaces - single port, workspace isolation via header, API key, or default resolution
• Agent orchestration - process-isolated agent pool with branch strategies, PowerShell sessions, and desktop automation
• Semantic search - ONNX-based vector embeddings with HNSW indexing, optional GraphRAG enhancement
• Requirements traceability - FR/TR/TEST document management with validation and Markdown/ZIP export
• Products - host-local PROD-* workspace groups that share FR/TR/TEST/layers into effective queries and product-requirements context without copying rows
• Use cases - workspace-scoped use-case modeling with FR Realizes links, coverage, UML canvas graph (schema v1), sequence diagrams, first-party UI at /usecases/, REST + MCP + typed client
• Multi-provider storage - SQLite, SQL Server, and PostgreSQL with startup migrations enabled by default; Mcp:Database:AutoMigrate=false requires an administrator to apply pending migrations before startup
• REPL CLI tool - qbrain-ai-repl for interactive use and agent STDIO access via single-line JSON request envelopes
• Agent memory - workspace-scoped remember/recall/explore/promote/consolidate/revert plus compat CRUD. All eight official plugins inject a raw REQUIRED MEMORIES block at host-supported request boundaries. Default CI bench stays Grok; ./build.ps1 BenchMemory -Plugin all is unblocked after H7a agree:true. Multi-turn v2 uses tokens as the primary metric (docs/benchmarks/).
• Typed .NET client - QBrainAI.Client NuGet package covering all API endpoints

Quick Start

# Build
./build.ps1 Compile

# Run
./build.ps1 StartServer --instance default

# Test
./build.ps1 Test

Open Swagger at http://localhost:7147/swagger.

Frontier agent setup prompt (draft)

Operator-facing copy-paste setup prompt for frontier coding agents (MCP-SETUPPROMPT-001). Status: DRAFT with hostile-validator overall AGREE (Accuracy 99, Completeness 99) on 2026-09-28 CT; live install dry-runs remain outside that draft acceptance.

• Draft: docs/setup/2026-09-28-frontier-agent-setup-prompt.DRAFT.md
• Receipts: docs/receipts/setup/ and docs/receipts/hv/hostile-validator-setupprompt-*

Architecture

src/
  QBrainAi.Support.Mcp     ASP.NET Core server (controllers, STDIO host, auth)
  QBrainAi.Client           Typed REST client library (NuGet)
  QBrainAi.McpAgent         Microsoft Agent Framework integration
  QBrainAi.Repl.Core        REPL protocol, request envelopes, trust bootstrap
  QBrainAi.Repl.Host        qbrain-ai-repl CLI tool
  QBrainAi.SessionLog.Transcripts  Transcript detection, normalization, and canonical YAML (Claude, Codex, Grok, Cline, Copilot, OpenCode)
  QBrainAi.Services         Business logic (ingestion, indexing, TODO, GitHub, agents)
  QBrainAi.Storage          EF Core abstraction + vector indexing
  QBrainAi.GraphRag         Hybrid semantic search with GraphRAG
  QBrainAi.Cqrs             Lightweight async CQRS framework (NuGet)
  QBrainAi.Cqrs.Mvvm        MVVM extensions for CQRS
  QBrainAi.Launcher          Windows GUI launcher
  QBrainAi.ServiceDefaults  Aspire service defaults, OpenTelemetry, health checks

Transports

HTTP

./build.ps1 StartServer --instance default
# Listens on http://localhost:7147

MCP Streamable HTTP

JSON-RPC MCP transport. No API key required.

POST http://localhost:7147/mcp-transport

MCP STDIO

dotnet run --project src/QBrainAi.Support.Mcp -- --transport stdio --instance default

REPL

./build.ps1 InstallReplTool
qbrain-ai-repl --interactive              # interactive mode
qbrain-ai-repl --agent-stdio              # STDIO mode for agent integration

Direct --agent-stdio callers send one single-line JSON request envelope per stdin line. Do not send formatted YAML or a type: batch envelope.

API Surface

Configuration

Primary config section: Mcp. Instance overrides under Mcp:Instances:{name}.

{
  "Mcp": {
    "Port": 7147,
    "RepoRoot": ".",
    "DataSource": "mcp.db",
    "ApiKey": "your-api-key",
    "TodoStorage": { "Provider": "database" },
    "Instances": {
      "default": { "Port": 7147, "RepoRoot": "." },
      "alt-local": { "Port": 7157, "TodoStorage": { "Provider": "database" } }
    }
  }
}

Environment overrides: PORT (runtime port), MCP_INSTANCE (instance selection).

Authentication

Storage

Database providers (EF Core with configurable startup migrations):

TODO items live in the configured database (the sole source of truth); docs/Project/TODO.yaml is a read-only projection. The removed yaml provider fails fast, and sqlite is a deprecated alias for database (TR-MCP-CFG-007).

Audit ledgers are permanent and local. New DataAuditLogs rows use versioned GZip payload columns; legacy text rows remain readable. TODO audit rows are excluded from federation and wiki exports. SQL Server deployments can use a restricted mcp_runtime role after an administrator applies the audit migration. See Permanent local audit storage for migration and runtime identity steps.

Vector indexing uses ONNX Runtime with Sentence Transformer embeddings and HNSW index for semantic search.

Deployment

Build System

Nuke build orchestrator via ./build.ps1 (or ./build.sh on Linux/macOS).

CI/CD

Versioning uses GitVersion (GitVersion.yml, next-version: 1.4.39). See docs/AZURE-PIPELINES.md for pipeline variables and the optional Octopus Deploy integration.

Client Library

dotnet add package QBrainAI.Client

builder.Services.AddQBrainAiClient(options =>
{
    options.BaseUrl = new Uri("http://localhost:7147");
    options.ApiKey = "your-api-key";
});

Covers: Todo, Context, SessionLog, Memory, GitHub, Repo, Workspace, ToolRegistry, Sync, and more.

Source: src/QBrainAi.Client/ | Package README

Agent Framework

QBrainAi.McpAgent integrates with the Microsoft Agent Framework:

builder.Services.AddQBrainAiMcpAgent();

Built-in MCP tools: mcp_repo_read, mcp_repo_list, mcp_repo_write, mcp_desktop_launch, mcp_powershell_session_*. Workflows: session log lifecycle, TODO management, requirements ingestion.

Sample host: src/QBrainAi.McpAgent.SampleHost/

Tests

22 test projects covering unit, integration, and Reqnroll validation (plus the QBrainAi.ProcessTree.TestHelper support project):

• Build.Tests - build system and configuration
• QBrainAi.Support.Mcp.Tests / .IntegrationTests - server API and database
• QBrainAi.Client.Tests - REST client serialization
• QBrainAi.McpAgent.Tests - agent workflows and tool adapters
• QBrainAi.Repl.Core.Tests / .IntegrationTests - REPL protocol
• QBrainAi.Cqrs.Tests - CQRS dispatcher and pipeline
• QBrainAi.QBAgent.Tests - QuadBrain agent behavior
• QBrainAi.Launcher.Tests - launcher host
• QBrainAi.Acid.IntegrationTests - ACID turn-closure matrix
• QBrainAi.TransactionSecurity.IntegrationTests - durable transaction security storage
• QBrainAi.PlanReview.Tests / QBrainAi.Review.Tests - plan and AI review flows
• QBrainAi.PluginIntegration.Tests - plugin integration
• 7 Reqnroll validation projects (Context, GitHub, Repo, SessionLog, Todo, ToolRegistry, Workspace)

./build.ps1 Test runs the unit gate only: it excludes every *.IntegrationTests project and filters out Category=Integration and Category=AiReview tests. Integration suites that need provisioned dependencies run through ./build.ps1 MigrationIntegrationTests or by targeting the project directly.

The audit payload migration integration tests cover SQLite, SQL Server (LocalDB by default), and PostgreSQL (ephemeral cluster by default). Run the focused provider set with:

dotnet test tests/QBrainAi.Support.Mcp.Tests/QBrainAi.Support.Mcp.Tests.csproj --filter "FullyQualifiedName~AuditPayloadMigrationTests|FullyQualifiedName~SqlServerAuditPayloadMigrationTests|FullyQualifiedName~PostgreSqlAuditPayloadMigrationTests"

Integration tests provision what they need. The QuadBrain Ollama tests probe http://localhost:11434 at fixture startup, adopt a server that is already running, or start one from a discovered ollama executable and stop that server again at teardown. Only a server the fixture started is stopped. When no executable is discoverable the failure names the InstallOllama target, which stages the portable binaries and the required model.

Prerequisites

• .NET SDK (version in global.json)
• PowerShell 7+ (pwsh.exe)
• Optional: Windows SDK (makeappx.exe) for MSIX, GitHub CLI (gh) for GitHub endpoints

Documentation

License

See LICENSE for details.

Shared Plugin Surfaces

This repository is the canonical home for the shared client surfaces used by all QBrainAi agent plugins:

• PowerShell: tools/powershell/McpRepl (published to PS Gallery as McpRepl)
• TypeScript: tools/typescript/mcp-repl-ts (published to npm as @qbrainai/qbrain-ai-repl)

See the respective READMEs in those directories and GROK-USAGE.md in the grok-plugin for usage details.