---
name: app_initialization_flow
description: 当需要适配桌面 App 初始化流程或理解项目首次启动配置时，应该索引本记忆
---

## 项目初始化流程（首次启动 / 桌面 App 适配必读）

### 关键文件
- `_bootstrap.sh` — 共享引导（定位项目根、准备 Python venv + Node 依赖）
- `setup.sh` — 首次初始化入口：调 `_bootstrap.sh` 后运行 `python -m scripts.setup`
- `scripts/setup.py` — **交互式配置向导**（终端），5 步生成 `.env` + `custom_models.json`

### setup.py 向导步骤
1. **运行模式** — `host`（单机本地沙箱）/ `web`（多用户 Docker），决定 `TERMINAL_SANDBOX_MODE`
2. **Web 监听** — 端口 (`WEB_SERVER_PORT`) + 地址 (`WEB_SERVER_HOST`)，host 模式默认 127.0.0.1
3. **数据目录** — `~/.astrion/astrion/<mode>/`，可自定义（设 `ASTRION_DATA_ROOT`）
4. **管理员账户** — `AGENT_ADMIN_USERNAME` + `AGENT_ADMIN_PASSWORD_HASH`（werkzeug hash）
5. **模型配置** — 写入部署级 `custom_models.json`（~/.astrion/astrion/config/）：model_name / url / apikey / model_id / thinking 支持
6. **自动生成** — `WEB_SECRET_KEY` + `API_TOKEN_SECRET`（secrets.token_hex(32)）

### 设计要点
- 向导**刻意不 import config**，以免在 `.env` 写之前过早锁定路径
- 以 `.env.example` 为模板，仅替换被接管键，其余原样保留（含注释）
- `.env` 写完后 chmod 600

### 桌面 App 适配要点
- 桌面 App 应固定 `TERMINAL_SANDBOX_MODE=host`
- 端口应自动找可用端口
- 模型配置可在 Web UI 中后续修改，但首次启动至少需要一个模型
- `_deploy_config_dir()` 推导逻辑必须与 `config/paths.py` 保持一致