// 本地开发和构建部署 aidev-ai-blueking（AI 小鲸）前端组件到 Django 模板项目的完整流程。涵盖 publish-template 前端开发、Python 包构建部署、常见问题排查。触发场景：构建 ai-blueking、部署小鲸、publish-template 开发调试、make build/deploy-aidev-ai-blueking、Django 模板项目本地运行。
| name | aidev-ai-blueking-dev |
| description | 本地开发和构建部署 aidev-ai-blueking（AI 小鲸）前端组件到 Django 模板项目的完整流程。涵盖 publish-template 前端开发、Python 包构建部署、常见问题排查。触发场景：构建 ai-blueking、部署小鲸、publish-template 开发调试、make build/deploy-aidev-ai-blueking、Django 模板项目本地运行。 |
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 链接）aidev-ai-blueking Python 包（内含前端构建产物）| 场景 | 命令 | 工作目录 |
|---|---|---|
| 前端本地开发 | pnpm dev | src/frontend/publish-template/ |
| 构建+部署一键完成 | make deploy-aidev-ai-blueking | 项目根目录 |
| 仅构建 Python 包 | make build-aidev-ai-blueking | 项目根目录 |
| 启动 Django 服务 | make dev | template/{{cookiecutter.project_name}}/ |
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
模板项目的 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>
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 模式）
]
如果 package.json 中依赖版本更新但 lock 文件未同步，pnpm install 会报 ERR_PNPM_OUTDATED_LOCKFILE。Makefile 已使用 --no-frozen-lockfile 参数自动处理。
组件表现不一致时按此排查：
rm -rf src/frontend/publish-template/node_modules/.cacheUV_PROJECT_ENVIRONMENT=.venv 安装，而非 condasrc/plugins/aidev_ai_blueking/dist/ 是否有多个 tarballcd src/frontend && pnpm install --no-frozen-lockfileurls.py 是否包含对应前端路由