athena-protocol

Athena Protocol MCP 服务：Context Orchestration Protocol 的前身

一个智能 MCP 服务，可作为编码 Agent 的 AI 技术负责人，在代码变更前提供专家级验证、影响分析和战略指导。如同资深工程师审查你的方案，Athena Protocol 能帮助 AI Agent 尽早发现关键问题，根据实际代码库验证假设，并优化问题解决策略。由此带来更高质量的代码、更少的回归问题，以及更周全的架构决策。

**核心功能：**借助 analysisTargets 精确分析文件——通过精准定位代码分析，将令牌用量减少 70-85%，性能提升 3-4 倍。详情请参阅增强型文件分析。

Context Orchestration Protocol：AI 辅助开发的未来

设想大模型使用精细且精准的上下文开展工作，从而消除猜测、将错误减少 80%，并以资深架构师般的精度交付代码——彻底改变 AI Agent 理解和增强复杂代码库的方式。

目录

• 安全性
• 背景
• 安装
• 用法
• API
• 参与贡献
• 许可证

安全性

此服务会处理多个大模型提供商的 API 密钥。请确保妥善保护 .env 文件，绝不要将其提交到版本控制系统。服务会在启动时验证所有 API 密钥，并针对配置问题提供详细的错误信息。

背景

Athena Protocol MCP 服务为 AI 编码 Agent 提供系统化思维验证。它支持 14 个大模型提供商，并提供多种验证工具，包括思维验证、影响分析、假设检查、依赖关系映射和思维优化。

主要功能：

• 智能客户端模式，支持精准定位代码分析（令牌用量减少 70-85%）
• 由环境变量驱动的配置，不使用硬编码默认值
• 支持多个大模型提供商（14 个），并自动回退
• 增强型文件读取，支持多种模式（全文、开头、结尾、范围）
• 并发文件操作，性能提升 3-4 倍
• 基于会话的验证历史记录和记忆管理
• 全面的配置验证与健康监控
• 双 Agent 架构，实现高效的验证工作流

安装

此模块需要具备 Node.js 和 npm 相关知识。

npm install
npm run build

先决条件

• Node.js >= 18
• npm 或 yarn

配置

Athena Protocol 完全由环境变量驱动配置，不包含硬编码的提供商值或默认值。请通过 .env 文件配置所有内容：

1. 复制示例配置：

   cp .env.example .env

2. 编辑 .env 并配置提供商：

   • 设置 DEFAULT_LLM_PROVIDER（例如 openai、anthropic、google）
   • 添加所选提供商的 API 密钥
   • 配置模型和参数（可选）

3. 验证并测试：

   npm install
   npm run build
   npm run validate-config  # Validates your .env configuration
   npm test
   

请参阅 .env.example，了解完整的配置选项和全部 14 个受支持的提供商。

关键配置要求

• PROVIDER_SELECTION_PRIORITY 为必填项——按优先级顺序列出提供商
• 不存在硬编码的回退配置——所有配置都必须在 .env 中明确指定
• 失败时快速终止验证——配置无效会导致启动立即失败
• 必须提供完整的提供商配置——每个提供商都需要 API 密钥、模型和参数

支持的提供商

Athena Protocol 支持 14 家大模型提供商。虽然常用 OpenAI，但你可以配置以下任意提供商：

主要云服务提供商：

• OpenAI - GPT-5（支持思考）、GPT-4o、GPT-4-turbo
• Anthropic - Claude Opus 4.1、Claude Sonnet 4.5、Claude Haiku 4.5
• Google - Gemini 2.5（Flash/Pro/Ultra）
• Azure OpenAI - 企业级 GPT 模型
• AWS Bedrock - Claude、Llama 等
• Google Vertex AI - 具备企业级功能的 Gemini

专业化提供商：

• OpenRouter - 可使用 400 多种模型
• Groq - 超快速推理
• Mistral AI - 开源模型
• Perplexity - 搜索增强型模型
• XAI - Grok 模型
• Qwen - 阿里巴巴的高性能大模型
• ZAI - GLM 模型

本地/可自托管：

• Ollama - 在本地运行模型

快速切换示例：

# Edit .env file
ANTHROPIC_API_KEY=sk-ant-your-key-here
DEFAULT_LLM_PROVIDER=anthropic

# Restart server
npm run build && npm start

切换提供商

完整设置说明请参阅提供商详细指南。

使用方法

MCP 客户端配置

详细且经过测试的 MCP 客户端配置，请参阅 CLIENT_MCP_CONFIGURATION_EXAMPLES.md

本地安装（使用 .env 文件）

使用 .env 文件的本地安装仍可完整正常运行，无任何变化。只需克隆仓库并运行：

npm install
npm run build

然后配置 MCP 客户端，使其指向本地安装：

{
  "mcpServers": {
    "athena-protocol": {
      "command": "node",
      "args": ["/absolute/path/to/athena-protocol/dist/index.js"],
      "type": "stdio",
      "timeout": 300
    }
  }
}

NPM 安装（使用 MCP 环境变量——推荐）

使用 npm/npx 时，请为 MCP 客户端配置环境变量。只有 CLIENT_MCP_CONFIGURATION_EXAMPLES.md 中的配置经过测试并保证可用。

GPT-5 示例：

{
  "mcpServers": {
    "athena-protocol": {
      "command": "npx",
      "args": ["@n0zer0d4y/athena-protocol"],
      "env": {
        "DEFAULT_LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "OPENAI_MODEL_DEFAULT": "gpt-5",
        "OPENAI_MAX_COMPLETION_TOKENS_DEFAULT": "8192",
        "OPENAI_VERBOSITY_DEFAULT": "medium",
        "OPENAI_REASONING_EFFORT_DEFAULT": "high",
        "LLM_TEMPERATURE_DEFAULT": "0.7",
        "LLM_MAX_TOKENS_DEFAULT": "2000",
        "LLM_TIMEOUT_DEFAULT": "30000"
      },
      "type": "stdio",
      "timeout": 300
    }
  }
}

完整且可用的配置请参阅 CLIENT_MCP_CONFIGURATION_EXAMPLES.md。

配置说明：

• NPM 安装：使用 npx @n0zer0d4y/athena-protocol 并设置 env 字段，可轻松完成配置
• 本地安装：使用本地 .env 文件运行仍可完整正常运行，无任何变化
• 环境变量优先级：MCP env 变量的优先级高于 .env 文件中的变量
• GPT-5 支持：包含 GPT-5 模型的专用参数
• 超时配置：推理模型（如 GPT-5）的默认超时时间为 300 秒（5 分钟）。对于响应更快的大模型（GPT-4、Claude、Gemini），可将其缩短至 60–120 秒
• GPT-5 参数说明：参数 LLM_TEMPERATURE_DEFAULT、LLM_MAX_TOKENS_DEFAULT 和 LLM_TIMEOUT_DEFAULT 目前是 GPT-5 模型所必需的，但模型本身不会使用这些参数。这是暂时的限制，将在未来的重构中解决
• 安全性：切勿将 API 密钥提交到版本控制中——请改用 MCP 客户端环境变量

未来的重构计划

GPT-5 参数优化

当前问题：GPT-5 模型目前需要标准 LLM 参数（LLM_TEMPERATURE_DEFAULT、LLM_MAX_TOKENS_DEFAULT、LLM_TIMEOUT_DEFAULT），尽管模型并未使用这些参数。

计划的解决方案：

1. 修改 getTemperature() 函数，对于 GPT-5 及更高版本的模型返回 undefined，而不是硬编码的默认值
2. 更新 AI 提供商接口，以处理 undefined 温度值
3. 实现条件参数验证，对于 GPT-5 及更高版本的模型跳过标准参数
4. 更新 OpenAI 提供商，在与 GPT-5 API 通信时省略未使用的参数

优点：

• 为 GPT-5 用户提供更简洁的配置
• 更准确地体现模型能力
• 更好地遵循 OpenAI 的 GPT-5 API 规范

时间线：目标是在 v0.3.0 中实现

服务模式

MCP 服务模式（用于生产环境）

npm start                    # Start MCP server for client integration (requires .env or MCP env)
npm run dev                  # Development mode with auto-restart
npx @n0zer0d4y/athena-protocol  # Run published version via npx (requires MCP env)

独立模式（用于测试）

npm run start:standalone     # Test server without MCP client
npm run dev:standalone       # Development standalone mode

配置工具

# Validate your complete configuration
npm run validate-config

# Or use the comprehensive MCP validation tool
node dist/index.js
# Then call: validate_configuration_comprehensive

主要功能

多提供商 LLM 支持

Athena Protocol 支持 14 个提供商，包括：

• 云提供商：OpenAI、Anthropic、Google、Azure OpenAI、AWS Bedrock、Vertex AI
• 专业提供商：OpenRouter（400+ 个模型）、Groq、Mistral、Perplexity、XAI、Qwen
• 本地／自托管：Ollama、ZAI

除用于本地模型的 Ollama 外，所有提供商都需要 API 密钥。设置方法请参阅配置部分。

智能思考验证

• 聚焦验证：通过精简的沟通验证推理的关键方面
• 双 Agent 架构：主 Agent 和验证 Agent 协同工作
• 置信度评分：提供明确的置信度级别以指导决策
• 防止循环：每项任务最多进行 3 轮交互，以避免分析瘫痪

系统化方法

• 仅提供必要信息：分享有效验证所需的信息
• 可执行的输出：提供清晰、具体且可立即应用的建议
• 渐进式优化：从宽泛的范围开始，仅在需要时深入细化
• 会话管理：在多次尝试中维持持久的验证会话

双模式运行

• MCP 服务模式：与 MCP 客户端（Claude Desktop、Cline 等）全面集成
• 独立模式：无需 MCP 客户端即可独立测试和验证

API

Athena Protocol MCP 服务提供以下工具，用于思考验证和分析：

thinking_validation

使用重点且必要的信息验证主 Agent 的思考过程。

必需参数：

• thinking（字符串）：对方案和推理过程的简要说明
• proposedChange（对象）：拟议更改的详细信息
  • description（字符串，必需）：将要进行的更改
  • code（字符串，可选）：实际代码更改
  • files（数组，可选）：受影响的文件
• context（对象）：验证所需的上下文
  • problem（字符串，必需）：问题简述
  • techStack（字符串，必需）：技术栈（react|node|python 等）
  • constraints（数组，可选）：关键约束
• urgency（字符串）：紧急程度（low、medium 或 high）
• projectContext（对象）：用于文件分析的项目上下文
  • projectRoot（字符串，必需）：项目根目录的绝对路径
  • workingDirectory（字符串，可选）：当前工作目录
  • analysisTargets（数组，必需）：指定需要定向读取的代码段
    • file（字符串，必需）：文件路径（相对路径或绝对路径）
    • mode（字符串，可选）：读取模式——full、head、tail 或 range
    • lines（数字，可选）：行数（适用于 head/tail 模式）
    • startLine（数字，可选）：起始行号（适用于 range 模式，从 1 开始计数）
    • endLine（数字，可选）：结束行号（适用于 range 模式，从 1 开始计数）
    • priority（字符串，可选）：分析优先级——critical、important 或 supplementary
• projectBackground（字符串）：项目简介，用于避免产生幻觉

可选参数：

• sessionId（字符串）：用于上下文持久化的会话 ID
• provider（字符串）：指定 LLM 提供方（openai、anthropic、google 等）

输出：

返回验证结果，包括置信度评分、关键问题、建议和测试用例。

impact_analysis

快速识别拟议更改的主要影响。

必需参数：

• change（对象）：更改的详细信息
  • description（字符串，必需）：要更改的内容
  • code（字符串，可选）：代码更改
  • files（数组，可选）：受影响的文件
• projectContext（对象）：项目上下文（结构与 thinking_validation 相同）
  • projectRoot（字符串，必需）
  • analysisTargets（数组，必需）：需要分析的文件及其读取模式
  • workingDirectory（可选）
• projectBackground（字符串）：项目简介

可选参数：

• systemContext（对象）：系统架构上下文
  • architecture（字符串）：架构简介
  • keyDependencies（数组）：系统的关键依赖项
• sessionId（字符串）：用于上下文持久化的会话 ID
• provider（字符串）：指定 LLM 提供方

输出：

返回总体风险评估、受影响的领域、级联风险以及可快速执行的测试。

assumption_checker

快速验证关键假设，避免过度分析。

必需参数：

• assumptions（数组）：需要验证的假设字符串列表
• context（对象）：验证上下文
  • component（字符串，必需）：组件名称
  • environment（字符串，必需）：环境（production、development、staging、testing）
• projectContext（对象）：项目上下文（结构与 thinking_validation 相同）
  • projectRoot（字符串，必需）
  • analysisTargets（数组，必需）：需要分析的文件及其读取模式
• projectBackground（字符串）：项目简介

可选参数：

• sessionId（字符串）：用于上下文持久化的会话 ID
• provider（字符串）：指定 LLM 提供方

输出：

返回有效假设、存在风险的假设及其缓解措施，以及快速验证步骤。

dependency_mapper

高效识别关键依赖项。

必需参数：

• change（对象）：变更详情
  • description（字符串，必需）：简要变更说明
  • files（数组，可选）：正在修改的文件
  • components（数组，可选）：正在变更的组件
• projectContext（对象）：项目上下文（结构与 thinking_validation 相同）
  • projectRoot（字符串，必需）
  • analysisTargets（数组，必需）：要分析的文件及其读取模式
• projectBackground（字符串）：简要项目说明

可选参数：

• sessionId（字符串）：用于上下文持久化的会话 ID
• provider（字符串）：覆盖 LLM 提供方

输出：

返回关键和次要依赖项，以及影响分析和测试重点。

thinking_optimizer

根据问题类型优化思考方式。

必需参数：

• problemType（字符串）：问题类型（bug_fix、feature_impl 或 refactor）
• complexity（字符串）：复杂程度（simple、moderate 或 complex）
• timeConstraint（字符串）：时间限制（tight、moderate 或 flexible）
• currentApproach（字符串）：当前思路的简要说明
• projectContext（对象）：项目上下文（结构与 thinking_validation 相同）
  • projectRoot（字符串，必需）
  • analysisTargets（数组，必需）：要分析的文件及其读取模式
• projectBackground（字符串）：简要项目说明

可选参数：

• sessionId（字符串）：用于上下文持久化的会话 ID
• provider（字符串）：覆盖 LLM 提供方

输出：

返回全面的优化策略，包括：

• optimizedStrategy：建议的方法、要使用的工具、时间分配细目、成功概率和重点领域
• tacticalPlan：详细的实施指导，包括问题分类、grep 搜索策略、关键发现假设、决策点、分步实施计划、测试策略、风险缓解、进度检查点以及价值／工作量评估
• metadata：所用提供方和文件分析指标

athena_health_check

检查 Athena Protocol 服务的运行状况和配置。

**参数：**无

输出：

返回默认提供方、具有有效 API 密钥的活跃提供方列表、配置状态和系统运行状况信息。

session_management

管理思考验证会话，以持久化上下文并跟踪进度。

必需参数：

• action（字符串）：会话操作——create、get、update、list 或 delete

可选参数：

• sessionId（字符串）：会话 ID（get、update、delete 操作必需）
• tags（数组）：用于对会话分类的标签
• title（字符串）：会话标题／描述（用于 create／update）

输出：

根据操作返回会话信息或会话列表。

---

增强的文件分析（NEW）

所有工具现均支持通过 analysisTargets 精准定位的智能客户端模式：

优势：

• 减少 70-85% 的 token 消耗，只读取相关代码段
• 速度提升 3-4×，支持并发读取文件
• 基于模式读取：full（全文）、head（前 N 行）、tail（后 N 行）、range（第 X-Y 行）
• 优先级处理：关键 → 重要 → 补充

示例：

{
  "projectContext": {
    "projectRoot": "/path/to/project",
    "analysisTargets": [
      {
        "file": "src/auth.ts",
        "mode": "range",
        "startLine": 45,
        "endLine": 78,
        "priority": "critical"
      },
      {
        "file": "src/config.ts",
        "mode": "head",
        "lines": 20,
        "priority": "supplementary"
      }
    ]
  }
}

**注意：**所有工具在分析文件时都需要 analysisTargets。请至少提供一个文件，并指定合适的读取模式（full、head、tail 或 range）。

重要通知

记忆系统状态

持久化记忆系统（thinking-memory.json）目前正在审查中，等待重构。虽然可以正常运行，但它：

• 会在项目根目录中创建记忆文件
• 会在不同会话间保留验证历史记录
• 在测试／开发期间可能需要手动清理

计划中的改进：

• 将存储位置移至被 .gitignore 忽略的目录（例如 athena-memory/）
• 添加自动清理机制
• 增强会话管理
• 改进文件路径处理

在重构完成前，请将此功能视为实验性功能，用于生产环境时请谨慎。

配置方法

Athena Protocol 支持两种配置方法，并有明确的优先级顺序：

1. MCP 客户端环境变量（优先级最高——推荐用于 npm 安装）
2. 本地 .env 文件（回退选项——用于本地开发）
3. 系统环境变量（优先级最低）

对于通过 npm 发布的用法，请直接在 MCP 客户端的 env 字段中配置所有设置。对于本地开发，请继续使用 .env 文件。

提供商测试状态

虽然 Athena Protocol 支持 14 个大模型提供商，但只有以下提供商经过了全面测试：

• OpenAI
• Google
• ZAI
• Mistral
• OpenRouter
• Groq

其他提供商（Anthropic、Qwen、XAI、Perplexity、Ollama、Azure、Bedrock、Vertex）已完成配置，应该可以正常使用，但尚未经过广泛测试。如果您在使用任何提供商时遇到问题，请提交 issue，并附上：

• 提供商名称和模型
• 错误消息或异常行为
• 您的 MCP 配置或 .env 配置（请遮盖 API 密钥）

贡献

此服务专为大模型编码 Agent 设计。贡献内容应侧重于：

• 添加新的大模型提供商
• 提高验证效果
• 增强上下文感知能力
• 扩大验证覆盖范围
• 优化记忆管理
• 添加新的验证策略

许可证

MIT 许可证——详情请参阅 LICENSE 文件。