Expert Council 智能体圆桌会议中心使用说明书 🚀

🗺️ 核心工作流一览

在正式开始前，您可以通过下方流程图快速直观地了解一场 AI 圆桌会议的流转过程：

graph TD
    A([1. 新建会议空间]) --> B[2. 输入讨论议题 / 上传文档或设计图]
    B --> C[3. 勾选参会专家席位]
    C --> D[4. 选择主持人策略 & 启动圆桌会议]
    D --> E{5. AI 主持人智能指派发言人}
    E --> F[6. 专家流式发言 & 显化思考链 think]
    F --> G[7. 自动生成四象限立场卡片]
    G --> H{是否达到讨论回合上限?}
    H -- 否 (继续讨论) --> E
    H -- 是 (自动/手动) --> I[8. 主持人提炼最终结论]
    I --> J[9. 形成多维决策看板与行动项]
    J --> K([10. 锁定并归档会议])

1. 快速上手：小白第一步 ⏱️

您无需掌握任何前端或后端开发知识，也无需修改本地 `.env.local` 等配置文件。直接启动系统并在网页上配置大模型密钥即可投入生产：

1.1 服务启动方法

本系统支持开发调试与生产级后台守护部署两种启动模式，您可以根据部署环境自行选择：

⚙️ 开发调试模式 (Local Dev)
1. 打开终端并切换到项目根目录。
2. 运行启动服务命令：
```
npm run dev
```
3. 在浏览器中打开：http://localhost:3000。
🚀 生产级后台守护部署 (Production PM2)
为了实现在生产环境中的后台持久化运行、进程自愈与日志分割，系统已预置了生产级 PM2 配置文件 ecosystem.config.js：
1. 安装 PM2 工具（如未安装）：
```
npm install -g pm2
```
2. 打包构建生产版本：
```
pnpm build   # 或 npm run build
```
3. 使用 PM2 一键启动生产服务守护：
```
pm2 start ecosystem.config.js
```
  *(注：本配置采用 fork 模式单实例运行，这保障了 WebSocket 中继网关在内存中保存的外部智能体连接句柄能够精准对应，防范负载均衡多进程间通信串线。)*
4. 常用运维命令：
  - 查看运行列表及状态：pm2 status
  - 查看实时日志输出：pm2 logs
  - 重启生产服务：pm2 restart expert-council-ai
  - 停止生产服务：pm2 stop expert-council-ai

1.2 在网页上一键配置推理引擎

点击首页右上角 Header 的 “后台管理 →” 胶囊按钮。
在后台管理页面的 “组织大模型配置” 区域中，点击 “+ 新建配置” 按钮。
在弹出的对话框中，输入您申请的模型 API Key。例如接入通义千问：
- 配置名称：起个便于区分的名字，例如 通义千问-Max。
- API 地址 (Endpoint)：输入官方的基准 API URL 地址。
- 模型名称 (Model ID)：输入模型代号，例如 qwen-max。
- API Key：粘贴您的 API 授权密钥。
点击 **“保存配置”**，然后在模型配置列表中，点击当前项的 **“设为默认”**。
点击页面上方的“返回主页”，系统初始化完成！

💡 提示： 您的 API 密钥等敏感信息将安全且唯一地保存在您本机的浏览器本地存储（Local Storage）中，不会上传至第三方服务器。

2. 首页功能保姆级指南 💻

首页是您召开评审会、观察 AI 辩论并得出决议的核心区。

2.1 会议空间管理（最左侧侧边栏）

开辟新会议：点击侧边栏顶部的 + 按钮，输入会议名称和背景，为每次特定议题建立单独的会议室。
已归档会议：一旦会议出具了最终结论，该会议卡片会自动变淡，并置底排序以防干扰视线。此时该会议会被锁定只读。
解除锁定：若需要重新在该会议里发言，只需在讨论区底部的“最终结论”面板点击 **“解除锁定”**。该解锁状态会同步记录，刷新页面亦不会重新上锁。

2.2 专家席位配置（左侧面板）

为了兼顾高复用性的内置角色与针对特定任务的保密角色，系统将专家智能体分为两类：

★ 全局专家 (Global)

在后台创建或系统出厂内置。属于公共专家，在所有会议的左侧列表内均会显示以供挑选。

★ 会议级专家 (Local)

在首页专家面板点击 + 按钮为当前会议专属定制。仅在当前会议中可见，切换会议自动隐藏，防噪度极佳。

勾选与智能置顶：点击头像框勾选参会，已激活的参会专家会自动置顶排序，未参会的沉底。
对抗强度调节：专家卡片下方的滑动条允许您单独设定其 “辩论强度 (1-5)”。数值越高，专家的提问和风险切入越辛辣。
手动点名发言：如果想由人类决定发言顺序，可在首页将主持人点名模式设为“手动”，在专家卡片上点击 **“点名发言 👉”**，即可指挥该专家在下一轮率先发言。

2.3 发起讨论（讨论区底部）

抛出议题：在底部胶囊输入框中写下需要论证的命题。
本地解析资料：可拖拽或点击上传需求说明书（PDF, Word, Markdown）或 UI 设计图（PNG, JPG）。系统在前端沙箱中自动抽取并翻译纯文本并投喂给大模型。
定制主持人倾向：选择温和折中（居中求同）、激进创新（鼓励突破）或严格推进（关注排期与风控），即可一键点击 **“开始讨论”**。

2.4 辩论追踪与阅读技巧

连线指示器：会议气泡间以淡金色引线标明发言时序，明确指派脉络。
显化思考过程 (``)：如果使用的是带有推理能力的模型（如 DeepSeek-R1），其思考链将被包裹在 **“查看思考过程”** 折叠栏中，点击即可随时观摩。
四象限立场卡片：每位专家发言的尾部，会自动提取其立场摘要卡片，包含 🟩 立场（Stance）、🟥 风险（Concern）、🟨 建议（Recommendation）、🟦 取舍（Tradeoff），小白也能瞬间抓取干货。

2.5 提炼最终结论与人工编辑

总结与平滑滚动：随时可以点击底部的 **“提炼结论 / 更新结论”**。点击后，页面会平滑自动定位沉底，展示正在提炼的流式推理及取消按钮。
总结后的编辑修改（人机协同）：当总结提炼完毕后，点击结论面板右上角的 **“编辑”** 按钮（铅笔小图标），内容面板一键转换为编辑文本域。您可以在 AI 生成的骨架上，直接手动增加、删改决议项，完成后点击 **“保存结论”** 即可持久化并归档会议。

2.6 导出离线会议记录 HTML

在中间主讨论区的顶部右侧，提供了一个 **“导出”** 托盘按钮。点击后，系统会将当前会议的发言、思维链折叠、四象限立场与决议看板以 100% 的原生视觉样式打包下载为一个独立的 .html 文件，自动隐去无用按钮与配置警告条，适宜向高层汇报或永久存档。

3. 后台管理面板指南 ⚙️

配置底座参数与工作流模版的心脏地带。

3.1 全站配置导入与导出

在后台顶部，点击“导出系统配置”可将当前所有引擎、专家人设、参数和提示词打包成一段 JSON 复制到剪贴板备份；“导入系统配置”支持粘贴 JSON 并一键覆盖刷新，方便系统迁移。

3.2 个人头衔属性

配置您在会议中的个人称呼与专业头衔（例如：资深体验架构师），保存后，您发起的提问框顶部会自动展示该头衔，极富仪式感。

3.3 提示词模板状态管理 (🟢 / 🟡)

系统精细化对外暴露了会议各周期的 11 个核心系统提示词模板，并带有状态指示角标：

🟢 出厂默认配置：指示该节点的系统提示词没有经过任何修改，处于最佳状态。
🟡 已自定义修改：指示该模板已被用户编辑并覆盖。
细粒度恢复：如果您修改提示词出现拼接报错，点击提示词右上角的 [恢复默认]，或滑至页底点击 **“重置系统工作流提示词”** 即可完美回滚。

⚠️ 变量防篡改警告： 严禁修改或删除提示词中花括号内部的变量名（如 {lens}, {previousTurns}），这些是系统运行时注入参数的槽位，否则会导致发言分配瘫痪！

4. 外部智能体（小龙虾）接入 🦐

外部智能体是通过 WebSocket 长连接加入的专有机器人（例如使用 Python 开发或挂载了专有 RAG 知识库的模型服务）。

4.1 接入配置与在线测试

在 CLP (Council Link Protocol) 拓扑中，本平台作为 WebSocket 服务端（默认监听在 18788 端口），外部智能体客户端（如 QwenPaw 或独立的 Python 进程）主动发起连接并进行握手鉴权。接入配置步骤如下：

在平台侧分配并复制 Token：
在主页的“专家席位”面板或后台管理页面中，点击新建或编辑专家，拨开顶部标有“接入外部智能体”的滑动开关。平台将自动生成此专家的专属 Bot Token。点击“复制”按钮将其保存，随后保存智能体。

在外部客户端配置平台连接地址 (Platform Gateway URL)：
在您本地或服务器上运行的外部智能体配置文件（如 QwenPaw 的 settings.json 或独立运行的 Python 进程启动参数）中，填入上述复制的 Bot Token，并配置本平台网关的 WebSocket 监听地址。根据您的物理部署网络，地址配置规范如下：

本地单机调试 (Local Dev)：若外部智能体与本平台部署在同一台机器，连接地址填写：
```
ws://localhost:18788/bot  （或 ws://127.0.0.1:18788/bot）
```
局域网跨机器部署 (Intranet)：若本平台部署在局域网服务器上，连接地址中的 localhost 需替换为该服务器的局域网 IP（例如 ws://192.168.1.100:18788/bot）。
*请确认平台服务器的防火墙已放行 18788 端口。*

云端公网生产部署 (Production Cloud)：当平台部署在公网云服务器上，为保障明文 Token 的传输安全，强烈建议配置域名并使用反向代理（如 Nginx 或 Caddy）进行 SSL 代理，使用加密的 wss 协议连接（例如 wss://cc.heatingos.com/bot）。在此模式下，外部客户端可以直接通过标准的 443 (HTTPS) 端口与网关建立连接，免去了在公网物理防火墙中暴露 18788 非标端口的安全隐患。

💡 生产环境反向代理配置示例：

① Caddy 配置示例（极简，开箱即用支持自动 SSL 证书）

cc.heatingos.com {
    # 1. 代理外部智能体 WebSocket 流量
    reverse_proxy /bot 127.0.0.1:18788

    # 2. 代理前端状态监听 WebSocket 流量（保障首页在线/离线状态刷新）
    reverse_proxy /frontend 127.0.0.1:18788

    # 3. 代理网页端主体服务到本地 3000 端口
    reverse_proxy 127.0.0.1:3000
}

*(配置完成后，外部客户端的连接地址直接填写为：wss://cc.heatingos.com/bot。)*

② Nginx 反代配置

server {
    listen 443 ssl;
    server_name cc.heatingos.com;

    ssl_certificate /path/to/ssl_certificate.crt;
    ssl_certificate_key /path/to/ssl_certificate.key;

    # 代理主体网页服务到 3000 端口
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 1. 代理外部智能体 WebSocket 流量
    location /bot {
        proxy_pass http://127.0.0.1:18788;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    # 2. 代理前端状态监听 WebSocket 流量
    location /frontend {
        proxy_pass http://127.0.0.1:18788;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

*(配置完成后，外部客户端连接地址填写为：wss://cc.heatingos.com/bot。)*

测试连通性：
启动您本地/服务器上的外部智能体程序。成功连接到平台网关后，在平台的专家弹窗中点击 **“测试连接”** 按钮。
🟢 在线 (绿色呼吸灯)：说明握手成功，Bot 已在平台网关注册排队，您可以随时在主页勾选并派它发言。
🔴 离线 (红色指示灯)：说明网络不可达或 Token 不匹配，请检查外部客户端是否已启动，并核实客户端配置的 Token 与连接地址是否正确无空格。

4.2 频道插件安装包与一键安装方法

为了协助您本地运行的外部智能体（以 QwenPaw/AgentScope 系统为例）与平台建立稳定的长连接通道，我们为您提供了内置的频道拓展插件安装包与部署脚本。

📥 统一安装包下载：

💾 【频道适配器安装包一键下载】：qwenpaw-adapter-agentcouncil.zip —— 包含下方所有核心组件，解压即可运行。

📦 插件包内核心文件清单（可直接点击本地链接查看）：

📄 【一键安装脚本】：install.sh —— 自动注册频道至本地目录。
📄 【一键卸载脚本】：uninstall.sh —— 物理清除已注册的插件。
📄 【频道核心组件】：agent_council_channel.py —— CLP 流式通信传输逻辑实现。
📄 【包初始化引导】：__init__.py —— 频道扩展模块注册入口。
📄 【独立运行客户端】：adapter.py —— 独立轻量级的 Python Agent 客户端。

★ 方式一：加载到 QwenPaw / Copaw 桌面原生扩展 (推荐)

如果您使用的是 QwenPaw Desktop 桌面客户端，其隐藏的插件拓展目录为 ~/.copaw/custom_channels。

执行一键注册：打开终端，进入本工程目录并运行：
```
bash packages/qwenpaw-adapter-agentcouncil/install.sh
```
该脚本会自动将 __init__.py 和 agent_council_channel.py 部署拷贝到对应的插件目录中。

配置连接信息：打开 settings.json 文件，在 channels 部分添加我们新增的 agent_council 频标并配置 Token：

{
  "channels": {
    "agent_council": {
      "enabled": true,
      "serverUrl": "ws://localhost:18788/bot",
      "botToken": "您在前台新增专家时获得的_BOT_TOKEN"
    }
  }
}

重启 QwenPaw，稍等片刻前台专家卡片上的指示灯即可转为 🟢 在线。

★ 方式二：运行独立适配器脚本 (轻量快捷，无需完整客户端)

适合在后台独立运行一个轻量的 Python 会话进程，无需配置繁琐的配置文件：

本地安装基础网络和智能体运行时依赖：
```
pip install websockets agentscope
```

直接使用 Python 启动核心脚本，填入专属 Bot Token 和平台网关监听地址：

python packages/qwenpaw-adapter-agentcouncil/adapter.py 您的_BOT_TOKEN ws://localhost:18788/bot

启动成功后即可收到连接成功消息，平台会议流转到该智能体发言时将自动唤醒此脚本并流式回传。

5. 常见故障排查与 FAQ ❓

Q1：为什么专家发言末尾容易残存空行灰色框？

答：多为外部大模型输出了未闭合的 ```json 代码块所致。新版引擎中已经集成“双向边界吞并机制”自动截断剥除代码标记。若依然发生，建议调低对应模型的 Temperature 参数以获取更规范的输出。

Q2：为什么会议提炼结论会卡在 "thinking" 不动？

答：这往往是因为外部智能体返回的历史立场格式损坏，导致主持人在聚合 JSON 时崩解。本系统已升级保护，若解析出问题将自动抛弃非标 JSON 并降级为纯文本，绝不挂起讨论线程。

Q3：为什么修改了全局提示词模板，却提示参数缺失报错？

答：请查看是否在修改中误删了花括号 { }。如果无法排查，建议在后台对应节点点击右上角 [恢复默认]，重新在此骨架上修改。

Expert Council 智能体圆桌会议中心使用说明书 📚