帮助中心

注册后，按以下顺序操作即可拿到一个能上线的 AI 客服：

1. 建一个 Agent：去 体验台，填 LLM 服务商 + API Key。
2. 导入知识：在 网站管理 抓取你的官网或文档。
3. 嵌入到网站：在 平台配置 → AI 模型 拿嵌入代码，粘进网页 `<body>` 末尾。

遇到 LLM 调用失败：去 AI 设置确认 API Key 和模型名拼写。

在 体验台 可以创建和调试 Agent。建议先把“这个 Agent 代表谁、应该解决哪些问题、不能回答什么”写清楚，再选择合适的 LLM 服务商和模型。

• 模型与 API Key：确认服务商、模型名和密钥可用；如果调用失败，优先检查密钥额度、模型名拼写和平台配置。
• 人设与边界：用第一方客服口吻说明品牌、职责、禁止承诺的内容，以及遇到未知问题时如何处理。
• 回答长度：默认应把用户问题解释清楚，不要只给极短答案；但结尾不要追加“如果你还想了解……”这类引导继续提问的话术。
• 测试方式：用真实客户问题反复测试身份介绍、产品介绍、价格咨询、售后问题和无法回答的场景。

上线前建议同时测试中英文提问、短问题、追问、多轮上下文和知识库命中效果。

每个 agent 在「AI 模型配置」页有一段嵌入代码，长这样：

<script src="https://your-domain/sdk.js"
  data-agent-id="agt_xxxxx"
  data-color="#14b89d"
  async></script>

放在网站 `</body>` 之前即可。常见自定义参数：

• data-color：主题色
• data-title：客服小窗标题
• data-position：bottom-right / bottom-left

跨域限制：必须先在「工作区设置」→「白名单」加你的网站域名。

去 API Tokens 页生成一条 token (pat_xxx)，调任何 v1 接口时加上：

curl https://your-domain/api/v1/agents:list \
  -H "Authorization: Bearer pat_xxxxxxxxxxxx"

三种权限范围：

• 只读：仅 GET 端点
• 读写：能改 agent / 知识库，不能改订阅
• 全权限：等同 owner

Token 明文只显示一次，丢了重新生成。

在 网站管理 中可以把官网、文档站、帮助中心等页面抓取为 Agent 可引用的知识。适合内容已经发布在网页上的产品介绍、FAQ、价格说明和政策条款。

• 单页 URL：只导入某一个页面，适合重要落地页或单篇文档。
• 抓取深度：控制从入口页继续访问链接的层级；深度越大，覆盖越广，但也更容易抓到无关页面。
• 最大页数：限制本次抓取页面数量，避免误抓全站或消耗过多额度。
• 自动抓取：用于定期更新已导入网页，适合经常变化的官网、帮助文档和公告页。

导入后建议在体验台用页面中的真实问法测试答案；如果回答不准确，优先检查网页正文是否清晰、是否被登录墙或脚本渲染阻挡。

在 渠道 页面可以管理不同入口，让同一个 Agent 服务网站访客或第三方平台用户。每个渠道应绑定正确的 Agent，并按平台要求配置回调、Token 或机器人参数。

• 网站 Widget：适合官网、SaaS 后台、文档站等网页入口，通过嵌入脚本加载聊天窗口。
• 第三方渠道：例如 Telegram 机器人，用于把外部平台消息接入统一会话和知识库。
• 会话统一：不同渠道进入的消息都会进入会话中心，方便 AI 自动回复、人工接管和历史追踪。

配置完成后请分别从真实网页或真实机器人发送消息测试，确认消息能进入会话中心、AI 能回复、人工接管能生效。

套餐管理在 订阅与账单 页。

• 升降级：选档位直接付，差额按 Stripe 规则算。
• 到期不续费：周期结束自动转入 7 天宽限期，再过期。可随时撤销。
• 换支付方式 / 看发票：点 "管理支付方式 / 发票"，跳到 Stripe Customer Portal。
• 按量计费：plan 配置了 metered_* 字段时，超出包含量的部分次日上报 Stripe。

去 团队成员 页：

1. 「邀请」→ 填邮箱 + 选角色 → 拿到邀请链接
2. 把链接发给对方，对方登录后点击 → 自动加入

5 个系统角色：

• Owner：全权限 + 改账单 + 删工作区
• Admin：管 agent + 成员，不能改账单
• Editor：编辑 agent / 知识库
• Operator：人工接管会话
• Viewer：只读

邀请的 email 必须等于被邀请人登录邮箱（防被截胡）。

访客在 widget 里点「转人工」后：

1. 会话出现在 会话中心，状态变为「人工接管」
2. 有 sessions.takeover 权限的坐席点「接管会话」→ 自动 assign 给自己
3. 窗口里直接回消息；访客看到的是统一对话流
4. 处理完点「停止接管」让它回到无人认领状态，其他坐席可以接手

消息和会话状态实时推送（WebSocket），无需手动刷新。

在 告警 Webhook 配 Slack / 钉钉 / 飞书机器人 URL，订阅以下事件：

• 转人工请求 / 新成员加入
• 订阅即将到期 / 已过期 / 套餐变更
• 配额预警 (即将达到限制)
• AI 错误 (连续失败)

每条 webhook 独立选事件 — 比如运维群只看订阅相关，客服群只看转人工。

钉钉自定义机器人的"安全设置"建议选"自定义关键词"，关键词填 "VAgent"。

用量总览 用于观察消息量、Agent 占比、配额使用和访客满意度；审计日志 用于追踪关键操作是谁在什么时候执行的。

• 配额监控：关注今日消息数、Agent 数、网页知识源和 Q&A 数量是否接近套餐上限。
• 质量观察：通过满意度、会话量趋势和不同 Agent 的使用占比判断哪些入口需要优化。
• 安全追踪：审计日志记录成员变更、角色调整、订阅操作、工作区删除和管理员重置密码等高风险行为。

平台管理员可以从 平台总览 和管理后台维护全局能力，确保多租户、套餐、模型和支付配置正常运行。

• 账号与角色：管理用户、重置密码、配置角色权限，控制谁能访问管理功能。
• 套餐与订阅：维护套餐可见性、额度、价格和订阅状态。
• AI 模型与系统配置：配置可用模型、默认服务商、RAG 参数、SMTP、OAuth、Sentry 和指标令牌。
• 支付配置：维护 Stripe Key、Webhook Secret 和价格 ID，确保订阅、发票和按量计费可同步。

系统每天凌晨 4 点 (UTC) 自动备份 SQLite 数据库到 /app/data/backups/，保留最近 14 天。

super_admin 可在 平台总览 立即触发一次备份。

恢复：把对应 .db.gz 解压并替换 vagent.db，重启服务即可。

生产环境建议把 VAGENT_BACKUP_DIR 指到挂载的持久卷或 NFS，并定期同步到云上 (S3 / OSS)。

在 工作区设置 的「双因素认证」区块：

1. 点「启用 2FA」→ 用 Google Authenticator / 1Password 扫码
2. 输入 App 显示的 6 位数字 → 完成
3. 务必保存 8 条恢复码，手机丢了就靠这个登

所有恢复码用过或丢了：点「重新生成恢复码」让旧的全部作废。

用户在工作区设置里有两个按钮：

• 导出我的数据：打包 zip 含账号、所属 workspace、agent 配置、知识源、会话与消息
• 注销账号：密码二次确认后软删除 + PII 擦除；唯一 owner 必须先转交或删 workspace

审计日志默认保留 180 天 (可改 AUDIT_LOG_RETENTION_DAYS)；超出后自动归档清理。