脑区 BrainRegion

English | 简体中文

BrainRegion is AI collaboration infrastructure for review, consultation, planning, and memory.

This project was formerly design-review-mcp. The internal Python package has moved to brain_region, while the old CLI command aliases remain available during the rename.

The current MCP server and CLI can fan out a plan, source change, or document to multiple LLM reviewer roles, retrieve project-specific knowledge, normalize duplicate findings, and return consensus-oriented reports that are easier to act on. It also includes external consultation tools for asking another expert model when the main assistant is stuck.

The core pipeline is project-agnostic. Project-specific behavior lives in adapters, so the default experience stays useful for general product, architecture, code, and document design reviews. Optional adapters can add domain knowledge without changing the core pipeline.

Highlights

• Review plans, code, Markdown, ADRs, RFCs, and config documents.
• Use reviewer roles such as planner, safety, architecture, performance, feasibility, and visionary.
• Run one model or a panel of models, including official LiteLLM providers and OpenAI/Anthropic-compatible gateways.
• Retrieve framework and project-local knowledge before review.
• Normalize findings into canonical buckets and separate consensus, majority, and individual issues.
• Render JSON, Markdown, and SARIF output.
• Track review memory with mark_finding so accepted/rejected findings can influence later confidence calibration.
• Ask external consultant models with consult_problem and record useful advice with mark_advice.
• Merge defaults from builtin values, global config, project config, environment variables, and explicit call arguments.

Architecture

Most pieces are swappable. Adapter-specific behavior stays out of core/.

Layer	Contract	Default implementation
ModelBackend	async complete(...)	LiteLLMBackend
KnowledgeProvider	retrieve/list_cases/add_case	YamlKnowledgeProvider
ProjectAdapter	read_context/version/convention + reviewers/knowledge	GenericAdapter, optional domain adapters
ReportRenderer	render(ReviewReport)	Markdown / JSON / SARIF renderers
Stage	process(ctx) -> ctx	retrieve, context, prompt, review, parse, normalize, consensus, score

Adding another project type should usually mean adding a new adapter package, not changing the core pipeline.

Review Pipeline

ReviewDocument
  -> RetrieveStage
  -> ContextStage
  -> PromptStage
  -> ReviewStage      # fan-out across panel x dimensions
  -> ParseStage
  -> NormalizeStage   # canonical finding buckets
  -> ConsensusStage
  -> ScoreStage
  -> ReviewReport

The pipeline is designed to reduce "confident but unsupported" feedback:

• Findings need evidence quotes.
• Knowledge retrieval can inject project gotchas and version-specific cases.
• Reviewer prompts are role-specific.
• Canonical normalization reduces duplicate phrasing across models.
• Calibrated confidence combines model agreement, severity, retrieval hits, and review memory.

External Consultation

consult_problem is for moments when the main assistant is stuck, uncertain, repeatedly debugging the same issue, or needs another expert perspective. It does not execute commands or edit files; it returns structured advice, hypotheses, next experiments, risks, and a recommended plan.

consult_problem(
    problem="FlowField updates occasionally deadlock",
    context="Unity ECS project; double buffering and JobHandle.CombineDependencies were already tried.",
    logs="Occasionally stalls near CompleteDependency()",
    attempts=["double buffering", "combined JobHandle dependencies"],
    mode="architecture",
)

Common modes:

• debugging: root-cause diagnosis.
• architecture: boundaries, state flow, and maintainability.
• performance: latency, throughput, token/API cost.
• simplicity: YAGNI and smaller MVP slices.
• game_design: gameplay and player experience.
• challenge: adversarial challenge to the current thinking.
• planning: task decomposition, risks, and acceptance criteria.

Recommended config:

{
  "consult_panel": ["modelbridge_openai/gpt-5.4-mini"],
  "consult_consultants": ["debugger", "critic"],
  "consult_max_cost_usd": 0.03,
  "consult_max_input_chars": 24000
}

If consult_panel is not configured, consultation falls back to panel. For day-to-day use, keep a cheaper/faster consult panel so one consultation does not expand the full review panel.

consult_problem returns a consultation_id, and each item in individual has a stable advice id. Mark useful or unhelpful advice with Advice Memory:

mark_advice(
    advice_id="consult-abc123-0",
    consultation_id="consult-abc123",
    decision="accepted",
    reason="identified the real race condition",
    outcome="added the suggested minimal reproduction test",
)

decision is one of accepted, rejected, partial, or unknown. The database stores advice metadata and user feedback, not the original prompt, problem text, or full advice body.

Knowledge Base

Review quality depends heavily on project knowledge. Built-in adapter packages may ship seed cases, but the most useful architecture decisions, historical bugs, and team conventions usually live in project-local knowledge files.

Recommended project-local location:

<project-root>/.brain-region/knowledge/*.yaml

The legacy .design-review/knowledge/ directory is still loaded first for compatibility. New .brain-region/knowledge/ cases load after it and can override legacy cases with the same id.

Example:

- id: API-001
  title: "Keep breaking API changes behind a migration path"
  version: {service: ">=2.0"}
  triggers: ["breaking change", "API contract", "migration"]
  category: compatibility
  bad_pattern: "Change a public request or response shape without a versioned fallback or migration notes."
  recommended_pattern: "Add a compatible path, document the migration window, and test old and new clients."
  source: "ADR-014#api-versioning"

Tips:

• Write one concrete, reproducible gotcha per case.
• Put words that will appear in plans or code into triggers.
• Keep sensitive project knowledge local and ignored by git.
• Use list_knowledge to inspect the loaded framework and local cases.

Installation

cd <path-to-brain-region-mcp>
uv sync --extra dev

Run the test suite:

uv run pytest tests/ -q
uv run --extra dev ruff check .

MCP Setup

Register the stdio server in Codex, Claude Code, or another MCP client:

{
  "type": "stdio",
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "<path-to-brain-region-mcp>",
    "brain-region-mcp"
  ],
  "env": {
    "UNITY_PROJECT_ROOT": "<path-to-project-root>",
    "BRAIN_REGION_CONFIG": "<path-to-brain-region-mcp>/brain_region_config.json"
  }
}

UNITY_PROJECT_ROOT is a historical project-root environment variable name. Point it at the project you want reviewed. Keep API keys in .env or process environment variables. Do not commit .env or local brain_region_config.json.

CLI

The brain-region CLI uses the same pipeline as the MCP server. The legacy design-review command is still available as an alias during the rename.

uv run brain-region plan path/to/plan.md --output markdown
cat plan.md | uv run brain-region plan -
uv run brain-region plan --text "# Plan" --dimensions planner feasibility
uv run brain-region code src/a.py src/b.py --output sarif --output-file review.sarif
uv run brain-region doc docs/rfc.md --type rfc --output markdown

Common options:

• --panel: model list or endpoint shortcuts.
• --dimensions: reviewer dimensions.
• --adapter: auto, generic, or another installed domain adapter.
• --retrieve-top-k: number of knowledge cases to retrieve.
• --effort: reasoning/thinking effort where supported.
• --max-cost-usd: preflight budget cap.
• --timeout: per-model timeout.

Configuration

Defaults are resolved in this order:

builtin < global config < project config < env < explicit tool args

See:

• Config precedence
• Endpoint configuration

Typical local config path:

<path-to-brain-region-mcp>/brain_region_config.json

brain_region_config.json can hold defaults such as:

• panel
• dimensions
• retrieve_top_k
• timeout
• normalizer_model
• effort
• max_cost_usd
• endpoints
• privacy_policy
• context_modes

Custom Gateway Endpoints

Use endpoints for OpenAI-compatible or Anthropic-compatible gateways such as New API, one-api, OpenRouter-style proxies, or internal model bridges. Use one endpoint per wire protocol.

{
  "endpoints": {
    "modelbridge_openai": {
      "provider": "openai",
      "base_url": "https://www.modelbridge.cloud/v1",
      "api_key_env": "MODEBRIDGE_API_KEY",
      "models": ["gpt-5.5", "gpt-5.4-mini"]
    },
    "modelbridge_anthropic": {
      "provider": "anthropic",
      "base_url": "https://www.modelbridge.cloud",
      "api_key_env": "MODEBRIDGE_API_KEY",
      "models": ["claude-haiku-4-5"]
    }
  },
  "panel": ["modelbridge_openai/gpt-5.5", "modelbridge_anthropic/claude-haiku-4-5"]
}

Panel shortcuts:

• "endpoints" expands every declared model under every endpoint.
• "endpoint_id" expands every model under one endpoint.
• "endpoint_id/model" runs one model through one endpoint.
• Native LiteLLM strings such as "gpt-4o" or "deepseek/deepseek-chat" bypass endpoint config and use provider env vars.

Cost And Effort Controls

Two optional controls are available:

• max_cost_usd: preflight cost cap for a review. Jobs are kept in panel order until the estimate would exceed the cap.
• effort: reasoning/thinking intensity for providers that support it. Unsupported providers ignore it.

The report includes estimated budget information and actual usage/cost where the provider returns it.

Privacy Mode

By default, every model in the panel receives the review document. For sensitive plan reviews, privacy_policy can enable a strict mode where a trusted model sees the full document, adversarial reviewers see a redacted summary, and the trusted model later mediates evidence.

{
  "privacy_policy": {
    "policy": "strict",
    "trusted": {"endpoint": "trusted_gateway", "model": "trusted-model", "label": "trusted"},
    "min_coverage": 0.5
  }
}

Strict privacy is most useful for plan review. Code review can lose too much semantic detail after redaction.

Review Memory

Use mark_finding to record whether a finding was useful:

mark_finding(finding_id="gpt-4o-3", decision="accepted", params_hash="...")

Valid decisions are accepted, rejected, and partial. Feedback is stored in the local SQLite review database and is used to calibrate future confidence per (model, dimension).

Output

Reports include:

• consensus: findings all models agreed on.
• majority: findings supported by multiple models.
• individual: one-model findings.
• failed_models: isolated model failures.
• budget, usage, risk, and context_compression metadata.

SARIF output can be uploaded to GitHub Code Scanning or consumed by IDEs.

Project Layout

brain_region/
  server.py              # MCP server entry point
  cli.py                 # brain-region CLI
  core/                  # pipeline, stages, schemas, report models
  adapters/              # generic and optional domain adapters
  providers/             # LLM backends
  knowledge/             # retrieval providers
  privacy/               # privacy policies
  output/                # renderers
tests/                   # pytest coverage
docs/                    # focused docs

Security Notes

• Do not commit .env, .env.local, API keys, generated databases, or local brain_region_config.json files.
• Legacy design_review_config.json files are still supported but should not be committed either.
• Prefer api_key_env over plaintext api_key.
• Generated review databases such as brain_region_reviews.db are local data and should not be used in tests. Legacy design_reviews.db files are still read when present.

License

Apache-2.0