NanZi AI 开源智能体平台 · 疑难解答与常见问题手册 (FAQ)

💡 最新实时版本提示：本手册随 NanZi AI 智能体平台代码持续迭代更新（最后更新：2026-09-18）。如需查看最新实时的第一手技术文档与更新记录，请查阅 GitHub 官方源文件：https://github.com/RandyChen1985/nanzi-ai-agent-platform/blob/main/FAQ.md

欢迎查阅 NanZi AI 开源智能体平台 常见问题与疑难解答手册。本手册按照平台左侧功能菜单结构进行编排分类，包含通俗易懂的原理机制解析、小白用户常见概念混淆答疑，以及各类运行环境配置与异常排查方法。

一、平台概览与基础环境

1.1 推荐运行依赖与系统要求

• 操作系统：Linux (Ubuntu 20.04+/CentOS 7+/Debian 11+)、macOS (Intel/Apple Silicon)、Windows (WSL2)；
• Python 运行时：Python 3.11（推荐使用 uv 极速虚拟环境管理器，严禁使用 Python 3.10 或 3.12+ 专有语法）；
• Node.js 运行时：Node.js 18.18+ / 20.x（用于前端 Vite 7 + Vue 3 编译与构建）；
• 缓存与搜索引擎：Redis Stack Server 7.x+（必须包含 RediSearch 模块，不能使用裸 Redis 6.x）；
• 主数据库：MySQL 8.0+ 或 PostgreSQL 14+；
• 安全沙箱环境 (Docker)：
• 推荐主机安装 Docker 20.10+；
• 核心建议：当平台自身部署在 Docker 容器内运行时，强烈建议安全沙箱配置走 docker 策略（通过在平台容器启动时挂载 -v /var/run/docker.sock:/var/run/docker.sock）。若在平台主容器内使用 local 策略，所有 Agent 执行的 Shell 脚本和命令都会在平台后端主服务容器内裸奔执行，可能导致平台主环境被污染或崩溃；而配置为 docker 沙箱策略，可以为每个用户在宿主机 Docker 引擎上独立拉起纯净隔离的沙箱子容器，实现真正的操作系统级多租户安全隔离！

1.2 本地与服务器快速启动指南 (dev.sh)

平台根目录下提供了自动化启动脚本 ./dev.sh：

1. 前台调试启动 (实时查看编译与后端日志)：

   ./dev.sh

1. 后台常驻启动 (Daemon 模式，适合服务器部署)：

   ./dev.sh -d
   # 或
   ./dev.sh --daemon

1. dev.sh 核心特性：

• 自动检测并停止占用旧端口的服务进程；
• 自动校验 frontend/package.json 的校验和（Checksum），在依赖变更时自动执行 npm install；
• 动态解析 .env 中的 API_SERVICE_PORT（默认 8001），避免端口硬编码；
• 前端自动执行 npx vite build 产出静态资源并交由 FastAPI 统一托管。

1.3 核心逻辑：平台前后端是如何协作运行的？

+-----------------------------------------------------------------------------------+
|                           1. 客户端展示层 (Client UI)                             |
|  - Vue 3 + TypeScript + Tailwind CSS + Vite 7 (单页面应用 SPA)                    |
|  - 智能助手对话流 (SSE 流式输出) | 交互画布 Canvas (HTML/Vue/Markdown 渲染与双向编辑)    |
+------------------------------------------+----------------------------------------+
                                           |
                                           |  ① REST API (鉴权/配置/元数据)
                                           |  ② SSE 事件长连接 (打字机流式推送)
                                           v
+-----------------------------------------------------------------------------------+
|                        2. 接入与服务托管层 (Gateway & Service)                     |
|  - FastAPI (Python 3.11 异步框架，统一单端口托管 8001)                             |
|  - 静态资源路由 (自动托管 frontend/dist 编译产物，免额外 Nginx)                   |
|  - 权限拦截与双层鉴权 (menu:* 菜单权限 + element:* 细粒度操作权限)                |
+------------------------------------------+----------------------------------------+
                                           |
                                           |  ③ 意图路由与会话分发 (Router / Dispatcher)
                                           v
+-----------------------------------------------------------------------------------+
|                     3. 智能体核心运行时与编排层 (Agent Runtime)                   |
|  - AgentScope 2.x 核心编排引擎 (状态感知 / 两阶段上下文压缩 / 思考预算控制)       |
|  - 专家路由体系 (ChatBI 数据分析师 / 知识库问答专家 / 代码审计员 / 自定义子代理) |
|  - 动态能力挂载 (平台 Skill 技能包 + FastMCP / STDIO / SSE 外部工具服务)          |
+---------------------+--------------------+--------------------+-------------------+
                      |                    |                    |
       ④ 安全沙箱执行 |     ⑤ 状态与向量检索 |     ⑥ 业务数据持久化 |
                      v                    v                    v
+-----------------------------+ +---------------------+ +---------------------------+
| 4. 隔离执行层 (Sandbox)     | | 5. 缓存与向量引擎   | | 6. 主持久化存储 (DB)      |
| - Docker 隔离子容器 (推荐)  | | - Redis Stack 7.x+  | | - MySQL 8.0+ / PG 14+   |
| - In-Container FastMCP 网关 | | - RediSearch 向量召回| | - 库表元数据 / 字典标注  |
| - Local / E2B / SSH 策略    | | - 会话与 30 天状态TTL| | - 用户角色 / 审计 / 任务|
+-----------------------------+ +---------------------+ +---------------------------+

1. 统一单端口托管：开发与生产环境下，FastAPI 会自动挂载并托管前端构建生成的 frontend/dist 静态资源目录。用户只需访问 http://IP:8001 即可体验完整的 Web 界面与后端 API 服务，无需额外配置复杂的 Nginx 反向代理。
2. 流式打字与协议通信：对话采用标准的 Server-Sent Events (SSE) 流式长连接。后端在执行 Agent 思考、工具调用、文字输出时，实时向前端推送结构化事件流。

1.4 小白高频问题与排查 Q&A

1.5 首次安装/部署后的核心检查清单 (必改默认值)

在执行初始 SQL 导入（如 db-prod/ 或 db-prod-pg/）后，数据库中包含了一套通用的默认预置数据与占位符。为了确保平台各项功能（智能助手对话、ChatBI 查数、知识库检索、工件下载、沙箱执行等）能正常运转，首次安装上线后必须依次完成以下三大检查与配置变更：

graph TD
    A[📦 完成初始 SQL 导入] --> B[1️⃣ 系统管理 -> 模型管理
配置真实可用模型与 API Key]
    B --> C[2️⃣ 系统设置 -> 参数设置
调整平台底层全局关键参数]
    C --> D[3️⃣ 智能体中心 -> 配置与发布
克隆预置智能体并换绑自有模型]
    D --> E[🚀 平台全功能就绪！]

检查点 1：模型管理（配置接入您自己的大模型）

• 操作路径：系统管理 -> 模型管理
• 操作说明：
  1. 初始数据中自带示例模型提供商与占位模型（如占位的 API Key 与 Base URL）；
  2. 请进入【模型提供商】或【模型列表】页面，添加或编辑您实际采购/私有部署的模型服务（如 DeepSeek、OpenAI、Anthropic、Ollama、Qwen 等），填入真实的 API Key 与 Base URL；
  3. 配置模型能力标识（Chat 对话、Embedding 向量、Reasoning 思考、Multimodal 多模态），并点击“连通性测试”确保能正常返回。

检查点 2：参数设置（根据环境调整关键底层参数）

• 操作路径：系统设置 -> 参数设置
• 必查参数影响全景表：

检查点 3：预置智能体换绑模型（克隆旧配置进行修改与发布）

• 操作路径：智能体开发平台 -> 智能体中心 -> 点击对应智能体卡片上的 「配置与发布」
• 操作说明：
  1. 平台默认初始化了若干核心专家智能体（如 主助手 (Main Agent)、ChatBI 数据分析专家、全栈代码专家、元数据建模专家 (metadata-specialist) 等）；
  2. 导入的初始版本绑定的可能是初始占位的示例模型 ID。若直接发起对话或触发 DDL 智能导入解析，可能因调用占位模型报模型不存在或认证失败；
  3. 标准换绑与升级流程：
     • 在目标智能体的版本管理列表中，点击旧版本的 「克隆」 按钮复制一份新草稿配置；
     • 在新草稿配置中，将 「对话基座模型」 下拉切换为在【检查点 1】中已配置测试通过的自有可用模型；
     • 保存并点击 「立即发布并激活」，将新版本设为当前生效版本；
     • 对上述核心预置智能体（尤其是主助手、ChatBI 专家与元数据建模专家）依次执行此操作即可。

二、智能助手与交互画布 (Smart Assistant & Canvas)

2.1 核心逻辑：智能助手、交互画布与三大门户工作台的协同机制

平台智能助手不仅是一个聊天窗口，而是一个集 “对话思考 + 工件渲染 + 数据资产 + 知识检索 + 沙箱文件管理” 于一体的现代化 IDE 级 Agent 工作台：

+----------------------------------------------------------------------------------------------------+
|                                    智能助手主工作台 (Workspace)                                    |
+------------------------------------+---------------------------------------------------------------+
|  【左侧：对话与多智能体控制区】     |  【右侧 / 侧边抽屉：交互画布与辅助门户】                     |
|                                    |                                                               |
|  - 实时 SSE 打字机流式对话         |  1. 🎨 交互画布 (Canvas)：                                    |
|  - 思考过程 (Thinking CoT) 展开折叠|     - HTML/Vue/JS 前端组件实时沙盒渲染与交互                  |
|  - 工具调用参数与执行日志可视化    |     - Markdown/Diff/图表预览、在线代码编辑与一键回写          |
|  - 交互式提问卡 (Ask User) 确认    |                                                               |
|  - TODO 动态任务拆解与进度卡片     |  2. 📊 数据门户 (Dataset Portal)：                            |
|                                    |     - 结构化数据源/库表资产树、智能推荐分析问句一键注入       |
|                                    |                                                               |
|                                    |  3. 📚 知识库门户 (Knowledge Portal)：                        |
|                                    |     - 企业 RAG 文档集检索、文档级高频问答推荐、召回参数调优   |
|                                    |                                                               |
|                                    |  4. 📁 浏览本地空间 (Workspace Browser)：                     |
|                                    |     - 沙箱工作区目录树、文件上传/重命名/回收站、右侧即时预览   |
+------------------------------------+---------------------------------------------------------------+
|  【底部全能工具箱】：附件上传 / @专家直选 / /快捷指令 / 技能包与MCP挂载 / 模型与思考预算控制     |
+----------------------------------------------------------------------------------------------------+

1. 左右分栏与双向协同：对话区 vs 交互画布 (Canvas)

• 左侧（对话与控制区）：负责智能体的自然语言交流、思考过程（Thinking CoT）展开折叠、工具调用状态跟踪、AI 提问卡片确认及 TODO 任务清单分步跟踪；
• 右侧（交互画布 Canvas）：当智能体生成前端代码（HTML/JS/Vue）、数据图表、Markdown 技术方案、或通过工具产出交付物文件时，右侧画布会自动呼出并实时渲染工件（Artifact）。用户可以在画布中直接编辑代码、切换设备预览尺寸（PC/平板/手机），并一键保存写回沙箱工作区。

2. 数据门户 (Dataset Portal)：结构化数据资产即点即查

• 核心定位：专为 ChatBI 数据分析 打造的可视化资产抽屉与快速探索入口；
• 核心功能：
  • 资产全貌洞察：快速浏览当前项目或全局挂载的数据集、关联数据表、字段业务别名与语义字典；
  • 智能推荐提问：自动聚合该数据集下的高频推荐分析问题与自定义模版，点击即可直接将结构化提问注入聊天输入框；
  • 动态参数微调：支持在门户中一键配置幻觉校验开关、元数据召回 Top-K 及检索权重，无需进入后台即可即时调优。

3. 知识库门户 (Knowledge Portal)：私域非结构化知识精准探查

• 核心定位：专为 RAG 文档知识检索 打造的沉浸式知识抽屉；
• 核心功能：
  • 文档切片与知识源树：实时查看已挂载的知识库（由 RAGFlow 等引擎驱动）包含的文档清单、状态与字符量；
  • 文档级推荐问句：基于知识库切片内容智能推荐核心 Q&A，方便用户快速掌握知识库重点并一键发起精准提问；
  • 检索增强控制：可直接在抽屉中调节向量相似度阈值（Similarity Threshold）、混合检索向量权重（Vector Weight）及置顶偏好。

4. 浏览本地空间 (Workspace Browser)：沙箱工作区文件资产管理器

• 核心定位：智能体在安全沙箱（Docker / Local / E2B）中操作的本地真实文件系统可视化窗口；
• 核心功能：
  • 目录树与资产浏览：支持按项目、按会话多级展开查看智能体生成或读取的代码、CSV、日志、图片及音视频文件；
  • 画布即时联动：在文件列表中点击任意文件，右侧交互画布（Canvas）会立即无缝切换展示该文件内容，支持在线编辑并直接保存写回沙箱工作区；
  • 完备的文件治理：支持拖拽上传本地文件到指定沙箱目录、文件/目录重命名、复制相对/绝对路径给 Agent，以及多级防误删回收站 (Trash)（支持一键还原与彻底清空）。

5. 灵活的吸附停靠 (Pin & Docking) 机制

所有门户抽屉（数据门户、知识库门户、本地空间）均支持钉住 (Pin)、自定义拖拽宽度以及与交互画布同侧/对侧自适应排布。在复杂的多任务分析场景下，用户可以同时展开本地文件树与交互画布，实现“边看代码、边看数据、边对话”的流畅协同体验。

2.2 聊天输入框全能工具箱与会话作用域 (用户会话 vs 项目会话)

平台输入框不仅是一个文本框，而是一个全功能 Agent 协同工作台：

1. 多模态附件与剪贴板截图粘贴

• 点击附件图标：支持上传本地图片（PNG/JPG/GIF/WebP）、文档（PDF/Word/Excel/TXT/CSV 等）；
• 剪贴板极速粘贴：在任意界面截图后，直接在输入框按 Ctrl+V（Mac 为 Cmd+V）即可快速贴入图片缩略图，智能体将自动调用多模态 Vision 模型进行图像理解与 OCR 识别。

2. @ 提及呼出专家直选与自动路由

• 输入 @ 符号：输入框上方将弹出专家智能体下拉列表（如 @ChatBI数据分析师、@代码审计员）；
• 专家直选模式：选中专家后本轮对话将精准直达该专属智能体，享受其定制的 System Prompt 与限定工具；
• 自动路由模式 (Auto-route)：默认模式，系统根据用户意图语义由 Router 自动分发给最适合的智能体或由主助手全能接管。

3. / 斜杠呼出快捷指令 (Slash Commands)

• 输入 / 符号：即刻呼出预设快捷指令面板（例如常用 Prompt 模板、数据集快捷提问、代码评审模板等）；
• 选中后自动将结构化提示词填充到输入框中，支持一键发送，大幅提升高频任务操作效率。

4. 技能 (Skill) 与 MCP 工具动态级联挂载

• 技能挂载 (Skills)：点击输入框底部的技能图标，可级联浏览并动态勾选当前会话需要生效的技能包（如 brand-guidelines、doc-coauthoring），无需全局修改 Prompt；
• MCP 工具集选择：点击 MCP 按钮，可直观查看并切换当前挂载的 In-Container / STDIO / SSE 外部工具服务。

5. 权限审批模式 (Approval Mode)

在输入框下方可随时切换当前会话的工具执行安全级别：

• 请求批准 (ask，默认)：执行文件写入、Bash 命令等需确认操作前，AI 会先弹出交互确认卡，由用户点击确认后方才执行；
• 自动批准 (allow)：全自动极速模式，自动放行所有常规工具调用，仅在触发高危安全规则时拦截；
• 拒绝执行 (deny)：严格只读防护模式，禁止一切写入与远程执行工具。

6. 模型选择与深度思考强度 (Reasoning Effort) 调节

• 实时切换模型：支持在输入框底部的下拉菜单中随时切换不同的对话基座大模型（如 DeepSeek-R1、Claude 3.7 Sonnet、GPT-4o、Qwen 2.5 等）；
• 思考模型控制：针对推理模型（如 DeepSeek-R1 / QwQ），支持开关思考模式，并精细化调节思考预算强度（无 / 极简 / 低 / 中 / 高 / 极高）。

7. 会话作用域：普通用户会话 vs 项目专属会话 (Project Session)

许多用户在使用时容易混淆 「普通用户会话」 与 「项目会话」。为了解决企业级多业务域下的数据混淆、跨库误查以及资源冗余问题，平台设计了两种不同层级的会话隔离模型：

📊 普通用户会话 vs 项目会话 全维对比表

💡 为什么必须要有“项目会话”？

1. 防止大模型“跨库幻觉”与数据串问：在拥有几十甚至上百张数据表的大型企业中，若不限定范围，大模型容易在 Text-to-SQL 时错选同名或结构相似的无关数据表；项目会话从物理上锁定了 Schema 边界，确保 SQL 绝对精准；
2. 免受冗余干扰：项目会话下，右侧「数据门户」与「知识库门户」只会展示该项目相关的资产与推荐问题，大幅减少查找翻阅时间；
3. 安全合规与权限收敛：在向团队演示或进行专项目标交付时，项目会话保证了会话只触达预先授权的边界资源。

2.3 输入框浮标：Token 水位线、压缩日志与沙箱运行状态卡片

在聊天输入框右上角集成了多功能自适应状态浮标：

1. Token 水位线与用量健康度：
   • 动态环形进度条展示当前会话已占用的 Token 数量及扣除预留输出后的当前预算上限（默认 64k）的占比；
   • 状态徽标自适应提示（🟢使用正常 / 🟡接近上限 / 🔴已达输入上限）；
2. 上下文压缩历史时间线 (Compaction Timeline)：
   • 当多轮会话触发平台两阶段压缩或 AgentScope 内部上下文压缩时，浮标展示压缩次数入口；
   • 点击可展开时间线弹窗，查看各轮次提炼的高浓度摘要与节省比例；
3. 沙箱运行环境卡片与全生命周期运维控制台：
   • 展开浮标可直观查看当前生效策略（Local / Docker / E2B / SSH）；
   • 在 docker 策略下，卡片实时呈现容器运行状态（🟢已运行 / 🟡启动中 / 🔴失败 / ⚪未启动）、分配的私有 Container ID、秒级递增运行时长（如 运行中 12m 34s）、以及「空闲 30m 自动回收」资源说明；
   • 「操作 ▾」全生命周期下拉管理菜单：
     • 🖥️ 进入终端 (Interactive Shell Terminal)：点击呼出 macOS 交通灯风格的沉浸式深色 CLI 交互式终端模态框。用户可以直接在当前私有沙箱容器内交互式执行 Shell 命令（如 ls -la, pip list, python --version, cat /workspace/app.py 等），支持实时命令执行流回传、常用快捷指令预设栏（一键填入常用命令）、上下键快速切换历史命令记录、一键清屏与一键复制全部终端输出；
     • 🔄 重启容器 (Restart Workspace)：当沙箱内发生代码死锁、后台进程卡住或需要清理临时缓存时，一键自动强制销毁旧容器并重新拉起全新的纯净沙箱环境，物理工作区挂载文件完全保留；
     • ⏹️ 停止关机 (Stop Workspace)：手动主动关停当前沙箱容器并释放宿主机 CPU 与内存资源，无需等待 30 分钟空闲自动回收。

2.4 界面设置与四大智能特性 (FEATURES) 开关深度解析

在智能助手聊天界面的设置弹窗（⚙️ 界面设置）中，提供了针对当前会话的默认智能体选择以及 ⚡ 智能特性 (FEATURES) 四大核心能力开关。它们直接决定了当前会话的调度深度、安全边界与推理体验：

mindmap
  root((⚙️ 界面设置))
    🤖 默认主责智能体
      主助手 / ChatBI 专家 / 代码专家等
      确定优先承接与主责领域
    ⚡ 智能特性 FEATURES
      👥 多智能体协同
        跨领域任务并行执行
        子代理动态孵化
      📄 SQL PLAN 中间层
        高风险查数前校验执行计划
        拦截全表扫描与慢 Join
      💡 思考过程
        DeepSeek-R1 / QwQ 思维链
        默认展开推演过程
      🛡️ 反幻觉校验
        Grounding 取证比对
        事实来源与偏差风险提示

1. 默认主责智能体切换 (Default Agent Selector)

• 功能定位：用户可选择当前会话由哪位智能体优先承接（如“主助手 (Main)”、“ChatBI 数据分析专家”、“全栈代码专家”等）；
• 底层含义：

  “默认智能体优先处理当前问题；主智能体仍可按任务需要调用其他智能体，适合明确主责领域的场景。”

  • 当用户问题属于通用领域或该智能体所长时，由其直接主导解答；
  • 当遇到复合任务时，主智能体依然拥有发起二级子代理调度的中枢指挥权。

2. ⚡ 智能特性 (FEATURES) 四大核心开关深度拆解

2.5 右上角控制台：排版主题、单/多轮记忆、模型调用全维统计与调试

在智能助手页面右上角的工具栏中，提供了深度的个性化与可观测性配置：

1. 排版主题与代码高亮风格 (Typography Themes)：

• 内置 5+ 套精美排版主题（极简白、优雅蓝、护眼绿、暗黑极客等）；
• 自动匹配高对比度代码高亮配色与等宽字体，支持一键切换适合阅读或截图的渲染风格；

1. 单轮 / 多轮记忆模式 (Memory Mode)：

• 多轮记忆（默认）：智能体在多轮对话中保持连续上下文与用户意图；
• 单轮模式：每轮对话独立处理，不携带历史上下文，非常适合独立 Prompt 效果测试或快速单步提问；

1. 模型调用四维 Token 拆解与性能分析 (Model Call Stats Modal)：

• 点击调试图标可弹出当前轮次调用的全维度性能面板：
• 包含：首字响应延迟 (TTFT)、总耗时 (Latency)、物理上下文窗口占用比；
• 四维 Token 结构化分项占比图：精准拆解 System Prompt、Tools Schema、Memory/History 与 Current Turn 的 Token 占比，方便开发者优化 Prompt 空间；

1. 会话管理与工件导出：

• 支持一键清空当前会话记忆、导出完整对话为 Markdown 文件或复制嵌入链接。

2.6 浏览器自动化会话与实时投屏接管 (Browser Automation & Live Takeover)

平台提供了企业级的 服务端浏览器自动化运行时 (Browser Runtime) 与 可视化投屏交互面板 (Browser Panel)，让智能体具备像人类一样真实浏览互联网、操作 SaaS 系统的能力。

1. 底层架构与运行原理

+----------------------------------------------------------------------------------------------------+
|                                    浏览器自动化与投屏协同架构                                       |
+----------------------------------------------------------------------------------------------------+
|  【前端用户交互区 (Browser Panel)】                                                                |
|  - 实时远程画面投影 (Frame Stream / 视口截图渲染)                                                  |
|  - 用户事件捕获 (鼠标坐标映射点击、滚轮滚动、键盘输入、网址栏跳转)                                 |
|  - 动作安全模式切换 (安全确认 guarded vs 自动执行 autopilot)                                        |
+------------------------------------+---------------------------------------------------------------+
                                     |  ▲
             ① 动作转发与事件控制 (WS/API)|  | ② 页面截图 / 状态变化实时回传
                                     v  |
+----------------------------------------------------------------------------------------------------+
|  【服务端浏览器运行时 (Browser Runtime & FastMCP Gateway)】                                         |
|  - 浏览器内核驱动 (Playwright / Chrome DevTools Protocol CDP)                                      |
|  - 独立 Profile 空间 (隔离持久化 Cookie、LocalStorage 与登录凭据，防止租户串门)                     |
|  - 智能体动作执行器 (DOM 树语义定位、智能表单输入、点击、滚动、OCR 与多模态截屏)                     |
|  - 控制权仲裁器 (AI 自动执行态 vs 人工接管态互斥锁，避免并发冲突)                                   |
+----------------------------------------------------------------------------------------------------+

1. 持久化 Profile 隔离环境：为每个用户/会话维护独立的远程浏览器上下文，用户的登录状态、Cookie 会被持久化加密存储，下次打开无需重复登录，且不同用户间强隔离；
2. 事件双向映射与低延时投屏：前端面板展示的是远程浏览器的高保真实时视口投影。当用户在画面上点击、滚动或打字时，前端会将视口相对坐标与按键事件实时转发至服务端 CDP 驱动远程浏览器执行。

2. AI 自动执行 vs 人工实时协同接管 (Human-in-the-loop)

浏览器自动化采用 “AI 为主跑腿、人工兜底破局” 的人机协同模式：

• 🤖 AI 自动驾驶 (Autopilot)：
  • 智能体根据任务目标，自动分析网页 DOM 结构、定位按钮与输入框、按序填表、翻页抓取数据、下载报表；
  • 面板右上角支持切换 安全确认 (guarded) 与 自动执行 (autopilot) 模式。在安全模式下，表单提交、资产变更等关键动作会先弹窗提示用户确认。
• 👨‍💻 人工无缝接管 (Manual Takeover)：
  • 遇到验证码 (Captcha)：当遇到滑块验证码、短信二次验证或人脸识别等 AI 无法独立通过的环节时，用户可直接在右侧投屏画面中手动滑动、输入验证码；
  • 控制权互斥锁定：用户介入操作时，系统会自动将控制权切换为 human，自动暂停 AI 轮询与并发动作，避免人机同时操作产生页面状态冲突；
  • 一键交回 AI：人工完成登录或验证后，智能体会自动感应到页面跳转并无缝接续后续的自动化流程。
• 后台常驻与随时复看：
  • 关闭浏览器面板不会中断后台正在进行的自动化任务；用户可在任务执行期间随时重新呼出面板查看最新进展。

3. 权限分配与开启前置条件

[!IMPORTANT] 浏览器自动化能力默认未向所有普通智能体全量开放，必须按需单独授权！

1. 为什么需要单独授权？：浏览器自动化会产生服务端常驻进程、消耗内存/带宽，且具备主动访问外网的能力，出于系统安全与资源保护考虑，平台实行白名单权限制；
2. 如何为智能体开启浏览器权限？：
   • 平台管理员或智能体创建者需进入 「智能体中心」-> 编辑智能体 ->「工具配置 (Tools)」；
   • 勾选挂载 browser_* (服务端浏览器工具集) 或将该智能体绑定具有浏览器操作权限的角色；
   • 未挂载该工具集的智能体，在对话中无法唤起远程浏览器。

4. 企业级典型合规应用场景矩阵

浏览器自动化（AI + RPA + 实时投屏）在企业内部运营、系统集成与质量保障等领域具有极高的生产力价值。以下为平台推荐的 5 大核心合规落地场景：

5. 浏览器进阶：拟人化轨迹拖拽、Stale 元素自适应等待与多标签页管理

在复杂现代 Web 应用与企业级 SaaS 系统的自动化交互中，平台实现了三项关键技术突破：

1. 贝塞尔拟人化轨迹拖拽 (browser_drag)：
   • 针对滑块验证码与拖拽排序组件，系统内置了非线性变速加速度与微扰动机率模型，生成拟人化贝塞尔曲线滑动轨迹，大幅提升防爬滑块通过率；
2. Stale Element 自动恢复与显式可用性等待 (browser_wait_for)：
   • 现代 Vue/React 单页面应用在数据更新时会高频重绘 DOM。平台自动化内核支持元素就绪探测与自动重试，在页面异步刷新导致旧 DOM 句柄失效时自动重新拾取最新节点，彻底消除 StaleElementReferenceException 偶发报错；
3. 多标签页生命周期全控 (browser_tabs / browser_switch_tab / browser_close_tab)：
   • 支持智能体在多标签页之间自由切换、读取后台标签页状态、并在完成特定流程后自动清理关闭临时标签页，维持轻量运行状态。

6. 依赖组件安装与启动排查（源码部署 vs Docker 部署）

• 🐳 Docker 容器化部署（开箱即用，无需任何操作）：

  • 平台官方 Docker 镜像（[docker/Dockerfile](file:///Users/chenxiaolong/workspace/nanzi-ai-agent-platform/docker/Dockerfile)）在构建阶段已全量执行了 playwright install --with-deps chromium，镜像内已预置 Chromium 二进制与所有 Linux 动态库依赖，启动容器即可直接使用浏览器自动化功能。

• 💻 本地/物理机源码直接部署（常见漏装排查）：

  • 报错现象：调用 browser_* 工具或点击浏览器面板时，后端日志抛出 Executable doesn't exist at .../chrome-linux/chrome 或 Host system is missing dependencies to run browsers；
  • 根本原因：通过 pip install -r requirements.txt 只安装了 Playwright 的 Python 接口库，并没有自动下载 Chromium 浏览器内核及其底层运行依赖；
  • 一键修复与安装命令：
    • macOS / Windows WSL2 本地环境：
      Bash复制

      # dev.sh 已准备好项目 .venv；使用该环境安装浏览器内核
      .venv/bin/python -m playwright install chromium
      

    • 原生 Windows PowerShell：
      Powershell复制

      .venv\\Scripts\\python.exe -m playwright install chromium
      

    • Linux 服务器（Ubuntu / Debian / CentOS 等）：
      Bash复制

      # 安装 Chromium 内核及 Linux 底层图形/音频动态链接库 (需要 sudo 权限)
      .venv/bin/python -m playwright install --with-deps chromium
      

7. ⚠️ 安全合规与法律风险红线警示

[!CAUTION] 平台严禁将浏览器自动化能力用于任何违法、违规或高危场景！

1. 严禁用于非法攻击与渗透测试：严禁利用智能体对未经授权的第三方站点进行撞库、弱口令爆破、漏洞扫描或发起网络攻击；
2. 严禁恶意爬取与侵犯数据隐私：严禁绕过合法鉴权批量爬取个人隐私数据、商业机密或违反目标网站 robots.txt 与服务协议；
3. 严禁自动化高危敏感业务：涉及资金支付、重要系统删除、账户解绑等极度敏感的高危动作，必须始终由人工亲自复核执行，严禁全权委托 AI 自动提交；
4. 全链路审计与追溯：平台对所有浏览器会话的访问 URL、操作时间戳、请求参数及审计日志均进行不可篡改的持久化留存。请务必在企业规章制度与国家法律法规合规框架内规范使用！

2.7 小白高频问题与交互排查 Q&A

三、智能体开发平台

3.1 核心逻辑：智能体、技能 (Skill) 与 MCP 工具的区别与联系

很多刚接触 Agent 开发的用户容易混淆这三个概念，它们在平台中的分工如下：

graph TD
    Agent["🤖 智能体 (Agent)
大脑与核心角色，定义 Prompt 与人格"] --> Skill["📚 技能 (Skill)
专业知识与工作流指导手册 (Markdown)"]
    Agent --> MCP["🛠️ MCP 工具 (Tool)
具体执行代码/查数据/调 API 的手脚程序"]
    Agent --> Memory["🧠 记忆 (Memory)
长短期记忆与用户偏好库"]

• 智能体 (Agent)：是拥有独立人设、目标和决策逻辑的 AI 角色实体；
• 技能 (Skill)：是传授给智能体的领域专业工作流知识（以标准 SKILL.md 形式存储），告诉智能体“遇到这类任务应该分几步做、遵循什么规范”；
• MCP 工具 (Model Context Protocol)：是智能体用来与外界交互的可执行代码接口（如查询天气、执行 Python 脚本、操作浏览器等）。

3.2 智能体中心与多 Agent 协作

【智能体中心】（Agent Management）是平台对 AI 角色、能力边界、模型绑定、知识记忆与多 Agent 协同体系进行全生命周期管理的控制台。

3.2.1 智能体核心构建的“五大要素”

创建一个高水准的专业智能体，平台提供了五个维度的精细化配置：

mindmap
  root((🤖 智能体))
    👤 角色人设 Persona
      System Prompt
      行为准则与约束
      动态变量插值
    🧠 双模型绑定
      主对话模型
      深度思考推理模型
    🛠️ 技能与工具集
      标准 MCP 工具
      专业 SKILL 工作流
      内置代码与沙箱
    📚 知识挂载范围
      企业知识库
      向量检索阈值
      Top-K 召回上限
    🔒 运行策略与沙箱
      安全沙箱策略
      最大执行轮数
      多代理协作模式

1. 角色人设与 Prompt 工程 (Persona & System Prompt)：

• 定义智能体的专业身份、语气风格、输出格式规范及禁止行为；
• 支持动态环境变量注入（如 {{user_name}}、{{current_time}}、{{workspace_root}}），使智能体精准感知用户身份与现实时间。

1. 双模型协同绑定 (Main Model + Reasoning Model)：

• 主对话模型 (Main Model)：负责通用交互、对话规划与工具调度（如通义千问 Qwen-Max、GPT-4o、DeepSeek-V3 等）；
• 思考推理模型 (Reasoning Model)：负责复杂数学运算、深度逻辑推演与多分支决策（如 DeepSeek-R1、QwQ-32B 等），支持输出 <think> 深度思考链。

1. 技能与工具集动态装载 (Skills & Tools)：

• 系统内置工具：代码解释器（Bash）、文件读写、网页浏览、工件发布等；
• 专业技能库 (Skills)：挂载领域专精的 SKILL.md（如金融对账、合同法务审查、爬虫解析）；
• 外部 MCP 扩展：无缝调用接入的外部数据库、内部 ERP/CRM API。

1. 私有知识库范围限定 (Knowledge Scope)：

• 指定该智能体仅允许检索哪些特定知识库，设置精准的相似度过滤阈值，避免不相关知识干扰。

1. 执行策略与沙箱环境 (Execution Policy & Sandbox)：

• 为该智能体单独指定运行沙箱（继承全局 / 强制 Docker / E2B / Local），设置最大执行步数（Max Steps）防范死循环。

3.2.2 多智能体协同编排与子代理机制 (Subagents Architecture)

在处理极其复杂的跨领域任务（如“先全网调研行业竞品，再编写后端 API 代码，最后生成可视化 HTML 报告”）时，单个智能体容易因为上下文过长而遗忘关键细节。

平台引入了主代理 + 专家子代理（Master-Subagent）编排模式：

sequenceDiagram
    autonumber
    actor User as 用户 (User)
    participant Master as 👑 主编排智能体 (Master Agent)
    participant Sub1 as 🔍 检索专家子代理 (Research Subagent)
    participant Sub2 as 💻 编程专家子代理 (Coding Subagent)
    participant Sub3 as 📊 汇报呈现子代理 (Report Subagent)

    User->>Master: 提出综合性复杂需求
    Master->>Master: 任务拆解与执行规划 (Task Decomposition)
  
    rect rgb(240, 248, 255)
    Note over Master,Sub1: 孵化独立会话上下文
    Master->>Sub1: 派发检索任务 (invoke_subagent)
    Sub1->>Sub1: 深度搜索与数据清洗 (私有上下文)
    Sub1-->>Master: 仅返回结构化调研摘要结论
    end

    rect rgb(255, 245, 238)
    Note over Master,Sub2: 孵化独立代码沙箱
    Master->>Sub2: 派发代码编写与沙箱验证任务
    Sub2->>Sub2: 编写并执行测试 (私有上下文)
    Sub2-->>Master: 仅返回最终代码工件与验证状态
    end

    rect rgb(245, 255, 250)
    Master->>Sub3: 派发可视化图表生成
    Sub3-->>Master: 返回交互图表 HTML
    end

    Master-->>User: 汇总交付高水准最终方案

🌟 子代理机制的杀手级优势：

• 上下文纯净隔离：子代理在自己独立的专属会话与沙箱中尝试、纠错与调试，产生的巨量中间过程日志绝不会污染主会话，主会话上下文始终保持轻量与高聚焦；
• 各司其职，模型异构：主代理可以使用规划能力强的通用模型，编程子代理可以使用代码微调模型，各取所长；
• 防止单点崩溃：某个子代理报错重试不影响主流程其他环节。

3.2.3 调度模式：智能委派、指定专家与 Main 子代理协同

在平台的日常使用中，系统支持两种入口：智能委派和指定专家。未指定专家时，请求统一直接进入默认 Main；Main 可以自己回答，也可以按需委派其他已授权专家。指定专家时保持直达该专家，且该专家仍可继续委派子代理。

graph TD
    UserQuery["💬 用户发送问题 / 提出任务需求"] --> ModeCheck{"用户是否显式指定了专家？
(如侧边栏选定 / @提及)"}
    
    ModeCheck -- "是 (指定专家)" --> DirectPath["🎯 指定专家模式 (Explicit Agent)
直连对应专家智能体，100% 专属 Prompt 与私有工具"]
    ModeCheck -- "否 (未指定)" --> Main["🤖 默认 Main
统一智能委派入口"]
    Main --> NeedDelegate{"Main 是否需要垂直能力?"}
    NeedDelegate -- "否" --> MainAnswer["Main 直接回答"]
    NeedDelegate -- "是" --> Delegate["🔀 Main 智能委派
sub_agent_call / sub_agent_batch_call"]
    Delegate --> SubAgent["已授权垂直专家执行子任务"]
    SubAgent --> Synthesis["Main 汇总结果"]

1. 两种入口的核心区别对比

2. 多专家协同场景实战举例 (Case Studies)

假设平台当前注册并启用了以下 4 位智能体：

1. 📊 专家 A：ChatBI 数据分析师（职责：业务数据集查询、指标统计、SQL 编写与可视化图表生成）
2. 💻 专家 B：全栈代码研发专家（职责：编写 Python/JS 代码、算法实现、代码沙箱自测与 Bug 修复）
3. ⚖️ 专家 C：企业法务与合规顾问（职责：合同法条审查、合规政策咨询、知识库法规检索）
4. 🤖 默认 Main：NanZi 全能主助手（职责：日常问答、任务分解、泛化文案撰写与跨领域统筹）

🌟 案例 1：业务数据查询与指标计算（Main 智能委派专家 A）

• 用户提问：“帮我查一下上个季度华东大区的总销售额，并找出客单价最高的前 5 名客户名单。”
• Main 委派流程：
  1. Main 判断该任务需要数据查询能力；
  2. Main 根据当前可用专家的名称、描述和能力，选择 专家 A (ChatBI 数据分析师)；
  3. Main 调用 sub_agent_call，专家 A 读取销售数据集的元数据 Schema，生成精准 SQL 并返回数据表格与柱状图。
• 为什么委派给 A：该任务需要 ChatBI 的只读数据库和 SQL 能力；候选与权限仍由平台门禁校验。

🌟 案例 2：工程代码编写与沙箱验证（Main 智能委派专家 B）

• 用户提问：“写一个 Python 异步高并发请求脚本，要求支持指数退避重试，并将抓取结果保存到本地 docs 目录中。”
• Main 委派流程：
  1. Main 判断该任务需要代码和沙箱能力；
  2. Main 选择 专家 B (全栈代码研发专家) 并调用 sub_agent_call；
  3. 专家 B 在 Docker 安全代码沙箱（/workspace）中编写 Python 脚本、运行测试确认无语法报错后，将最终代码文件产物返回给 Main。
• 为什么委派给 B：专家 B 拥有代码沙箱执行与自测工具。

🌟 案例 3：合同条款合规审查（Main 智能委派专家 C）

• 用户提问：“我们供应商采购合同第 8 条约定的逾期违约金比例为每日千分之五，这在法律上是否存在过高违约金被法院调整的风险？”
• Main 委派流程：
  1. Main 判断该任务需要法务与知识库能力；
  2. Main 调用 sub_agent_call 委派给 专家 C (企业法务与合规顾问)；
  3. 专家 C 自动检索其挂载的《民法典合同编司法解释》私有知识库，援引关于“违约金超过造成损失的百分之三十”之法律条款，出具结构化的法务风险提示与修改建议。

🌟 案例 4：通用规划与日常问答（Main 直接回答）

• 用户提问：“请为我们技术团队设计一份为期 3 天的千岛湖秋季团建策划方案，预算人均 1500 元。”
• Main 处理流程：
  1. Main 判断该问题属于自身可以完成的方案策划，不需要调用垂直子代理；
  2. Main 直接构思并输出包含行程日程表、预算明细表与注意事项的完整方案。
• 优势：避免了不必要的子代理来回调用开销，响应速度最快。

3. 进阶协同：指定了专家，如果该专家能力不足能否调用其他子代理？

答案是：完全支持，且平台原生具备“专家向子代理跨领域求助”的能力！

很多用户存在误解，以为“一旦在左侧锁定了某个专家，就只能使用该专家自己绑定的工具”。实际上，在 NanZi 智能体架构中，任何被指定的专家智能体，都拥有调用 sub_agent_call（串行委派）或 sub_agent_batch_call（并行委派）作为父代理向其他专家发起协同的能力。

sequenceDiagram
    autonumber
    actor User as 👤 用户 (指定了 ChatBI 数据专家)
    participant ExpertA as 📊 父专家：ChatBI 数据分析专家
    participant SubAgentB as 💻 协助子代理：全栈代码研发专家
    participant Sandbox as 📦 Docker 安全代码沙箱

    User->>ExpertA: "找出上月销售额倒数第1的门店，并写个 Python 脚本模拟向店长发送企微告警"
    Note over ExpertA: 1. 执行自身专长：查数据库
    ExpertA->>ExpertA: 执行 SQL 查询数据集，查出门店为「杭州西湖店」
    
    rect rgb(254, 243, 199)
    Note over ExpertA,SubAgentB: 2. 识别超出自身专长（写工程代码与沙箱执行）
自主发起二级子代理调用 (sub_agent_call)
    ExpertA->>SubAgentB: 委派任务: "请根据杭州西湖店数据，编写企微告警 Python 脚本并自测"
    end

    rect rgb(240, 249, 255)
    Note over SubAgentB,Sandbox: 3. 子代理在私有独立沙箱中编写与自测
    SubAgentB->>Sandbox: 写入 alert_wecom.py 并运行验证
    Sandbox-->>SubAgentB: 脚本测试通过 (ExitCode 0)
    SubAgentB-->>ExpertA: 仅返回交付的代码工件路径与执行测试结论
    end

    Note over ExpertA: 4. 父专家整合数据结论与代码工件
    ExpertA-->>User: 交付完整答复（包含数据分析结论 + 现成可用的企微告警脚本）

🌟 典型协同场景剖析：

• 场景设定：用户在左侧直接选择了 ChatBI 数据分析专家（该专家专注 SQL、Schema 与报表，未挂载复杂 Python 工程调试工具）。
• 复合任务输入：“请帮我查出上周退款率最高的商品，并写一段带签名验证的 Python Webhook 脚本通知供应商，最后在沙箱跑一下看有没有语法错误。”
• 协同执行流程：
  1. 分步拆解：ChatBI 专家 首先发挥自身优势，连接只读数据库执行 SQL，精准算出退款率最高的是“智能降噪耳机 Pro”；
  2. 跨界求助：当进入“编写 Python 签名算法脚本并在沙箱运行自测”阶段时，ChatBI 专家 发现自身缺少底层代码编译器工具，随即调用内置工具 sub_agent_call(agent_name="code_developer", query="...")；
  3. 子代理接力：全栈代码研发专家 作为子代理被动态拉起，在独立的 Docker 沙箱（/workspace）中编写代码并执行 python -m py_compile 校验，确认脚本完全合规可用；
  4. 统一交付：子代理向 ChatBI 专家 汇报完成；ChatBI 专家 汇总最终的“商品退款数据解读”与“自测通过的 Python 脚本”，以结构化方式向用户交付。

🔒 平台层面的安全与防环死锁保护：

1. 递归调用深度熔断 (max_subagent_depth)：系统默认设置最大子代理嵌套深度（如最多 2~3 层），严格禁止 A 专家调 B、B 又反调 A 造成的递归死循环；
2. 权限单向继承：子代理严格继承发起人（父会话用户）的权限边界，用户本人无权访问的数据或接口，被调用的子代理同样会被权限拦截；
3. 主上下文防污染：子代理在沙箱里执行几十次代码重试与报错排查的冗长日志全部封装在子沙箱中，绝不污染用户的当前主聊天窗口。

4. 最佳实践建议：如何选择最合适的模式？

• 💡 日常办公与发散探索：保持使用 智能委派，想到什么问什么，默认由 Main 统一承接；需要时 Main 会调度最合适的已授权专家；
• 💡 高强度专业作业：如果接下来半小时内全部是专注于某一个系统（例如在做财务月结审计、或在集中编写微服务后端），建议直接在左侧 指定专家 进入专属会话，享受最纯粹的单领域沉浸式交互；
• 💡 遇到复合跨界需求：即使已指定专家也无需手动切出会话，放心地直接提出复合需求，专家会自动拉起其他专家子代理协助完成！

3.2.4 嵌入式发布与一键共享 (Embed Chat)

【嵌入式对话组件】（Embed Chat，路由地址 /embed/chat）是平台面向企业第三方系统（如内部 OA、CRM、ERP、运维监控看板、Wiki 文档库、客服门户或官网）提供的高性能、零侵入、自适应嵌入方案。

1. 为什么选择 Embed Chat 嵌入集成？

• 全功能开箱即用：内置多模态附件上传、交互画布抽屉（代码高亮/Markdown渲染/图表生成/工件下载）、多轮记忆控制、快捷指令库与独立站内消息弹窗；
• 自适应响应式布局：无论是 380px 的右下角悬浮气泡挂件，还是 100% 宽高的全屏嵌入，均可自动适配亮色/暗色主题；
• 全隔离多实例机制：支持通过 instance_id 在同一页面挂载多个独立的智能体挂件，会话与上下文互不串扰。

2. 企业级生产架构：Embed Ticket 临时票据体系

为彻底避免在前端浏览器中暴露长期 API Key，生产环境强烈推荐使用 Embed Ticket 三步安全时序：

sequenceDiagram
    autonumber
    actor User as 业务系统员工 (User)
    participant HostFront as 宿主系统前端 (CRM/OA)
    participant HostBack as 宿主系统后端 (Server)
    participant NanziAPI as 平台接口 (NanZi Backend)
    participant EmbedFrame as EmbedChat IFrame

    User->>HostFront: 登录并打开业务工单/分析页面
    HostFront->>HostBack: 请求加载 AI 助手
    HostBack->>NanziAPI: POST /api/v1/embed/tickets (携带系统 Master Key & username)
    Note over HostBack,NanziAPI: 长期 API Key 留在宿主后端环境变量，绝不出内网
    NanziAPI-->>HostBack: 返回 5 分钟一次性 Ticket (如 emt_a8f9c2d1...)
    HostBack-->>HostFront: 下发 ticket
    HostFront->>EmbedFrame: 挂载 IFrame: /embed/chat?ticket=emt_xxx
    EmbedFrame->>NanziAPI: 自动核销 Ticket 并兑换 24 小时短期 Session Token (阅后即焚)
    NanziAPI-->>EmbedFrame: 鉴权通过，建立 SSE 流式连接
    EmbedFrame->>EmbedFrame: 渲染专属对话面板，就绪可用
    Note over EmbedFrame,NanziAPI: 持续聊天时自动触发活跃滑动续期 (Sliding TTL)

3. 服务端签发 Ticket 示例与标准 IFrame 挂载

① 宿主后端签发 Ticket 接口规范：

• 请求方式：POST /api/v1/embed/tickets
• 请求头：X-API-Key: YOUR_SYSTEM_MASTER_KEY
• 请求体 (JSON)：

  {
    "username": "zhangsan",          // 必填：目标员工用户名（代表谁提问，自动关联该用户权限与记忆）
    "agent_id": "sys-agent-chatbi",  // 可选：指定初始锁定的智能体 ID（留空则走全局智能路由）
    "expires_in": 300                // 可选：Ticket 有效期（秒，默认 300 秒，一次性核销）
  }

② 宿主前端 HTML 嵌入代码：

<!-- 宿主前端：直接传入 ticket 渲染 IFrame -->
<iframe
  src="https://your-nanzi-platform.com/embed/chat?ticket=emt_a8f9c2d1e0b3456789abcdef&theme=light"
  width="100%"
  height="680"
  frameborder="0"
  allow="clipboard-read; clipboard-write"
  style="border: 0; border-radius: 12px; box-shadow: 0 8px 24px rgba(15, 23, 42, 0.08);"
></iframe>

4. 高级进阶：PostMessage 双向通信与业务上下文注入

当宿主页面需要动态向智能体注入业务上下文（如当前正在浏览的工单详情、设备资产编号、客户档案），或实现会话超时无感自动重连时，推荐使用 PostMessage 标准协议：

<iframe
  id="nanzi-agent-frame"
  src="https://your-nanzi-platform.com/embed/chat?instance_id=crm-assistant"
  width="100%"
  height="680"
  frameborder="0"
></iframe>

<script>
const frame = document.getElementById('nanzi-agent-frame');
const nanziOrigin = 'https://your-nanzi-platform.com';

// 监听 EmbedChat 组件生命周期与上行事件
window.addEventListener('message', async (event) => {
  if (event.origin !== nanziOrigin) return;
  const { source, type, payload } = event.data || {};
  if (source !== 'nanzi-agent-embed') return;

  // 1. 组件就绪：发送 Ticket 鉴权并注入业务上下文
  if (type === 'NANZI_WIDGET_READY') {
    const ticket = await fetchMyHostTicket(); // 从宿主后端申请 Ticket
    frame.contentWindow.postMessage({
      source: 'nanzi-host',
      type: 'INIT_CONFIG',
      payload: {
        ticket: ticket,
        theme: 'light',
        business_context: {
          order_id: 'ORD-2026-0822',
          customer_name: '阿里云计算有限公司',
          environment: '生产机房A区'
        }
      }
    }, nanziOrigin);
  }

  // 2. 会话闲置超 24h 断开：自动静默重新申请 Ticket 续期
  if (type === 'INIT_FAILURE' && payload?.reason === 'session_expired') {
    const newTicket = await fetchMyHostTicket();
    frame.contentWindow.postMessage({
      source: 'nanzi-host',
      type: 'RESET_SESSION',
      payload: { ticket: newTicket }
    }, nanziOrigin);
  }
});
</script>

5. Embed Chat 常用 URL 参数速查表

📖 完整技术集成规范与多语言 Demo：
更多关于 Java (Spring Boot) / Python (FastAPI) / Go (Gin) 服务端完整代码、Vue 3 / React / 悬浮球组件示例及 PostMessage 协议字典，请参阅：
👉 docs/md/embed_integration_guide.md (NanZi 智能体平台嵌入式组件集成指南)

3.2.5 小白实战：我该用单智能体还是多智能体？

3.3 技能工作台与平台审核机制 (Skills Management)

【技能工作台】（Skills Management）是企业沉淀行业领域经验与标准化作业程序（SOP）的专家知识库。

3.3.1 什么是技能 (Skill)？技能包的结构规范

技能并不是死板的代码，而是将人类专家的操作规范、分步流程、代码规范与避坑准则系统化封装成的“指南包”。

一个标准的技能包含以下两个核心组成部分：

1. YAML Frontmatter 元数据（定义技能名、触发描述、图标与分类标签）：

   ---
   name: financial-reconciliation
   description: 专门用于处理财务对账、发票核对及银行流水匹配的专业技能。当用户提到账单核对、流水对比、差异对账时自动激活。
   tags: [finance, reconciliation, audit]
   icon: DocumentChartBarIcon
   ---

1. Markdown 结构化指令正文（指导智能体分步骤如何思考与执行）：

• Step 1 检查数据格式：必须校验金额字段是否为两位小数；
• Step 2 执行比对规则：以订单号为唯一主键进行 Left Join 比对；
• Step 3 输出规范：强制以 Markdown 表格形式列出对账差异项，并标注差异原因分类。

3.3.2 私有技能 vs 平台公共技能及审核流转

为了兼顾“个人自由创新”与“企业安全合规”，平台设计了严密的工作流转生命周期：

flowchart LR
    User["👤 普通用户 / 开发者"] --> Create["1. 创建私有技能
(仅自己可见并调试)"]
    Create --> Test["2. 在对话中实战测试验证"]
    Test --> Submit["3. 点击【提交审核】"]
    Submit --> Review{"4. 平台管理员审查
(element:skills:admin)"}
    Review -- "审核通过" --> Public["5. 晋升为全局公共技能
(全员可用并可挂载)"]
    Review -- "驳回修改" --> Reject["返回修改并说明原因"]
    Reject --> Create

3.3.3 大模型是如何“动态发现与按需加载”技能的？

• 痛点：如果企业沉淀了 100 个技能，一次性全塞给大模型会导致上下文瞬间溢出且大幅消耗费用。
• 解决机制：智能体在每轮对话开始时，先根据用户输入的语义意图，与所有可用技能的 description 进行语义相似度快速匹配；仅当意图命中时，系统才会把该技能的完整 Markdown 内容动态注入上下文，实现按需加载、毫秒级响应、极低 Token 消耗。

3.4 MCP 工具集规范与容器内网关 (MCP Management)

【MCP 工具集】（Model Context Protocol）是连接大模型与外部数字化世界（数据库、Git 仓库、私有 API、操作系统）的标准桥梁。

3.4.1 什么是 MCP？为什么它是智能体进化的关键？

在过去，让大模型调用工具需要针对每个平台编写专有适配代码。 MCP (Model Context Protocol) 统一了智能体调用工具的标准协议：

• 任何外部工具只需实现一次 MCP Server，就能被任何支持 MCP 协议的智能体无缝调用；
• MCP 协议原生支持工具发现 (Tools Discovery)、提示词模板 (Prompts) 与上下文资源暴露 (Resources)。

3.4.2 平台支持的 MCP 连接协议类型

平台全面支持两种标准 MCP 通信协议：

1. STDIO MCP (标准输入输出)：
   • 适用于本地可执行命令或脚手架工具（例如 python -m my_mcp_server 或 npx -y @modelcontextprotocol/server-postgres）；
   • 后端通过直接拉起子进程进行管道通信，低延迟、安全性高。
2. SSE MCP (Server-Sent Events / HTTP)：
   • 适用于独立微服务或部署在云端的 MCP 服务；
   • 通过标准 HTTP/SSE 端点进行远程 RPC 交互，适合跨主机、跨网络集群调用。

3.4.3 Docker 安全沙箱中的 In-Container FastMCP 网关机制

当沙箱策略配置为 docker 时，平台在容器化隔离与 MCP 协议上实现了极致优雅的架构：

• 容器启动时，平台自动在容器内的独立虚拟环境中拉起轻量级 FastMCP 网关；
• 容器内的 Bash 命令行执行、文件读取（read）、文件写入（write）均以标准 FastMCP Tool 方式暴露；
• 智能体与容器完全通过标准 MCP 协议通信，容器发生任何死循环或异常都不会影响宿主机主进程。

3.4.4 MCP 三步向导与同一服务地址多命名空间注册规范

为了降低企业将现有微服务或自建 MCP 接入平台的门槛，平台设计了 MCP 接入三步向导 并放开了同源地址多命名空间隔离注册机制：

1. 三步标准化接入流转：
   • Step 1：配置连接与握手探活：输入 STDIO 命令或 SSE HTTP 端点，平台发起协议握手自检，确保服务正常响应；
   • Step 2：动态工具发现 (Tools Discovery)：自动列出该 MCP 服务所暴露的全部函数、参数 Schema 与描述定义，支持按需勾选启用/禁用特定工具；
   • Step 3：版本发布与权限绑定：为工具集分配命名空间（Namespace）并一键发布上线，立即向智能体挂载生效。
2. 同一 MCP Server 地址多命名空间支持：
   • 企业级部署中，往往一个大型 MCP 微服务（如内部中台网关）同时包含了财务工具集、人事工具集与运维工具集；
   • 平台支持基于同一服务地址分别注册多个独立的 MCP 记录，通过指定不同的命名空间与路由过滤，分别赋权给不同业务部门的专属智能体，避免工具混乱与权限外溢。

3.4.5 自有 MCP 如何接收和使用 NanZi 用户身份

如果业务 MCP 需要知道“这次调用对应哪个 NanZi 登录用户”，可以在该 MCP 的管理页面打开 「开启用户身份传递」。这是 MCP 级别的可选开关：

这里有两个不同用途的认证信息：

页面上需要配置什么？

页面将 MCP 自身认证拆成两部分：Authorization 使用独立开关，开启后只填写 Token 内容，系统固定补全 Bearer 前缀；其他 API Key 或租户信息放在「其他 Header」区域。编辑已有配置时不会回显密钥原文，只显示开关状态或 ********，点击「编辑」后填写新值才会替换，直接保存会保留原配置。Authorization 是否配置与用户身份传递相互独立；即使不配置 Authorization，也可以开启用户身份传递。不需要用户手工生成公钥或私钥。

系统会针对当前 MCP 自动生成并保存签名密钥：

业务方只需要把页面上的 Audience、Issuer 和 JWKS 地址复制到自己的 MCP 服务配置中；如果业务 MCP 配置了 Authorization Bearer Token，再把该 Token 放入业务方自己的 Secret 管理系统。详细的 Python、Java 中间件示例见：MCP UserContext 接入指南。

业务 MCP 收到请求后怎么处理？

推荐按以下顺序处理：

1. 如果当前 MCP 配置了 Authorization: Bearer，先按原有方式校验；未配置时跳过这一步。
2. 如果 NanZi 开启了用户身份传递，读取 X-Nanzi-User-Assertion，根据 JWT Header 中的 kid 从当前 MCP 对应的 JWKS 地址选择公钥。
3. 使用 Ed25519 / EdDSA 验证签名，并校验 iss、aud、iat、exp、jti、sub。
4. 校验 sub 与 user_context.user_id 一致，并将 jti 写入 Redis 等短期存储，重复使用的 jti 必须拒绝。
5. 读取 user_context.user_id，映射为业务系统自己的用户 ID，再执行业务 MCP 的数据权限和操作权限判断。

NanZi 登录用户
    ↓ 后端签发短期签名断言
业务 MCP 验证可选的 Authorization Bearer Token + JWS
    ↓
读取 user_context.user_id
    ↓
关联业务用户并执行业务权限判断

验签后的核心数据示例：

{
  "iss": "nanzi-platform",
  "aud": "mcp:<当前 MCP 的系统生成 ID>",
  "sub": "nanzi:user:123",
  "user_context": {
    "user_id": "123",
    "user_name": "zhangsan",
    "real_name": "张三",
    "dept_code": "sales",
    "org_path": "/集团/销售部"
  },
  "custom_attributes": {
    "employee_level": "L3",
    "region_code": "east"
  },
  "agent_id": "agent-sales-assistant",
  "agent_version_id": "agent-version-2026-01",
  "request_id": "req-20260901-001",
  "jti": "assertion-uuid",
  "iat": 1788230000,
  "exp": 1788230060
}

业务 MCP 主要使用 user_context.user_id 关联业务用户；agent_id、agent_version_id 和 request_id 用于审计追踪；custom_attributes 是经过平台安全过滤的可扩展 key-value。当前版本不传 tenant_id、scope 或完整权限树，最终业务权限仍由业务 MCP 自己判断。

第三方 MCP 不解析这个 Header 会有影响吗？

没有影响。只有开启用户身份传递的 MCP 才会收到 X-Nanzi-User-Assertion；未开启的 MCP 完全沿用原来的调用方式。即使开启后，暂时不识别该扩展 Header 的 MCP 通常也会忽略它，但如果业务方需要按 NanZi 用户做用户映射、数据隔离或审计，就必须实现上述验签中间件。

完整认证方案见：MCP 业务集成认证方案。

3.4.6 如何使用 MCP Echo 测试服务验证真实调用链路

管理员在【MCP 管理】的【平台 MCP】页点击【创建 Echo 测试 MCP】即可创建平台级测试服务。Echo MCP 默认包含一个已发布的 echo 工具，所有有权限的智能体都可以按现有方式挂载和调用。重复点击是幂等操作，不会轮换既有凭证。

生产环境使用 Docker 部署时，需要在 .env 中配置平台公网 Origin，例如 APP_PUBLIC_URL=https://your-domain.example.com。Compose 会将它传入 API 容器，Echo MCP 启动时自动据此配置 Host/Origin 白名单并生成 MCP 地址。若出现 421 Invalid Host header， 请确认容器内能读取该变量、反向代理转发的 Host 与公网地址一致，并重新创建容器；已有 Echo 配置还需要重新点击一次“创建 Echo 测试 MCP”同步地址。测试页面不需要填写 request.base_url 或 allowed_hosts。

调用结果会返回“已收到”和以下安全诊断：

Echo 不会返回原始 Bearer Token、完整 JWS、私钥或 jti，只会返回中间为 *** 的脱敏样例和 processing_log。浏览器也无法直接查看后端发往 MCP 的 Header，应以 Echo 返回的 user_assertion_received、user_assertion_valid、verified_user_id 和 request_context.request_id 作为验证依据。详细步骤见：MCP Echo 测试服务使用说明。

3.4.7 NanZi 平台级 MCP 如何对外提供服务

NanZi 对外提供的是一个统一的 NanZi Platform MCP，智能体、会话和元数据都作为同一个 MCP 服务下的方法组，不拆成多个独立 Server：

第一期已接入上述方法，只支持能安全保存 client_secret 的 Confidential Client，采用 OAuth2 标准授权（完整 OIDC 的 ID Token/JWKS 作为后续扩展）：

3.4.7.1 如何使用 MCP 服务台页面

进入【系统管理 → MCP 服务台】后，按下面顺序完成配置：

1. 在【服务配置】打开 Platform MCP 总开关，再按需打开 agent、conversation、knowledge、metadata 能力组开关。
2. 在【外部 Client】点击“创建 Client”，填写接入名称、Redirect URI 和允许申请的 Scope；创建成功后立即复制只展示一次的 client_secret。
3. 如需限制该 Client 可以访问的具体资源，在 Client 卡片的“资源访问”区域分别编辑智能体、知识库和数据集白名单。每类资源都有独立的勾选弹框，支持搜索、全选当前结果、清空和恢复全部用户可访问资源。
4. 临时接入 Cursor、Claude Desktop 等客户端时，在对应 Client 卡片点击“生成当前用户 Access Token”，选择有效期和 Scope。
5. 在 Token 向导第二步复制 Access Token 或完整 MCP JSON，粘贴到客户端的 MCP 配置中。
6. 在【能力与 Scope】确认方法是否已发布，在【审计日志】检查后续 tools/list、tools/call 请求。

Client 按创建人隔离；即使是管理员，也只能管理自己创建的 Client。服务台只显示凭证原文一次，不要把 Client Secret、Access Token 或 NanZi 用户 API Key 提交到代码仓库。

资源白名单的三种状态如下：

• 绿色：跟随用户权限：该 Client 不额外限制此类资源，实际访问范围由当前用户权限决定；
• 黄色：已限制 N 项：该 Client 只允许配置的资源，实际结果仍会与当前用户权限取交集；
• 红色：禁止访问：该类资源保存为空数组，全部拒绝。

白名单只能缩小权限，不能让 Client 获得当前用户原本没有的资源。服务端保存时还会校验资源存在、启用状态和当前用户权限；直接构造请求提交非法或越权资源 ID 也会被拒绝。

3.4.7.2 如何给 Cursor 等客户端生成个人 Token

人工联调或桌面客户端接入不必先实现完整 OAuth2：

1. 使用目标 NanZi 用户登录平台。
2. 打开【MCP 服务台 → 外部 Client】，创建或选择一个自己创建的启用中 Client。
3. 点击“生成当前用户 Access Token”，选择需要的 Scope 和有效期。
4. 复制 Token 或生成的 mcpServers JSON，并在客户端中使用。

这个 Token 永远代表当前登录用户，不能选择或代发其他用户身份；调用时统一携带 Authorization: Bearer <access_token>。Token 过期后重新登录并生成即可，个人 Token 不创建 Refresh Token。修改 Client 的 Scope、资源白名单、回调地址、授权模式或状态后，原有 Token、Refresh Token、授权关系和未消费授权码会失效，需要重新授权或生成 Token。

3.4.7.3 外部系统如何通过 OAuth2 调用 NanZi MCP

CRM、OA、后台服务等程序化系统使用 Authorization Code + PKCE：

1. 在服务台创建 Client，并登记业务系统真实的回调地址。
2. 外部系统将用户跳转到 /oauth/authorize，携带 client_id、精确匹配的 redirect_uri、请求 Scope、resource 和 PKCE S256 参数。
3. 用户登录 NanZi 并在授权页确认后，外部系统接收授权码。
4. 外部系统后端使用 client_id + client_secret + code + code_verifier 请求 /oauth/token 换取 Access Token。
5. 调用 https://<NanZi 域名>/mcp/platform 时，仅携带 Authorization: Bearer <access_token>；Client Secret 只能用于 Token Endpoint，不能放入 MCP 请求或前端代码。

Token Endpoint 支持 authorization_code 和 refresh_token，但 Platform MCP 不签发无用户身份的 Token。服务端会同时校验 Token、Client、Resource、Scope、用户授权关系以及 NanZi 内部资源权限。

3.4.7.4 权限、开关与常见排查

停用 Client、重置 Secret 或删除 Client 都会使相关 Token 立即失效；删除是软删除，审计记录仍会保留。关闭 Platform MCP 不影响 NanZi 作为 MCP Client 调用外部业务 MCP。

Client Secret 的使用方式：它只放在业务方后端请求 /oauth/token 时，用来证明“这是哪个外部系统”；Access Token 才放在每次 MCP 请求的 Authorization: Bearer Header 中。Platform MCP 不签发没有用户身份的 Token，每个 Access Token 都必须绑定完成 NanZi 用户授权的用户：

TOKEN_RESPONSE=$(curl --request POST "https://nanzi.example.com/oauth/token" \
  --user "$NANZI_CLIENT_ID:$NANZI_CLIENT_SECRET" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=$NANZI_REDIRECT_URI" \
  --data-urlencode "code_verifier=$PKCE_CODE_VERIFIER" \
  --data-urlencode "resource=https://nanzi.example.com/mcp/platform")
ACCESS_TOKEN=$(printf "%s" "$TOKEN_RESPONSE" | jq -r '.access_token')
curl --request POST "https://nanzi.example.com/mcp/platform" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

其中 $AUTHORIZATION_CODE 和 $PKCE_CODE_VERIFIER 来自同一次用户授权流程；业务方后端使用 client_id + client_secret + code + code_verifier 换取的 Access Token 才代表该用户。Client Secret 不应放进 Cursor、浏览器、移动端或 MCP JSON；Cursor 等人工配置场景直接在服务台生成当前用户 Token 即可。完整 curl、Python 和两种场景的向导说明见：NanZi 平台级 MCP 对外服务技术方案 的“外部系统调用示例”章节。

因此两条链路的定位是：人工联调、Cursor/桌面客户端等使用服务台生成的当前用户个人 Token；CRM、OA、后台任务等程序化集成使用标准 OAuth2 动态获取 Token。服务台个人 Token 不创建 Refresh Token，过期后由当前用户重新登录并生成，不能把 NanZi 登录 Cookie 或用户 API Key 交给第三方。

管理权限采用三层开关：Platform MCP 总开关、能力组开关、Client 独立开关。三层任一关闭，调用都会被拒绝或对应方法不再发布；关闭对外服务不会影响 NanZi 作为 MCP Client 调用外部业务 MCP。

MCP 服务台中的“使用指南”Tab 提供 OAuth2 调用流程、Endpoint/Metadata 地址用途和可复制的通用 mcpServers JSON；完整的端点、Token、数据表、审计、错误码与验收方案见：NanZi 平台级 MCP 对外服务技术方案。

3.5 平台全量工具矩阵与功能清单 (Platform Tool Registry & Built-in Matrix)

平台内置了涵盖沙箱执行、数据分析、文档处理、网络浏览、知识检索、人机协同、任务调度与通知分发的八大类原生工具库，同时支持通过 MCP 协议 与 OpenAPI 进行无限生态扩展。

以下为平台支持的全量工具功能清单与内置属性一览：

1. 沙箱系统与代码执行类工具 (Sandbox & System Execution)

2. 数据分析与智能报表类工具 (Data & ChatBI)

3. 网络检索与浏览器自动化类工具 (Web & Browser Automation)

4. 知识库与企业协作类工具 (Knowledge & Enterprise Collab)

5. 多智能体协同、人机交互与记忆类工具 (Multi-Agent, HITL & Memory)

6. 任务调度台与消息通知类工具 (Task Scheduling & Notifications)

7. 技能与资源目录发现类工具 (Skill & Resource Discovery)

8. 生态扩展工具体系 (Extensible Ecosystem Tools)

3.6 平台多级记忆系统与上下文管理专题 (Memory & Context Architecture)

许多用户在使用大模型时最常遇到的痛点是：“聊了多轮后前面说的忘了”、“换了个新会话 AI 就不认识我了” 或者 “对话太长导致上下文超限爆掉”。

平台基于 Redis Stack + RediSearch 向量检索与 AgentScope 运行时，构建了企业级 “四级渐进式记忆与上下文生命周期体系”：

+----------------------------------------------------------------------------------------------------+
|                                  四级渐进式记忆与上下文生命周期体系                                  |
+----------------------------------------------------------------------------------------------------+
|                                                                                                    |
|  1. ⚡ 会话工作记忆 (Session Working Memory)                                                        |
|     - 基于 Redis LIST (单调递增 Seq 计数器)，秒级读写最近对话轮次与临时工具执行结果 (30天 TTL)      |
|                                                                                                    |
|                                       │ 会话轮次逼近上下文预算 (64k / 128k)                         |
|                                       ▼                                                            |
|  2. 🗜️ 两阶段上下文溢出压缩 (Two-Phase Compaction)                                                  |
|     - 自动触发增量摘要提炼，将早期长对话浓缩为高浓度 Digest 摘要注入 System，保留近期活跃轮次      |
|                                                                                                    |
|                                       │ 异步防抖归纳 (Debounce 轮次/时间窗口)                      |
|                                       ▼                                                            |
|  3. 📅 每日摘要记忆 (Daily Summary & Consolidation)                                                |
|     - 自动跨会话聚合提炼当天多次对话，提取 key_facts (事实), decisions (决策), open_items (待办)   |
|     - 形成用户每日工作轨迹与时间线，支持按日期回溯                                                 |
|                                                                                                    |
|                                       │ 文本 Embedding 向量化入库                                  |
|                                       ▼                                                            |
|  4. 🧠 跨会话长期向量记忆 (Long-Term Vector Memory & memory_search)                                |
|     - RediSearch 构建稠密向量索引，沉淀用户专属技术栈、业务偏好与长期实体                          |
|     - 智能体需要时自主调用 memory_search(scope='summary'|'history') 进行语义相似度精准召回          |
+----------------------------------------------------------------------------------------------------+

3.6.1 四大多级记忆机制深度剖析

1. 会话工作记忆 (Session Working Memory)

• 底层机制：基于 Redis LIST 数据结构与会话专属 Key (conversation:{user_id}:{conversation_id}:history) 存储；
• 单调序号与分支隔离：采用单调递增序号计数器（seq_counter）与分支版本控制（context_revision）。即使用户在中途“编辑重发”或截断历史，系统也能精准基于当前分支重新组织记忆，不会产生脏乱交叉。

2. 两阶段滑动窗口与上下文溢出压缩 (Context Compaction)

• 解决痛点：避免超长大模型会话触发 Context Window 上限而报错或丢失首要指令；
• 压缩流程：
  • 第一阶段（动态监控）：输入框浮标实时监控 Token 水位线；
  • 第二阶段（增量浓缩）：当超出设定的预算水位线时，后台自动触发两阶段压缩算法，将早期冗余的中间工具调用输出与长对话提炼为结构化 Digest 摘要（独立存储于 Redis digest Key 中），只在当前活跃上下文中保留最近几轮完整消息，实现兼顾全域背景与极低 Token 消耗。

3. 每日摘要记忆 (Daily Summary & Consolidation)

• 解决痛点：用户一天内可能创建了 5~10 个不同会话，零散分散在各处，AI 无法统揽当天的整体工作进展；
• 智能抽取五大维度：后台异步调度引擎在会话静默防抖（Debounce）后，自动对当日所有会话进行阶段性提炼，沉淀为结构化每日档案：
  • 📌 Key Facts (核心事实)：提取今天确认的业务数据指标、系统环境信息；
  • 🎯 Topics (讨论主题)：归类当日聚焦的业务板块或技术模块；
  • ⚖️ Decisions (关键决策)：沉淀对话中达成一致的技术选型、业务结论；
  • 📝 Open Items (待办事项)：智能提取尚未完成的遗留任务；
  • 🏷️ Entities (关键实体)：关联的数据库名、API 接口名或项目专有名词。

4. 跨会话长期向量记忆与自主检索 (memory_search)

• 跨会话持久沉淀：用户的偏好习惯（如“喜欢用 Vue3 + TS”、“默认使用 MySQL 8.0 语法”）会被长期沉淀在 RediSearch 向量库中；
• 智能体主动召回：当用户在全新的会话中提问 “我昨天让你总结的财务指标是什么？” 或 “按照我之前偏好的风格写代码” 时，智能体会主动唤起原生内置工具 memory_search：
  • scope='summary'：快速模糊搜索历史会话与每日摘要；
  • scope='history'：结合目标 conversation_id 精准调取原始对话明细，实现宛如真人的长期记忆连贯性！

3.6.2 记忆工作台控制台与运维排查 (/memory)

在平台左侧导航栏点击 【记忆工作台】（需要 menu:memory_management 权限），进入系统级记忆管理中心：

+-----------------------------------------------------------------------------------+
|                           记忆工作台 (Memory Workbench)                           |
+-----------------------------------------------------------------------------------+
|  [⚙️ 服务配置]           [📋 记忆数据大盘]          [🔍 语义检索测试]              |
|                                                                                   |
|  - 向量引擎健康度自检     - 按用户/日期/会话筛选      - 模拟输入 Query 在线召回     |
|  - 记忆开关与防抖轮次     - 查看摘要与五大提取标签    - 直观比对余弦相似度 Score    |
|  - 30天 TTL 与半衰期      - 手动纠错、编辑或单条删除  - 验证 RediSearch 索引有效性  |
+-----------------------------------------------------------------------------------+

1. 向量引擎健康度自检 (Vector Health Check)：
   • 实时探测平台主 Redis Stack / RediSearch 模块是否就绪、向量索引 nanzi:idx:memory:session_summary 是否建立成功、Embedding 模型服务是否连通；
2. 记忆参数热调优 (Config Settings)：
   • memory_service_enabled：全局记忆服务总开关；
   • memory_summary_ttl_days：摘要记忆保留周期（默认 30 天，可根据企业合规需求延长或缩短）；
   • memory_summarize_debounce_turns：防抖轮次，控制会话每进行多少轮触发一次增量摘要提炼；
   • memory_base_half_life：遗忘半衰期系数，让越近的记忆拥有更高的召回权重。
3. 数据管理与在线语义搜索测试：
   • 管理员与用户可在此查看沉淀的所有历史会话卡片与每日摘要；
   • 支持直接在检索框中输入测试语句，实时查看向量匹配的 Top-K 记忆片段与相似度分值（Score），若发现沉淀了错误或过期的偏好，支持一键删除或手动清空。

3.6.3 智能助手端内「记忆抽屉」联动 (Memory Browser Drawer)

在智能助手（EmbedChat）对话界面中，用户也可以随时点击输入框下方的 【记忆】 图标呼出快捷抽屉：

• 直观翻阅当前已沉淀的历史会话摘要；
• 一键挂载至本轮输入框：选中以往的某条关键摘要，即可直接将其作为上下文提示词注入当前对话，免去手动复制粘贴的繁琐操作。

3.7 任务调度台 (Task Center) 与 Cron 定时任务

【任务调度台】（Task Center）将智能体从传统的“人问机答”被动交互模式，升级为**“AI 自主定时工作并汇报”的自动化无人值守工作流**。

3.7.1 任务中心核心运行原理

sequenceDiagram
    autonumber
    participant Cron as ⏰ 平台 Cron 调度引擎
    participant Agent as 🤖 目标业务智能体
    participant Sandbox as 📦 隔离执行沙箱
    participant Push as 📢 通知通道 (企微/钉钉/飞书/邮件)

    Cron->>Cron: 检测到调度时间触发 (如每天 09:00)
    Cron->>Agent: 派发预设 Prompt 任务 (携带专属任务上下文)
    Agent->>Sandbox: 自动执行脚本、拉取数据、分析生成报告
    Sandbox-->>Agent: 返回数据结果与工件下载链接
    Agent-->>Cron: 汇总生成最终格式化报告 (Success / Failed)
    Cron->>Push: 根据任务推送策略向群机器人/邮件投递报告

3.7.2 定时任务创建“四步指南”

1. 选择执行智能体：指定由哪个业务智能体负责该任务（例如选择【销售数据对账智能体】）；
2. 编写执行指令 (Task Prompt)：
   • 给出清晰详尽的工作指令（例如：“拉取昨日全渠道销售订单，核对退款明细，若退款率超过 5% 标红预警，并生成分析表格”）；
3. 配置调度周期 (Cron 表达式)：
   • 支持标准 5 位 Cron 表达式（分钟 小时 日 月 星期）；
   • 界面内置常用快捷模板（每小时、每天早晨、工作日早晨、每月 1 号等）；
4. 绑定通知通道与触发策略：
   • 选择推送到指定的企业微信群、钉钉群、飞书群或管理员邮箱；
   • 推送策略：
     • 全部通知：任务每次执行完毕（无论成功失败）均推送完整图文报告；
     • 仅失败通知：执行成功保持静默，仅在异常报错时触发紧急告警。

3.7.3 任务执行实例与生命周期监控

• 每次触发会自动创建唯一的 Task Run 历史记录；
• 记录任务的精确开始时间、结束时间、执行耗时、消耗 Token 及完整的智能体思考过程与工具调用日志；
• 执行失败时自动保留失败状态和执行记录；可通过任务中心的「立即执行」手动重新触发，或在「执行失败策略」中配置定时触发失败后的自动重试。

3.7.4 多节点部署与调度器节点开关

• 默认行为：TASK_SCHEDULER_ENABLED 未配置时等同于 true，单节点部署无需额外设置。
• 多节点部署必须人工指定唯一的调度器节点：
  • 调度器节点：TASK_SCHEDULER_ENABLED=true；
  • 其他 API 节点：TASK_SCHEDULER_ENABLED=false。
• 这个配置是人工开关，不是自动选主。如果多个节点都为 true，每个进程都会启动 APScheduler；虽然部分智能体执行有 Redis 执行期锁保护，但不能据此保证所有定时任务只执行一次，可能出现重复触发或重复通知。
• 关闭调度器的节点仍可提供登录、API、任务管理和「立即执行」能力，只是不启动 Cron 定时器。
• 开启调度器的节点会每 30 秒从共享主库对账任务和报告订阅；所有节点必须连接同一平台主库和 Redis。关闭节点上的任务新增、修改、停用或删除通常会在一个对账周期内同步到调度器节点。
• 修改 .env、Docker Compose 环境变量或 Kubernetes ConfigMap 后，必须重启对应服务。滚动发布时应避免两个节点短时间同时以 true 启动。

3.7.5 定时任务失败重试策略

• 配置入口：任务中心 → 编辑定时任务 → 执行失败策略。
• 最大重试次数支持 0–3 次，默认 0（默认不重试）；重试间隔支持 1–60 分钟，默认 5 分钟。
• 自动重试只针对 Cron/定时触发的任务执行失败；任务中心的「立即执行」不会自动重试，也不会自动进入这套重试流程。
• 每次失败和重试都会保留对应的执行记录；达到最大重试次数后，任务最终按失败状态结束，并依据任务的通知策略发送失败通知。
• Redis 执行期锁冲突属于并发保护场景，不等同于任务执行失败；同一任务已经运行时，后续触发可能被跳过，不会按普通失败次数累计重试。

3.7.6 任务未执行或重复执行排查

1. 先看节点开关：确认实际运行进程中只有一个节点为 TASK_SCHEDULER_ENABLED=true；修改环境变量后确认服务已经重启。关闭节点启动时会在日志中打印调度器关闭提示。
2. 再看任务本身：确认任务状态为启用、Cron 表达式正确，并核对平台时区配置（默认 Asia/Shanghai）。
3. 检查共享依赖：多节点必须使用同一主库和 Redis；Redis 不可用时无法可靠提供执行期锁，存在重复执行风险。
4. 等待对账或重启验证：任务定义变更后通常等待约 30 秒即可同步；若仍未生效，查看调度器节点日志和任务执行历史。
5. 区分调度问题与智能体问题：使用「立即执行」验证智能体、模型、工具和沙箱本身；若立即执行也失败，应继续排查运行链路，而不是只调整 Cron 或重试参数。

3.8 智能体单步调试 (Agent Debug) 与接口调试台 (Playground)

• 智能体单步调试 (Agent Debug)：可视化拆解智能体的 Thought -> Action -> Observation -> Final Answer 执行链；
• 接口调试台 (Playground)：便于开发者直接调试底层 API 端点与参数。

3.9 小白高频问题与智能体排查 Q&A

四、ChatBI 开发平台

4.1 核心逻辑：ChatBI 是如何安全查询企业数据的？

很多企业用户担心：“用大模型查数据库，会不会把我的机密客户数据泄露给第三方大模型服务商？”

平台的实现逻辑绝对安全，严守数据不出域原则：

flowchart TD
    UserQuery["用户自然语言提问
（例如：上月华东区销售额是多少？）"] --> Step1["① 提取元数据字典与字段别名
（仅包含表结构，绝无真实业务数据！）"]
    Step1 --> Step2["② 发送给 LLM 生成只读 SQL"]
    Step2 --> Step3["③ 平台本地只读连接池执行 SQL"]
    Step3 --> Step4["④ 在本地将统计结果绘制为图表返回给前端"]

1. 只传 Schema，不传数据：发送给大模型的只有数据表结构、字段说明和几条示例，数据库中的真实数据记录绝不会发送给大模型；
2. 纯只读安全执行：生成的 SQL 仅在平台本地数据库连接池中执行，并强制拦截一切写操作。

4.2 元数据同步与业务语义字典标注 (Metadata Management)

【元数据管理】（Metadata Management）是 ChatBI 平台中最为关键的知识中枢与数据底座。它是大模型理解企业底层数据仓库的“罗塞塔石碑”与“业务翻译官”。

graph TD
    DS["💾 物理数据源
(MySQL / PG / ClickHouse)"] --> Dataset["📂 数据集 (Dataset)
按业务域划分 (交易域 / 流量域 / 财务域)"]
    Dataset --> TableMeta["📁 库表级元数据
表物理名 + 表中文名 + 业务说明 + 启用状态"]
    TableMeta --> ColMeta["📊 字段级元数据
物理列名 + 中文业务名 + 数据类型 + 维度/度量 + 主外键关系"]
    ColMeta --> DictMeta["🏷️ 业务枚举与代码字典
状态代码 -> 真实业务含义 (0=未支付, 1=已支付)"]
    DictMeta --> Assembly["🧠 动态 Schema 召回与 Prompt 组装
按用户提问按需抽取最相关的 3~5 张表组装注入大模型"]

4.2.1 为什么元数据是 Text-to-SQL 的生命线？

大语言模型虽然懂通用的 SQL 语法规则，但它完全不了解企业私有业务的缩写习惯与命名规范：

• 例如：如果数据库字段名为 c_je、f_is_vld、biz_cgy_cd，大模型无法凭空猜出其实际业务含义；
• 如果没有主外键关联关系，大模型在进行多表联结时容易发生 CROSS JOIN 笛卡尔积或错误的 ON 关联条件；
• 如果状态码（如 0/1/2/3）没有业务字典，用户提问“查已退款订单”时，大模型只能盲猜 status = 1 或 status = 'refund'，导致查询结果完全错误。

元数据管理的目的，就是将生硬的物理数据库表结构，转化为大模型一读即懂的“业务语义网络”。

4.2.2 数据集 (Dataset) 与数据域划分架构

在大型企业中，一个数据库往往包含几百上千张数据表。如果把所有表全量塞给大模型，会导致严重的上下文溢出与 Token 浪费。 平台通过数据集 (Dataset) 实现业务域分流与隔离：

• 按业务域组织：例如划分为【电商交易数据集】、【会员用户数据集】、【财务账单数据集】；
• 针对性挂载：针对特定岗位的智能体（如“财务对账助手”），只为其挂载【财务账单数据集】，既降低了大模型混淆不同业务表的概率，又极大提升了响应速度与安全性。

4.2.3 新建数据集的 3 种核心方式与分步操作指南

[!IMPORTANT] 🚀 前置准备与运行依赖检查 (必读)： 在新建数据集及导入数据表元数据之前，请务必确认以下底层环境配置已就绪，否则在元数据落库时将无法生成向量索引或在 ChatBI 问答时无法正常召回库表：

1. 确保向量模型 (Embedding) 已正确配置：进入【系统管理 -> 模型管理】确保已注册并启用 Embedding 向量模型，或在【系统设置 -> 参数设置】中已配置好有效的 embed_api_url（如 Ollama 的 /v1 向量端点或兼容 API），用于表注释与字段语义的向量化计算；
2. 确保向量索引引擎已正确配置并运行 (二选一)：在【系统设置 -> 参数设置】中已正确指定 metadata_provider（redis 或 ragflow），且对应的 Redis 向量版 (Redis Stack Server 7.x+ 含 RediSearch) 或 RAGFlow 引擎已完成独立部署与网络连通测试，用于承载元数据的毫秒级语义索引与动态召回；
3. 检查元数据专家智能体 (metadata-specialist) 模型绑定：在执行 DDL 智能导入解析、表关联关系推荐与业务指标推荐时，系统会优先调用名为 metadata-specialist 的专属智能体。若系统中已初始化该智能体，请务必进入【智能体中心】检查其激活版本绑定的模型是否已换绑为您自己的真实可用模型（若未激活该智能体，系统会自动平滑降级使用【参数设置】中的 llm_model_name 全局兜底模型）。

平台在【ChatBI 开发平台】->【元数据管理】提供了 3 种灵活的数据集创建与初始化方式，满足从零规划、现有 SQL 脚本导入以及直连物理数仓同步等不同阶段的需求：

graph TD
    Entry["📂 进入【元数据管理】数据集列表"] --> Choice{"选择创建方式"}
    Choice -- "方式 1" --> Mode1["📄 空白新建
(手动定义基本信息，后续加表)"]
    Choice -- "方式 2" --> Mode2["⚡ 智能导入 DDL
(粘贴建表 SQL/上传文件，AI 自动解析标注)"]
    Choice -- "方式 3" --> Mode3["💾 直连物理数据库导入
(从已配置数据源勾选物理表批量同步)"]

🌟 方式一：空白新建 (Blank Dataset Creation)

• 适用场景：先规划好业务域数据集边界，后续再按需逐张添加数据表或逐步配置。
• 分步操作指南：
  1. 点击新建：进入【元数据管理】，点击右上角的 「新建数据集」 主按钮（或下拉菜单中的「空白新建」）；
  2. 填写基本信息：
     • 物理名称 (Unique Name)：唯一英文标识，如 ds_trade_orders、crm_customer_hub；
     • 显示名称 (Display Name)：中文友好名称，如 全渠道交易域数据集；
     • 数据源 ID (Data Source ID)：点击右侧图标可下拉选择已配置的数据源连接（如 mysql_crm_01），后续 ChatBI 查数会通过该数据源连接执行 SQL；留空则使用系统默认数据源；
     • 业务描述 (Description)：简要描述该数据集包含的核心业务主题；
     • 业务标签 (Tags)：输入标签（如 电商、核心财务）并按回车添加，便于检索与分类治理；
  3. 确认创建：点击「确认创建」完成初始化。随后可进入该数据集详情页，进行后续的数据表添加、DDL 导入或字段标注。

⚡ 方式二：智能导入 DDL / SQL 脚本 (Smart Import DDL)

• 适用场景：已有现成的数据库建表 SQL（CREATE TABLE ...）或 .sql 导出的 DDL 脚本，希望借助 AI 极速自动解析表结构、字段类型并批量生成高质量的中文业务标注。
• 分步操作指南：
  1. 打开向导：在右上角新建按钮右侧点击下拉箭头，选择 「智能导入 (DDL)」；
  2. 输入 DDL 来源 (Step 1: Input)：
     • 直接粘贴：在文本框内直接粘贴多张表的建表 SQL 语句；
     • 文件上传：点击「上传文件」或将本地的 .sql / .txt 脚本文件直接拖拽入上传区域，系统自动读取文件内容；
     • 配置数据集属性：填写目标数据集的物理名称、显示名称以及关联的数据源；
  3. AI 智能分析解析：
     • 点击 「开始 AI 智能分析」，系统后台启动 Agent 深度解析流水线；
     • 自动提取表物理名、字段类型、主外键关联关系，并调用大模型根据字段英文名与原始注释推导出规范的中文业务别名与指标度量分类；
  4. 可视化预览与微调 (Step 2: Preview & Confirm)：
     • 进入结果预览面板，系统结构化展示识别出的所有库表清单、字段映射表及推导出的表间 JOIN 关系；
     • 支持在界面上直接二次编辑修改表中文名、字段业务别名或开关字段；
  5. 保存入库：点击 「保存并创建数据集」，一键完成数据集与底层全量表结构元数据的落库构建。

💾 方式三：直连物理数据库批量导入 (Live Database Schema Import)

• 适用场景：已在系统【数据源配置】中录入了真实数据库连接（MySQL / PostgreSQL / ClickHouse），需要直接从物理库中批量挑选已有数据表同步到平台元数据中心。
• 分步操作指南：
  1. 前置确认：确保在【系统设置】->【数据源配置】中已添加目标数据库连接并通过连通性测试；
  2. 发起导入：
     • 可在「智能导入向导」中点击 「从数据库导入」；或在已有数据集详情页中点击 「导入数据表 -> 从数据源导入」；
  3. 选择目标数据源 (Step 1: Connection)：
     • 在已保存的数据源列表中选择目标连接，点击「测试并继续」，系统自动通过 Information Schema 加载远端库表清单；
  4. 勾选数据表 (Step 2: Select Tables)：
     • 列表呈现远端数据库中的所有物理表，系统会自动将当前数据集已导入的表置灰禁用防止重复添加；
     • 支持搜索过滤表名，勾选本次需要同步的目标数据表（支持批量多选与全选）；
  5. 确认同步：
     • 点击「确认导入」即可快速将表物理名、列类型、注释、主键与索引信息同步落库；
     • 导入后还可一键触发 「AI 智能画像与指标推荐 (Profile & Metrics)」，由大模型自动为新导入的表补充完善中文业务别名与关系推导。

4.2.4 库表与字段属性治理体系

在元数据管理界面中，支持对库表与字段进行多维度的精细化配置：

1. 库表级属性治理：
   • 表物理名 (Table Name)：数据库中的真实物理表名（如 dwd_trade_orders_hi）；
   • 表中文业务名 (Display Name)：面向业务的规范命名（如 全渠道订单明细表）；
   • 表用途说明 (Description)：简述该表的核心业务场景与时间粒度（如 按天增量记录所有在线销售订单）；
   • 启用 / 禁用 (Visibility)：支持将底层的临时表、日志表或敏感薪资表设置为“禁用”，禁用的表绝不会被暴露给大模型。
2. 字段级属性治理：
   • 字段物理名 (Column Name) 与 中文业务别名 (Field Alias)；
   • 字段类型 (Data Type)：明确指定 VARCHAR, BIGINT, DECIMAL, DATETIME；
   • 维度 vs 度量 (Dimension vs Metric)：
     • 维度 (Dimension)：用于分组与过滤的分类字段（如 省份、商品分类、客户等级）；
     • 度量 (Metric)：用于聚合统计的数值字段（如 订单金额、销量、客单价）；
   • 主键 / 外键关系 (Primary Key / Foreign Key)：
     • 明确标注各表的主键与外键关联目标表字段（如 t_order.user_id -> t_user.id），大模型在生成多表 JOIN 时能够 100% 准确编写关联条件。

4.2.5 业务枚举与代码字典映射 (Dictionary Mapping)

针对包含状态码、类型代码的字段，平台提供了专属的枚举字典配置器：

• 配置示例：针对 pay_status 字段配置：
  • 0 -> 未支付 / 待付款
  • 1 -> 已支付 / 付款成功
  • 2 -> 已退款 / 退单
  • 3 -> 已取消 / 订单关闭
• 模型理解效果：当用户提问“统计今年各渠道退单总金额”时，大模型根据字典映射直接生成 WHERE pay_status = 2，精准无误。

4.2.6 AI 辅助一键智能标注与动态 Schema 召回组装

针对数仓中上千个字段手动标注过于耗时的痛点，平台提供了智能化自动治理机制：

1. 一键同步元数据 (Auto Sync)：系统通过 Information Schema 毫秒级抓取最新表结构；
2. AI 智能推荐中文别名：系统自动调用大模型根据表名英文单词、字段注释推导并推荐最地道的中文业务名称，管理员仅需人工复核点击保存；
3. 动态 Schema 召回 (Dynamic Schema Retrieval)：
   • 用户提问时，系统并不是把整个数据集全部塞进 Prompt；
   • 而是先根据提问语义在元数据向量库中检索出与本次问题最相关的 Top 3~5 张数据表；
   • 动态拼接精准的最小 Schema 注入大模型，节约 80% 以上的 Token 消耗。

4.2.7 小白实战避坑指南

• 💡 避坑 1：字段别名千万不要重名。例如在同一张表里不要把两个不同字段都起名叫“金额”，应明确标注为“订单总金额”与“实付金额”；
• 💡 避坑 2：日期字段务必标明格式。如某些历史表用 VARCHAR 存 YYYYMMDD 字符串，需在字段说明中注明，以便大模型使用正确的字符串格式化函数（如 SUBSTR 或 STR_TO_DATE）；
• 💡 避坑 3：库表结构变动后善用【Schema 巡检与差异治理】或配置【定时巡检】。当物理数据库新增了列、删除了字段/整表或变更了数据类型时，系统会自动通过 ChatBI 运行时报错自愈反哺或定时巡检探测差异并呈现于首页横幅待办；您可随时进入【Schema 巡检与差异治理】一键收录新字段、下线整表或同步物理类型，系统会自动刷新向量知识库并沉淀变更审计日志 (Changelog)。

4.2.8 智能指标发现 (Smart Metric Discovery) 操作指南与避坑

【智能指标发现】是平台基于大模型与数据架构师专家经验打造的自动化指标挖掘引擎。它能自动解析数据集 Schema、业务术语与字段类型，智能推导并推荐出合规、高价值、具备即席分析意义的 KPI、分布占比与核心视图，并自动生成 ClickHouse / MySQL 兼容的 SQL 计算逻辑。

flowchart TD
    DatasetSchema["📂 选定分析数据表 Schema (支持动态裁剪)"] --> Generator["🤖 AI 数据架构师 (Metadata Specialist)"]
    Pref["💡 用户自定义业务偏好 (可选通用模式)"] --> Generator
    Deduplicate["🛡️ Redis 10分钟去重 + DB既有指标负向排除"] --> Generator
    Generator --> Output["✨ 推荐指标 (聚合度量 / 维度分布 / 极值排行)"]
    Output --> Adopt["📥 多选批量采纳入库 -> 支撑 ChatBI 精准问答"]

🚀 核心入口与使用方式

1. 全局发掘入口：进入数据集详情页 -> 切换到【业务指标】Tab -> 点击右上角 「✨ 智能发现」 按钮；
2. 单表快捷发掘入口：在数据集【数据表】Tab 中，每张数据表卡片的操作区（删除按钮右侧）提供了快捷按钮 「✨ 为此表智能发现指标」。点击后弹窗将自动仅勾选当前单表，极大方便针对核心事实表或维度表进行定向深度挖掘。

💡 核心操作技巧

1. 数据表范围精准裁剪与折叠：
   • 支持按需勾选参与分析的数据表（默认全选），支持关键词实时搜索与全选/取消；
   • 顶部提供【折叠/展开】切换，折叠态展示已选表标签摘要，避免占据屏幕空间；
   • 后端原理：系统仅提取选中表的 Schema YAML 注入 Prompt，既节约 70% 以上 Token，又使大模型更加聚焦于指定业务主线。
2. 自定义业务偏好与 5 大通用模式：
   • 支持在输入框中输入自定义关注点（如“重点关注各销售大区的退款率与履约时效”）；
   • 点击输入框右上角 「？」 帮助按钮，可查看结构化填法指南，并支持一键套用 5 大全行业通用模式：
     • 📈 总量与核心趋势：适用于发掘总金额、订单量、活跃用户等大盘核心 KPI；
     • 🍰 维度分布与占比：适用于分析按渠道、地区、品类分组的占比度量；
     • 🎯 转化率与质量分析：适用于计算转化率、退单率、履约达成率等比率指标；
     • ⚠️ 异常监控与风险预警：适用于统计超时订单数、高频告警、失败流水等风控指标；
     • 🏆 TOP 排名与极值洞察：适用于发掘销售冠军、高客单价用户等排序视图。
3. ⏱️ 秒表计时、等待提示与随时取消：
   • 深度分析大表 Schema 与多表口径通常需要 15~60 秒，环形加载动画中央实时显示已耗时秒数；
   • 支持点击 【✕ 取消生成】 按钮，系统基于 AbortController 立即终止网络请求并恢复配置状态。
4. 🛡️ 10 分钟自动去重与负向排除：
   • 系统自动将数据库已有指标与近 10 分钟内已推荐过的指标（Redis TTL=600s）注入 Prompt 作为严禁重复推荐的负向排除清单，并在模型返回后进行代码级后置剔除，杜绝短期内重复推荐相同指标。

4.2.9 实体关系智能发现 (Smart Relationship Discovery) 与双视图 ER 拓扑

在大型数据仓库中，多表之间的主外键关联（Foreign Key / Join 路径）是实现跨表分析（如“查询买过某商品的用户所在城市分布”）的关键纽带。 【实体关系智能发现】通过大模型交叉比对各表字段命名（如 order_id 与 id）、字段类型、业务描述与事实-维度关系，自动推导跨表 Join 条件与关联类型（一对一 / 一对多 / 多对一），并输出置信度。

🌟 双视图工作台 (Dual View Workbench)

在结果展示界面，平台提供 【📋 列表卡片】 与 【🕸️ 关系 ER 图】 两种专业视图自由切换：

graph LR
    subgraph View1["📋 列表卡片视图"]
        L1["源表 🔑 -> 目标表 🔗"]
        L2["中文关系类型标签 (一对多 / 多对一 / 一对一)"]
        L3["指示灯置信度徽章 (🟢 95% 高置信 / 🟡 中置信)"]
        L4["JOIN 语法等宽代码块与业务说明"]
        L5["支持按【置信度】或【源表】即时排序"]
    end
    subgraph View2["🕸️ 交互式 ER 图画布"]
        G1["ECharts 力导向拓扑关系图"]
        G2["节点区分事实表 (蓝/紫) 与维度表 (绿)"]
        G3["连线高亮已选采纳关系 (实线/置信度色)"]
        G4["支持鼠标滚轮缩放、拖拽画布与平移"]
        G5["💡 点击拓扑连线可直接切换勾选/取消采纳"]
    end

💡 实体关系推导使用建议

1. 至少勾选 2 张数据表：由于关联推导涉及跨表比对，至少需选择 2 张表；支持表名检索与一键折叠；
2. 全行业 5 大通用关联偏好：
   • 🔗 核心主外键关联：事实表与基础维度表之间的连接；
   • 👥 用户与单据归属：操作人、审批人与业务单据关联；
   • 📦 主子表明细关联：主订单与子项明细、主任务与执行步骤关联；
   • 🏢 组织机构与多级层级：部门、机构、租户与业务表关联；
   • ⚙️ 流转状态与事件流水：业务实体与状态变更、审计日志流水关联。
3. 解除 10 条数量限制：系统不设固定条数上限，根据选定表的复杂程度尽可能全面输出所有高置信度关联；
4. 一键批量入库：勾选满意的关系后点击【采纳选中关系】，系统自动根据物理表名反查数据库表 ID 并批量写入实体关系库，立即生效于 ChatBI 跨表 SQL 生成。

4.2.10 元数据物理结构巡检与 Schema 漂移闭环治理 (Schema Drift & Consistency Inspection)

在企业数据仓库中，业务物理数据库（MySQL / PostgreSQL / Oracle / ClickHouse 等）经常会发生 DDL 变动：例如业务升级删除了过时列、新增了扩展字段、下线并删除了废弃数据表（DROP TABLE）、或将列数据类型从字符串改为日期/枚举等。

如果元数据未能及时感知这些变动，大模型在生成 SQL 时就会因为引用了已不存在的表或字段而频繁报错（如 Unknown column、Table doesn't exist），或者因为类型不匹配生成错误的过滤与转换函数。

平台首创了 「双源感知 + 物理巡检 + 人机协同 (HITL) + 定时巡检告警」 的完整闭环治理体系，绝不盲目篡改线上元数据，全程可审计、可回溯。

flowchart TD
    subgraph S1["🔍 漂移双源发现机制"]
        R1["⚡ 运行时物理报错反哺
ChatBI 执行 SQL 报 Unknown column 等错误
自愈剔除后非阻塞反哺至漂移待办"]
        R2["⏱️ 物理结构一致性巡检
直连底层物理数据库
支持单数据集即时体检 / 全库批量流式巡检 / 定时自动巡检"]
    end

    subgraph S2["🚨 汇聚与感知大盘"]
        AlertDB[("📦 漂移待办告警库
meta_schema_drift_alerts")]
        Banner["⚠️ 元数据首页常驻预警横幅
展示待办数据集与漂移项计数"]
        Notice["📢 离线告警通知通道
仅异常时推送：站内信必达 + 钉钉/企微/飞书/邮件"]
    end

    subgraph S3["🛠️ 人机协同 (HITL) 精准治理控制台"]
        Drawer["⚡ Schema 巡检与差异治理抽屉
分类胶囊过滤 Pills · 表名/字段名即时搜索"]
        Act1["🏢 物理表缺失 (table_missing_in_db)
👉 一键【下线整表】（级联清理下属列与历史告警）"]
        Act2["🗑️ 字段物理缺失 (column_missing_in_db)
👉 一键【下线该字段】"]
        Act3["🔄 类型跨大类不匹配 (type_mismatch)
👉 一键【同步物理类型】（智能探测真实类型）"]
        Act4["📥 物理新增字段 (column_added_in_db)
👉 一键【录入到数据集】"]
        Batch["🚀 顶部一键批量通道
一键下线缺失表 / 一键同步全部类型 / 一键录入新增 / 一键下线字段"]
    end

    subgraph S4["📋 闭环溯源与知识库生效"]
        Changelog["📝 数据集变更日志 (Changelog)
自动记录操作人、操作时间、变更原因
详情页呈现时间线与字段级红绿 Diff"]
        VectorSync["🔄 本地向量知识库自动重构
级联刷新 Redis 向量索引，大模型语义即刻生效"]
    end

    R1 --> AlertDB
    R2 --> AlertDB
    AlertDB --> Banner
    R2 -.->|检出异常/漂移| Notice
    Banner --> Drawer
    Drawer --> Act1 & Act2 & Act3 & Act4 & Batch
    Act1 & Act2 & Act3 & Act4 & Batch --> Changelog
    Act1 & Act2 & Act3 & Act4 & Batch --> VectorSync

🌟 核心能力与治理场景

1. 🏢 物理表级缺失（table_missing_in_db）精准探测与整表下线：

   • 痛点：过去当物理库执行了 DROP TABLE，元数据若未清理，模型仍会检索并生成针对该表的 SQL，导致高频语法/物理错误；
   • 快速判定：巡检引擎在逐表扫描前，优先通过数据源适配器调用 adapter.get_tables() 获取物理库当前存活的所有真实物理表集合；若纳管的数据表已不存在，精准标记为「整表物理缺失」并跳过后续无谓的列扫描；
   • 整表安全下线处置：在抽屉中点击【下线整表】（或顶部【🏢 一键下线全部缺失表】），系统自动将该表从数据集中注销，ORM 级联清理下属列定义；同时自动将该表关联的所有历史待处理告警流转为已处置（status=1），杜绝残留孤儿告警。

2. 🔄 物理类型不匹配（type_mismatch）智能校准：

   • 跨大类精准识别：算法剥离方言修饰符（长度、unsigned 等），仅在发生跨大类质变（如字符串 varchar ↔ 日期 date/datetime、整型 ↔ 字符串等）时才判定为不匹配，避免不同数据库方言同族名称差异产生无效误报；
   • 双重策略自动同步：点击【同步物理类型】（或顶部【🔄 一键同步全部类型差异】），系统优先通过数据库适配器实时探测物理库实际类型进行修正；若数据源临时离线，则自动通过正则从告警异常样本中提取真实物理类型智能兜底，确保 100% 成功校准。

3. 📥 物理新增字段（column_added_in_db）一键收录：

   • 当业务表新增字段时，巡检引擎实时捕获未纳管列；
   • 点击【录入到数据集】（或顶部【📥 一键收录全部新增字段】），系统自动将新列载入元数据模型，支持直接继承物理注释作为业务说明，并自动同步向量。

4. 📝 数据集变更日志 (Changelog) 全生命周期溯源：

   • 下线整表、下线字段、录入新增字段或同步物理类型时，后端全量调用变更审计服务；
   • 自动记录当前登录操作人（user_name）、操作时间、结构化原因（如 元数据巡检：下线物理缺失表 orders）；
   • 在数据集详情页【变更日志】Tab 中提供高辨识度的时间线节点与字段级红绿 Diff 对比（展示被删除字段、新增字段及修改前后的字段属性变更）。

5. ⚡ 全量定时巡检配置与安全防护 (Cron Inspection)：

   • 专属入口：元数据管理页右上角【+ 新建数据集】下拉菜单中的 「⏱️ 定时巡检」（受权限严格保护，仅平台管理员 Admin 可见可配置）；
   • 预设周期与 Cron 自由设定：提供每日凌晨 2:00、4:00、每周一及自定义 5 位标准 Cron 表达式；
   • 系统旁路调度（零 Token 消耗）：集成 APScheduler 调度引擎（系统任务 metadata_inspection），直接异步直连物理数据库扫描比对，全程不消耗大模型 Token；支持一键「⚡ 立即运行一次」；
   • 维护期隔离安全防护 (active_only=True)：定时巡检与全量巡检自动过滤 MetaDataset.status == 1，自动跳过下线或维护中的数据集，避免夜间打扰或无效报错；
   • 离线告警通知渠道（站内信必达 + 外部机器人/邮件按需选择）：
     • 站内信 (Portal Inbox) 强制锁定勾选，确保管理员在平台内拥有持久化的系统告警记录；
     • 可自由叠加勾选 钉钉群机器人、企业微信群机器人、飞书群机器人或邮件通知；
     • 静默免打扰机制：严格遵守「仅当检出漂移差异或执行异常时才派发通知」原则，全库物理结构一致正常时完全静默不打扰；
   • 任务中心保护与执行历史回溯：在任务中心展示专属 ⚡ 系统 · 元数据巡检 紫蓝色系统徽标，严格禁止非 Admin 修改或删除；每次执行自动生成专属 trace_id 与执行耗时、扫描表数、差异结果，可在任务中心「执行历史回溯」抽屉中完整追溯每一次巡检轨迹。

4.3 案例集管理与 Few-Shot 向量匹配 (Examples Management)

【案例集管理】（Examples Management）是进一步将企业复杂查询准确率提升至 98% 以上 的核心武器。

4.3.1 什么是 Few-Shot 案例集？为什么它不可或缺？

企业在日常运营中存在大量复杂的特定业务口径（例如：“算复购率时剔除退款订单”、“跨多表的复杂 GROUP BY 统计”、“同比环比窗口函数”）。

单纯依赖表结构，大模型很难一次性猜中企业专属的计算口径。 案例集 将人类数据分析师精心调优好的黄金样本（自然语言提问 -> 标准答案 SQL）结构化沉淀进平台。

4.3.2 动态 Few-Shot 向量相似度召回流程

sequenceDiagram
    autonumber
    actor User as 用户 (User)
    participant ChatBI as 🧠 ChatBI 引擎
    participant VectorDB as 📚 案例集向量库 (RediSearch)
    participant LLM as 🤖 大语言模型

    User->>ChatBI: 提问：“统计华东区各门店上月的复购率”
    ChatBI->>VectorDB: 计算提问向量，检索语义最相似的 Top-N 案例
    VectorDB-->>ChatBI: 召回 2 条高度相似的真实历史对账 SQL 范例
    ChatBI->>LLM: 组装 Prompt：[表结构元数据] + [召回的 2 条黄金 SQL 案例] + [用户当前提问]
    Note over LLM: 大模型“依葫芦画瓢”参考相似范例生成 SQL
    LLM-->>ChatBI: 输出 100% 符合企业特定口径的正确 SQL
    ChatBI-->>User: 执行 SQL 并自动绘制柱状图/折线图呈现

4.3.3 案例沉淀的双向闭环

• 主动录入：数据分析师在【案例集管理】中录入高频疑难提问与标准 SQL；
• 一键采纳：在【聊天日志】中，如果用户对某次生成的 SQL 点赞或业务验证正确，管理员可“一键采纳沉淀为案例”。

4.3.4 案例向量同步的目标随检索模式自动区分

审核通过后，【案例集管理】中的“一键同步 / 单条同步”会按 metadata_provider 检索模式自动选择同步目标：

• RAGFlow 模式（metadata_provider = ragflow）：同步到 RAGFlow 知识库（chatbi-sample-knowledge-base），并同时联动写入本地 Redis 向量索引；
• 本地模式（metadata_provider = local）：仅同步到本地 Redis 向量索引（RediSearch/HNSW），全程不连接 RAGFlow，避免未部署 RAGFlow 时误报同步失败。此模式下案例列表的“RAG 同步”状态列会自动隐藏。

本地模式真正的全量向量重建入口是【系统配置 → 参数设置】中的“重构本地向量数据”，或服务启动时 metadata_provider=local 触发的自动同步。

当每个 SQL 生成轮触发“经验库检索”思考卡片且卡片为 未命中经验库案例 时，卡片详情会附上本次检索过程的诊断信息，方便判断卡在哪一环：

• 检索模式（local · Redis 向量检索 / ragflow · RAGFlow）
• 检索词：实际用于检索的词（若经过意图改写会标注「原问题改写而来」）
• top_k、相似度阈值 两个检索参数
• 向量召回 N 条 / 阈值后有效 M 条（归因“是根本没召回到近邻”还是“召回到了但相似度不足/缺 SQL 被滤掉”）
• 关键词兜底 Z 条〔词1、词2〕（向量链路空后才走的 MySQL LIKE 兜底结果数，并列出实际拆分的检索关键词）
• 耗时（本轮检索实际毫秒数）

说明：若卡片的诊断信息显示“向量库中未检索到任何近邻案例”，通常是本地向量数据尚未构建或库中尚无高质量案例；显示“已召回近邻但未通过阈值/可用 SQL 过滤”时，可考虑调低【系统配置】中的 chatbi_sample_similarity_threshold，或补充更多审核通过的高质量 SQL 案例。

案例集检索模拟器（主动测试命中情况）

在【案例集管理】工具栏点击「检索测试」可打开案例集检索模拟器：输入一条用户问题后，以与 ChatBI 运行时完全一致的链路在经验库中检索相似案例，并在“高级参数配置”中临时覆盖检索模式 / Top K / 相似度阈值 / 向量权重（仅 ragflow 生效），查看：

• 左侧命中结果：状态条（Hit/Miss）+ 命中案例卡片（编号、相似度、数据集、SQL 预览）；
• 右侧执行日志 (Trace)：实际生效的检索模式、检索词、Top K、阈值、向量召回数、过滤后有效数、关键词兜底数与耗时。

该测试为只读操作，不落库、不影响线上检索配置（临时参数仅本次测试生效），便于批量审核后验证样例集的命中质量与调参效果。

4.4 常见 ChatBI 问答与 SQL 执行排查 Q&A

4.5 数据门户与固化报表专题 (Saved Reports)

【数据门户】（Data Portal）是企业全员敏捷消费数据资产、浏览固定分析看板与调度订阅的核心统一入口。其中，【固化报表】（Saved Reports） 是承载企业标准权威查询口径、消除大模型重复思考与保障数据 100% 确定性的核心支柱。

graph TD
    subgraph Sourcing["📥 固化报表三大沉淀来源"]
        Src1["方式 1: 门户手工开发新建
(数据分析师手写 SQL + 在线试跑)"]
        Src2["方式 2: ChatBI 对话流一键固化
(用户在满意的问答卡片点击 ⭐ 固化报表)"]
        Src3["方式 3: 门户抽屉快捷沉淀
(ChatBI 侧边栏抽屉快速归档)"]
    end
    subgraph Repo["📊 统一固化报表中心 (数据门户 / 抽屉)"]
        Template["结构化 SQL 模板 + 动态参数配置
SELECT ... WHERE dept = {{dept_name}}"]
    end
    subgraph Consumption["🚀 四大敏捷消费场景"]
        C1["⚡ 门户在线运行 (修改参数/图表渲染/下载)"]
        C2["💬 ChatBI 智能体秒级直接召回引用"]
        C3["⏰ Cron 定时任务与通知通道推送订阅"]
        C4["🔗 嵌入式仪表盘分享至第三方业务系统"]
    end
    Sourcing --> Repo
    Repo --> Consumption

4.5.1 什么是固化报表？为什么全平台统一定名「固化报表」？

1. 核心定义：
   • 「固化报表 / 固化 SQL」是指将经过数据分析师、业务专家严格验证且口径权威、高频复用的标准 SQL 逻辑沉淀为参数化的固定报表资产；
   • 它支持自定义参数插值（如 {{start_date}}、{{channel}}）、多种数据可视化图表（柱状图/折线图/饼图/表格）、CSV 数据导出以及周期性自动化推送。
2. 为什么全平台统一定名为「固化报表」？：
   • 早期部分系统称其为“黄金报表 / 黄金 SQL (Golden SQL)”，容易让小白用户产生“金融理财产品”、“VIP 特权报表”或“仅限付费用户”等语义混淆；
   • 统一命名为**「固化报表」**，直观表达“将高频验证正确的即席查询固化沉淀为标准报表”的业务本质，全平台界面（数据门户、ChatBI 对话卡片、调试面板、通知中心）统一术语。

4.5.2 沉淀固化报表的 3 种核心方式

平台提供了从“手工专业开发”到“对话无缝沉淀”的多路径闭环：

🌟 方式一：数据门户手工新建与在线试跑 (Manual Builder)

• 适用场景：数据工程师或分析师主动沉淀经过精密编排的标准多表关联分析 SQL；
• 分步操作：
  1. 进入【数据门户】-> 点击【固化报表】Tab -> 点击右上角 「+ 新建报表」；
  2. 选择数据源与数据集：指定底层执行的数据连接；
  3. 编写/粘贴 SQL：在 Monaco 语法高亮编辑器中输入 SQL，支持使用 {{参数名}} 定义动态参数；
  4. 在线试跑语法验证：点击 「▶ 试跑测试 SQL」，系统将在后台安全沙箱中执行该 SQL，并即时预览返回的前 50 条真实数据与执行耗时；
  5. 保存入库：试跑成功后填写报表名称、业务说明与图表默认类型，点击保存。

🌟 方式二：ChatBI 对话流一键固化 (ChatBI One-Click Save)

• 适用场景：业务人员在与智能助手日常问答中，发现某次生成的复杂 SQL 结果非常精准有用，希望沉淀为固定报表供全团队日常查看；
• 分步操作：
  1. 在智能助手对话流中，找到满意的 ChatBI 数据卡片；
  2. 点击消息卡片底部的 「⭐ 固化报表」 按钮；
  3. 系统自动提取当前对话生成的精准 SQL、问题标题与数据集绑定，唤起编辑弹窗；
  4. 点击确认即可一键沉淀至固化报表库。

🌟 方式三：数据门户抽屉管理 (Dataset Portal Drawer)

• 在智能助手右侧随时展开【数据门户抽屉】，快速查看已沉淀的固化报表，并支持一键将其以对话消息卡片的形式发送至当前会话。

4.5.3 动态参数配置与在线调试沙箱

固化报表不仅支持静态查询，更支持强大的动态参数化插值绑定：

• 参数占位语法：在 SQL 中使用 {{参数名}}，例如：
  SQL复制

  SELECT 
      department_name, 
      COUNT(*) AS total_orders, 
      SUM(pay_amount) AS total_amount
  FROM orders_fact
  WHERE created_at >= {{start_date}}
    AND department_name = {{dept_name}}
  GROUP BY department_name;
  

• 参数类型配置：
  • 系统自动解析 SQL 中所有的 {{...}} 占位符；
  • 支持配置每个参数的显示标签（如“开始日期”、“部门名称”）、数据类型（文本 / 数字 / 日期）以及默认试跑值；
  • 运行或试跑时，系统安全替换对应参数值，防止 SQL 注入。

4.5.4 固化报表的运行、图表可视化、数据导出与定时调度订阅

1. 多维图表秒级渲染：
   • 运行报表后，系统根据数据结构自动推荐最适合的可视化图形（表格、柱状图、折线图、饼图、面积图），并支持全屏缩放与维度切换；
2. 全量数据导出：
   • 结果界面提供【导出 CSV】与【下载 Excel】按钮，分析师可随时将查询结果下载到本地进一步深度加工；
3. 定时任务自动化订阅：
   • 固化报表支持与平台【任务调度台】深度打通：可配置 Cron 定时计划（如每周一上午 9:00），系统自动运行最新参数并在执行完成后将报表概览与下载链接自动推送到企业微信/钉钉/飞书群或邮件。

五、知识库开发平台

5.1 核心逻辑：RAG 知识库检索与文档切片原理

知识库（RAG，检索增强生成）解决的是大模型“知识过时”与“不知道企业内部私有文档”的问题。

其底层处理分为两个阶段：

1. 构建期（文档切片与向量化）：

用户上传 PDF/Word 等文档 -> 平台智能切片为一个个段落（Chunk） -> 调用 Embedding 模型将文字转换为多维数学向量 -> 存入 RediSearch 向量数据库；

1. 检索期（语义匹配与回答生成）：

用户提问 -> 提问内容转换为向量 -> 在知识库中比对查找最相似的 Top-K 个文档片段 -> 将这些片段作为参考依据喂给大模型 -> 大模型生成有依有据的回答。

5.2 知识库创建与 RAGFlow 引擎对接

• 支持解析 PDF、Word (.docx)、Excel、Markdown、TXT 等格式文档；
• 集成 RAGFlow 深度文档理解引擎，支持智能表格抽取与多模态图表解析。

5.3 混合检索 (Hybrid Search) 与重排序 (Rerank) 调优

• 混合检索 (Hybrid Search)：结合向量语义相似度（Dense Retrieval）与 BM25 关键词全文匹配（Sparse Retrieval）；
• 重排序 (Rerank)：支持接入 BGE-Reranker 等重排模型，对初筛结果进行二次精排打分。

5.4 运营分析与无答案问题聚类挖掘

• 自动统计知识库召回命中率、用户点赞/点踩率；
• 聚类“未命中任何知识库切片”的疑难问题，辅助知识库管理员针对性补充缺失文档。

5.5 小白高频问题与知识库排查 Q&A

六、日志与 Token 分析

6.1 核心逻辑：什么是 Token？平台是如何计费与统计的？

• 什么是 Token？

Token 是大语言模型处理文本的基本单位。大模型不直接读文字，而是将文字拆解为一个个 Token 编码。

• 中文：通常 1 个汉字 ≈ 1 ~ 2 个 Tokens；
• 英文：通常 1 个英文单词 ≈ 1.3 个 Tokens。
• Prompt Token vs Completion Token：
• Prompt Tokens（输入）：你发送给模型的提示词、系统指令、历史对话和知识库参考内容；
• Completion Tokens（输出）：大模型回复生成的文字内容。

6.2 审计日志 (Audit Logs) 与操作追溯

• 完整记录平台所有敏感运维动作（用户管理、角色赋权、系统配置修改、数据源变动等），记录操作人、来源 IP、时间戳与前后变更 Diff。

6.3 聊天日志 (Chat Logs) 与复盘诊断

• 管理员可多维度检索全平台的会话记录，查看完整的上下文压缩日志、模型 Token 消耗及工具调用细节。

6.4 Token 统计与企业多维度成本分摊

• 支持按模型提供商、按具体模型、按用户及按时间跨度（日/周/月）统计 Prompt Tokens、Completion Tokens 与总消耗量；
• 支持模型单价配置与企业调用成本自动核算及报表导出。

6.5 小白高频问题与日志分析 Q&A

七、系统管理与配置

7.1 用户与角色权限

平台采用了兼具灵活性与严格安全性的 RBAC（基于角色的访问控制）架构，针对前端展示与后端 API 操作实施双重防护。

7.1.1 平台双层权限架构 (菜单 menu vs 元素 element)

1. 菜单权限 (menu:*)：

• 决定用户在左侧侧边栏能看到并进入哪些页面。
• 例如：menu:system:config 控制【系统配置】菜单可见性，menu:skills_management 控制【技能工作台】可见性。

1. 元素/功能级权限 (element:*)：

• 决定用户在页面中是否具备执行敏感操作（创建、编辑、删除、发布、审核）的权限。
• 例如：平台技能审核与全局技能管理使用 element:skills:admin 进行后端校验。

7.1.2 API Key 的安全生成与使用

• 每个平台用户在创建时会自动生成唯一的 api_key（亦可在用户中心随时重新生成）。
• API Key 具有与该用户完全相同的权限上下文，外部系统调用平台 API 时，需在 HTTP 请求头中携带：

  Authorization: Bearer <YOUR_API_KEY>

7.1.3 外部 V1 API 访问控制与白名单机制

• 白名单核心接口 (is_v1_api_whitelisted)：

基础对话（/api/v1/chat）、嵌入式会话（/api/v1/embed）、任务状态（/api/v1/tasks）及 Docker 沙箱工作区（/api/v1/sandbox/docker/workspace）为平台基础能力，登录用户无需单独分配资源权限即可直接调用。

• 受控分配接口 (ASSIGNABLE_V1_API_RESOURCES)：

对于个人资料读取（GET:/api/v1/users/profile）、数据库 Schema 导出（POST:/api/v1/schema）及 ChatBI 独立 SQL 执行（POST:/api/v1/chatbi/sql/execute），需由管理员在【角色管理】中显式勾选分配。

7.1.4 常见用户与权限 Q&A

7.2 模型注册与提供商管理

【模型管理】（Model Registry）是平台所有 AI 对话、推理思考、多模态识图与向量检索的统一底座。

7.2.1 支持的模型提供商生态与配置规范

平台原生内置了一线主流模型厂商与自建推理服务的预设：

• 公有云大模型：OpenAI、DeepSeek（深度求索）、Qwen（阿里百炼 / 通义千问）、Volcengine Ark（火山引擎 / 豆包）、SiliconFlow（硅基流动）、Moonshot（月之暗面）、ZhipuAI（智谱 GLM）、Baichuan（百川）等；
• 私有化与开源服务：Ollama（本地推理）、vLLM、Xinference、LocalAI 等兼容 OpenAI 协议的推理框架；
• 企业云平台：Azure OpenAI、AWS Bedrock 等。

7.2.2 模型能力分类 (Chat / Embedding / Multimodal / Reasoning)

在模型注册时，需根据模型实际能力指定模型类型：

• chat (LLM)：通用大语言模型，用于智能体对话、代码生成、SQL 编写与任务规划。
• embedding (向量模型)：用于知识库检索、语义相似度计算与元数据召回（如 text-embedding-v3、bge-large-zh-v1.5 等）。
• multimodal (多模态识图)：当主对话模型不具备视觉能力时，系统可通过配置的 multimodal_model_name 自动将图片解析为结构化文本注入上下文。
• reasoning (思考模型)：具备深度思考与 CoT 推理能力的大模型（如 deepseek-reasoner / qwq-32b）。

7.2.3 Base URL 智能版本号识别与端点规范化

在配置自定义 Embedding 或 Chat Base URL 时，平台具备智能版本号自动感知与规范化能力：

• 若用户输入已带版本号的 URL（如火山引擎 Ark 提供的 https://ark.cn-beijing.volces.com/api/coding/v3），平台会自动识别并只补齐 /embeddings，而不会错误硬拼 /v1/embeddings 导致 404；
• 若输入为根域名（如 https://api.openai.com），平台会自动规范化为 https://api.openai.com/v1/embeddings。

7.2.4 深度思考模型 (DeepSeek-R1 / QwQ 等) 工具调用兼容层

• 背景：部分深度推理模型在强制工具调用（Forced Tool Choice）或多步骤 Agent 规划场景下，倾向于先输出 <think>...</think> 思考过程再输出工具调用，这在标准 OpenAI 工具协议下易导致解析中断或死循环。
• 机制：平台内建 ThinkingToolChoiceCompatAgent 与流式事件适配器，能智能解析并过滤/转义 <think> 思考块，确保推理链完整呈现给用户界面的同时，准确触发底层的函数调用。

7.2.5 常见模型配置与调用 Q&A

7.3 参数配置专题

进入 系统管理 -> 系统配置 -> 参数配置，可全局微调平台 Agent 运行时行为。

7.3.1 多策略安全沙箱 (Local / Docker / K8s / E2B / SSH) 对比选型

⚠️ 强烈注意（平台容器化与集群部署场景选型建议）：

1. 单机 Docker 容器化部署：安全沙箱强烈建议配置走 docker 策略（并在启动平台容器时挂载宿主机 Docker 套接字 -v /var/run/docker.sock:/var/run/docker.sock 并配置 HOST_DATA_DIR）。
   • 为什么不能在平台容器内使用 local 策略？
   • 若使用 local 策略，所有用户通过智能体执行的 Shell 命令（如 apt-get、pip install、甚至死循环/删文件）都会在平台后端主服务的容器内直接执行，极易污染平台主运行环境、耗尽主容器资源或误杀主服务进程！配置为 docker 沙箱策略后，平台会通知宿主机 Docker 引擎为每个用户独立启动专用的纯净子容器，从根本上隔离运行风险。
2. Kubernetes 集群部署：安全沙箱首选且强烈推荐配置走 k8s 策略（详见 7.3.6 Kubernetes 原生 Pod 安全沙箱）。
   • 生产集群禁止将宿主机 Docker Socket 挂载进业务 Pod，使用 k8s 策略由平台直接调用 Kubernetes API 动态拉起受限的轻量沙箱 Pod，彻底杜绝容器逃逸与宿主机特权提权隐患，配合平台开箱即用的 RBAC 模板与 PVC 动态挂载，实现多租户严格安全隔离。

7.3.2 Docker 沙箱运行前提条件

要启用并稳定运行 docker 安全沙箱策略，需满足以下环境要求：

1. 宿主机需安装 Docker 引擎：
   • 机器需安装 Docker 20.10+ / Docker Desktop，并确保 dockerd 守护进程正在运行。
   • 在终端执行 docker ps 或 docker info 验证可正常连通。
2. 后端 Python 环境依赖：
   • Python 环境需安装 aiodocker 依赖（已内置于平台的 requirements.txt 中）：
     Bash复制

     pip install aiodocker
     

3. 平台自身使用 Docker 容器化部署时的注意事项：
   • 若平台后端服务本身是以 Docker 容器方式运行，需在启动命令或 docker-compose.yml 中挂载宿主机的 Docker Socket，使后端容器具备调用宿主机 Docker daemon 的能力（Docker-out-of-Docker）：
     YAML复制

     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
     

   • DooD 工作区路径必须额外配置 HOST_DATA_DIR。它必须填写 Docker daemon 所在宿主机上的数据目录绝对路径，并与 /app/data 的 Compose 源目录一致：
     YAML复制

     volumes:
       - /data/yunshu-aiagent/data:/app/data
       - /var/run/docker.sock:/var/run/docker.sock
     environment:
       - HOST_DATA_DIR=/data/yunshu-aiagent/data
     

   • 映射关系为：宿主机 /data/yunshu-aiagent/data/agent_workspaces/{user_key} → 平台容器 /app/data/agent_workspaces/{user_key} → 用户沙箱 /workspace。{user_key} 通常是 用户名__用户ID，例如 admin__1。
   • 不能只配置 /app/data 挂载而留空 HOST_DATA_DIR。平台容器可能正常看到 sessions，但宿主 Docker daemon 会收到错误的 /app/data/... 挂载源，导致沙箱 /workspace/sessions 为空。

7.3.3 Docker 沙箱镜像预构建指南

Docker 沙箱运行依赖 AgentScope 规范的专用执行基座镜像（内置 Python 运行时与 In-Container FastMCP 工具网关）。为避免用户首次发起对话时耗时等待构建，平台提供了一键预构建加速功能。

1. 选择容器基础镜像

在【系统配置】->【参数配置】->【安全沙箱】中：

• 平台默认使用官方标准 python:3.11-slim（或完整版 python:3.11）；
• 如在离线或内网环境部署，可选择「自定义镜像地址…」填写私有 Harbor 仓库镜像或已认证的企业镜像加速地址。

2. 后台界面一键预构建

1. 管理员登录系统，进入 系统管理 -> 系统配置 -> 参数配置 面板；
2. 在【安全沙箱】分组中，将安全策略切换为 docker；
3. 点击 ⚡ 预构建 / 重新预构建 按钮；
4. 后端将基于确定性哈希自动生成镜像构建上下文并持久化 Tag（例如 agentscope-workspace:6e0fab447d44）；
5. 构建完成后，界面将高亮展示 ✅ 镜像已预构建。

3. 管理端点 API 触发预构建

管理员亦可通过运维接口或 CI/CD 流程预先触发构建：

# 检查当前预构建状态
curl -X GET "http://127.0.0.1:8001/api/v1/admin/sandbox/docker/prebuild-status" \
     -H "X-API-Key: <ADMIN_API_KEY>"

# 强制触发预构建
curl -X POST "http://127.0.0.1:8001/api/v1/admin/sandbox/docker/prebuild?force=true" \
     -H "X-API-Key: <ADMIN_API_KEY>"

4. 运维脚本直接构建与代理支持（推荐排查方案）

在需要网络代理才能拉取 Docker 镜像或安装 pip 依赖的受限网络环境中，您可直接在宿主机或进入平台 Docker 容器内部运行预构建运维脚本：

# 1. 演练模式（仅生成 Dockerfile 与上下文，不触发构建）
./sandbox/docker/build-docker-sandbox-image.sh --dry-run

# 2. 探测本地所有已构建的沙箱镜像清单
./sandbox/docker/build-docker-sandbox-image.sh --list

# 3. 带 HTTP/HTTPS 代理执行预构建（实时流式查看 Docker build 进度）
./sandbox/docker/build-docker-sandbox-image.sh --proxy http://10.0.0.1:7890

# 4. 或在环境中预设代理环境变量后直接运行（自动识别，支持 -y 免交互）
export HTTP_PROXY=http://10.0.0.1:7890 HTTPS_PROXY=http://10.0.0.1:7890
./sandbox/docker/build-docker-sandbox-image.sh -y

# 5. 仅检查预构建状态与确定性 Tag
./sandbox/docker/build-docker-sandbox-image.sh --status

# 6. 指定特定基础镜像或强制重建
./sandbox/docker/build-docker-sandbox-image.sh --base-image python:3.11-slim --force --proxy http://10.0.0.1:7890

💡 提示：通过 ./sandbox/docker/build-docker-sandbox-image.sh 直接构建属于服务器本地/容器内部运维操作，无需传递 API Key。构建成功后会自动将预构建完成标记写入数据库与 Redis，回到前端管理页面刷新即可看到已就绪状态。

7.3.4 Docker 沙箱核心运行全流程与架构

sequenceDiagram
    autonumber
    actor User as 用户 (User)
    participant Front as 前端界面 (Web UI)
    participant Backend as 平台后端 (FastAPI)
    participant Daemon as Docker Daemon
    participant Container as 沙箱容器 (Sandbox Container)
    participant Gateway as In-Container Gateway (MCP)

    User->>Front: 发送对话请求 / 调试指令
    Front->>Backend: POST /api/v1/chat (携带 session & token)
    Backend->>Backend: 检查沙箱策略 (sandbox_policy = docker)
    Backend->>Daemon: 探测或拉起该用户私有容器 (agentscope-workspace:)
    Note over Backend,Daemon: 仅精准挂载当前用户目录 agent_workspaces/
    Daemon->>Container: 启动容器并孵化 In-Container Gateway
    Container->>Gateway: 拉起 FastMCP 工具服务 (Bash / Read / Write)
    Backend->>Gateway: 建立健康探活并分发智能体工具调用
    Gateway->>Container: 在隔离容器内执行 Shell / 代码
    Gateway-->>Backend: 返回截断保护的标准输出/错误日志
    Backend-->>Front: SSE 流式响应渲染结果给用户
    Note over Container: 30 分钟无交互自动触发空闲回收

流程关键节点解析：

1. 多租户按需拉起：每个登录用户拥有独立的容器与物理隔离的工作区（agent_workspaces/{user_key}），互不干扰。
2. 同路径物理映射与 DooD 挂载对齐：宿主机用户物理工作区挂载到平台容器的 /app/data/agent_workspaces/{user_key}，再挂载到沙箱容器的 /workspace。平台后端部署在 Docker 中时，必须通过 HOST_DATA_DIR 将容器内 /app/data 换算为 Docker daemon 所在宿主机上的真实数据目录；否则平台容器可见的文件不会自动出现在沙箱中。
3. In-Container Gateway 通信：AgentScope 在容器内拉起专用的 FastMCP 网关，智能体调用工具均通过 RPC/STDIO 协议与网关交互，异常崩溃不影响平台主进程。
4. 纵深安全防御：
   • 防路径穿越：容器内工具严禁 .. 越界访问工作区之外的文件；
   • 硬超时保护：命令执行单次上限 600 秒，防止死循环耗尽资源；
   • 日志截断保护：输出限制最大 100,000 字符，防范 OOM 溢出。
5. 空闲自动回收：连续 30 分钟无交互的容器自动停止并回收，释放内存与 CPU。
6. 用户端全生命周期管控与交互式 Shell 终端：
   • 交互式 Shell 终端调试：用户可在输入框浮标卡片中点击【进入终端】，唤起全功能 CLI 命令行模态框，在隔离沙箱内直接运行 pip, python, ls, curl 等指令排查环境依赖与执行结果；
   • 一键重启自愈：当沙箱因死循环进程卡住时，用户可点击【重启容器】（POST /sandbox/docker/workspace/restart）强制销毁旧容器并拉起新容器，同时完整保留工作区数据；
   • 手动主动关停：点击【停止关机】（POST /sandbox/docker/workspace/stop）即可随时提前释放沙箱资源。

7.3.5 常见 Docker 沙箱排查与报错解决

# 应用最小权限 RBAC 模板
kubectl apply -f k8s_deploy/sandbox-rbac.example.yaml

flowchart TD
    Edit["① 管理员在前端修改表单输入项
(此时仅存在于浏览器 Vue 响应式状态中)"] --> ClickSave["② 点击页面底部【保存配置】按钮"]
    ClickSave --> API["③ 发起 POST /api/portal/system/configs"]
    API --> DB["④ 持久化写入数据库 system_config 表"]
    DB --> Cache["⑤ 后端内存配置单例热刷新 (Hot Reload)
SystemConfigService.reload_cache()"]
    Cache --> Effective["✅ 智能体与各引擎即刻使用最新参数生效"]

7.4 通知通道与外部集成

平台支持将自动化任务调度（Task Center）的执行结果、审批提醒及系统异常实时推送到第三方办公与协作平台。

7.4.1 多通道通知配置指引 (企微 / 钉钉 / 飞书 / 邮件 / Webhook)

在【系统配置】->【通知渠道】中支持配置以下通道：

1. 企业微信群机器人 (WeCom Bot)：

• 填入企微群机器人的 Webhook Key / URL 即可。

1. 钉钉机器人 (DingTalk Bot)：

• 支持填写 Webhook 地址；若开启了“加签”安全设置，需同步填写加签 Secret。

1. 飞书机器人 (Feishu Bot)：

• 填入飞书群机器人的 Webhook URL；若开启签名校验需配置 Secret。

1. SMTP 邮件通知 (Email)：

• 配置 SMTP 主机（如 smtp.exmail.qq.com / smtp.163.com）、端口（SSL 465 或 TLS 587）、发件人邮箱及授权码。

1. 通用 Webhook (Custom Webhook)：

• 支持向企业内部业务系统推送标准 JSON Payload（包含事件类型、任务详情、错误堆栈与执行耗时）。

7.4.2 自动化任务调度中心的通知与告警绑定

• 在【任务调度台】中创建或编辑 Cron 定时任务时，可针对单任务选择通知通道，并设置触发策略：
• 全部通知：任务每次执行完毕（成功/失败）均发送报告；
• 仅失败通知：任务执行成功保持静默，仅在异常报错时触发告警；
• 关闭通知：不发送外部消息。

7.4.3 常见通知推送失败排查 Q&A

7.5 数据库与缓存维护

平台主库全面支持 MySQL 与 PostgreSQL，并强依赖 Redis Stack 实现高速会话记忆与语义检索。

7.5.1 MySQL 与 PostgreSQL 双数据库迁移规范

• MySQL 迁移目录：db-prod/（命名如 V129-*.sql）；
• PostgreSQL 迁移目录：db-prod-pg/（命名如 V29-*.sql）；
• 开发与升级准则：

1. 平台支持两套数据库，所有数据表结构变更必须同步新增双库版本的增量迁移 SQL；
2. 严禁直接手动修改已有历史版本的 SQL 脚本，保证平滑增量升级。

7.5.2 Redis Stack / RediSearch 依赖与 30 天状态 TTL

• RediSearch 引擎：平台利用 RediSearch 对历史会话记忆与上下文进行高效的向量与全文检索。
• 全链路 30 天 TTL 保障：会话历史（MemoryService）、上下文压缩快照（ContextCompactionLogService）、工件下载链接及 Agent 运行时状态缓存统一设置为 30 天（2592000秒）有效周期，确保用户长周期跨天会话不丢上下文。

7.5.3 常见数据库与缓存排查 Q&A

  docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest