人工智能顾问

Name: 人工智能顾问
Author: blueman82

作者：blueman82134 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

AI 咨询

一个真正的审议共识型MCP服务器，其中AI模型在多轮次中进行辩论并完善各自立场。

🎬 观看演示

云模型辩论 (Claude Sonnet, GPT-5.1 Codex, Gemini):

mcp__ai-counsel__deliberate({
  question: "我们应该使用REST还是GraphQL作为我们的新API？",
  participants: [
    {cli: "claude", model: "claude-sonnet-4-5-20250929"},
    {cli: "codex", model: "gpt-5.1-codex"},
    {cli: "gemini", model: "gemini-2.5-pro"}
  ],
  mode: "conference",
  rounds: 3
})

结果: 达成混合架构共识（置信度0.82-0.95）• 查看完整记录

本地模型辩论 (100%私有，零API成本):

mcp__ai-counsel__deliberate({
  question: "我们应该优先考虑代码质量还是交付速度？",
  participants: [
    {cli: "ollama", model: "llama3.1:8b"},
    {cli: "ollama", model: "mistral:7b"},
    {cli: "ollama", model: "deepseek-r1:8b"}
  ],
  mode: "conference",
  rounds: 2
})

结果: 第一轮辩论后有2个模型改变立场 • 查看完整记录

这有什么不同

AI咨询实现了真正的审议共识，其中模型可以看到彼此的回答并在多轮次中完善各自的立场：

模型参与实际辩论（看到并回应对方）
多轮次收敛，带有投票和置信水平
完整审计跟踪，附带AI生成的总结
当达成共识时自动停止（节省API成本）

特性

🎯 两种模式：快速（单轮次）或会议（多轮次辩论）
🤖 混合适配器：CLI工具（claude, codex, droid, gemini）+ HTTP服务（ollama, lmstudio, openrouter）
⚡ 自动收敛：当意见稳定时停止（节省API成本）
🗳️ 结构化投票：模型以置信水平和理由进行投票
🧮 语义分组：相似投票选项自动合并（相似度0.70+）
🛠️ 模型控制停止：模型决定何时停止审议
🔬 基于证据的审议：模型可以读取文件、搜索代码、列出文件和运行命令来使决策基于现实
💰 本地模型支持：使用Ollama、LM Studio、llamacpp实现零API成本
🔐 数据隐私：通过自托管模型保持所有数据本地化
🧠 上下文注入：自动查找类似过去的辩论并注入上下文以加快收敛
🔍 语义搜索：使用query_decisions工具查询过去决策（找到矛盾、追踪演变、分析模式）
🛡️ 容错：个别适配器故障不会中断审议
📝 完整记录：带有AI生成总结的Markdown导出

快速开始

几分钟内启动并运行：

安装 – 按照安装中的命令克隆仓库，创建虚拟环境，并安装依赖项。
配置 – 使用.mcp.json示例设置您的MCP客户端，参见[在Claude Code中配置](#在Claude Code中配置)。
运行 – 使用python server.py启动服务器，并使用用法中的示例触发deliberate工具。

尝试一次审议：

// 混合本地和云端模型，本地模型零API成本
mcp__ai-counsel__deliberate({
  question: "我们应该为新功能添加单元测试吗？",
  participants: [
    {cli: "ollama", model: "llama2"},           // 本地
    {cli: "lmstudio", model: "mistral"},        // 本地
    {cli: "claude", model: "sonnet"}            // 云端
  ],
  mode: "quick"
})

⚠️ 模型大小对审议很重要

推荐：使用7B-8B+参数模型（如Llama-3-8B、Mistral-7B、Qwen-2.5-7B）以获得可靠的结构化输出和投票格式。

不推荐：小于3B参数的模型（例如Llama-3.2-1B）可能难以处理复杂指令并产生无效投票。

可用模型：claude（sonnet, opus, haiku），codex（gpt-5.1-codex），droid，gemini，HTTP适配器（ollama, lmstudio, openrouter）。详情参见CLI模型参考。

关于模型选择和选择工作流，请参阅模型注册表与选择器。

安装

先决条件

Python 3.11+：python3 --version
至少一种AI工具（可选 - HTTP适配器无需CLI即可工作）：
- Claude CLI：https://docs.claude.com/en/docs/claude-code/setup
- Codex CLI：https://github.com/openai/codex
- Droid CLI：https://github.com/Factory-AI/factory
- Gemini CLI：https://github.com/google-gemini/gemini-cli

设置

git clone https://github.com/blueman82/ai-counsel.git
cd ai-counsel
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux; Windows: .venv\Scripts\activate
pip install -r requirements.txt
python3 -m pytest tests/unit -v  # 验证安装

✅ 准备就绪！服务器包含核心依赖项以及可选的收敛后端（scikit-learn, sentence-transformers）以达到最佳准确性。

配置

编辑config.yaml以配置适配器和设置：

adapters:
  claude:
    type: cli
    command: "claude"
    args: ["-p", "--model", "{model}", "--settings", "{\"disableAllHooks\": true}", "{prompt}"]
    timeout: 300

  ollama:
    type: http
    base_url: "http://localhost:11434"
    timeout: 120
    max_retries: 3

defaults:
  mode: "quick"
  rounds: 2
  max_rounds: 5

注意：使用type: cli用于CLI工具，type: http用于HTTP适配器（Ollama, LM Studio, OpenRouter）。

模型注册表配置

控制哪些模型可供选择。每个模型都可以启用或禁用而不删除其定义：

model_registry:
  claude:
    - id: "claude-sonnet-4-5-20250929"
      label: "Claude Sonnet 4.5"
      tier: "balanced"
      default: true
      enabled: true  # 模型处于活动状态且可用
    - id: "claude-opus-4-20250514"
      label: "Claude Opus  4"
      tier: "premium"
      enabled: false  # 暂时禁用（成本控制、测试等）

启用字段行为：

enabled: true（默认）- 模型出现在list_models中并且可用于审议
enabled: false - 模型从选择中隐藏但定义保留以便轻松重新启用
禁用的模型即使在deliberate调用中明确指定也无法使用
默认模型选择会自动跳过禁用的模型

使用案例：

成本控制：暂时禁用昂贵的模型而不丢失配置
测试：在集成测试期间启用/禁用特定模型
分阶段推出：配置新模型为禁用状态，准备就绪时启用
性能调整：在快速迭代期间禁用慢速模型
合规性：在等待审批期间临时限制模型

核心功能深入探讨

收敛检测与自动停止

当意见稳定时，模型会自动收敛并停止审议，从而节省时间和API成本。状态：已收敛（≥85%相似度）、正在精炼（40-85%）、分歧（<40%）或僵局（稳定分歧）。投票优先：当模型进行投票时，收敛反映投票结果。

→ 完整指南 - 阈值、后端、配置

结构化投票

模型以置信水平（0.0-1.0）、理由和继续审议信号进行投票。投票确定共识：一致（3-0）、多数（2-1）或平局。相似选项在0.70+相似度阈值下自动合并。

→ 完整指南 - 投票结构、示例、集成

HTTP适配器与本地模型

本地运行Ollama、LM Studio或OpenRouter以实现零API成本和完全数据隐私。与云端模型（Claude、GPT-4）混合使用。

→ 设置指南 - Ollama、LM Studio、OpenRouter、成本分析

扩展AI咨询

添加新的CLI工具或HTTP适配器以适应您的基础设施。简单的3-5步过程，附带示例和测试模式。

→ 开发者指南 - 分步教程、真实世界示例

基于证据的审议

通过查询实际代码、文件和数据来使设计决策基于现实：

// MCP客户端示例（例如Claude Code）
mcp__ai_counsel__deliberate({
  question: "我们应该从SQLite迁移到PostgreSQL吗？",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-4"}
  ],
  rounds: 3,
  working_directory: process.cwd()  // 必需 - 使工具能够访问您的文件
})

在审议过程中，模型可以：

📄 读取文件：TOOL_REQUEST: {"name": "read_file", "arguments": {"path": "config.yaml"}}
🔍 搜索代码：TOOL_REQUEST: {"name": "search_code", "arguments": {"pattern": "database.*connect"}}
📋 列出文件：TOOL_REQUEST: {"name": "list_files", "arguments": {"pattern": "*.sql"}}
⚙️ 运行命令：TOOL_REQUEST: {"name": "run_command", "arguments": {"command": "git", "args": ["log", "--oneline"]}}

示例流程：

模型A基于假设提出PostgreSQL
模型B请求：read_file检查当前配置
工具返回：database: sqlite, max_connections: 10
模型B搜索：search_code数据库查询
工具返回：50+具有复杂JOIN的查询
模型达成共识：“需要PostgreSQL以应对查询复杂性和规模”
决策基于证据而非意见

优点：

决策基于当前状态而非假设
应用于代码审查、架构选择、测试策略
记录中包含完整的证据审计跟踪

支持的工具：

read_file - 读取文件内容（最大1MB）
search_code - 搜索正则表达式模式（默认使用ripgrep或Python回退）
list_files - 列出匹配glob模式的文件
run_command - 执行安全只读命令（ls, git, grep等）

配置

控制工具行为在config.yaml中：

工作目录（必需）：

调用deliberate工具时设置working_directory参数
工具从该目录解析相对路径
示例：working_directory: process.cwd()在JavaScript MCP客户端中

工具安全性（deliberation.tool_security）：

exclude_patterns：阻止访问敏感目录（默认：transcripts/, .git/, node_modules/）
max_file_size_bytes：read_file的最大文件大小（默认：1MB）
command_whitelist：run_command的安全命令（ls, grep, find, cat, head, tail）

文件树（deliberation.file_tree）：

enabled：将存储库结构注入到第1轮提示中（默认：true）
max_depth：目录深度限制（默认：3）
max_files：包含的最大文件数（默认：100）

适配器特定要求：

适配器	工作目录行为	配置
Claude	通过子进程自动隔离`{working_directory}`	不需要特殊配置
Codex	没有真正隔离 - 可以访问任何文件	安全注意事项：模型可以读取`{working_directory}`之外的文件
Droid	通过子进程自动隔离`{working_directory}`	不需要特殊配置
Gemini	强制执行工作区边界	必需：`--include-directories {working_directory}`标志
Ollama/LMStudio	N/A - HTTP适配器	没有文件系统访问限制

了解更多：

完整配置参考 - 解释所有config.yaml设置
工作目录隔离 - 适配器如何处理文件路径
工具安全模型 - 白名单、限制和排除
添加自定义工具 - 开发者指南以扩展工具系统

故障排除

“文件未找到”错误：

确保在MCP客户端调用中正确设置了working_directory
使用发现模式：list_files → read_file
检查文件路径是否相对于工作目录

“访问被拒绝：路径匹配排除模式”错误：

工具默认阻止transcripts/, .git/, node_modules/
通过deliberation.tool_security.exclude_patterns在config.yaml中自定义

Gemini“文件路径必须在工作区内”错误：

验证Gemini的--include-directories标志使用了{working_directory}占位符
查看上面的适配器特定设置

工具超时错误：

增加deliberation.tool_security.tool_timeout以适应缓慢操作
默认：文件操作10秒，命令30秒

了解更多：

添加自定义工具 - 开发者指南以扩展工具系统
架构与安全 - 工具的工作原理
常见陷阱 - 高级设置和已知问题

决策图记忆

AI咨询从过去的审议中学习以加速未来的决策。两个核心能力：

1. 自动上下文注入

当开始新的审议时，系统：

在过去的辩论中搜索类似的问题（语义相似性）
找到最相关的前k个决策（可配置，默认：3）
自动注入上下文到第1轮提示中
结果：模型从机构知识开始，更快地收敛

2. 使用`query_decisions`进行语义搜索

程序化查询过去的审议：

搜索相似：找到与问题相关的决策
查找矛盾：检测冲突的过去决策
追踪演变：查看意见随时间的变化
分析模式：识别重复的主题

配置（可选 - 默认设置开箱即用）：

decision_graph:
  enabled: true                       # 默认开启自动注入
  db_path: "decision_graph.db"        # 解析到项目根目录（适用于任何用户/文件夹）
  similarity_threshold: 0.6           # 调整以控制上下文相关性
  max_context_decisions: 3            # 注入多少过去的决策

适用于任何用户从任何目录 - 数据库路径解析到项目根目录。

→ 快速入门 | 配置 | 上下文注入