Skip to content

norbertm2050/agent-huddle

BranchesTags

Repository files navigation

Agent讨论组 Agent Huddle — Multi-model AI Discussion / LLM Deliberation Workspace

一个轻量的多模型分层讨论系统 / 多智能体讨论工作台：像拉起一个 Agent 讨论组一样，让多个大语言模型围绕同一个问题逐层分析、互相补充，并透明展示每一层的输入、输出和最终结论。

A lightweight multi-model AI discussion and LLM deliberation workspace: bring multiple models into one huddle, let them analyze a question layer by layer, and inspect how each answer flows into the final synthesis.

Agent Huddle landing page

在线使用 / Live Demo

  • 立即访问：https://discuss.219214.xyz
  • 推荐流程：注册/登录 → 在「模型接入」添加你的 OpenAI-compatible 接口和 Key → 读取模型列表 → 回到「发起讨论」输入一个问题并开始分层讨论。
  • 隐私提示：Provider Key 只保存在后端数据库中，并使用服务端 ENCRYPTION_KEY 加密；不要把真实 Key 写入 README、Issue、截图或公开日志。

关键词 / Keywords

这些词描述项目真实用途，方便中文和英文用户在 GitHub、Google、Bing 等搜索引擎里找到本项目。

中文：Agent讨论组、多模型讨论、多模型协作、多智能体讨论、大模型合议、AI 合议庭、LLM 分层推理、模型并行分析、AI 辩论、模型编排、OpenAI-compatible 模型接入、AI Agents 工作流、复杂问题拆解、透明推理过程。

English: Agent Huddle, multi-model AI discussion, multi-agent debate, LLM deliberation, LLM ensemble, layered reasoning, AI council, model orchestration, OpenAI-compatible providers, collaborative AI, AI agents workflow, answer synthesis, transparent reasoning, decision support AI.

目录

项目定位

Agent讨论组 / Agent Huddle 是一个面向复杂问题拆解的 multi-model AI discussion / LLM deliberation 工具。它不是普通聊天页面，也不是把多个模型简单并排摆放的模型面板；它解决的是一个更明确的问题：

当一个问题需要多个模型、多个角度、多轮推理时，如何让用户清楚看到“谁在分析、分析了什么、上一层结果如何进入下一层、最终结论从哪里来”。

适合场景：

  • 产品决策：让多个模型分别从用户价值、商业模式、风险、执行路径讨论。
  • 技术评审：让模型分层分析架构、性能、安全、可维护性。
  • 产品方案/文档审查：逐层提炼共识、分歧、关键假设和待验证问题。
  • 投资/研究辅助：让不同模型从正反观点、风险点、数据缺口分别输出。
  • 复杂问题拆解：需要多轮、多模型、透明链路，而不是一次性答案。

核心功能

1. 一个 Prompt 发起讨论

发起页只保留一个类似 ChatGPT 的输入框。用户不需要拆标题、背景、分类；直接输入问题即可。

2. 模型接入和模型库记忆

  • 支持 OpenAI-compatible 接口。
  • 可以输入不同接口地址和访问密钥，读取可用模型列表。
  • 模型和 Provider 配置按登录用户/工作区保存。
  • 可以刷新已保存端点的模型列表。
  • 可以跨接口混选模型。
  • 默认会记住上一次选择的模型组合。

3. 分层讨论配置

  • 层数：1 到 10 层。
  • 每层模型数：1 到 10 个。
  • 讨论模式：轻量、标准、深度。
  • 角色模式：无角色 / 启用角色。
  • 最终输出模型：默认选择较强模型，也可手动指定。

4. 透明的层级运行展示

运行页按“层”平铺展示。每一层有多个模型窗口，类似多个小型 Chat 窗口：

  • 每个模型窗口显示模型、状态、输入摘要和输出。
  • 同层模型可以横向滚动查看。
  • 单个模型内容可以纵向滚动。
  • 中间层共享输入默认折叠，避免重复长文本。
  • 层与层之间展示材料流动：上一层输出会合并为下一层输入材料。
  • 模型出错时显示在对应层附近，并允许继续、停止或调整后续流程。

5. 最终输出

最后一层结束后，只由一个最终输出模型生成最终结论。最终输出以全宽阅读面板展示，不再额外制造第二个“最终回答”概念。

6. 历史记录和导出

  • 历史页查看已有讨论。
  • Run 页面可回放过程。
  • 支持导出运行结果和关键内容。

7. 中英文界面

前端内置语言切换，支持中文和英文界面。默认会根据浏览器语言和本地设置记忆语言偏好。

运行流程

flowchart LR
  A[输入问题 Prompt] --> B[选择 Provider 和模型]
  B --> C[设置层数/每层模型数/讨论模式]
  C --> D[预览每层模型与角色]
  D --> E[第 1 层并行讨论]
  E --> F[合并为下一层材料]
  F --> G[第 N 层继续分析]
  G --> H[最终模型输出结论]
  H --> I[历史记录/导出/复盘]
Loading

界面预览

截图由 Playwright 从当前公网部署 https://discuss.219214.xyz 采集，路径位于 docs/assets/readme/。也可以用本文后面的截图脚本重新生成本地或公网截图。

首页

Landing

发起讨论

New discussion

模型接入

Providers

分层运行详情

Run detail

流程动图

Agent Huddle walkthrough

技术架构

flowchart TB
  User[Browser] --> Web[Next.js Web]
  Web --> Proxy[Next.js same-origin /api proxy]
  Proxy --> API[FastAPI API]
  API --> DB[(Postgres / SQLite dev)]
  API --> Provider[OpenAI-compatible providers]
  API --> SSE[SSE run events]
  SSE --> Web
Loading

前端

  • Next.js 16 App Router
  • React 19
  • TypeScript
  • Tailwind CSS 4
  • TanStack Query
  • Zustand
  • React Markdown
  • Playwright E2E / screenshot automation

后端

  • FastAPI
  • SQLAlchemy async
  • Alembic
  • SQLite 开发模式 / Postgres 生产模式
  • SSE 事件流
  • OpenAI-compatible Provider 适配
  • Fernet 加密保存 Provider 凭据
  • Prometheus metrics

快速启动

1. 准备环境

需要：

  • Python 3.12+
  • uv
  • Node.js 22+
  • npm
  • Docker 可选

2. 复制环境变量

cp .env.example .env

开发环境可以直接使用 .env.example 里的开发默认值；生产环境必须替换所有密钥，见 安全与隐私。

3. 安装依赖

make install

如果没有 make：

cd api && uv sync
cd ../web && npm install

4. 启动推荐本地运行态

./scripts/start_runtime.sh

默认地址：

  • Web: http://127.0.0.1:43117
  • API: http://127.0.0.1:43127
  • Health: http://127.0.0.1:43127/healthz

日志：

  • .runtime/api.log
  • .runtime/web.log
  • .runtime/web-build.log

5. 开发模式分别启动

make api-dev
make web-dev

默认地址：

  • Web: http://localhost:3000
  • API Docs: http://localhost:8000/docs
  • API Health: http://localhost:8000/healthz

接入真实模型

推荐方式：在页面中配置

  1. 注册或登录。
  2. 打开「模型接入」。
  3. 输入 Provider 名称，例如 openai_compatible、openrouter、your_gateway。
  4. 输入 Base URL，例如 https://example.com/v1。
  5. 输入访问密钥。
  6. 点击读取模型列表。
  7. 选择要参与讨论的模型。

密钥会加密保存在后端数据库中，不会进入前端 bundle，也不应写入仓库。

环境变量方式

只建议在自用部署或内部测试中使用：

DEFAULT_OPENAI_API_KEY=...
DEFAULT_OPENAI_BASE_URL=https://your-gateway/v1
DEFAULT_OPENAI_MODEL=gpt-5.4-mini

不要把真实访问密钥写入 .env.example、README、截图、日志或 Git 历史。

常用命令

# 后端测试
cd api && uv run pytest -q

# 后端语法检查
cd api && uv run python -m compileall app

# 前端 lint / typecheck / build
cd web && npm run lint
cd web && npx tsc --noEmit
cd web && npm run build

# 生成 OpenAPI 和前端类型
make generate-types

# 本地安全扫描
./scripts/security_scan.sh

# Docker 构建检查
docker build -t agent-huddle-api:local-check ./api
docker build -t agent-huddle-web:local-check ./web

Playwright 截图和 README 图片

项目可以用 Playwright 采集真实页面截图。采集当前公网部署：

README_WEB_BASE_URL=https://discuss.219214.xyz \
README_API_BASE_URL=https://discuss.219214.xyz/api \
node scripts/capture_readme_assets.mjs

采集本地运行态：

./scripts/start_runtime.sh
node scripts/capture_readme_assets.mjs

输出：

  • docs/assets/readme/landing.png
  • docs/assets/readme/new-run.png
  • docs/assets/readme/providers.png
  • docs/assets/readme/run-detail.png
  • docs/assets/readme/walkthrough.gif

如果本机没有 ImageMagick convert 或 ffmpeg，脚本会保留 PNG 截图并跳过 GIF。

Docker

本地开发版：

docker compose up --build

VPS + Traefik + Cloudflare 生产版（默认绑定 discuss.219214.xyz，并生成本机私有 .env.production.local）：

PUBLIC_HOST=discuss.219214.xyz ./scripts/deploy_traefik.sh

生产版只把 Web 容器接入外部 app-network，API、Postgres、Redis 默认不暴露宿主机端口；浏览器通过同源 /api 代理访问后端。Cloudflare 小黄云建议 SSL/TLS 使用 Full。当前生产 Compose 不启用 Traefik 的 letsencrypt certresolver，避免 Cloudflare 代理导致 ACME TLS-ALPN 反复失败。如果要使用 Full (strict)，请先给源站安装 Cloudflare Origin Certificate，或把 Traefik 改成 Cloudflare DNS-01 验证。

启用 Temporal 编排：

ORCHESTRATOR_MODE=temporal docker compose --profile temporal up --build

启用监控：

docker compose --profile monitoring up --build

部署方式

完整产品不能只靠 GitHub Pages，因为系统需要：

  • FastAPI 后端
  • 数据库
  • 登录鉴权
  • Provider Key 加密保存
  • SSE 流式事件
  • API 代理

推荐部署形态：

  1. 最简单完整部署：Docker Compose + VPS/云主机。
  2. 免费/低成本托管组合：
    • Web: Vercel Hobby，项目根目录 web/
    • API: Render / Fly.io / Railway 等 Docker Web Service
    • DB: Neon / Supabase Postgres
  3. GitHub Pages：只适合静态官网、文档或只读介绍页，不适合完整运行服务。

当前公网部署入口：https://discuss.219214.xyz

详细说明见：

安全与隐私

上线或开源前必须执行：

./scripts/security_scan.sh

该脚本会扫描工作树中的常见密钥模式；如果当前目录是 Git 仓库，也会扫描历史提交。

不要提交

  • .env
  • .env.local
  • .runtime/
  • .omx/
  • output/
  • api/data/
  • 日志文件
  • 截图中的访问密钥
  • 真实 Provider 访问密钥
  • 数据库密码或生产密钥

生产环境必须设置

APP_ENV=production
SECRET_KEY=<32+ char random secret>
ENCRYPTION_KEY=<Fernet key>
DATABASE_URL=postgresql+asyncpg://...
CORS_ORIGINS=https://your-web-domain.example
DEFAULT_BUILTIN_PROVIDER_ENABLED=false

生产模式会拒绝开发默认 SECRET_KEY、开发默认 ENCRYPTION_KEY 和本地/CORS 通配配置。

Git 历史泄漏处理

如果真实密钥进入过 Git 历史：

  1. 立即旋转密钥。
  2. 用 git-filter-repo 或 BFG 清理历史。
  3. 重新运行 ./scripts/security_scan.sh。
  4. 再公开仓库。
  5. 在 GitHub 开启 Secret Scanning / Push Protection。

测试与上线验收

上线前建议至少跑：

./scripts/security_scan.sh
cd api && uv run pytest -q
cd api && uv run python -m compileall app
cd web && npm run lint
cd web && npx tsc --noEmit
cd web && npm run build
docker build -t agent-huddle-api:local-check ./api
docker build -t agent-huddle-web:local-check ./web

压力和运行态验收见：

  • docs/release/launch-readiness-runbook.md
  • scripts/stress_runs.py

项目结构

.
├── api/                         # FastAPI 后端
│   ├── app/api/v1/              # REST / SSE API
│   ├── app/core/                # 配置与安全默认值
│   ├── app/db/                  # SQLAlchemy models/session/init
│   ├── app/providers/           # 内置、OpenAI、OpenAI-compatible provider
│   ├── app/services/            # 编排、执行、导出、加密、种子数据
│   └── tests/                   # 后端测试
├── web/                         # Next.js 前端
│   ├── src/app/                 # App Router 页面
│   ├── src/components/          # UI 和 run 展示组件
│   ├── src/lib/                 # API/i18n/presentation utilities
│   └── tests/e2e/               # Playwright tests
├── docs/                        # 部署、发布、审查文档和截图资产
├── deploy/                      # 托管平台示例配置
├── scripts/                     # 运行、压测、安全扫描、截图脚本
├── docker-compose.yml           # 本地/服务器 compose
└── README.md

许可证

本项目采用 PolyForm Noncommercial License 1.0.0。

你可以在非商业目的下运行、学习、测试、修改和分发本项目；但不得将本项目或修改版本用于商业用途，包括但不限于：

  • 对外销售软件或托管服务；
  • 作为收费 SaaS / API / 内部商业生产系统的一部分；
  • 为公司、客户或商业项目提供生产用途；
  • 将本项目包装后作为商业产品分发。

如果你需要商业授权，需要获得权利人的单独书面许可。

注意：由于包含 Noncommercial 限制，本项目是 source-available / noncommercial，不是 OSI 定义下的 open source 项目。

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

You may run, study, test, modify, and distribute the project for noncommercial purposes. Commercial use is not permitted without separate written permission from the rights holder. Because the license restricts commercial use, this repository is source-available/noncommercial rather than OSI-approved open source.

已知限制

  • 免费托管平台可能休眠，首次请求会慢。
  • 公开给不可信用户使用前，还需要更严格的限流、额度保护和审计日志。
  • 当前仓库如果不是 Git checkout，无法扫描 Git 历史；正式发布必须在真实 Git 仓库中扫描历史。
  • 当前许可证禁止商业使用；如果将来需要商业版授权，建议另建清晰的商业授权流程。

English summary

Agent Huddle is a lightweight layered multi-model discussion workspace.

Live demo: https://discuss.219214.xyz

You enter one prompt, connect one or more OpenAI-compatible providers, choose models, set layer depth and model count, then watch each model discuss the question layer by layer. Outputs from one layer become labeled materials for the next layer, and one final model produces the final answer.

Core capabilities:

  • Useful for search terms such as multi-model AI discussion, multi-agent debate, LLM ensemble, LLM deliberation, AI council, layered reasoning, model orchestration, collaborative AI, and OpenAI-compatible AI agents workflow.
  • One-prompt discussion creation.
  • Saved provider credentials and model catalog per workspace.
  • Cross-provider model selection.
  • Up to 10 layers and 10 models per layer.
  • Plain or role-based discussion modes.
  • Transparent layer-by-layer run view.
  • SSE-based progress updates.
  • History, export, bilingual UI, and local/hosted deployment paths.

Recommended local run:

cp .env.example .env
cd api && uv sync
cd ../web && npm install
./scripts/start_runtime.sh

Open http://127.0.0.1:43117.

About

Agent Huddle: multi-model AI discussion and LLM deliberation workspace for layered reasoning, AI agents workflows, and OpenAI-compatible model orchestration.

discuss.219214.xyz

Topics

ai nextjs multi-agent multi-model agents ai-agents fastapi llm llm-orchestration openai-compatible llm-ensemble agent-huddle layered-reasoning

Resources

Readme

License

View license

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages