tomevault-io AI 小鲸本地开发与构建部署
项目架构
src/frontend/
├── publish-template/ # 前端构建模板（pnpm dev 本地开发 / pnpm build 生产构建）
├── ai-blueking/ # 旧版小鲸组件（workspace 包，逐步废弃）
└── bkui-chat-x/ # 新版小鲸组件 monorepo（独立 workspace）
└── packages/ai-blueking/ # @blueking/ai-blueking 新架构
src/plugins/aidev_ai_blueking/ # Python 包（包含构建后的前端静态文件）
template/{{cookiecutter.project_name}}/ # Django 模板项目（最终运行环境）
依赖关系
publish-template通过 npm 依赖@blueking/ai-blueking（固定版本，非 workspace 链接）- Django 模板项目通过 pip 依赖
aidev-ai-bluekingPython 包（内含前端构建产物）
快速命令
| 场景 | 命令 | 工作目录 |
|---|---|---|
| 前端本地开发 | pnpm dev |
src/frontend/publish-template/ |
| 构建+部署一键完成 | make deploy-aidev-ai-blueking |
项目根目录 |
| 仅构建 Python 包 | make build-aidev-ai-blueking |
项目根目录 |
| 启动 Django 服务 | make dev |
template/{{cookiecutter.project_name}}/ |
前端本地开发（publish-template）
cd src/frontend/publish-template/
pnpm install
pnpm dev # 端口 5005
环境变量配置：
.bk.env— 所有环境通用（BK_API_PREFIX等）.bk.development.env— 开发模式专用（BK_STATIC_URL等）
构建部署流程
一键命令
# 项目根目录执行，自动完成：清缓存 → pnpm install → build → uv build → 安装到 .venv
make deploy-aidev-ai-blueking
手动分步
# 1. 构建
make build-aidev-ai-blueking
# 2. 安装到模板项目的 .venv
cd template/{{cookiecutter.project_name}}/
UV_PROJECT_ENVIRONMENT=.venv uv pip install --reinstall \
../../src/plugins/aidev_ai_blueking/dist/aidev_ai_blueking-*.tar.gz
# 3. 启动 Django 验证
make dev # 端口 5000
关键注意事项
.venv vs conda/系统 Python
模板项目的 Makefile 使用 uv run 启动 Django，始终使用项目目录下的 .venv，与 shell 中激活的 conda 环境无关。
安装包时必须指向 .venv：
# 正确 — 装到 .venv
UV_PROJECT_ENVIRONMENT=.venv uv pip install --reinstall <tarball>
# 错误 — 装到 conda，Django 用不到
conda activate xxx && uv pip install <tarball>
webpack 缓存
publish-template/node_modules/.cache/webpack/ 可能缓存旧版组件代码。pnpm dev（热加载）不受影响，但 pnpm build（生产构建）会命中缓存导致产物过时。
Makefile 已包含 rm -rf node_modules/.cache 步骤。如果手动运行 pnpm build，需先清缓存：
rm -rf node_modules/.cache && pnpm run build
添加前端路由
新增前端页面路由后，需同步更新 Django URL 配置，否则刷新页面 404：
文件：src/plugins/aidev_ai_blueking/aidev_ai_blueking/urls.py
urlpatterns = [
re_path(r"^$", IndexView.as_view(), name="index"),
re_path(r"^page/$", IndexView.as_view(), name="index"),
re_path(r"^side-slider/$", IndexView.as_view(), name="index"),
re_path(r"^chat-window/$", IndexView.as_view(), name="index"),
# 新增路由在此添加，统一指向 IndexView（SPA 模式）
]
pnpm-lock.yaml 不一致
如果 package.json 中依赖版本更新但 lock 文件未同步，pnpm install 会报 ERR_PNPM_OUTDATED_LOCKFILE。Makefile 已使用 --no-frozen-lockfile 参数自动处理。
排查清单
组件表现不一致时按此排查：
- webpack 缓存：
rm -rf src/frontend/publish-template/node_modules/.cache - 装错环境：确认用
UV_PROJECT_ENVIRONMENT=.venv安装，而非 conda - 旧 dist 残留：检查
src/plugins/aidev_ai_blueking/dist/是否有多个 tarball - lock 文件过期：
cd src/frontend && pnpm install --no-frozen-lockfile - Django 路由缺失：检查
urls.py是否包含对应前端路由
Source: TencentBlueKing/bk-aidev-agent — distributed by TomeVault.