智辩无幻

面向挑战杯“领域知识个性化生成与多智能体协同决策系统研究”赛题的多智能体个性化训练项目。

工程代号：IM-Training-Agent；参赛作品正式名称为“智辩无幻”。

“智辩无幻”面向垂直领域技能训练，围绕“学习者差异识别—多智能体协同决策—专业内容生成与校验—交互反馈—动态调整”构建完整训练闭环。

1. 项目定位

挑战杯赛题要求系统能够：

• 根据不同学习者背景和先验知识形成差异化训练；
• 由至少 3 个职责明确的智能体完成“分析—生成—校验—决策”协作；
• 结合学习者画像与领域专业知识，动态生成个性化学习资源；
• 展示多智能体协作过程、个人学情与资源匹配情况；
• 根据学习反馈继续调整解释难度、训练路径和后续任务；
• 通过交叉验证、审核、知识溯源等机制降低专业内容幻觉。

因此，本项目最终应围绕下面的业务主链建设：

学习者输入 / 学情数据
        ↓
学情诊断与任务理解
        ↓
多智能体协同决策
        ↓
领域知识检索 / 工具调用
        ↓
个性化资源生成
        ↓
审核、评估与迭代修正
        ↓
学习交互与测试反馈
        ↓
学习状态更新 / 下一轮训练决策

2. 当前代码底座

当前仓库已经具备一套可运行的通用多智能体编排底座，主要包括：

多智能体核心

src/core/

• Agent 基础抽象；
• 消息、上下文与类型系统；
• Agent 执行接口与错误处理。

协作与通信

src/collaboration/、src/communication/

• 串行协作；
• 并行协作；
• 专家组；
• 辩论、审核等协作模式；
• 多种 Agent 通信结构。

深度规划与协同执行

src/orchestration/

当前核心链路为：

DeepPlanner
   ↓
任务拆解 / Agent 分工 / 依赖关系
   ↓
AgentCluster
   ↓
并行或依赖驱动执行
   ↓
工具调用 + 共享记忆
   ↓
DeepEvaluator
   ↓
质量不足时重新规划与迭代
   ↓
最终综合输出

这部分是真实代码能力，不是前端演示动画。

多模型运行时

src/models/

• 多模型 Provider 注册；
• 模型路由；
• 按任务复杂度和能力选择模型；
• OpenAI-compatible 模型接入。

共享记忆与工具

src/memory/、src/tools/

• Agent 间共享任务信息；
• 工具注册和调用；
• Agent-as-Tool 等扩展能力。

动态工作流

src/workflow/

支持自动生成并运行多阶段协作流程，包括流水线、并行处理、预算控制和结构化结果。

学习产品服务端

server/

• Express API；
• Cookie 登录与学习者数据隔离；
• 学习路径、证据、资源、笔记与作答持久化；
• 多智能体学习任务执行与消息轮询。

前端

web/

当前是 Next.js 前端，产品入口由四个工作台组成：

• 学习路径：查看知识树、画像和证据驱动的学习建议；
• 协同学习：引用路径节点，观察检索、生成、审核与发布过程；
• 学习资源：阅读讲义、查看 PPT、做分层习题、浏览知识脉络、记笔记并回传反馈；
• 验证：复核运行产物、Claim 证据链、裁决结果和离线完整性校验。

3. 当前阶段必须认清的边界

现有代码底座的强项是“通用多智能体编排”，但挑战杯作品不能停留在这里。

比赛真正需要继续产品化和领域化的是：

1. 学习者画像层：把学历、先验测试、知识点掌握度、学习历史等变成真实状态，而不是一次性 Prompt 文本；
2. 领域知识层：建立可检索、可引用、可审核的专业知识库；
3. 个性化资源层：生成讲义、PPT、分层习题和知识脉络四类资源，并和学习者能力匹配；
4. 反馈学习层：根据答题、交互和资源使用结果更新学习状态；
5. 比赛创新层：把多智能体交叉验证、审核、争议处理与决策依据做成可解释机制，而不是只展示“有几个 Agent”；
6. 评测层：围绕幻觉率、资源难度适配率、核心知识覆盖率等比赛指标做真实评估。

换句话说：

通用 Multi-Agent Runtime ≠ 最终挑战杯产品

通用底座应该成为比赛领域内核的基础设施，而不是最终叙事本身。

4. 品牌约定

项目统一名称：

IM-Training-Agent

代码包名使用 npm 合法的小写形式：

im-training-agent

新的运行环境变量优先使用：

IM_TRAINING_AGENT_LEARNING_DB
IM_TRAINING_AGENT_DATASET_DB
IM_TRAINING_AGENT_METROPT_CSV

5. 本地运行

环境要求

• Node.js 18+
• 可用的大模型 API Key

安装依赖

pnpm install

模型配置

项目提供 DashScope qwen-plus 作为无运行时设置时的基础回退，也支持在设置页接入任意 OpenAI-compatible 模型服务。添加服务时系统会读取服务商的模型目录；上下文窗口和输出预算在服务端自动同步、缓存和降级处理，不要求用户填写，也不在普通界面展示。实际执行模型始终以设置页选择为准。真实密钥只放在本地 .env 或 Git 忽略的运行时配置中：

DASHSCOPE_API_KEY=your-dashscope-api-key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen-plus

也可以在根目录 models.config.ts 提供部署时的模型服务初始值；设置页保存的本机配置会覆盖同名初始值。

启动后端

pnpm server

默认地址：http://localhost:3001

启动前端

另开终端：

pnpm --dir web dev

默认地址：http://localhost:3000

平台基础设施：PostgreSQL + Redis（挑战杯主线）

技术总规见 docs/挑战杯技术开发总规.md。PostgreSQL 16 + pgvector 是唯一业务数据源，Redis 7 只负责 BullMQ 队列、锁与 run 事件分发。两者以 Docker 容器运行（数据落在 Docker 的数据磁盘中）：

docker compose up -d postgres redis   # 启动数据库与队列
pnpm db:migrate                       # 应用 PostgreSQL schema 迁移

.env 中配置 DATABASE_URL 与 REDIS_URL（见 .env.example）。运行时只连接 PostgreSQL 16 + pgvector；若本机 5432/6379 已被原生服务占用，在 .env 中改用 POSTGRES_PORT/REDIS_PORT 指定空闲端口。

可选网络补全：SearXNG

SearXNG 是一个可选检索插件，不替代 PostgreSQL，也不会变成启动应用的前置条件。默认关闭；启用后，流程是“本地 SQL + 文档混合检索 → 必要时网络摘要补全 → 领域分析 → 资源生成 → Claim 审核”。

• 仅在本地文档证据偏少、用户明确询问最新资料/标准/论文，或 Claim 复核要求寻找反证时调用；
• 当前只接收 SearXNG 的标题、摘要、链接与搜索引擎名：结果即时进入 EvidencePack，同时最多三个规范化 URL 登记为 web_search 候选；不下载网页正文，也不写入向量库；
• 每条网络结果以 web_search 证据类型记录，可信度为低，不能替代本地结构化数据和领域文档的交叉验证；
• 包含密钥、邮箱、手机号或身份证号的查询会被隐私门禁拦截，不会转发；服务不可用、超时或返回异常时自动退回本地证据链。

启动本机搜索服务并在 .env 中把 SEARXNG_ENABLED=true 后，重启 pnpm server 和 pnpm worker：

docker compose --profile search up -d searxng
curl "http://127.0.0.1:8088/search?q=工业设备轴承故障诊断方法&format=json"

注意：SearXNG 本身在本机运行，但它会把经过隐私门禁的检索词转发给所启用的公开搜索源；“本地部署”不等于搜索请求永远不出网。候选账本只保存哈希后的查询元数据，搜索摘要必须经过正文抓取、许可证确认和智能策展后才可能进入正式知识库。部署配置和可调阈值见 .env.example，搜索状态可由已登录用户通过 GET /api/learning/web-search/status 查看。

受管资料候选库与智能策展

本地资料不再直接复制为知识卡。资料包会先进入候选区，保留原件 SHA-256、抽取文本、解析质量、来源版本与候选状态；正式切片由服务端 knowledge-curator 按相关性、质量、重复风险与隐私门禁自动决定，不要求普通学习者承担资料管理员职责。升级前已有的知识卡与 MetroPT-3 说明保持可用。

pnpm db:migrate
pnpm knowledge:ingest ".\\资数据收集料.zip"

导入命令仅接受 ZIP 内的 PDF 与 Markdown，先检查路径穿越和格式，再用本机 pdftotext 抽取 PDF。资料原件被保存到 Git 忽略的 data/knowledge/sources/，导入包与暂存文件同样不提交；重复导入相同包时会返回 newCandidateVersions: 0。候选资料在智能策展通过前不会写入 document_chunks，也不会被学习 Agent 引用。

对已登记的本地候选资料运行内部策展任务：

pnpm knowledge:curate

任务逐份调用领域策展智能体；通过的本地正文候选才会生成版本化切片，低置信度资料继续留在候选区。仅有 SearXNG 摘要的候选会被明确保留，等待受限正文抓取和许可证确认；含敏感信息的资料会被拒绝并关闭检索资格。

用户上传资料默认只在本次任务内使用，设置页不提供人工审核入口。用户可在上传时明确同意“允许智能体沉淀”，服务端随后只向领域策展智能体发送有限摘录，并先执行凭据/个人信息阻断；只有达到相关性、质量、重复风险门槛的资料，才会以版本化来源写入本地知识库。评估失败、低质量、疑似重复或含敏感信息时，原文不会保存。

同时启动

pnpm dev:full

准备完整 MetroPT-3 数据（可选）

仓库默认包含 AI4I CSV、MetroPT-3 字段/故障窗口说明和知识卡，因此不下载大文件也能运行。需要完整的 151 万行 MetroPT-3 时序训练时，在 Windows 执行：

pnpm data:metropt

脚本从 UCI 官方地址下载约 208 MB 的 CC BY 4.0 数据包、校验 SHA256，并只解出 CSV。CSV 被 Git 忽略；后端下次启动时会自动导入 PostgreSQL。也可以通过 IM_TRAINING_AGENT_METROPT_CSV 指向已有文件。

6. 目录结构

IM-Training-Agent/
├─ src/
│  ├─ core/              # Agent 核心抽象
│  ├─ orchestration/     # 深度规划、Agent 集群与质量评估
│  ├─ collaboration/     # 多智能体协作模式
│  ├─ communication/     # Agent 通信结构
│  ├─ models/            # 多模型注册、路由与客户端
│  ├─ memory/            # 共享记忆
│  ├─ tools/             # 工具系统
│  └─ workflow/          # 动态工作流
├─ server/               # Express 学习产品服务
├─ web/                  # Next.js 前端
├─ docs/                 # 当前代码唯一技术基线
├─ data/                 # 知识库、数据集与画像导出
├─ models.config.ts      # 模型配置
└─ 挑战杯.md             # 官方赛题与评分要求

文档维护边界固定如下：README 负责仓库入口、运行方式和当前产品总览；docs/挑战杯技术开发总规.md 负责代码架构、数据契约和当前验收口径；所有评委可见的作品介绍、设计实现、测试、评测、部署和提交清单只维护在 提交包-湖南师范大学—佘硕—智辩无幻—17267081925/。findings.md、progress.md 和 task_plan.md 只记录内部决策与过程，不作为比赛材料副本。

7. 开发原则

后续开发应遵循以下原则：

• 测试通过只是底线，不等于产品完成；
• 所有比赛展示功能必须有真实后端状态和数据链路支撑；
• 不通过堆叠 Agent 名称包装创新；
• 不把一次 Prompt 生成伪装成持续学习；
• 多智能体过程要能够实时、自然地展示，而不是任务结束后一次性回放；
• 用户可见内容优先使用中文，技术协议、代码标识和第三方标准名按需要保留英文；
• 任何“高准确率、低幻觉率、个性化有效”等结论都应由可复现评测支撑。

8. 比赛目标

最终作品应能够在一次完整演示中清晰呈现：

不同背景学习者
   ↓
差异化学情诊断
   ↓
多智能体实时协作与决策
   ↓
专业知识约束与交叉校验
   ↓
个性化学习资源
   ↓
学习 / 作答反馈
   ↓
学习状态更新
   ↓
下一轮个性化训练

这条闭环才是 IM-Training-Agent 作为挑战杯项目最重要的产品主线。