docs: enrich domain glossary and rewrite open questions for handoff

CLAUDE.md

@@ -0,0 +1,3 @@
+项目规范统一维护在 AGENTS.md（单一事实来源），本文件仅作 Claude Code 自动加载的导入入口，不要在此另写规则。
+
+@AGENTS.md

CONTEXT.md

@@ -14,32 +14,80 @@ _Avoid_: Organization、tenant
 工作空间的标识。历史上的 `oid` 和 `workspace_id` 字段表示同一个概念。
 _Avoid_: 把 `oid` 理解成独立的组织概念
 
+**System Admin / 系统管理员**:
+内置的系统级管理员账号，拥有全部管理能力，不属于工作空间角色体系。
+_Avoid_: Workspace Admin
+
+**Workspace Admin / 工作空间管理员**:
+工作空间内拥有管理能力的成员角色，由成员权重非零标识。
+_Avoid_: System Admin
+
 **Datasource / 数据源**:
 已配置的外部数据源，以及 SQLBot 用于生成查询的表、字段、关系和 embedding 等元数据。
 _Avoid_: Database、connection
 
+**Excel Datasource / Excel 数据源**:
+上传的 Excel/CSV 物化到内置库后按 PostgreSQL 处理的导入型数据源。
+_Avoid_: 外部连接型数据源、内存数据源
+
+**Dynamic Datasource / 动态数据源**:
+高级应用每次会话从宿主 API 实时拉取的数据源，不落库。
+_Avoid_: 内置数据源、普通数据源
+
+**Table Relation / 表关系**:
+人工在关系图上维护的表关联，为多表查询提供 JOIN 上下文。
+_Avoid_: 外键约束（数据库层的约束）
+
 **SQL Example / SQL 示例**:
-用于引导 SQL 生成的“问题 + SQL”示例。
+用于引导 SQL 生成的“问题 + SQL”示例，必须归属于一个数据源或一个高级应用。
 _Avoid_: Data training、training data
 
 **Terminology / 术语**:
-业务词或短语的解释，可包含同义词，用于提升问题和表结构理解。
+业务词或短语的解释，由主词和同义词构成，用于提升问题和表结构理解。
 _Avoid_: Custom prompt、SQL example
 
 **Custom Prompt / 自定义提示词**:
-附加在模型任务上的场景指令，可按工作空间、数据源或助手场景生效。
+附加在模型任务上的场景指令，按任务环节（生成 SQL、分析、预测）分类，可按工作空间、数据源或高级应用生效。
 _Avoid_: Terminology、SQL example
 
+**Knowledge Scope / 知识作用域**:
+术语、SQL 示例和自定义提示词生效的边界：工作空间、数据源或高级应用。高级应用是独立知识域，不继承工作空间级知识。
+_Avoid_: 权限——作用域决定向模型注入哪些知识，权限决定用户能访问哪些数据
+
+**Row Permission / 行权限**（xpack）:
+对表追加的行级过滤条件；同一表命中多条时取 AND，经改写 SQL 执行。
+_Avoid_: Column Permission
+
+**Column Permission / 列权限**（xpack）:
+从可见字段中剔除指定列；同一表命中多条时求交，作用于提供给模型的表结构。
+_Avoid_: Row Permission
+
+**Base Model / 基础模型**:
+实际调用供应商 API 时使用的模型标识。
+_Avoid_: 模型名称（仅显示用，与基础模型无强制关系）
+
+**Default Model / 默认模型**:
+系统全局唯一的默认问答模型；工作空间不设各自的默认模型。
+_Avoid_: 工作空间默认模型（该概念不存在）
+
 ### 会话
 
 **Chat / 会话**:
 用户在一个工作空间内连续提出数据问题的对话。
 _Avoid_: Assistant、dashboard
 
+**Chat Origin / 会话来源**:
+会话创建入口的溯源标记：页面、MCP 或小助手。
+_Avoid_: 助手目标域名（Assistant Domain）
+
 **Chat Record / 会话记录**:
 一次问题执行的可持久化结果，包含问题、生成 SQL、查询结果、图表配置、错误以及关联的后续记录。
 _Avoid_: Chat
 
+**Opening Record / 开场记录**:
+助手会话开始时自动创建的占位记录，无提问，承载数据源配置的推荐问题；不是一次真实的问答。
+_Avoid_: 会话中第一条问答记录
+
 **Analysis / 分析**:
 基于既有问题结果的模型生成解读。
 _Avoid_: Prediction
@@ -75,9 +123,37 @@ _Avoid_: Ordinary assistant、page-embedded assistant
 _Avoid_: Ordinary assistant、advanced assistant
 
 **Assistant Domain / 助手目标域名**:
-小助手对接的外部目标系统域名。
+允许承载小助手或嵌入页面的宿主 origin 精确白名单，仅在握手类接口校验。
 _Avoid_: Business domain、workspace
 
+**Assistant Certificate / 助手凭据**:
+高级应用逐请求透传给宿主数据源 API 的宿主系统凭据。
+_Avoid_: App Secret（验签密钥，不是透传凭据）
+
+**App Secret / 应用密钥**:
+页面嵌入应用与宿主页面共享的密钥，用作宿主自签 JWT 的验签依据。
+_Avoid_: app_id（仅用于反查应用，无认证作用）、Assistant Certificate
+
+**MCP**:
+以独立服务进程暴露问数工具集的集成形态，调用者以真实用户身份接入，数据权限按该用户计算。
+_Avoid_: Ordinary Assistant、Page-embedded Assistant
+
 **Dashboard / 仪表板**:
-为重复分析保存的数据视图集合。
+由会话图表快照与文本、Tab 组件组成的画布；图表组件是会话记录的配置快照，数据在查看时实时查询。
 _Avoid_: Chat、chat record
+
+### 商业扩展（xpack）
+
+以下词条的实现位于商业扩展包 sqlbot-xpack。
+
+**License / 许可证**（xpack）:
+商业授权凭据，以整体有效或失效门控商业功能，无功能级能力项。
+_Avoid_: 社区版/企业版（代码仅区分许可证有效与否）
+
+**Authentication Source / 认证源**（xpack）:
+用于外部身份登录的 SSO 身份源，支持 CAS、OIDC、LDAP、OAuth2、SAML2。
+_Avoid_: Platform Integration
+
+**Platform Integration / 平台集成**（xpack）:
+企业微信、钉钉、飞书、Larksuite 的组织与用户同步及扫码登录。
+_Avoid_: Authentication Source

docs/agents/backend.md

@@ -3,12 +3,11 @@
 ## 领域与代码映射
 
 - `oid` 和 `workspace_id` 是同一个工作空间 ID 的历史命名。
-- `AssistantModel.type`：
-  - `0`：普通小助手；
-  - `1`：高级应用；
-  - `4`：页面嵌入。
+- `AssistantModel.type` 实际值域 `0`–`4`：`0` 普通小助手；`1` 高级应用；`4` 页面嵌入；`2`、`3` 为遗留兼容值，行为分别等同 `0`、`1`，当前无创建入口。
 - `AssistantModel.domain` 表示对接目标系统的域名，不是业务领域。
 - `DataTraining` 是「SQL 示例库」概念的持久化命名。
+- `Chat.chat_type` 目前只有 `chat` 一个有效值；`datasource` 是为未实现的表字段备注自动生成功能预留的遗留值。
+- `ChatRecord.recommended_question` 同时承载两种内容：开场记录中是数据源配置的推荐问题，普通记录中是模型生成的猜测问题。
 
 ## 代码组织
 
@@ -85,7 +84,7 @@ Endpoint 命名沿既有风格：
 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 消息。
+4. 已绑定数据源时，服务先提取关键词并扩展术语，再筛选适用的术语、SQL 示例和自定义提示词，随后组装 SQL 消息；筛选的作用域、命中和组合规则见 `docs/agents/knowledge-enhancement.md`。
 5. 未绑定数据源时，先由模型选择数据源；服务随后校验数据源访问权和连接可用性。
 6. 模型生成 SQL 后，服务解析 SQL、对照允许的表元数据校验引用表，并按需应用行权限或助手动态 SQL 变换。
 7. 服务执行最终 SQL，规范化大数字和带限定名的列结果，并持久化查询结果。
@@ -95,4 +94,12 @@ Endpoint 命名沿既有风格：
 
 `ChatFinishStep` 允许一次执行在生成 SQL、查询数据或生成图表后停止。不要假设所有调用方都需要完整图表流程。
 
+### 记录状态与衍生关系
+
+- 记录终态二元：`finish=true` 即终态，`error` 非空即失败。生成 SQL、执行、图表任一阶段失败都写同一个 `error` 字段；失败阶段从已填充字段推断（有 SQL 无数据为执行失败，有数据无图表为图表失败），精确失败点看 ChatLog 的 `error` 标记。
+- 分析和预测各生成一条新的完整记录，复制源记录的问题、图表和数据，以 `analysis_record_id` / `predict_record_id` 指回源记录；衍生记录不能再被分析、预测或再生。
+- 再生记录以 `regenerate_record_id` 指向被再生记录，形成链，沿链回溯可取到原始问题。
+- 开场记录（`first_chat=true`）不能被分析、预测或再生；查找"上一条记录"时排除开场记录。
+- 问题快捷入口按位置分两个标签："猜你想问"是会话级快捷提问入口（开场记录展示数据源配置的推荐问题，输入框区域展示生成的猜测问题）；"继续问"是每次成功回答后的追问入口（生成的猜测问题）。
+
 验证要求与测试选择标准见 `docs/agents/testing.md`。

docs/agents/domain-open-questions.md

@@ -2,63 +2,68 @@
 
 这份文件是待查证目录，不是每项任务都要逐条询问的问卷。只处理影响当前任务的边界，先检查源码、测试和已有文档；仍无法确定且影响业务决策时再询问使用者。问题确认后，把稳定术语移入根目录 `CONTEXT.md`，行为规则放入对应按需文档，再从本文删除对应问题。
 
+2026-09-24 全量查证过一轮（主仓库 + sqlbot-xpack 可读源码）：各节"已确认"为代码事实，对应词条已入 `CONTEXT.md`；标注【待答】的问题需要产品/设计判断，均附代码现状，回答后按开头流程归档（"设计 vs 待修"类问题需二选一：按现状入档+风险注记，或转待修项）。
+
 ## 工作空间与用户
 
-- 用户在工作空间中的角色如何定义？`UserWsModel.weight` 的取值和含义是什么？
-- 系统管理员、工作空间管理员、普通用户、数据源管理员之间的权限边界是什么？
-- 用户是否可以同时属于多个工作空间？切换工作空间对会话、数据源、模型和助手上下文有什么影响？
+已确认：成员权重 0=普通成员、1=工作空间管理员（-1 为"无关联记录"哨兵）；系统管理员为内置 id=1 的 admin 账号，与成员权重正交；用户可同时属于多个工作空间，当前工作空间是用户表上的单值；数据源可见性=工作空间归属。
 
-## 数据源与元数据
+【待答】
+- "数据源管理员"这一角色叫法是否存在于产品文案？代码中不存在该角色：数据源管理接口全部要求工作空间管理员，行/列权限面向普通用户配置。
+- 用户-工作空间关联表（sys_user_ws）无 (uid, oid) 唯一约束，理论上可出现重复关联行。接受现状还是待修？
 
-- 数据源的完整生命周期是什么？创建、连接校验、元数据同步、启用/禁用、删除分别如何界定？
-- Excel 数据源在领域上是普通数据源的一种，还是有独立生命周期和限制？
-- 表关系、表备注、字段备注、embedding 的业务含义和维护责任分别是什么？
-- 高级应用动态数据源与普通数据源在领域上的差异是什么？
+## 数据源与元数据
 
-## 知识增强
+已确认：创建时不校验连接（校验是独立步骤，重新勾选表前强制执行）；元数据同步无定时任务，仅创建、重新勾选表、单表字段同步三个触发点；数据源级无启用/禁用（仅表/字段级）；Excel 为物化进内置库的导入型数据源；表关系人工维护、无自动推断；备注为"同步值 + 用户值"双轨且用户值优先；表级/数据源级两级 embedding；动态数据源每次会话实时拉取宿主 API、不落库。
 
-- 术语、SQL 示例、自定义提示词的作用域规则是否完全一致？
-- 当同一问题命中多个术语、多个 SQL 示例或多个自定义提示词时，选择和组合规则是什么？
-- embedding 相似度、关键词匹配和高级应用/数据源绑定之间的优先级是什么？
+【待答】
+- 删除数据源时不清理推荐问题（ds_recommended_problem）和行/列权限（ds_permission、ds_rules），成为孤儿数据。接受现状还是待修？
+- CoreDatasource.status 全代码只见赋值 "Success"；是否存在其他历史取值或预期取值（如连接失败标记）？
 
 ## 权限
 
-- 工作空间权限、数据源权限、行权限、列权限、API 权限如何叠加？
-- 权限冲突时使用交集、并集还是显式拒绝优先？
-- 页面嵌入、高级应用和 MCP 场景下的用户身份与数据权限如何映射？
+已确认：数据源可见性=工作空间归属（硬边界，校验失败拒绝）；行权限多条命中 AND、列权限多条命中求交；无 deny 语义；admin（id=1）绕过行/列权限；高级应用不走本地行/列权限、改用宿主表级 rule；行权限经 LLM 改写 SQL 执行；列权限只作用于提供给模型的表结构和数据预览。
 
-## 助手与集成
+【待答】
+- 行权限的强制执行方式是"LLM 改写 SQL"，无确定性的 WHERE 注入或结果集二次过滤兜底。按现状入档+风险注记，还是列待加固项？
+- 行/列权限未命中任何规则即不限制（fail-open）；white_list_user 字段在权限两个模型中已定义但全代码无读取。同上二选一。
 
-- `AssistantModel.type` 目前确认 `0` 普通小助手、`1` 高级应用、`4` 页面嵌入；是否还有其他历史值或保留值？
-- 普通小助手、高级应用、页面嵌入在目标系统认证、数据源获取和页面能力上的完整差异是什么？
-- `app_id`、`app_secret`、`domain` 与目标系统信任关系如何建模？
+## 助手与集成
 
-## Chat 流程与产物
+已确认：type 实际值域 0/1/2/3/4，2≡0、3≡1（遗留兼容值、无创建入口，已记入 backend.md）；普通小助手/高级应用/页面嵌入三形态的认证、数据源获取、页面能力差异已查明；domain 是 origin 精确白名单、仅握手类接口校验、运行期 API 不校验；app_id 仅反查、app_secret 作 HMAC 验签。
 
-- `Chat.chat_type`、`Chat.origin`、`first_chat`、`regenerate_record_id` 等状态字段的完整业务含义是什么？
-- 分析记录、预测记录和普通问答记录的生命周期与展示关系是什么？
-- 生成失败、执行失败、图表失败时，`ChatRecord` 的最终状态如何界定？
-- 猜测问题和推荐问题在产品展示上是否使用相同入口？二者是否需要统一命名？
+【待答】
+- /system/assistant/info/{id}、/system/assistant/app/{appId} 在认证白名单内且响应未剔除 app_secret：通过 origin 校验的页面即可获取应用的 app_id 与 app_secret。按现状入档+风险注记，还是列待加固项？
+- type=3 除与 type=1 共用动态数据源分支外是否曾有专属语义？（代码无单独分支，历史命名无法追溯。）
 
 ## 模型配置
 
-- 供应商、模型类型、基础模型、模型名称、默认模型、工作空间映射之间的准确关系是什么？
-- 系统默认模型和工作空间可用模型的决策顺序是什么？
-- 自定义模型在助手和 MCP 场景中的约束是什么？
+已确认：模型名称是显示名、基础模型是真实模型标识；默认模型为系统全局唯一标志（首个模型自动成为默认、禁删），无"工作空间默认模型"概念；工作空间映射决定可选范围；选型链为助手自定义模型 → MCP 指定模型 → 系统默认，指定模型校验失败静默回退；embedding 使用固定本地模型，不走供应商/默认模型体系。
+
+【待答】
+- 助手/MCP 指定模型会校验其属于当前工作空间的映射，但回退到系统默认模型时不校验默认模型是否映射到该工作空间。设计如此还是缺陷？
+- model_type 字段存而不用（前端仅 0=大语言模型有效，运行时引擎实际由 protocol 决定）。遗留预留还是待实现？
 
 ## 仪表板
 
-- 仪表板只能由会话图表创建，还是也可以独立创建和编辑？
-- 仪表板组件、会话记录、图表配置之间的归属关系是什么？
-- 仪表板查看和编辑权限如何与工作空间、数据源权限叠加？
+已确认：可独立创建（含文件夹、文本、Tab 组件），非只能来自会话图表；图表组件是会话图表的整份配置快照（无外键引用），查看时按快照内数据源+SQL 实时重执行，数据源被删则该组件标记失败；仅创建者本人可见可改；无分享无导出。
+
+【待答】
+- 仪表板纯私有（无分享/协作）是否为产品定位？
+- 删除会话不级联删除其记录（无外键、无清理）；删除文件夹不级联删除子节点（孤儿在资源树上不显示）。接受现状还是待修？
 
 ## MCP 与嵌入
 
-- MCP 调用者、工作空间和数据源之间的授权关系是什么？
-- 页面嵌入、小助手嵌入、MCP 在产品分类上的边界是什么？
+已确认：MCP 为独立服务进程（8001 端口），暴露 7 个工具；调用者以真实用户身份接入，数据源授权=其工作空间全部数据源（无显式授权列表）；行/列权限按该用户生效；另有 Open API 形态（API Key 验签映射到真实用户）；页面嵌入、小助手嵌入、MCP 的认证边界已查明。
+
+【待答】
+- mcp_model_list（仅凭 oid 即返回该工作空间模型列表）与 mcp_assistant（构造内置用户、无调用方鉴权）两个无鉴权入口：产品上有外层防护预期（网关/内网部署）还是待修？
+- mcp_question 不校验会话归属：持有有效 token 加 chat_id 即可向他人会话提问（主应用 /chat/question 有权限装饰器而 MCP 路径没有）。设计如此还是待修？
+- Open API（API Key）是否作为第四种对外暴露形态在 CONTEXT.md 立词条？
 
 ## xpack 商业概念
 
-- 许可证能力项、版本限制和功能开关如何影响领域对象？
-- 认证源、平台集成、审计日志和商业权限的领域边界是什么？
-- xpack 侧是否需要独立 `CONTEXT.md` 来维护商业扩展术语？
+已确认：许可证仅整体有效/失效门控（无功能级能力项，硬校验为 product 与有效期）；有效时才挂载外观、自定义提示词、认证源、平台集成、审计五组路由（到期动态摘除）；行/列权限路由不受许可证门控；认证源=SSO 身份源、平台集成=企业 IM 对接、审计=查询侧在 xpack、写入侧在主仓库。词条已入 CONTEXT.md"商业扩展（xpack）"小节。
+
+【待答】
+- 许可证数据的 edition、count 字段已定义但代码不消费（可能在 validator 二进制内部检查）。按现状记录，还是属于待实现？