内容
# 脑区
[English](README.md) | [简体中文](README.zh-CN.md)
脑区是用于评审、咨询、规划和记忆的AI协作基础设施。
该项目以前名为`design-review-mcp`。内部Python包已移至`brain_region`，而旧的CLI命令别名在重命名期间仍然可用。
当前的MCP服务器和CLI可以将计划、源代码更改或文档分发给多个LLM评审角色，检索特定于项目的知识，规范化重复的发现，并返回更容易实施的共识导向报告。它还包括用于在主助手卡住时询问另一个专家模型的外部咨询工具。
核心流程与项目无关。特定于项目的行为存在于适配器中，因此默认体验对于一般的产品、架构、代码和文档设计评审仍然有用。可选的适配器可以在不更改核心流程的情况下添加领域知识。
## 亮点
- 评审计划、代码、Markdown、ADRs、RFCs和配置文件。
- 使用`planner`、`safety`、`architecture`、`performance`、`feasibility`和`visionary`等评审角色。
- 运行一个模型或一组模型，包括官方LiteLLM提供商和OpenAI/Anthropic兼容网关。
- 在评审前检索框架和项目本地知识。
- 将发现规范化为规范桶，并将共识、多数和个别问题分开。
- 渲染JSON、Markdown和SARIF输出。
- 使用`mark_finding`跟踪评审记忆，以便接受/拒绝的发现可以影响后来的置信度校准。
- 使用`consult_problem`询问外部顾问模型，并使用`mark_advice`记录有用的建议。
- 使用`plan_task`生成可执行的任务计划，然后在实施前评审计划。
- 使用`route_regions`将目标/问题路由到可能的脑区，作为上下文调度的本地确定性前置。
## 架构
大多数部分都是可互换的。适配器特定的行为保持在`core/`之外。
| 层 | 契约 | 默认实现 |
|---|---|---|
| `ModelBackend` | `async complete(...)` | `LiteLLMBackend` |
| `KnowledgeProvider` | `retrieve/list_cases/add_case` | `YamlKnowledgeProvider` |
| `ProjectAdapter` | `read_context/version/convention + reviewers/knowledge` | `GenericAdapter`，可选领域适配器 |
| `ReportRenderer` | `render(ReviewReport)` | Markdown / JSON / SARIF渲染器 |
| `Stage` | `process(ctx) -> ctx` | retrieve，context，prompt，review，parse，normalize，consensus，score |
添加另一种项目类型通常意味着添加一个新的适配器包，而不是更改核心流程。
## 评审流程
```text
ReviewDocument
-> RetrieveStage
-> ContextStage
-> PromptStage
-> ReviewStage # 跨面板和维度分发
-> ParseStage
-> NormalizeStage # 规范发现桶
-> ConsensusStage
-> ScoreStage
-> ReviewReport
```
该流程旨在减少“自信但无依据”的反馈：
- 发现需要证据引用。
- 知识检索可以注入项目陷阱和版本特定案例。
- 评审员提示是角色特定的。
- 规范化减少了模型之间的重复措辞。
- 校准的置信度结合了模型一致性、严重性、检索命中和评审记忆。
## 外部咨询
`consult_problem`用于主助手卡住、不确定、重复调试相同问题或需要另一个专家视角时的情况。它不执行命令或编辑文件；它返回结构化的建议、假设、下一步实验、风险和推荐计划。
```python
consult_problem(
problem="FlowField更新偶尔死锁",
context="Unity ECS项目；已经尝试了双缓冲和JobHandle.CombineDependencies。",
logs="偶尔在CompleteDependency()附近卡住",
attempts=["双缓冲", "组合JobHandle依赖"],
mode="architecture",
)
```
常见模式：
- `debugging`：根本原因诊断。
- `architecture`：边界、状态流和可维护性。
- `performance`：延迟、吞吐量、token/API成本。
- `simplicity`：YAGNI和较小的MVP切片。
- `game_design`：游戏玩法和玩家体验。
- `challenge`：对当前思维的对抗性挑战。
- `planning`：任务分解、风险和验收标准。
推荐配置：
```jsonc
{
"consult_panel": ["modelbridge_openai/gpt-5.4-mini"],
"consult_consultants": ["debugger", "critic"],
"consult_max_cost_usd": 0.03,
"consult_max_input_chars": 24000
}
```
如果未配置`consult_panel`，则咨询会退回到`panel`。对于日常使用，请保留一个更便宜/更快的咨询面板，以便一次咨询不会扩展整个评审面板。
`consult_problem`返回一个`consultation_id`，而`individual`中的每个项目都有一个稳定的建议`id`。使用建议记忆标记有用或无用的建议：
```python
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",
)
```
## 规划
`plan_task`将目标转化为结构化的、可评审的实施计划。它故意是一个薄的Planner MVP：它不执行命令，不编辑文件，也不运行多模型辩论。它按顺序尝试配置的模型面板，并返回第一个可解析的计划。
```python
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.",
],
)
```
推荐流程：
```text
Goal -> plan_task -> review_plan -> implement -> review_code -> mark_finding / mark_advice
```
可选配置：
```jsonc
{
"planner_panel": ["modelbridge_openai/gpt-5.4-mini"],
"planner_max_cost_usd": 0.03,
"planner_max_input_chars": 24000
}
```
如果未配置`planner_panel`，则规划会退回到`consult_panel`，然后是`panel`。
## 脑区
`route_regions`是面向区域的上下文调度的第一步小尝试。它是故意本地和确定的：它不调用模型、不读取内存，也不触发评审/咨询/规划工具。它只按明确的触发器排序静态区域定义，并返回激活跟踪。
```python
route_regions(
goal="Optimize a Unity ECS FlowField system that allocates too much memory",
files={
"Assets/Scripts/FlowFieldSystem.cs": "...",
},
top_k=3,
)
```
示例结果形状：
```jsonc
{
"selected": [
{"id": "unity_ecs", "score": 4, "matched_triggers": [...]},
{"id": "performance", "score": 4, "matched_triggers": [...]}
],
"trace": {
"strategy": "deterministic_keyword_v1",
"input": {"file_contents_used": false}
}
}
```
内置区域目前包括`planning`、`review`、`debugging`、`performance`、`security`、`memory`、`research`和`unity_ecs`。该工具是咨询性的；未来的调度器必须明确决定是否使用其结果。
## 知识库
评审质量在很大程度上取决于项目知识。内置适配器包可能会提供种子案例，但最有用的架构决策、历史错误和团队约定通常存在于项目本地知识文件中。
推荐的项目本地位置：
```text
<project-root>/.brain-region/knowledge/*.yaml
```
旧的`.design-review/knowledge/`目录仍然被加载以保持兼容性。新添加的`.brain-region/knowledge/`案例在加载后可以覆盖具有相同`id`的旧案例。
示例：
```yaml
- id: API-001
title: "在迁移路径后面保留破坏性API更改"
version: {service: ">=2.0"}
triggers: ["breaking change", "API contract", "migration"]
category: compatibility
bad_pattern: "在没有版本后备或迁移说明的情况下更改公共请求或响应形状。"
recommended_pattern: "添加兼容路径，记录迁移窗口，并测试旧客户端和新客户端。"
source: "ADR-014#api-versioning"
```
提示：
- 为每个案例编写一个具体的、可重现的陷阱。
- 将可能出现在计划或代码中的词语放入`triggers`。
- 保留敏感的项目知识本地，并被git忽略。
- 使用`list_knowledge`检查加载的框架和本地案例。
## 安装
```bash
cd <path-to-brain-region-mcp>
uv sync --extra dev
```
运行测试套件：
```bash
uv run pytest tests/ -q
uv run --extra dev ruff check .
```
## MCP设置
在Codex、Claude Code或其他MCP客户端中注册stdio服务器：
```jsonc
{
"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`是一个历史上的项目根环境变量名称。将它指向您要评审的项目。 将API密钥保留在`.env`或进程环境变量中。不要提交`.env`或本地`brain_region_config.json`。
## CLI
`brain-region` CLI使用与MCP服务器相同的流程。旧的`design-review`命令在重命名期间仍然作为别名可用。
```bash
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
```
常见选项：
- `--panel`：模型列表或端点快捷方式。
- `--dimensions`：评审维度。
- `--adapter`：`auto`、`generic`或其他已安装的领域适配器。
- `--retrieve-top-k`：检索的知识案例数量。
- `--effort`：支持的推理/思考努力。
- `--max-cost-usd`：预检预算上限。
- `--timeout`：每个模型的超时。
## 配置
默认配置按以下顺序解析：
```text
builtin < global config < project config < env < explicit tool args
```
参见：
- [配置优先级](docs/config_precedence.md)
- [端点配置](docs/endpoint_config.md)
典型的本地配置文件路径：
```text
<path-to-brain-region-mcp>/brain_region_config.json
```
`brain_region_config.json`可以保存以下默认值：
- `panel`
- `dimensions`
- `retrieve_top_k`
- `timeout`
- `normalizer_model`
- `effort`
- `max_cost_usd`
- `endpoints`
- `privacy_policy`
- `context_modes`
## 自定义网关端点
使用`endpoints`进行OpenAI兼容或Anthropic兼容的网关，例如New API、one-api、OpenRouter样式的代理或内部模型桥。每个线协议使用一个端点。
```json
{
"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"]
}
```
面板快捷方式：
- `"endpoints"`扩展了每个端点下的每个声明模型。
- `"endpoint_id"`扩展了某个端点下的每个模型。
- `"endpoint_id/model"`通过某个端点运行一个模型。
- 原生LiteLLM字符串（如`"gpt-4o"`或`"deepseek/deepseek-chat"`）绕过端点配置并使用提供商环境变量。
## 成本和努力控制
提供了两个可选控制：
- `max_cost_usd`：评审的预检成本上限。作业按面板顺序保留，直到估计超过上限。
- `effort`：支持它的提供商的推理/思考强度。不受支持的提供商会忽略它。
报告包括估计的预算信息和提供商返回的实际使用/成本。
## 隐私模式
默认情况下，面板中的每个模型都会收到评审文档。对于敏感的计划评审，`privacy_policy`可以启用严格模式，其中受信任的模型看到完整文档，对抗性评审者看到删节的摘要，而受信任的模型稍后会调解证据。
```json
{
"privacy_policy": {
"policy": "strict",
"trusted": {"endpoint": "trusted_gateway", "model": "trusted-model", "label": "trusted"},
"min_coverage": 0.5
}
}
```
严格隐私对于计划评审最有用。代码评审可能会在删节后失去太多语义细节。
## 评审记忆
使用`mark_finding`记录发现是否有用：
```text
mark_finding(finding_id="gpt-4o-3", decision="accepted", params_hash="...")
```
有效决定是`accepted`、`rejected`和`partial`。反馈存储在本地SQLite评审数据库中，并用于根据`(model, dimension)`校准未来的置信度。
## 输出
报告包括：
- `consensus`：所有模型都同意的发现。
- `majority`：多个模型支持的发现。
- `individual`：单个模型的发现。
- `failed_models`：隔离的模型失败。
- `budget`、`usage`、`risk`和`context_compression`元数据。
SARIF输出可以上传到GitHub Code Scanning或被IDE消费。
## 项目布局
```text
brain_region/
server.py # MCP服务器入口点
cli.py # brain-region CLI
core/ # 流程、阶段、模式、报告模型
adapters/ # 通用和可选领域适配器
providers/ # LLM后端
knowledge/ # 检索提供商
privacy/ # 隐私策略
output/ # 渲染器
tests/ # pytest覆盖率
docs/ # 重点文档
```
## 安全说明
- 不要提交`.env`、`.env.local`、API密钥、生成的数据库或本地`brain_region_config.json`文件。
- 旧的`design_review_config.json`文件仍然受支持，但也不应提交。
- 优先使用`api_key_env`而不是纯文本`api_key`。
- 生成的评审数据库（如`brain_region_reviews.db`）是本地数据，不应在测试中使用。旧的`design_reviews.db`文件在存在时仍然会被读取。
## 许可证
Apache-2.0
