From 4d5950c0a101c17d4c5455c7c89d906d21063993 Mon Sep 17 00:00:00 2001 From: ulleo Date: Thu, 24 Sep 2026 10:52:18 +0800 Subject: [PATCH] docs(agents): document xpack runtime facts and source-link prerequisites --- docs/agents/backend.md | 4 ++-- docs/agents/frontend.md | 2 +- docs/agents/xpack.md | 13 +++++++++++++ 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/agents/backend.md b/docs/agents/backend.md index ba68674c..a5062d13 100644 --- a/docs/agents/backend.md +++ b/docs/agents/backend.md @@ -15,7 +15,7 @@ - 领域代码放在 `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、静态资源挂载和 xpack 初始化属于 `backend/main.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/`，不要硬编码新文案。 @@ -76,7 +76,7 @@ Endpoint 命名沿既有风格： - 生成 SQL、路径、Host 头和上传文件都按不可信输入处理。 - 不要削弱行数限制、权限过滤、元数据查询控制、Host 校验或路径穿越防护。 - 修改连接池、事务和异步执行边界时，先阅读相邻实现和回归测试；不要把阻塞调用移回事件循环。 -- 商业实现留在 xpack；本仓库只保留对已发布包的调用和初始化。 +- 商业实现留在 xpack；本仓库只保留对已发布包的调用和初始化。xpack 是必装硬依赖（启动即 import，无降级），许可证只做功能门控；加载场景见 `docs/agents/xpack.md`。 ## Chat 问题流程 diff --git a/docs/agents/frontend.md b/docs/agents/frontend.md index 58e41ee3..f1e3b72c 100644 --- a/docs/agents/frontend.md +++ b/docs/agents/frontend.md @@ -71,7 +71,7 @@ request.get('/path', { - 普通登录和管理员登录白名单； - `/assistant`、`/embeddedPage`、`/embeddedCommon`、`/401` 助手白名单； - `userStore.isAdmin` 与 `isSpaceAdmin` 的路由差异； - - xpack 静态脚本加载失败路径。 + - xpack 静态脚本加载失败路径：`LicenseGenerator` 是无类型声明的 window 全局，登录/改密加密（`sqlbotEncrypt`）和动态路由注册都硬依赖它，脚本加载失败只提示并中断导航，没有降级。 - 新路由必须配置名称、标题 i18n 和正确父布局；不要绕过已有访问控制。 ## 视图、组件与样式 diff --git a/docs/agents/xpack.md b/docs/agents/xpack.md index d9f01c22..bc100263 100644 --- a/docs/agents/xpack.md +++ b/docs/agents/xpack.md @@ -2,6 +2,17 @@ `sqlbot-xpack` 默认作为版本范围由 `backend/pyproject.toml` 约束的已发布 wheel 使用；`uv.lock` 不入库，只用于冻结本机安装。日常任务不读取、不修改本地 xpack checkout。 +## 主工程对 xpack 的运行时依赖 + +以下事实在"已发布 wheel"与"源码联调（editable）"两种模式下一致，修改依赖、初始化、许可证或前端集成前先掌握： + +- `sqlbot-xpack` 是 `backend/pyproject.toml` 的**必装依赖**（不是 optional extra），索引指向 TestPyPI，CE 镜像构建必然包含；构建环境需能访问 test.pypi.org。 +- 后端启动即无条件 import：`backend/main.py` 与多个业务模块（登录加解密、AES 落库、审计、行权限、参数管理、embedded 签名）顶层 import，没有降级路径——xpack 缺失则后端无法启动。8001 的 MCP 进程因 `uvicorn main:mcp_app` import 同一 `main` 模块，同样加载。 +- `sqlbot_xpack.init_fastapi_app(app)` 在 import main 时执行：license/config/sse/row-permission/embedded 路由无条件注册；appearance/custom_prompt/authentication/platform/audit 仅在许可证 valid 时注册，到期后由监控任务动态摘除。 +- 静态资源在启动时从 wheel 解包复制到 `../frontend/dist/xpack_static`（相对路径，要求后端进程 CWD 在 `backend/`），由主 app 挂载 serve——前端 dist 静态挂载的实际位置在 xpack `core.py`，不在 `main.py`。 +- 许可证只做功能门控，不做加载门控：无许可证时 xpack 仍完整加载，登录加密、SSE、行权限、审计等基础功能照常走 xpack 代码。 +- 前端首次路由必加载 `/xpack_static/license-generator.umd.js`（window 全局 `LicenseGenerator`，无类型声明）；登录/改密加密和动态路由注册硬依赖它，脚本加载失败无降级，只提示并中断导航。 + 只有任务确实需要修改或调试闭源 xpack 代码，或者需要两个仓库联动验证时，才检查本地关联开关。未提交的根目录 `AGENTS.local.env` 保存本机配置： ```dotenv @@ -30,3 +41,5 @@ uv run --no-sync pytest -q ``` 在 `backend/` 执行 `uv sync` 可恢复已发布包。变更和提交必须分开：SQLBot 变更留在本仓库，xpack 变更留在独立仓库。完整发布顺序以 `docs/agents/packaging.md` 为准。 + +**源码联调的前提与影响面**：checkout 里的 `src/sqlbot_xpack/static` 被 gitignore、全新 checkout 不存在，而后端启动时会把包内 `static` 复制到前端 dist——目录缺失会让 `init_fastapi_app` 直接抛错、后端无法启动。因此首次联调前必须先在 xpack 仓库根目录执行一次 `./build_scripts/build-dev.sh`（构建并复制静态资源），之后每次改动 `xpack_static/` 也要重跑再重启。editable 安装作用于 backend 共享环境，8000 主服务和 8001 MCP 进程都会改用源码；改 Python 源码同样需要重启后端才生效。