SmartHub

SmartHub 是一个面向跨境企业的询盘成交 Agent 工作台。它不做泛化的“万能 Agent 平台”，而是围绕一条可交付的外贸业务链路展开：

企业知识库 -> 询盘接入 -> 客服接待 -> RFQ 拆解 -> 报价草稿 -> 人工风控审批 -> 客户跟进 -> CRM 任务

项目目标是帮助外贸工厂、产业带服务商和跨境代运营团队，把零散的客户询盘、产品资料、认证文件、报价规则和跟进动作，收敛成一个可追踪、可审批、可复盘的成交闭环。

核心价值

• 面向真实业务闭环：从询盘录入到报价审批、跟进邮件和销售任务，形成端到端流程。
• 企业知识库驱动：产品能力、认证文件、FAQ、MOQ、交期、报价规则和禁用承诺都可维护、核验和引用。
• RFQ 自动结构化：从客户原始询盘中抽取数量、市场、认证、交期、包装、港口、贸易条款和风险字段。
• 报价不直接外发：Agent 可以生成报价草稿，但价格、认证、交期、付款等外部承诺必须经过人工审批。
• Agent Run 可追踪：记录每次 Agent 的输入、输出、状态、置信度、风险说明和所用模型。
• 演示与开发都可运行：内置 Node.js 后端同时提供静态前端和 /api/v1/* 工作流 API；无真实模型密钥时自动回退到本地规则 Agent。

功能清单

询盘与客户

• 询盘配置表单：企业、客户、来源、产品、目标市场、能力卖点和原始询盘。
• 询盘收件箱：集中查看多条询盘，支持切换当前处理对象。
• 客户详情：展示客户询盘历史、RFQ、报价、审批和跟进资产。
• 询盘状态流转：新询盘、待补充、待报价、待审批、已报价、已跟进等业务阶段。

知识库与合规

• 企业知识库条目管理：产品、认证、报价、交付、风控、FAQ。
• 条目状态：缺失、草稿、已核验。
• 文件元数据管理：证书、测试报告、验厂文件、有效期、适用市场和是否可外发。
• 知识库覆盖度统计，帮助判断当前资料是否足够支撑报价和客户回复。

RFQ 与报价

• RFQ 拆解：数量、国家、认证、Logo/包装、交期、目的港、贸易条款、付款条款。
• RFQ 编辑：业务人员可以人工补齐或修正字段。
• 三档报价草稿：标准款、品牌定制款、包装升级款。
• 报价金额和毛利自动计算。
• 客户报价单 HTML 预览和导出。

审批与风控

• 报价审批中心：集中查看待审批报价。
• 角色权限：销售可创建询盘和报价，审批人负责批准或驳回，管理员拥有完整权限。
• 风控边界：报价、认证、交期、付款、独家供应等承诺不能由 Agent 自动外发。
• 审批通过后才允许生成客户跟进邮件。

跟进与任务

• 审批通过后生成英文报价跟进邮件。
• 本地 outbox 记录发送状态。
• 发送后自动创建 CRM 跟进任务。
• 顶部指标自动更新：待处理询盘、已发跟进邮件、报价机会额、风险拦截率。

AI / Agent

• 支持三种模式：
  • 本地规则 Agent：默认启用，不需要 API Key。
  • OpenAI Responses API：配置 OPENAI_API_KEY 后启用。
  • GLM / OpenAI-compatible Chat Completions：配置 GLM Key 后启用。
• 当前模型能力接入点：
  • RFQ 抽取。
  • Agent Run 编排。
  • 报价跟进邮件草稿。

技术架构

SmartHub
├─ index.html              # 主页面结构
├─ styles.css              # 工作台样式
├─ app.js                  # 前端启动、渲染和事件编排
├─ src/
│  ├─ api/                 # 前端 API 封装
│  ├─ domain/              # RFQ、报价、知识库、Agent、跟进邮件等领域逻辑
│  ├─ state/               # 浏览器本地状态和演示数据
│  └─ ui/                  # 拆分出的 UI 渲染模块
├─ server/
│  ├─ app.js               # HTTP 服务和 /api/v1 路由
│  ├─ aiProvider.js        # OpenAI / GLM / 本地规则 Agent 适配
│  ├─ db.js                # 本地 JSON 数据持久化
│  ├─ mailService.js       # 本地 outbox 邮件发送模拟
│  └─ seed.js              # 初始演示数据
├─ data/                   # 本地运行数据
├─ docs/                   # 产品、API、数据模型和工程化文档
└─ tests/                  # Node test 测试

后端是零依赖 Node.js 服务，负责两件事：

• 提供静态前端页面。
• 提供 /api/v1/* 工作流 API。

前端会优先使用后端 API。如果后端不可用，部分演示状态会回退到浏览器 localStorage，但登录、审批、发送等完整闭环建议始终通过 Node 后端访问。

快速开始

环境要求

• Node.js 18 或更高版本。
• npm。

启动

npm run dev

默认访问：

http://localhost:8000

如果 8000 端口已被占用，可以换端口：

$env:PORT=20000; npm run dev

然后访问：

http://localhost:20000

注意：不要只用 Python / VS Code 静态服务器打开页面。静态服务器没有 /api/v1 后端接口，登录和工作流 API 会失败。

演示账号

角色	邮箱	密码	权限
管理员	admin@smarthub.local	admin123	完整工作流权限，包括知识库、设置、审批和发送。
销售	sales@smarthub.local	sales123	询盘、RFQ、报价草稿、跟进、Agent Run；不能批准报价。
审批人	approver@smarthub.local	approve123	报价审批和 Agent Run；不能维护知识库和发送跟进。

推荐演示流程

1. 打开本地地址，例如 http://localhost:20000。
2. 使用管理员账号登录。
3. 在左侧“询盘成交配置”中填写或载入样例：
   • 行业解决方案。
   • 企业名称。
   • 客户名称。
   • 询盘来源。
   • 主推产品。
   • 目标市场。
   • 企业能力与卖点。
   • 海外客户询盘。
4. 点击“全自动处理当前询盘”。
5. 在 Agent Command Center 查看流程推进：
   • 询盘接入。
   • RFQ 拆解。
   • 知识匹配。
   • 报价草稿。
   • 风控审批。
   • 客户跟进。
6. 进入“询盘收件箱”，补齐 RFQ 字段，例如目的港、贸易条款、付款条款。
7. 进入“RFQ 与报价”，查看三档报价草稿、修改价格或导出 HTML 报价单。
8. 进入“成交工作台”，填写审批备注并批准报价。
9. 审批通过后生成跟进邮件，点击发送或标记已发送。
10. 查看 CRM 跟进任务和顶部指标是否更新。

AI 模型配置

默认情况下，SmartHub 使用本地规则 Agent，便于无密钥环境下稳定演示。

OpenAI Responses API

$env:SMARTHUB_AI_PROVIDER="openai"
$env:OPENAI_API_KEY="sk-..."
$env:SMARTHUB_OPENAI_MODEL="gpt-5.5"
npm run dev

可选：

$env:SMARTHUB_OPENAI_REASONING_EFFORT="low"

GLM / OpenAI-compatible Chat Completions

$env:SMARTHUB_AI_PROVIDER="glm"
$env:SMARTHUB_GLM_API_KEY="sk-..."
$env:SMARTHUB_GLM_MODEL="glm-5.1"
npm run dev

如果比赛平台提供自定义兼容端点：

$env:SMARTHUB_GLM_BASE_URL="https://open.bigmodel.cn/api/paas/v4/chat/completions"

查看模型状态

页面右上角会显示当前 API / Agent 状态。也可以请求：

GET /api/v1/ai/status

常用命令

# 启动本地服务
npm run dev

# 语法检查
npm run check

# 运行测试
npm test

API 概览

接口统一前缀：

/api/v1

主要接口：

模块	接口
认证	POST /auth/login, GET /auth/me
AI 状态	GET /ai/status
统计	GET /analytics/summary
公司与设置	GET /company, GET /settings, PATCH /settings
知识库	GET/POST /knowledge-items, PATCH /knowledge-items/{id}, POST /knowledge-items/{id}/verify
文件	GET/POST /files, POST /knowledge-items/{id}/files
询盘	GET/POST /inquiries, GET/PATCH /inquiries/{id}
RFQ	POST /inquiries/{id}/extract-rfq, PATCH /rfqs/{id}
自动流程	POST /inquiries/{id}/auto-run
报价	POST /rfqs/{id}/quote-drafts, PATCH /quote-drafts/{id}
审批	POST /quote-drafts/{id}/submit-approval, GET /approvals?status=pending, POST /approvals/{id}/approve, POST /approvals/{id}/reject
跟进	POST /quote-drafts/{id}/follow-ups, POST /follow-ups/{id}/send, POST /follow-ups/{id}/mark-sent
任务	GET /tasks?status=open, POST /tasks/{id}/complete
Agent Run	GET/POST /inquiries/{id}/agent-runs

更完整的 API 合同见 docs/API_CONTRACT.md，后端说明见 docs/BACKEND_V1.md。

数据持久化

本地后端数据存储在：

data/smarthub.json

邮件发送模拟记录存储在：

data/outbox.json

如果需要重置后端演示数据，可以停止服务后删除 data/smarthub.json，下次访问 API 时会根据 server/seed.js 自动重建初始数据。

浏览器侧还会保存部分演示状态到 localStorage。页面左侧提供“导出状态”“导入状态”和“重置演示数据”入口，用于演示备份和恢复。

测试说明

项目使用 Node.js 内置测试框架。

npm test

当前测试覆盖：

• RFQ 字段抽取。
• 报价草稿生成和金额计算。
• 知识库覆盖度计算。
• Agent Run 风控阻断规则。
• 审批后的跟进邮件生成。
• 报价单 HTML 渲染。
• 后端 API 从询盘到审批、跟进、任务的主链路烟测。
• OpenAI / GLM Provider 的配置路径测试。

当前交付边界

当前版本已经具备可演示、可测试、可本地持久化的完整 V1 闭环：

• 前端工作台。
• Node.js 后端 API。
• 本地 JSON 数据存储。
• 演示登录和角色权限。
• 知识库、文件元数据、询盘、RFQ、报价、审批、跟进、任务、统计和 Agent Run。
• 本地规则 Agent，以及 OpenAI / GLM 的可选接入。

尚未接入生产级能力：

• 生产数据库，例如 PostgreSQL。
• 真实文件上传和对象存储。
• 真实邮件、CRM、WhatsApp、ERP 集成。
• 多企业租户隔离和生产级鉴权。
• 模型评测、监控、审计和提示词版本管理。

文档索引

• 产品路线图
• 数据模型
• API 合同
• 后端 V1 说明
• 前端工程化计划

参赛说明

SmartHub 的参赛重点不是“聊天式泛 Agent”，而是一个能真正落到跨境业务操作台里的 Agent 工作流。它把企业知识、客户询盘、RFQ、报价、审批和跟进放在同一条链路里，让 Agent 输出始终受到业务资料、审批权限和风险边界约束。

评审时建议重点体验：

• 使用自然语言询盘触发 RFQ 结构化。
• 查看 Agent Command Center 中的阶段状态。
• 补齐 RFQ 后生成报价草稿。
• 使用审批角色批准或驳回报价。
• 审批通过后生成并发送跟进邮件。
• 观察顶部业务指标、CRM 任务和 Agent Run 记录的变化。