脑区 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 brainregion, 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.
• Generate executable task plans with plan_task, then review the plan before implementation.
• Route a goal/problem to likely Brain Regions with route_regions as a local, deterministic precursor to context scheduling.
• Suggest explicit manual next steps with suggest_workflow without auto-calling tools or models.
• Inspect model routing with list_model_routes so bare model names and endpoint-backed models are not confused.
• Attach model profile metadata such as cheap, fast, flagship, sleep, or awake for preflight visibility.
• Recommend a model panel with suggest_panel from profile tags and cost/speed/quality scores without calling models.
• Plan auditable Skill/Region wakes with plan_region_activation, including hard prerequisites, deny conditions, and bounded context requests.
• 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.

Planning

plan_task turns a goal into a structured, reviewable implementation plan. It is intentionally a thin Planner MVP: it does not execute commands, does not edit files, and does not run a multi-model debate. It tries the configured model panel in order and returns the first parseable plan.

plan_task(
    goal="Add a Planner MVP to BrainRegion",
    context="Python MCP server with existing consult_problem and review_plan tools.",
    constraints=[
        "Do not auto-execute tasks.",
        "Reuse existing budget and input guardrails.",
    ],
    success_criteria=[
        "The MCP tool returns milestones, tasks, risks, acceptance criteria, and tests.",
        "Unit tests cover parsing and routing.",
    ],
)

Recommended flow:

Goal -> plan_task -> review_plan -> implement -> review_code -> mark_finding / mark_advice

Optional config:

{
  "planner_panel": ["modelbridge_openai/gpt-5.4-mini"],
  "planner_max_cost_usd": 0.03,
  "planner_max_input_chars": 24000
}

If planner_panel is not configured, planning falls back to consult_panel, then panel.

Brain Regions

route_regions is the first small step toward region-based context scheduling. It is deliberately local and deterministic: it does not call models, read memory, or trigger review/consult/planner tools. It only ranks static region definitions by explicit triggers and returns an activation trace.

route_regions(
    goal="Optimize a Unity ECS FlowField system that allocates too much memory",
    files={
        "Assets/Scripts/FlowFieldSystem.cs": "...",
    },
    top_k=3,
)

Example result shape:

{
  "selected": [
    {"id": "unity_ecs", "score": 4, "matched_triggers": [...]},
    {"id": "performance", "score": 4, "matched_triggers": [...]}
  ],
  "trace": {
    "strategy": "deterministic_keyword_v1",
    "input": {"file_contents_used": false}
  }
}

Built-in regions currently include planning, review, debugging, performance, security, memory, research, and unity_ecs. This tool is advisory; future schedulers must explicitly decide whether to consume its result.

Structured Activation Contracts

plan_region_activation is the next deterministic layer after candidate routing. Existing Skill manifests may declare an activation contract with positive signals, deny conditions, required tools/capabilities, context selectors, and budgets. Manifests without a contract remain inert.

plan_region_activation(
    task_intents=["diagnose_failure"],
    events=["test_failed"],
    available_tools=["git"],
    max_regions=2,
    max_context_tokens=2000,
)

The result records every Skill as wake, skip, or defer. A wake includes a bounded context_request; a skip includes the failed prerequisite or deny reason. Defer is reserved for a future cheap semantic gate. The hard gate itself never calls a model, retrieves memory, or executes a tool.

load_region_context consumes the same hard-gate plan and materializes only activated provider Skills into short-lived ContextBlock values:

load_region_context(
    query="Why did the parser keep failing after several repair attempts?",
    events=["repeated_attempt_failed"],
    scope_regions=["debugging"],
    max_context_tokens=2000,
)

Provider failures are isolated, and both block count and estimated tokens are bounded. Advisory/action Skills remain visible in the activation trace but are not executed by this call. Retrieval does not call a model, write memory, or retain the returned context in the runtime.

Cognitive Workspace Delivery

stage_region_context loads activated provider context into a process-local task workspace and returns only a delivery receipt. Region-private block contents are not included in the staging result:

stage_region_context(
    task_id="parser-debug",
    query="Repeated parser failures after several repair attempts",
    events=["repeated_attempt_failed"],
    audience="region",
    target_region="debugging",
    ttl_steps=3,
)

workspace_context provides four lifecycle operations through one MCP tool:

• read: main consumers see main + shared; region consumers see their region + shared.
• inspect: returns delivery metadata and evidence references without context contents.
• advance: decrements explicit task-step TTL and unloads expired entries.
• clear: unloads every workspace entry for one task.

The workspace stores evidence and structured task context, not model chain of thought. It is an architectural routing boundary rather than an authorization boundary; process restart also clears it. Read operations apply a fresh block and estimated-token budget before returning context.

Region Status and Escalation

A successful stage now records a RegionContextReceipt containing observable retrieval state: provider outcomes, block/token counts, evidence references, removed stale candidates, conflicts, and selector coverage. Coverage remains unverified until a provider explicitly confirms selectors; retrieval success is not treated as proof that a model understands the task.

Experts publish structured reports through the existing workspace tool:

workspace_context(
    task_id="parser-debug",
    operation="publish_report",
    report={
        "region": "debugging",
        "state": "needs_decision",
        "summary": "Historical constraints change the parser design.",
        "evidence_refs": ["memory:id:exp-parser"],
        "context_state": "ready",
        "decision_scope": "architecture",
        "risk": "medium",