使用说明

SCOUT - 战略首席技术官运营与统一工具平台

个人MCP服务器，通过协调AI团队提升CTO（首席技术官）的生产力。

SCOUT协调专门的人工智能代理（Gemini、OpenAI、Claude、OpenRouter、Grok）来完成复杂的架构设计、分析和战略任务，遵循模型上下文协议（MCP）。

📋 功能

多供应商AI编排无缝使用5家AI提供商，统一界面
基于团队的执行配置主节点+验证器模型以达成共识
**MCP协议原生（或：MCP协议本地）**与Claude桌面版和网页版完全兼容
合同优先开发JSON模式定义了严格的工具契约
80%以上的测试覆盖率强制检测确保可靠性
结构化日志记录完整可追溯性，支持请求关联
成本追踪实时监控API使用情况和成本
智能缓存基于Redis的缓存减少了冗余的API调用

🚀 快速入门

先决条件

Python 3.11及以上版本
Redis（发音类似“雷迪斯”，但通常直接音译为“瑞迪斯”或保持原英文名） （本地或云端）
API密钥 对于至少一家人工智能提供商（Gemini、OpenAI、Anthropic、OpenRouter 或 Grok）

1. 克隆并设置

# Clone repository
git clone <repository-url>
cd SCOUT

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

2. 配置环境

# Copy environment template
cp .env.example .env

# Edit .env and add your API keys
# Required: At least one AI provider API key
# Required: REDIS_URL (default: redis://localhost:6379)

所需的最少变量：

# Choose at least one provider
GEMINI_API_KEY=AIza...          # OR
OPENAI_API_KEY=sk-proj-...      # OR
ANTHROPIC_API_KEY=sk-ant-...    # OR
OPENROUTER_API_KEY=sk-or-v1-... # OR
GROK_API_KEY=xai-...

# Infrastructure
REDIS_URL=redis://localhost:6379

3. 设置 Redis

选项A：Docker（推荐）

# Run Redis container
docker run -d \
  --name scout-redis \
  -p 6379:6379 \
  redis:7-alpine

# Verify connection
docker exec scout-redis redis-cli ping
# Expected output: PONG

选项B：本地安装

Windows：

# Install via Chocolatey
choco install redis-64

# Start Redis
redis-server

macOS:

# Install via Homebrew
brew install redis

# Start Redis service
brew services start redis

Linux（Ubuntu/Debian）：

# Install Redis
sudo apt update
sudo apt install redis-server

# Start Redis service
sudo systemctl start redis
sudo systemctl enable redis

选项C：云Redis（Upstash）

在（某网站/平台）创建免费账户 Upstash（注：这是一个专有名词，可能指某个特定的公司、服务或产品名称，在中文中没有直接对应的翻译，因此保持原样。）
创建Redis数据库

复制连接URL到 .env：

REDIS_URL=redis://default:<password>@<host>:<port>

4. 测试安装

# Run tests
pytest

# Check coverage
pytest --cov=src/scout --cov-report=html

# Start MCP server (when implemented)
python -m scout

📁 项目结构

SCOUT/
├── .specify/                   # SpecKit framework
│   ├── memory/
│   │   └── constitution.md     # Project governance (7 principles)
│   └── templates/              # Feature spec/plan/tasks templates
├── src/scout/
│   ├── tools/                  # MCP-exposed tools (chat, planner, analyse, etc.)
│   ├── providers/              # AI provider abstractions
│   │   ├── base.py             # BaseAIProvider interface
│   │   ├── gemini.py           # Google Gemini
│   │   ├── openai.py           # OpenAI (GPT-4o, o3-mini)
│   │   ├── anthropic.py        # Anthropic Claude
│   │   ├── openrouter.py       # OpenRouter aggregator
│   │   ├── grok.py             # X.AI Grok
│   │   └── factory.py          # Provider factory
│   ├── core/
│   │   ├── orchestrator.py     # Tool routing and execution
│   │   ├── team_selector.py    # AI team selection logic
│   │   └── state_manager.py    # Redis state management
│   ├── config/
│   │   ├── loader.py           # YAML configuration loader
│   │   └── models.py           # Pydantic configuration schemas
│   └── utils/
│       ├── cache.py            # Redis caching
│       ├── rate_limiter.py     # Request rate limiting
│       ├── retry.py            # Retry logic with backoff
│       └── logger.py           # Structured logging setup
├── config/
│   └── scout.yaml              # Main configuration (providers, teams, mappings)
├── tests/
│   ├── unit/                   # Unit tests (mocked dependencies)
│   └── integration/            # Integration tests (mocked providers)
├── docs/
│   ├── api/                    # Auto-generated API docs
│   ├── architecture.md         # System architecture
│   └── quickstart.md           # This file
├── pyproject.toml              # Python project metadata & dependencies
├── .env.example                # Environment variables template
└── README.md                   # This file

🏗️ 建筑学

SCOUT遵循一个 契约优先， 模块化架构 如……中所定义宪法。

┌─────────────────────────────────────────────────────────────┐
│                  Claude Desktop/Web (MCP Client)             │
└─────────────────────┬───────────────────────────────────────┘
                      │ MCP Protocol (STDIO/HTTP+SSE)
┌─────────────────────▼───────────────────────────────────────┐
│                  SCOUT MCP Server                            │
│  ┌────────────────────────────────────────────────────────┐ │
│  │         Tool Router & Orchestrator                      │ │
│  │         (FastMCP + Tool Registry)                       │ │
│  └───┬──────────────────────────────────────────────┬─────┘ │
│      │                                               │       │
│  ┌───▼────────┐  ┌──────────────┐  ┌───────────────▼────┐ │
│  │   Tools    │  │   AI Team    │  │   State Manager    │ │
│  │  Registry  │  │   Selector   │  │   (Redis)          │ │
│  └───┬────────┘  └──────┬───────┘  └───────────────┬────┘ │
│      │                  │                           │       │
│  ┌───▼──────────────────▼───────────────────────────▼────┐ │
│  │            Provider Abstraction Layer                  │ │
│  │   (Unified Interface: Gemini, OpenAI, Claude, etc.)   │ │
│  └───┬──────┬──────┬─────────┬──────────┬───────────────┘ │
└──────┼──────┼──────┼─────────┼──────────┼─────────────────┘
       │      │      │         │          │
   ┌───▼──┐ ┌▼───┐ ┌▼──────┐ ┌▼────────┐ ┌▼────┐
   │Gemini│ │OAI │ │Claude │ │OpenRoute│ │Grok │
   └──────┘ └────┘ └───────┘ └─────────┘ └─────┘

核心原则（摘自宪法）

合同优先开发 - 每个工具均通过MCP架构定义
模块化架构 - 严格的职责分离
强制性检测 - 覆盖率≥80%（不可商量）
自动生成的文档 - 来自模式的文档
强大的错误处理 - 结构化异常处理 + 恢复
结构化日志记录 - 请求关联性 + 可观测性
提供者抽象 - 统一的多模型接口

🛠️ 配置

SCOUT 使用一种类型安全的YAML配置系统，支持环境变量替换和自动验证。

快速配置

创建 config/scout.yaml 来自示例：

cp config/scout.yaml.example config/scout.yaml

最小配置（单一提供商）：

providers:
  gemini:
    api_key: ${GEMINI_API_KEY}
    models:
      flash:
        id: "gemini-2.0-flash-exp"
        max_tokens: 8192
        temperature: 0.7

teams:
  general:
    description: "General purpose team"
    primary:
      provider: "gemini"
      model: "flash"

tool_team_mapping:
  default: "general"

system:
  default_team: "general"
  request_timeout_seconds: 90
  max_retries: 3
  cache_ttl_seconds: 7200

integrations:
  notion_api_key: null
  tavily_api_key: null

多供应商验证：

providers:
  gemini:
    api_key: ${GEMINI_API_KEY}
    models:
      flash: { id: "gemini-2.0-flash-exp", max_tokens: 8192 }

  openai:
    api_key: ${OPENAI_API_KEY}
    models:
      gpt4o: { id: "gpt-4o", max_tokens: 16384 }

teams:
  architect:
    description: "Architecture team with validation"
    primary:
      provider: "gemini"
      model: "flash"
    validators:
      - provider: "openai"
        model: "gpt4o"
        trigger: "always"  # Validate all responses

tool_team_mapping:
  system_design: "architect"

环境变量替换

必需的： ${VAR} - 必须设置变量
可选： ${VAR:-default} - 未设置时使用默认值

system:
  request_timeout_seconds: ${REQUEST_TIMEOUT:-90}  # Default: 90
  cache_ttl_seconds: ${CACHE_TTL:-7200}            # Default: 7200

配置特性

✅ 类型安全 - Pydantic 验证在启动时捕获错误 ✅（勾选标记，表示正确、确认或完成） 不可变的 - 冻结模型防止运行时修改 ✅ 安全日志/错误中自动对API密钥进行遮蔽处理 ✅ 快 - 加载时间约5毫秒（在50个提供商、100个团队中测试） ✅ 交叉引用验证 - Teams引用现有的提供者/模型 ✅ 环境感知的 - 不同环境下的不同配置

文档

📖 快速入门: specs/001-config-system/quickstart.md
📋 数据模型: specs/001-config-system/data-model.md
📝 示例： config/scout.yaml.example - 5家供应商，3个团队
🔧 JSON Schema（JSON架构）: specs/001-config-system/contracts/config-schema.json

添加新的提供商（<5分钟）

添加到 config/scout.yaml：

providers:
  new_provider:
    api_key: "${NEW_PROVIDER_API_KEY}"
    models:
      model_name:
        id: "model-id"
        max_tokens: 8192

设置环境变量：

export NEW_PROVIDER_API_KEY=your-key-here

团队中的参考：

teams:
  new_team:
    primary:
      provider: "new_provider"
      model: "model_name"

就是这样！交叉引用验证确保所有设置都正确无误。

🧪 开发工作流程

SCOUT遵循 SpecKit（注：这是一个专有名词或特定软件/工具的名称，直接翻译为“光谱工具包”可能不够准确，具体翻译需根据上下文确定，此处仅为一种可能的翻译）开发过程：

1. 指定功能

/speckit.specify <feature-description>

创建包含以下内容的详细规格说明：

用户场景（按优先级排序）
需求（功能需求+非功能需求）
MCP合同（JSON模式）
验收标准

2. 消除歧义

/speckit.clarify

识别出未明确说明的领域，并提出有针对性的问题。

3. 制定实施计划

/speckit.plan

制定分阶段实施计划，包括：

技术设计
依赖分析
风险缓解
测试策略

4. 生成任务

/speckit.tasks

生成按用户故事组织的、具有依赖关系的检查清单。

5. 实施

/speckit.implement

遵循测试驱动开发（Test-Driven Development，TDD）原则执行实施。

6. 分析一致性

/speckit.analyze

对规范、计划、任务和代码进行交叉验证，确保一致性。

✅ 测试

运行所有测试

# Run full test suite
pytest

# Run with coverage report
pytest --cov=src/scout --cov-report=term-missing

# Run only unit tests
pytest tests/unit -m unit

# Run only integration tests
pytest tests/integration -m integration

# Run performance benchmarks
pytest -m benchmark

编写测试（必做）

每个工具都必须具备：

# tests/unit/test_chat.py
import pytest
from scout.tools.chat import chat_handler

@pytest.mark.asyncio
async def test_chat_valid_input(mock_dependencies):
    """Test nominal case with valid input."""
    result = await chat_handler(
        message="Hello",
        **mock_dependencies
    )
    assert "response" in result
    assert result["metadata"]["cost_usd"] > 0

@pytest.mark.asyncio
async def test_chat_invalid_input():
    """Test schema validation with invalid input."""
    with pytest.raises(ValidationError):
        await chat_handler(message="")  # Empty message

@pytest.mark.asyncio
async def test_chat_provider_failure(mock_failing_provider):
    """Test error handling when provider fails."""
    with pytest.raises(ProviderError):
        await chat_handler(
            message="Test",
            provider_factory=mock_failing_provider
        )

📊 监控与可观测性

结构化日志记录

所有日志均使用带有请求关联性的JSON格式：

{
  "event": "tool_execution_started",
  "request_id": "uuid-1234-5678",
  "tool_name": "analyse",
  "team": "architect",
  "timestamp": "2025-10-18T10:30:00Z"
}

指标（OpenTelemetry）

scout.tool.duration_ms - P50/P95/P99 延迟
scout.tool.errors - 按类型统计的错误数量
scout.tool.cost_usd - 每次工具执行的成本
scout.provider.requests - 每个提供商的请求数量

成本追踪

实时追踪成本：

# Automatic tracking per tool execution
logger.info(
    "tool_execution_completed",
    cost_usd=0.023,
    tokens={"input": 1200, "output": 800}
)

当预算达到每天50美元的阈值时，将触发预算提醒（可配置）。

🔒 安全

密钥管理（或“机密管理”）

永远不要 提交（或“确定”、“执行”） .env （在 .gitignore）
永远使用环境变量来存储API密钥
旋转 API密钥，每90天一次
使用用于检测秘密的pre-commit钩子：

# Install pre-commit hook
pip install pre-commit
pre-commit install

# Manually scan for secrets
detect-secrets scan

输入验证

所有输入均通过 Pydantic 进行验证：

class AnalyseInput(BaseModel):
    target: constr(max_length=100000)
    analysis_type: Literal["code_quality", "architecture", "performance"]

    @validator('target')
    def sanitize_target(cls, v):
        return v.strip()

速率限制

自动速率限制防止滥用：

每个用户每小时100次请求
全球每日1000次请求
特定提供者限制（Gemini：每分钟60次请求等）

📚 文档

宪法：指定/memory/constitution.md（文件路径或指令，根据上下文可理解为“在内存/配置文件中指定constitution.md文件”或类似意思）
PRD 可以翻译为“民主革命党”（注：这里的翻译是基于政治术语的常见翻译，但具体翻译可能因上下文和语境的不同而有所变化）。然而，在更广泛的语境中，PRD 也可能是一个缩写或代号，代表不同的组织或概念，因此需要根据具体情况进行判断。在没有具体上下文的情况下，最通用的翻译是“民主革命党”: PRD.md 翻译为中文是：“产品需求文档（.md 格式）”。其中，“PRD”代表“Product Requirements Document”，即“产品需求文档”，而“.md”是Markdown文件格式的后缀
建筑: docs/architecture.md （即将推出）
API 参考文档： docs/api/ （自动生成）

🤝 贡献

SCOUT遵循严格的治理原则，通过宪法.

拉取请求检查清单

[ ] 所有测试通过（pytest）
[ ] 覆盖率 ≥ 80%（pytest --cov)
[ ] 没有秘密泄露（detect-secrets scan)
[ ] 代码已格式化 (black src/ tests/）
[ ] 代码清理（Linting clean）ruff check src/ tests/)
[ ] 类型检查通过 (mypy src/)
[ ] 文档已更新
[ ] MCP模式已验证（无破坏性变更）
[ ] 公报中提及的宪法原则

在提交之前

# Format code
black src/ tests/

# Lint
ruff check --fix src/ tests/

# Type check
mypy src/

# Test
pytest --cov=src/scout --cov-fail-under=80

# Security scan
bandit -r src/
detect-secrets scan

📈 路线图

第一阶段：基础设施核心（第1-2周）

[x] 项目结构
[x] 宪法
[x] 配置系统 ✅（116个测试，覆盖率94.86%）
[ ] 提供者抽象层
[ ] 球队选择器
[ ] 工具注册表

第二阶段：首个工具“聊天”（第3-4周）

[ ] 聊天工具实现
[ ] 状态管理器（Redis）
[ ] MCP服务器入口点
[ ] 与Claude桌面版的集成

第三阶段：必备工具（第5-6周）

[ ] apilookup（API查询）
[ ] 计划者/规划者
[ ] 分析
[ ] 深思熟虑

第四阶段：高级工具（第7-8周）

[ ] 共识
[ ] 挑战
[ ] secaudit（注：此词可能为特定领域或上下文中的术语，直接翻译为“安全审计”可能不够准确，需根据具体语境调整）
[ ] 重构

🆘 故障排除

Redis 连接失败

错误： redis.exceptions.ConnectionError

解决方案：

# Check Redis is running
docker ps | grep redis

# Test connection
redis-cli ping

# Verify REDIS_URL in .env
echo $REDIS_URL

导入错误

错误: ModuleNotFoundError: No module named 'scout'

解决方案:

# Install in editable mode
pip install -e .

API密钥错误

错误： ConfigurationError: Missing API key