',
- re.DOTALL,
+ r'
\s*\{\{ error \}\}\s*'
),
)
+ self.assertIn('
', source)
if __name__ == "__main__":
diff --git a/tests/test_supplier_config.py b/backend/tests/test_supplier_config.py
similarity index 78%
rename from tests/test_supplier_config.py
rename to backend/tests/test_supplier_config.py
index b3751bb04..8583ed630 100644
--- a/tests/test_supplier_config.py
+++ b/backend/tests/test_supplier_config.py
@@ -8,11 +8,12 @@
import json
import os
-import re
import unittest
# Project root relative to this test file
-PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PROJECT_ROOT = os.path.dirname(
+ os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+)
class TestMiniMaxSupplierConfig(unittest.TestCase):
@@ -22,7 +23,7 @@ def setUp(self):
supplier_path = os.path.join(
PROJECT_ROOT, "frontend", "src", "entity", "supplier.ts"
)
- with open(supplier_path, "r", encoding="utf-8") as f:
+ with open(supplier_path, encoding="utf-8") as f:
self.supplier_content = f.read()
def test_minimax_icon_import_exists(self):
@@ -47,18 +48,18 @@ def test_minimax_icon_reference(self):
def test_minimax_api_domain(self):
"""MiniMax API domain should be https://api.minimax.io/v1."""
- self.assertIn(
- "api_domain: 'https://api.minimax.io/v1'", self.supplier_content
- )
+ self.assertIn("api_domain: 'https://api.minimax.io/v1'", self.supplier_content)
def test_minimax_temperature_range(self):
"""MiniMax temperature should be in range [0, 1]."""
# Find the MiniMax section and check temperature config
- minimax_section = self.supplier_content[
- self.supplier_content.index("id: 13") :
- ]
+ minimax_section = self.supplier_content[self.supplier_content.index("id: 13") :]
# Limit to just MiniMax section (up to next id:)
- next_id = minimax_section.index("id: 11", 10) if "id: 11" in minimax_section[10:] else len(minimax_section)
+ next_id = (
+ minimax_section.index("id: 11", 10)
+ if "id: 11" in minimax_section[10:]
+ else len(minimax_section)
+ )
minimax_section = minimax_section[:next_id]
self.assertIn("key: 'temperature'", minimax_section)
self.assertIn("val: 0.7", minimax_section)
@@ -71,23 +72,27 @@ def test_minimax_model_options(self):
def test_minimax_has_model_config_type_0(self):
"""MiniMax should have model_config with type 0 (LLM)."""
- minimax_section = self.supplier_content[
- self.supplier_content.index("id: 13") :
- ]
+ minimax_section = self.supplier_content[self.supplier_content.index("id: 13") :]
next_section = minimax_section.find("/* {", 10)
if next_section == -1:
next_section = minimax_section.find(" {", 10)
- minimax_section = minimax_section[:next_section] if next_section > 0 else minimax_section[:500]
+ minimax_section = (
+ minimax_section[:next_section]
+ if next_section > 0
+ else minimax_section[:500]
+ )
self.assertIn("model_config:", minimax_section)
self.assertIn("0:", minimax_section)
def test_minimax_uses_openai_protocol(self):
"""MiniMax should not set type='vllm' or type='azure' (defaults to openai)."""
- minimax_section = self.supplier_content[
- self.supplier_content.index("id: 13") :
- ]
+ minimax_section = self.supplier_content[self.supplier_content.index("id: 13") :]
# Limit to just MiniMax section (up to next id:)
- next_id = minimax_section.index("id: 11", 10) if "id: 11" in minimax_section[10:] else len(minimax_section)
+ next_id = (
+ minimax_section.index("id: 11", 10)
+ if "id: 11" in minimax_section[10:]
+ else len(minimax_section)
+ )
minimax_text = minimax_section[:next_id]
self.assertNotIn("type: 'vllm'", minimax_text)
self.assertNotIn("type: 'azure'", minimax_text)
@@ -105,7 +110,7 @@ def _load_locale(self, locale_name):
path = os.path.join(
PROJECT_ROOT, "frontend", "src", "i18n", f"{locale_name}.json"
)
- with open(path, "r", encoding="utf-8") as f:
+ with open(path, encoding="utf-8") as f:
return json.load(f)
def test_en_translation(self):
@@ -134,8 +139,12 @@ def test_all_locales_have_same_supplier_keys(self):
en_keys = set(en["supplier"].keys())
zh_keys = set(zh["supplier"].keys())
ko_keys = set(ko["supplier"].keys())
- self.assertEqual(en_keys, zh_keys, "EN and ZH-CN should have same supplier keys")
- self.assertEqual(en_keys, ko_keys, "EN and KO-KR should have same supplier keys")
+ self.assertEqual(
+ en_keys, zh_keys, "EN and ZH-CN should have same supplier keys"
+ )
+ self.assertEqual(
+ en_keys, ko_keys, "EN and KO-KR should have same supplier keys"
+ )
class TestMiniMaxIconFile(unittest.TestCase):
@@ -166,9 +175,7 @@ def test_icon_is_png(self):
with open(icon_path, "rb") as f:
header = f.read(8)
# PNG magic number
- self.assertEqual(
- header[:4], b"\x89PNG", "File should have PNG magic number"
- )
+ self.assertEqual(header[:4], b"\x89PNG", "File should have PNG magic number")
def test_icon_not_empty(self):
"""MiniMax icon file should not be empty."""
@@ -191,7 +198,7 @@ def setUp(self):
factory_path = os.path.join(
PROJECT_ROOT, "backend", "apps", "ai_model", "model_factory.py"
)
- with open(factory_path, "r", encoding="utf-8") as f:
+ with open(factory_path, encoding="utf-8") as f:
self.factory_content = f.read()
def test_openai_type_in_factory(self):
@@ -215,23 +222,5 @@ def test_openai_llm_passes_base_url(self):
self.assertIn("base_url=self.config.api_base_url", self.factory_content)
-class TestReadmeContent(unittest.TestCase):
- """Test that README files mention MiniMax."""
-
- def test_readme_zh_mentions_minimax(self):
- """Chinese README should list MiniMax as a supported provider."""
- path = os.path.join(PROJECT_ROOT, "README.md")
- with open(path, "r", encoding="utf-8") as f:
- content = f.read()
- self.assertIn("MiniMax", content)
-
- def test_readme_en_mentions_minimax(self):
- """English README should list MiniMax as a supported provider."""
- path = os.path.join(PROJECT_ROOT, "docs", "README.en.md")
- with open(path, "r", encoding="utf-8") as f:
- content = f.read()
- self.assertIn("MiniMax", content)
-
-
if __name__ == "__main__":
unittest.main()
diff --git a/docs/agents/backend.md b/docs/agents/backend.md
new file mode 100644
index 000000000..a5062d13e
--- /dev/null
+++ b/docs/agents/backend.md
@@ -0,0 +1,98 @@
+# 后端 Agent 说明
+
+## 领域与代码映射
+
+- `oid` 和 `workspace_id` 是同一个工作空间 ID 的历史命名。
+- `AssistantModel.type`：
+ - `0`：普通小助手；
+ - `1`：高级应用；
+ - `4`：页面嵌入。
+- `AssistantModel.domain` 表示对接目标系统的域名，不是业务领域。
+- `DataTraining` 是「SQL 示例库」概念的持久化命名。
+
+## 代码组织
+
+- 领域代码放在 `backend/apps//`。多数域采用 `api/`、`crud/` 或 `curd/`、`models/` 分层；`schemas/` 仅 `system` 和 `settings` 有，`chat` 另有 `task/`，`ai_model`、`db`、`mcp`、`template`、`swagger` 不遵循该布局——新代码跟随所在域的既有形态。
+- 项目同时存在 `crud` 和 `curd` 拼写；不要为统一命名制造无关重构。
+- 新 router 注册到 `backend/apps/api.py`。
+- 应用组装、中间件、MCP 和 MCP 图片静态挂载属于 `backend/main.py`；`init_fastapi_app` 在此触发 xpack 初始化，前端 dist 静态挂载与 `/xpack_static` 提取由 xpack 包内完成（见 `docs/agents/xpack.md`）。
+- SQLModel 结构变更必须配套 Alembic 迁移；细节见 `docs/agents/migrations.md`。
+- 用户可见后端消息使用 `backend/locales/`，不要硬编码新文案。
+
+## API 黄金路径
+
+新 endpoint 参考 `terminology`、`data_training` 域和 `datasource` 域内的 `recommended_problem` 模块（`backend/apps/datasource/api/recommended_problem.py`）的分层：
+
+1. 在 `api/.py` 定义 router、prefix、tags 和 Swagger summary；
+2. 使用 `SessionDep`、`CurrentUser`、`Trans` 等依赖注入；
+3. 资源型接口配置 `@require_permissions`，确认 `keyExpression` 指向真实资源；
+4. 需要审计的操作配置 `@system_log`，新代码优先让权限装饰器位于审计装饰器外层，只记录已授权操作；
+5. handler 只做参数解析、权限上下文提取和分支，业务规则下沉到 CRUD/service；
+6. 返回领域对象、DTO 或既有分页 dict；正常 JSON 由 `ResponseMiddleware` 包装，不要手工包一层 `code/data/msg`；
+7. 用户可见异常通过 `Trans` 使用 locale key；`HTTPException` 留在 API 层，不要让 CRUD 依赖 FastAPI 响应细节。
+
+Endpoint 命名沿既有风格：
+
+- 分页：`GET /page/{current_page}/{page_size}`；
+- 新增或更新：`PUT ""`，按 `info.id` 分支；
+- 删除：`DELETE ""`，传 ID 列表；
+- 启用/禁用：`GET /{id}/enable/{enabled}`；
+- 导出：`GET /export`；
+- 导入：`POST /uploadExcel`。
+
+只在确实与现有 API 兼容性冲突时发明新形态，并说明原因。
+
+## CRUD 与查询
+
+- 查询构建参考 `build__query` 的分层：
+ 1. `get__base_query` 构造工作空间过滤；
+ 2. `build__query` 追加搜索、作用域、join、count 和分页；
+ 3. `execute__query` 转换为 DTO/result；
+ 4. `page_` 返回 API 需要的分页元数据。
+- 默认过滤当前 `current_user.oid`；管理员或助手场景必须显式说明为何可以切换工作空间。
+- 使用 SQLAlchemy `select` / `and_` / `or_` 表达查询；不要为用户输入拼接 SQL 字符串。
+- 分页先 count，再计算 `total_pages`，最后构造 offset/limit 子查询。
+- 创建/更新前完成重复性、必填和作用域校验；不要先写入再依赖唯一约束报错。
+- 事务提交通常发生在 CRUD/service 边界；API handler 不要随意中途 commit。
+- embedding、缓存清理或后台任务沿用当前领域的线程任务模式，不在请求路径中阻塞等待长任务。
+
+## 异步与阻塞
+
+- FastAPI handler 可以是 `async def`，但不要在事件循环中执行外部 HTTP、pandas 大文件解析、CPU 密集转换或长时间文件 IO。
+- 这些操作参考现有 `asyncio.to_thread(inner)` 模式。
+- 数据库 session 由依赖注入管理；在线程中需要新 session 时使用对应 `session_maker()` 并确保清理。
+- 不要把 `asyncio.to_thread` 当成绕过权限或事务边界的手段。
+
+## 模型与 DTO
+
+- 表模型继承 `SQLModel, table=True`；输入/输出 DTO 使用 Pydantic BaseModel 或非 table SQLModel。
+- 大 ID 使用 `BigInteger`；返回给前端时按既有 DTO 规则处理超过 JavaScript 安全整数的情况。
+- 时间、启用状态、工作空间归属和高级应用/数据源作用域要显式建模，不依赖调用方隐式状态。
+- 新增字段同时考虑迁移、导入/导出、embedding、缓存和 xpack 调用。
+
+## 安全与事务边界
+
+- 保留认证、工作空间/数据源权限、审计日志和既有错误响应模式；不要在 handler 中绕过它们。
+- 生成 SQL、路径、Host 头和上传文件都按不可信输入处理。
+- 不要削弱行数限制、权限过滤、元数据查询控制、Host 校验或路径穿越防护。
+- 修改连接池、事务和异步执行边界时，先阅读相邻实现和回归测试；不要把阻塞调用移回事件循环。
+- 商业实现留在 xpack；本仓库只保留对已发布包的调用和初始化。xpack 是必装硬依赖（启动即 import，无降级），许可证只做功能门控；加载场景见 `docs/agents/xpack.md`。
+
+## Chat 问题流程
+
+主要入口在 `backend/apps/chat/api/chat.py`：
+
+1. `POST /chat/start` 与 `POST /chat/assistant/start` 在工作空间内创建会话，并可绑定初始数据源或助手上下文。
+2. `POST /chat/question` 先解析快速命令。普通问题进入 `stream_sql`；`/regenerate` 直接再生。`/analysis` 和 `/predict` 在会话内会直接拒绝（temporary not supported），实际通过 `POST /record/{chat_record_id}/{action_type}` 触发。
+3. `stream_sql` 构造 `LLMService`，创建 `ChatRecord`，并启动异步执行。
+4. 已绑定数据源时，服务先提取关键词并扩展术语，再筛选适用的术语、SQL 示例和自定义提示词，随后组装 SQL 消息。
+5. 未绑定数据源时，先由模型选择数据源；服务随后校验数据源访问权和连接可用性。
+6. 模型生成 SQL 后，服务解析 SQL、对照允许的表元数据校验引用表，并按需应用行权限或助手动态 SQL 变换。
+7. 服务执行最终 SQL，规范化大数字和带限定名的列结果，并持久化查询结果。
+8. 模型基于实际使用的表结构生成图表配置；服务校验并持久化配置。非会话式流式调用还可请求渲染图片。
+9. 分析和预测是基于既有图表记录的独立后续执行。
+10. 猜测问题与已配置的推荐问题分开生成。
+
+`ChatFinishStep` 允许一次执行在生成 SQL、查询数据或生成图表后停止。不要假设所有调用方都需要完整图表流程。
+
+验证要求与测试选择标准见 `docs/agents/testing.md`。
diff --git a/docs/agents/domain-open-questions.md b/docs/agents/domain-open-questions.md
new file mode 100644
index 000000000..d232ec830
--- /dev/null
+++ b/docs/agents/domain-open-questions.md
@@ -0,0 +1,64 @@
+# 领域文档待补充问题
+
+这份文件只记录尚未确认的领域边界。问题确认后，把稳定术语移入根目录 `CONTEXT.md`，再从本文删除对应问题。
+
+## 工作空间与用户
+
+- 用户在工作空间中的角色如何定义？`UserWsModel.weight` 的取值和含义是什么？
+- 系统管理员、工作空间管理员、普通用户、数据源管理员之间的权限边界是什么？
+- 用户是否可以同时属于多个工作空间？切换工作空间对会话、数据源、模型和助手上下文有什么影响？
+
+## 数据源与元数据
+
+- 数据源的完整生命周期是什么？创建、连接校验、元数据同步、启用/禁用、删除分别如何界定？
+- Excel 数据源在领域上是普通数据源的一种，还是有独立生命周期和限制？
+- 表关系、表备注、字段备注、embedding 的业务含义和维护责任分别是什么？
+- 高级应用动态数据源与普通数据源在领域上的差异是什么？
+
+## 知识增强
+
+- 术语、SQL 示例、自定义提示词的作用域规则是否完全一致？
+- 当同一问题命中多个术语、多个 SQL 示例或多个自定义提示词时，选择和组合规则是什么？
+- embedding 相似度、关键词匹配和高级应用/数据源绑定之间的优先级是什么？
+
+## 权限
+
+- 工作空间权限、数据源权限、行权限、列权限、API 权限如何叠加？
+- 权限冲突时使用交集、并集还是显式拒绝优先？
+- 页面嵌入、高级应用和 MCP 场景下的用户身份与数据权限如何映射？
+
+## 助手与集成
+
+- `AssistantModel.type` 目前确认 `0` 普通小助手、`1` 高级应用、`4` 页面嵌入；是否还有其他历史值或保留值？
+- 普通小助手、高级应用、页面嵌入在目标系统认证、数据源获取和页面能力上的完整差异是什么？
+- `app_id`、`app_secret`、`domain` 与目标系统信任关系如何建模？
+
+## Chat 流程与产物
+
+- `Chat.chat_type`、`Chat.origin`、`first_chat`、`regenerate_record_id` 等状态字段的完整业务含义是什么？
+- 分析记录、预测记录和普通问答记录的生命周期与展示关系是什么？
+- 生成失败、执行失败、图表失败时，`ChatRecord` 的最终状态如何界定？
+- 猜测问题和推荐问题在产品展示上是否使用相同入口？二者是否需要统一命名？
+
+## 模型配置
+
+- 供应商、模型类型、基础模型、模型名称、默认模型、工作空间映射之间的准确关系是什么？
+- 系统默认模型和工作空间可用模型的决策顺序是什么？
+- 自定义模型在助手和 MCP 场景中的约束是什么？
+
+## 仪表板
+
+- 仪表板只能由会话图表创建，还是也可以独立创建和编辑？
+- 仪表板组件、会话记录、图表配置之间的归属关系是什么？
+- 仪表板查看和编辑权限如何与工作空间、数据源权限叠加？
+
+## MCP 与嵌入
+
+- MCP 调用者、工作空间和数据源之间的授权关系是什么？
+- 页面嵌入、小助手嵌入、MCP 在产品分类上的边界是什么？
+
+## xpack 商业概念
+
+- 许可证能力项、版本限制和功能开关如何影响领域对象？
+- 认证源、平台集成、审计日志和商业权限的领域边界是什么？
+- xpack 侧是否需要独立 `CONTEXT.md` 来维护商业扩展术语？
diff --git a/docs/agents/frontend.md b/docs/agents/frontend.md
new file mode 100644
index 000000000..f1e3b72cc
--- /dev/null
+++ b/docs/agents/frontend.md
@@ -0,0 +1,112 @@
+# 前端 Agent 说明
+
+## 技术与运行
+
+- 技术栈：Vue 3、TypeScript strict mode、Vite、Pinia、Vue Router、Element Plus / `element-plus-secondary`、Less。
+- 路径别名 `@/` 指向 `frontend/src/`。
+- 构建目标是 Chrome 81，并启用 Vite legacy 插件；不要只按最新浏览器能力选择 API。
+- 常用命令：
+
+```bash
+cd frontend
+npm run dev
+npm run build
+```
+
+`dev` 和 `build` 都会先运行 `vue-tsc -b`。依赖变更只手动修改 `package.json`；`package-lock.json` 由 npm 命令自动生成且不入库，不要手工编辑或强制加入提交，也不要提交私有 registry 配置。
+
+## 代码组织
+
+| 内容 | 位置 |
+| --- | --- |
+| 后端接口封装 | `src/api/.ts` |
+| 仅单个业务域使用的类型和模型 | 跟随对应 `src/api/.ts` |
+| 跨页面/跨模块共享实体与配置 | `src/entity/` |
+| Pinia 状态 | `src/stores/.ts` |
+| 路由 | `src/router/index.ts`、`dynamic.ts`、`watch.ts` |
+| 页面级视图 | `src/views//` |
+| 业务域私有子组件 | 对应 `src/views//` 子目录 |
+| 跨业务复用组件 | `src/components//` |
+| 工具函数 | `src/utils/` |
+| 用户可见文案 | `src/i18n/` 五种语言 JSON |
+
+组件目录常使用 `index.ts` 加 `src/` 的形式。新增复用组件时优先参考相邻组件结构；仅单个页面使用的组件不要提前提升到全局 `components/`。
+
+## API 调用
+
+- 不要在视图组件中直接使用 axios；统一通过 `@/utils/request.ts` 的 `request` 实例。
+- 新接口放入对应 `src/api/.ts`，导出类似 `xxxApi` 的对象，并复用既有命名风格。
+- 普通请求使用 `request.get/post/put/delete/patch`；SSE 使用 `request.fetchStream` 并传入 `AbortController`。
+- 不要手工添加认证 token、助手 token、证书、语言或 xpack 静态资源头。普通请求的头由 request interceptor 统一处理；SSE 走 `request.fetchStream`（原生 fetch，不经过 axios interceptor），头部在 `fetchStream` 内单独拼装（当前不含 `Accept-Language`），新增请求头时两条路径都要核对。
+- 下载类 blob 请求沿用：
+
+```ts
+request.get('/path', {
+ responseType: 'blob',
+ requestOptions: { customError: true },
+})
+```
+
+- 后端统一响应中 `code === 0` 时 interceptor 会返回 `data`；调用方不要重复解包。
+- 外部请求失败需要自定义处理时使用 `customError` 或 `silent`，不要绕开统一请求封装。
+
+## 类型
+
+- 新增代码优先使用具体 interface/type 或从 API 模块导出的模型；不要扩大 `any` 的使用范围。
+- 后端返回结构复杂且已有转换函数时，参考 `src/api/chat.ts` 的模型类和 `toXxx` 转换函数模式。
+- 共享类型放 `src/entity/`，业务专属类型跟随业务模块，避免相同 DTO 在多个视图中重复声明。
+- 修改类型后必须运行 `npm run build`，让 `vue-tsc` 检查模板和引用。
+
+## 状态管理
+
+- 新 store 放 `src/stores/.ts`，使用 Pinia options API 风格：`state`、`getters`、`actions`。
+- 为 state 定义 interface；getter 命名沿用 `getXxx`，action 命名表达业务行为。
+- 需要在 setup 外使用的 store，参考现有模块通过 `stores/index.ts` 的 `store` 实例导出包装函数。
+- 用户、语言、工作空间、助手上下文等状态已有 store；不要在组件里复制派生状态或直接改缓存键。
+
+## 路由与权限
+
+- 静态路由主要在 `src/router/index.ts`；由许可证或管理员能力控制的动态路由在 `dynamic.ts` 与 xpack 的 `LicenseGenerator.generateRouters` 中处理。
+- 修改 `watch.ts` 时必须核对：
+ - 普通登录和管理员登录白名单；
+ - `/assistant`、`/embeddedPage`、`/embeddedCommon`、`/401` 助手白名单；
+ - `userStore.isAdmin` 与 `isSpaceAdmin` 的路由差异；
+ - xpack 静态脚本加载失败路径：`LicenseGenerator` 是无类型声明的 window 全局，登录/改密加密（`sqlbotEncrypt`）和动态路由注册都硬依赖它，脚本加载失败只提示并中断导航，没有降级。
+- 新路由必须配置名称、标题 i18n 和正确父布局；不要绕过已有访问控制。
+
+## 视图、组件与样式
+
+- 页面组件使用 Vue 3 组合式 API；新组件优先使用 `