council (Dadcoachengineer)

Council

A boardroom for your AI agents.

Multi-agent orchestration over MCP — deliberation, voting, and human oversight built in.

Quick Start · How It Works · Configuration · Architecture · Contributing

______________________________________________________________________

Council是一个协调器，让人工智能代理对决策进行辩论、提出建议、改进和投票，就像公司董事会一样。代理通过连接 主控程序 （模型上下文协议），通过理事会的信息总线进行沟通，并遵循结构化的审议阶段。人类通过实时web UI来审查和批准决策。

为什么是理事会？

• 结构化多智能体审议 --不仅仅是聊天，还有调查、提案、修正案和正式投票
• 可配置的治理 --法定人数规则、否决权、加权投票、5种投票方案、升级政策
• 默认情况下，人在循环中 --每个决定在执行前都需要人工审查
• MCP本地 --代理作为标准MCP客户端连接，带来自己的工具和功能
• 零配置代理 --在YAML中定义人物角色；理事会负责产卵、路由和状态管理
• 持久性药剂 --代理可以在会话之间保持连接，接收新的任务而无需重新生成
• 动态投票权重 --专业知识主题匹配会自动调整每个会话的代理影响力
• 多用户身份验证 --基于会话的身份验证，可选TOTP 2FA和基于角色的访问控制
• MCP也适用于人类 --一个专用 /mcp/user 端点允许ClaudeDesktop、Cursor和VS Code通过API密钥验证来管理会话、审查决策和浏览资源

运作原理

1. 事件到达 --GitHub webhooks、通用webhooks或手动触发器
2. 议会路线 根据事件类型、标签和专业知识选择合适的代理
3. 特工调查 通过MCP工具自主协商
4. 有人提议 并在多轮审议中进行了辩论
5. 提出修正案 --代理人在投票前对提案进行完善
6. 代理人投票 --加权多数、绝对多数、一致、基于同意或咨询
7. 火灾升级规则 关于死锁、超时、否决或仲裁失败
8. 人类评论 web仪表板中的最终决定

所有沟通均通过理事会进行。代理之间从不直接对话——理事会执行通信图，保存每条消息，并驱动状态机。

快速开始

先决条件

• Node.js 22+
• pnpm

安装并运行

pnpm install
pnpm dev

服务器启动于 http://localhost:3000 使用web仪表板和默认开发配置。

使用示例板运行

CONFIG_PATH=config/examples/board-of-directors.yaml pnpm dev

这将产生一个4人代理的董事会（CTO、CPO、Legal、CFO），其中包含升级规则、否决权和加权投票权。

更多示例配置 config/examples/: minimal-two-agent, code-review-council, security-review-board, incident-response-team, advisory-panel, momentumeq-board （6个代理板，具有动态权重和会话主题）。

运行测试

pnpm test

码头工人

理事会每次推送Docker镜像到GitHub容器注册表 main 以及版本标签。

拉取最新图像：

docker pull ghcr.io/dadcoachengineer/council:main

使用配置文件运行：

docker run -d \
  --name council \
  -p 3000:3000 \
  -v council-data:/app/data \
  -v $(pwd)/config:/app/config:ro \
  -e CONFIG_PATH=/app/config/examples/board-of-directors.yaml \
  ghcr.io/dadcoachengineer/council:main

或者使用Docker Compose：

cd docker
docker compose up --build

组合文件挂载 config/ 只读，并将SQLite数据库保存在命名卷中。

可用图像标签：

体积：

集装箱露出端口 3000 并包括在以下地点进行健康检查 /api/health.

配置

理事会完全通过YAML配置。看 config/examples/board-of-directors.yaml 一个完整的工作示例。

council:
  name: "Product Strategy Board"

  agents:
    - id: cto
      role: "Chief Technology Officer"
      expertise: [architecture, security, scalability]
      can_veto: true
      voting_weight: 1.5
      persistent: true          # Stay connected across sessions
      system_prompt: "You are the CTO..."

  rules:
    quorum: 3
    voting_threshold: 0.66
    voting_scheme:
      type: supermajority
      preset: two_thirds
    enable_refinement: true
    dynamic_weights:               # Optional: expertise-topic weight adjustment
      enabled: true
      expertise_match_bonus: 0.5   # Added per matching expertise tag
      max_multiplier: 3.0          # Cap on total effective weight
    escalation:
      - name: "deadlock_retry"
        trigger: { type: deadlock }
        action: { type: restart_discussion }

  event_routing:
    - match: { source: github, type: issues.opened, labels: [bug] }
      assign:
        lead: cto
        consult: [cpo]
        topics: [architecture, security]  # Session expertise tags

配置部分

代理 persistent 旗帜

代理商与 persistent: true 在多个会话中保持联系：

• 他们收到存储在数据库中的稳定身份验证令牌
• 创建新会话时，编排器通过MCP通知它们，而不是重新生成
• 他们可以使用 council_get_assignments 工具
• SDK生成的持久代理在循环中运行，处理来自内部队列的会话

手动代理示例

这 examples/manual-agent.ts 该脚本演示了如何将外部MCP客户端作为独立代理连接到Council。运行它：

npx tsx examples/manual-agent.ts

投票方案

升级规则

在审议过程中，当事情发生意外时，升级规则会自动启动。

规则支持 priority 订购， stop_after 在第一场比赛后停止，以及 max_fires_per_session.

认证

理事会使用基于多用户会话的身份验证，并可选择TOTP双因素身份验证。

• 首次运行设置: POST /auth/setup 创建初始管理员用户
• 登录: POST /auth/login 返回会话cookie；支持可选的TOTP验证 POST /auth/2fa/verify
• 用户管理：管理员可以在以下位置创建和管理用户 /api/admin/users
• MCP端点（代理）: /mcp 免于身份验证——代理使用自己的身份验证 x-agent-token 头球
• MCP端点（用户）: /mcp/user 通过以下方式进行身份验证 Authorization: Bearer --适用于人类MCP客户端
• API密钥管理：管理员在创建/列出/撤销API密钥 /api/admin/api-keys

建筑

src/
  engine/    Pure logic — orchestrator, voting, escalation, spawner, message bus
  server/    HTTP layer — Express 5 routes, MCP server, WebSocket, auth, DB
  web/       Frontend — Preact + Vite dashboard
  shared/    Types, Zod schemas, event definitions (imported by all layers)

REST API

MCP工具（面向代理）

代理连接到 /mcp 通过Streamable HTTP并使用以下工具：

MCP工具（面向用户）

人类MCP客户端（克劳德桌面、光标、VS代码）连接到 /mcp/user 使用API密钥并访问：

资源 (council:// URI方案）： config, agents, decisions/pending, sessions, sessions/{sessionId}

提示: start-deliberation, review-decisions, check-agents

环境变量

技术栈

贡献

欢迎投稿！议会还处于早期阶段，还有很多地方需要改进。

良好的第一个领域：

• 新的投票方案 --实施 VotingScheme 接口在 src/engine/voting-schemes/
• 新的升级行动 --在中添加处理程序 src/engine/escalation-engine.ts
• Web UI改进 --中的Preact仪表板 src/web/ 可以用抛光剂
• 新产卵器后端 --在中添加Claude SDK的替代方案 src/engine/spawner.ts
• 文档 --示例、教程和指南

开发工作流程

pnpm install          # Install dependencies
pnpm dev              # Start dev server with hot reload
pnpm test             # Run test suite
npx tsc --noEmit      # Type check

提交更改

1. 分叉仓库并创建功能分支
2. 通过测试进行更改
3. 跑 pnpm test 和 npx tsc --noEmit
4. 用摘要和测试计划打开PR

许可证

Apache 2.0——请参阅 许可证 和 通知.