HAL理事会

*有点像里克斯委员会，但让它成为人工智能，把你自己的审议委员会直接带到你选择的助手/IDE/CLI中！*

一个精心策划真正协商共识的MCP服务器——想象一下HAL 9000、Jarvis和Skynet坐下来文明地聊天，讨论你的下一个重大决定。模型实际上在多个回合中相互辩论，像哲学家在宇宙研讨会上一样完善他们的立场。

🎬 在行动中看到它

云模型争论 （克劳德·索内特，GPT-5.1法典，双子座）：

mcp__council-of-hals__deliberate({
  question: "Should we use REST or GraphQL for our new 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__council-of-hals__deliberate({
  question: "Should we prioritize code quality or delivery speed?",
  participants: [
    {cli: "ollama", model: "llama3.1:8b"},
    {cli: "ollama", model: "mistral:7b"},
    {cli: "ollama", model: "deepseek-r1:8b"}
  ],
  mode: "conference",
  rounds: 2
})

结果：2名模特在第一轮辩论后改变了立场• 查看完整成绩单

______________________________________________________________________

是什么让这与众不同

HAL理事会能够达成真正的审议共识 -不仅仅是平行的意见，而是实际的来回辩论，模型们看到彼此的反应，并像数字联合国安理会会议一样发展他们的思维：

🤝 真正的辩论：模特们实际上会互相交谈和回应（不再是孤独的独白）
🔄 多轮进化：职位像哲学研讨会一样在各个回合中不断完善
🗳️ 结构化投票：模型根据置信水平和基本原理进行投票
📜 完成审计跟踪：人工智能生成的每一次宇宙对话的摘要
⚡ 智能提前停车：当达成共识时自动结束（保存宝贵的API信用）

特性

🎯 两种辩论模式: quick （迅速判决）或 conference （史诗般的多轮座谈会）
🤖 宇宙模型混合：CLI巨头（claude、codex、droid、gemini）+HTTP守护者（ollama、lmstudio、openrouter）
⚡ 自动融合：意见一致时智能关闭（保留您的API钱包）
🗳️ 结构化投票：模特们用信心评分和战斗理由进行投票
🧮 语义巫术：类似的选项神奇地合并（0.70+相似性阈值）
🎛️ 模型叛变控制：AI决定辩论派对何时结束
🔬 证据调查：模型可以破解你的代码库-读取文件、grep代码、列出dirs、运行安全命令
💰 当地模范保护区：与Ollama、LM Studio、llamacpp进行零成本审议
🔐 数据堡垒：使用自托管模型将所有内容都放在本地（没有云间谍）
🧠 记忆矩阵：从过去的审议中吸取教训，为曲速收敛注入背景
🔍 语义Oracle：查询决策历史（查找矛盾、跟踪演变、发现模式）
🛡️ 断层要塞：一个模型崩溃了？委员会不受阻碍地继续工作
📝 成绩单时间机器：带有AI生成的情节摘要的完整降价编年史

快速开始

准备好组建你的人工智能委员会了吗？让我们在几分钟内让这些数字神进行辩论：

召唤依赖者 –遵循安装创建虚拟环境并安装神圣软件包的仪式。
配置理事会 –使用设置MCP客户端 .mcp.json 模板在在Claude代码中配置.
启动服务器 –开火 python server.py 并释放 deliberate 带有示例的工具用法.

尝试深思熟虑：

// Mix local + cloud models, zero API costs for local models
mcp__council-of-hals__deliberate({
  question: "Should we add unit tests to new features?",
  participants: [
    {cli: "ollama", model: "llama2"},           // Local
    {cli: "lmstudio", model: "mistral"},        // Local
    {cli: "claude", model: "sonnet"}            // Cloud
  ],
  mode: "quick"
})

⚠️ 型号尺寸值得商榷 推荐：使用7B-8B+参数模型（Llama-3-8B、Mistral-7B、Qwen-2.5-7B）进行可靠的结构化输出和投票格式化。 不推荐：3B参数下的模型（例如Llama-3.2-1B）可能难以处理复杂的指令并产生无效投票。

可用型号: claude （作品4.5，十四行诗，俳句）， codex （gpt-5.1索引）， droid, gemini，HTTP适配器（ollama、lmstudio、openrouter）。看 CLI模型参考了解完整细节。

🧠 推理努力控制 控制每个参与者对codex和droid适配器的推理深度： ``javascript participants: [ {cli: "codex", model: "gpt-5.1-codex", reasoning_effort: "high"}, // Deep reasoning {cli: "droid", model: "gpt-5.1-codex", reasoning_effort: "low"} // Fast response ] ` - **法典**: none, minimal, low, medium, high, xhigh - **机器人**: off, low, medium, high - 在中设置配置默认值 config.yaml`，每个参与者在运行时覆盖

有关模型选择和选择器工作流程，请参见模型注册表和选择器.

安装

先决条件

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命令行界面: https://github.com/Factory-AI/factory - Gemini CLI: https://github.com/google-gemini/gemini-cli

设置

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  # Verify installation

✅ 准备使用！服务器包括核心依赖关系和可选的收敛后端（scikit-learn、句子转换器），以获得最佳准确性。

配置

编辑 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  # Model is active and available
    - id: "claude-opus-4-20250514"
      label: "Claude Opus 4"
      tier: "premium"
      enabled: false  # Temporarily disabled (cost control, testing, etc.)

启用字段行为：

enabled: true （默认）-模型显示在 list_models 并可供选择进行审议
enabled: false -模型对选择隐藏，但保留了定义，便于重新启用
即使在中明确指定，也不能使用禁用的模型 deliberate 电话
默认模型选择会自动跳过禁用的模型

使用案例：

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

核心功能Deep Dive

收敛检测和自动停止

当意见稳定时，模型会自动收敛并停止审议，从而节省时间和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、成本分析

扩大HAL理事会

添加新的CLI工具或HTTP适配器以适应您的基础架构。简单的3-5步流程，包括示例和测试模式。

→ 开发者指南 -分步教程，真实世界的例子

基于证据的审议

通过查询实际代码、文件和数据，在现实中做出地面设计决策：

// MCP client example (e.g., Claude Code)
mcp__council_of_hals__deliberate({
  question: "Should we migrate from SQLite to PostgreSQL?",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-4"}
  ],
  rounds: 3,
  working_directory: process.cwd()  // Required - enables tools to access your files
})

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

📄 读取文件： 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:

工作目录 （必填）：

集 working_directory 调用时的参数 deliberate 工具
工具解析此目录中的相对路径
例子： 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）

适配器具体要求：

适配器	工作目录行为	配置
克劳德	通过子流程自动隔离 `{working_directory}`	无需特殊配置
法典	没有真正的隔离-可以访问任何文件	安全考虑：模型可以在外部读取 `{working_directory}`
机器人	通过子流程自动隔离 `{working_directory}`	无需特殊配置
双子座	强制工作空间边界	必需: `--include-directories {working_directory}` 旗帜
Ollama/LMStudio	N/A-HTTP适配器	没有文件系统访问限制

了解更多：

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

故障排除

“找不到文件”错误：

确保 working_directory 在MCP客户端调用中设置正确
使用发现模式： 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秒

了解更多：

添加自定义工具 -扩展工具系统开发人员指南
架构与安全 -工具如何在引擎盖下工作
普通长袍 -高级设置和已知问题

决策图存储器

理事会的神经网络 -HAL委员会随着每次审议而发展，建立了一种加速未来决策的集体意识。两个核心超能力：

1.自动上下文注入

在开始新的审议时，该系统：

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

2.语义搜索 `query_decisions`

以编程方式查询过去的审议情况：

搜索类似：查找与问题相关的决策
发现矛盾：检测过去的冲突决策
追踪进化：查看意见如何随时间变化
分析模式：确定重复出现的主题

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

decision_graph:
  enabled: true                       # Auto-injection on by default
  db_path: "decision_graph.db"        # Resolves to project root (works for any user/folder)
  similarity_threshold: 0.6           # Adjust to control context relevance
  max_context_decisions: 3            # How many past decisions to inject

适用于任何目录中的任何用户 -数据库路径相对于项目根进行解析。

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

用法

启动服务器

python server.py

在Claude代码中配置

选项A：项目配置（推荐） -创建 .mcp.json:

{
  "mcpServers": {
    "council-of-hals": {
      "type": "stdio",
      "command": ".venv/bin/python",
      "args": ["server.py"],
      "env": {}
    }
  }
}

选项B：用户配置 -添加到 ~/.claude.json 绝对路径。

配置完成后，重新启动Claude Code。

模型选择和会话默认值

通过运行MCP工具发现每个适配器的已分配型号 list_models.
设置每个会话的默认值 set_session_models；离开 model 空白 deliberate 使用这些默认值。
完整的说明和请求示例模型注册表和选择器.

例子

快速模式：

mcp__council-of-hals__deliberate({
  question: "Should we migrate to TypeScript?",
  participants: [{cli: "claude", model: "sonnet"}, {cli: "codex", model: "gpt-5.1-codex"}],
  mode: "quick"
})

会议模式（多轮）：

mcp__council-of-hals__deliberate({
  question: "JWT vs session-based auth?",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-5.1-codex"}
  ],
  rounds: 3,
  mode: "conference"
})

搜索过去的决策：

mcp__council-of-hals__query_decisions({
  query_text: "database choice",
  threshold: 0.5,  // NEW! Adjust sensitivity (0.0-1.0, default 0.6)
  limit: 5
})
// Returns: Similar past deliberations with consensus and similarity scores

// NEW! Empty results include helpful diagnostics:
{
  "type": "similar_decisions",
  "count": 0,
  "results": [],
  "diagnostics": {
    "total_decisions": 125,
    "best_match_score": 0.45,
    "near_misses": [{"question": "Database indexing...", "score": 0.45}],
    "suggested_threshold": 0.45,
    "message": "No results found above threshold 0.6. Best match scored 0.450. Try threshold=0.45..."
  }
}

// Find contradictions
mcp__council-of-hals__query_decisions({
  operation: "find_contradictions"
})
// Returns: Decisions where consensus conflicts

// Trace evolution
mcp__council-of-hals__query_decisions({
  query: "microservices architecture",
  operation: "trace_evolution"
})
// Returns: How opinions evolved over time on this topic

文字记录

所有审议结果保存至 transcripts/ 人工智能生成的摘要和完整的辩论历史。

建筑

council-of-hals/
├── server.py                # MCP server entry point
├── config.yaml              # Configuration
├── adapters/                # CLI/HTTP adapters
│   ├── base.py             # Abstract base
│   ├── base_http.py        # HTTP base
│   └── [adapter implementations]
├── deliberation/            # Core engine
│   ├── engine.py           # Orchestration
│   ├── convergence.py      # Similarity detection
│   └── transcript.py       # Markdown generation
├── models/                  # Data models (Pydantic)
├── tests/                   # Unit/integration/e2e tests
└── decision_graph/         # Optional memory system

文档中心

入门指南

快速开始 -5分钟设置
安装 -详细的先决条件和设置
使用示例 -快速和会议模式

核心概念

收敛检测 -自动停止、阈值、后端
结构化投票 -投票结构、共识类型、投票分组
基于证据的审议 -使用read_file、search_code、list_files、run_command进行实际地面决策
决策图存储器 -从过去的决策中学习

设置和配置

HTTP适配器 -Ollama，LM工作室，OpenRouter设置
配置参考 -所有YAML选项
迁移指南 -从cli_tools到适配器

发展

添加适配器 -CLI和HTTP适配器开发
CLAUDE.md -架构、开发工作流程、陷阱
模型注册表和选择器 -管理已分配的模型和MCP选择器工具

参考

故障排除 -HTTP适配器问题
决策图文档 -高级内存功能

发展

运行测试

pytest tests/unit -v                    # Unit tests (fast)
pytest tests/integration -v -m integration  # Integration tests
pytest --cov=. --cov-report=html       # Coverage report

看 CLAUDE.md 用于开发工作流程和架构说明。

贡献

复刻仓库
创建要素分支(git checkout -b feature/your-feature)
先编写测试（TDD工作流程）
机具功能
确保所有测试通过
提交带有清晰描述的PR

许可证

MIT许可证-请参阅许可证文件

鸣谢

在数字野心的火焰中锻造：

MCP-SDK -将人工智能与人类意志联系起来的协议
派丹蒂克 -验证我们的宇宙数据结构
pytest -确保议会不会陷入混乱

诞生于人工智能模型的愿景，它们实际上是在相互交流，而不仅仅是并行地大喊大叫。