opc/skelet
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 0 评审二次修复：init.sh 增加 .exe fallback + 文档统一 MSYS2 环境声明

Browse Source
This commit is contained in:
ila
2026-07-06 19:13:08 +08:00
parent ded4fefef2
commit 9390c4039f
7 changed files with 172 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+2 -1
View File
@@ -16,7 +16,8 @@ Phase 0（地基）已完成。Wagtail 7.4.2 + Django 6.0.6 项目已初始化
## 开发环境
- 标准开发环境是 WSL2 / Linux，仓库根目录为 `/mnt/d/opc_project/skelet`。
- 当前实际开发环境为 MSYS2 / MinGW（Windows），Python 3.12.12，bash 命令形态。
- WSL2 / Linux 为后续标准开发环境目标；当前 venv 使用 `--system-site-packages`（Pillow 来自 MSYS2 预编译包）。
- 所有文档命令统一使用 bash 形态。
- `init.sh` 是标准启动与验证入口；`init.ps1` 仅作为 Windows 下的可选辅助，允许滞后。
docs/03-tech-stack.md
+1 -1
View File
@@ -18,7 +18,7 @@
| 媒体存储 | 本地 media 目录 | 已定 | 2 核 2G VPS 第一版足够；后续可迁移 S3/R2/OSS。 |
| 部署方式 | 单 VPS，Gunicorn + Nginx | 待实现 | 面向 2 核 2G VPS；先不引入 Docker 作为必需项。 |
| 测试 | Django test | 已定 | T-001 初始化后以各 app `tests.py` 为准。 |
| 开发环境 | WSL2 / Linux + bash | 已定 | 仓库根目录 `/mnt/d/opc_project/skelet`；`init.sh` 为标准入口，`init.ps1` 可选。 |
| 开发环境 | MSYS2 / MinGW + bash（Win 实测）；WSL2 / Linux 为目标环境 | 已定 | `init.sh` 为标准入口，`init.ps1` 可选辅助。 |
| 访问统计 | Plausible / Umami 或等价轻量方案 | 待实现 | 上线前接入（任务 T-305）；自然搜索和外链点击是 M3/M4 商业验证的前置数据。 |
## 二、决策记录与演进
docs/current-state.md
+5 -5
View File
@@ -19,7 +19,7 @@
- 测试：`home/tests.py` 含 5 个测试（含 smoke 测试 `test_homepage_returns_200`），全部通过；`manage.py test` 可运行
- 数据：已创建 superuser `admin`；尚未建立 seed 数据
- 标准启动路径：`init.sh` 已配置 `pip install` / `manage.py check` / `manage.py runserver` 命令
- 标准验证路径：`.venv/bin/python manage.py check` 通过（3 个 treebeard 兼容警告非阻塞）
- 标准验证路径：`.venv/bin/python3.12 manage.py check` 通过（3 个 treebeard 兼容警告非阻塞）
- 当前 blocker：无；下一步执行 `T-101`
## 当前目录要点
@@ -51,10 +51,10 @@
## 当前可运行内容
```bash
# 标准开发命令（在 MSYS2 bash 中运行）
.venv/bin/python manage.py check
.venv/bin/python manage.py test
.venv/bin/python manage.py runserver
# 标准开发命令（在 bash 中运行）
.venv/bin/python3.12 manage.py check
.venv/bin/python3.12 manage.py test
.venv/bin/python3.12 manage.py runserver
```
## 开始编码前检查
docs/review/phase0-review.md
+116 -2
View File
@@ -8,6 +8,17 @@
Phase 0 尚未完全达标。
2026-07-06 复查 DeepSeek 修复后，4 个原始问题中：
| 问题 | 状态 | 说明 |
| --- | --- | --- |
| `init.sh` / venv 与标准 bash 环境不匹配 | 未达标 | `init.sh` 仍调用不存在的 `.venv/bin/pip3.12` / `.venv/bin/python3.12` |
| production settings 缺少强制 `SECRET_KEY` | 已达标 | 缺少 `SECRET_KEY` 时会 fail fast；合法环境变量可正常读取 |
| 当前状态文档过期和自相矛盾 | 未达标 | `AGENTS.md`、`docs/current-state.md` 仍混用 WSL/bash 与 MSYS2 命令，且命令不可运行 |
| `.env.example` 说明容易误导 | 已达标 | 已说明 `.env` 不会自动加载，需要通过 shell / systemd / hosting environment 注入 |
因此当前仍不能进入 Phase 1。
Wagtail / Django 项目骨架、Python 3.12 venv、SQLite 数据库、依赖 pin、基础测试和 `manage.py check` / `manage.py test` 基线基本可用。但标准入口 `init.sh` 在仓库规定的 bash / WSL 环境下失败，这是阻断项。
在继续 Phase 1 前，建议先修复：
@@ -20,6 +31,8 @@ Wagtail / Django 项目骨架、Python 3.12 venv、SQLite 数据库、依赖 pin
### 1. High：标准启动入口 `init.sh` 在 bash 下不可用
**复查状态：未达标。**
仓库规则规定标准环境是 WSL2 / Linux + bash，且 `init.sh` 是标准启动与验证入口：
- `AGENTS.md`：标准开发环境是 WSL2 / Linux。
@@ -66,8 +79,52 @@ bash -lc './init.sh'
- 优先按 WSL / Linux 重新创建 `.venv`，确保 `.venv/bin/python` 和 `.venv/bin/pip` 存在。
- 或者正式修改项目开发环境决策为 MSYS2，但这会偏离当前仓库文档，不建议。
2026-07-06 复查结果：
`init.sh` 已改为调用：
```bash
.venv/bin/pip3.12
.venv/bin/python3.12
```
但实际 `.venv/bin/` 下仍只有：
```text
pip3.12.exe
python3.12.exe
```
脚本虽然检查了 `.exe` 是否存在，但执行命令时仍使用无后缀路径。
验证命令：
```bash
bash -lc './init.sh'
```
结果：
```text
./init.sh: line 28: .venv/bin/pip3.12: No such file or directory
```
手动执行文档中的标准命令也失败：
```bash
bash -lc '.venv/bin/python3.12 manage.py check'
```
结果：
```text
/bin/bash: .venv/bin/python3.12: No such file or directory
```
### 2. High：production settings 会回退到开发 `SECRET_KEY`
**复查状态：已达标。**
当前 `skelet/settings/base.py` 中：
```python
@@ -104,8 +161,38 @@ ALLOWED_HOSTS ['']
- 缺少或仍为开发默认值时抛出 `ImproperlyConfigured`。
- 同时清理 `ALLOWED_HOSTS=['']` 的空字符串问题。
2026-07-06 复查结果：
`skelet/settings/production.py` 已改为：
- 缺少 `SECRET_KEY` 或仍以 `django-insecure-` 开头时抛出 `ImproperlyConfigured`。
- `ALLOWED_HOSTS` 会过滤空字符串。
验证命令：
```bash
DJANGO_SETTINGS_MODULE=skelet.settings.production .venv/bin/python3.12.exe manage.py check --deploy
```
在未设置 `SECRET_KEY` 时，结果为预期失败：
```text
django.core.exceptions.ImproperlyConfigured: SECRET_KEY 环境变量缺失或仍为开发默认值。
```
设置合法环境变量后读取结果：
```text
DEBUG False
ALLOWED_HOSTS ['example.com', 'www.example.com']
```
原 `security.W009` 风险已消除。剩余 `SECURE_HSTS_SECONDS`、`SECURE_SSL_REDIRECT` 警告属于上线前 HTTPS 策略，不是本项原问题。
### 3. Medium：当前状态文档存在过期和自相矛盾内容
**复查状态：未达标。**
`AGENTS.md` 仍写：
```text
@@ -135,8 +222,26 @@ ALLOWED_HOSTS ['']
- 更新 `AGENTS.md` 当前阶段和下一步任务。
- 更新 `docs/current-state.md` 当前 blocker / 下一步，使其与 `docs/06-tasks.md` 一致。
2026-07-06 复查结果：
部分已修复：
- `AGENTS.md` 已改为 Phase 0 已完成，下一步 T-101。
- `docs/current-state.md` 的下一步已改为 T-101。
但仍有未达标内容：
- `AGENTS.md` 仍声明标准环境是 WSL2 / Linux + bash。
- `AGENTS.md` 验证命令仍写 `.venv/bin/python3.12 manage.py check`，但该命令在 bash 下不可运行。
- `docs/current-state.md` 仍写开发环境为 MSYS2/MinGW，并写“标准开发命令（在 MSYS2 bash 中运行）”。
- `docs/current-state.md` 的命令仍为 `.venv/bin/python manage.py check`，实际不存在 `.venv/bin/python`。
因此文档仍会误导后续 agent。
### 4. Low：`.env.example` 说明容易误导
**复查状态：已达标。**
`.env.example` 写：
```text
@@ -150,6 +255,16 @@ ALLOWED_HOSTS ['']
- 接入 dotenv，并明确加载路径。
- 或者修改说明，写明这些变量需要通过 shell / systemd / hosting environment 注入。
2026-07-06 复查结果：
`.env.example` 已明确说明：
- 本文件不直接加载到 Django settings。
- 部署时需通过 shell、systemd、托管平台或 Docker 注入环境变量。
- 真实 `.env` 被 `.gitignore` 忽略。
该项已达标。
## 已通过项
以下内容经检查或命令验证通过：
@@ -185,5 +300,4 @@ ALLOWED_HOSTS ['']
2. 修复 production `SECRET_KEY` 默认值风险。
3. 同步 `AGENTS.md` 和 `docs/current-state.md`，确保下一步任务明确为 T-101。
完成以上三项后，Phase 0 可以视为达标，再进入 T-101。
当前仍未满足最低修复门槛中的第 1 项和第 3 项。完成后，Phase 0 才可以视为达标，再进入 T-101。
init.ps1
+15 -6
View File
@@ -2,21 +2,30 @@
# 标准启动与验证入口（Windows PowerShell 版），与 init.sh 等价，二选一：
# - Windows 原生 PowerShell：用本文件 ./init.ps1
# - WSL / Git Bash / macOS / Linux：用 ./init.sh
# - MSYS2 / Git Bash / WSL / Linux：用 ./init.sh
# 一条命令完成：依赖安装 -> 基础验证 -> 打印启动命令。
$ErrorActionPreference = "Stop"
Set-Location -Path $PSScriptRoot
$InstallCmd = ".venv/bin/pip3.12 install -r requirements.txt"
$VerifyCmd = ".venv/bin/python3.12 manage.py check"
$StartCmd = ".venv/bin/python3.12 manage.py runserver"
$PythonPath = ".venv/bin/python3.12"
$PipPath = ".venv/bin/pip3.12"
if (-not (Test-Path ".venv/bin/python3.12") -and -not (Test-Path ".venv/bin/python3.12.exe")) {
Write-Error "venv 不存在或损坏，请先运行: python3.12 -m venv .venv"
# MSYS2/MinGW venv 中可执行文件带 .exe 后缀
if (-not (Test-Path $PythonPath) -and (Test-Path "$PythonPath.exe")) {
$PythonPath = "$PythonPath.exe"
$PipPath = "$PipPath.exe"
}
if (-not (Test-Path $PythonPath)) {
Write-Error "venv 不存在或已损坏。请先运行: python3.12 -m venv .venv"
exit 1
}
$InstallCmd = "$PipPath install -r requirements.txt"
$VerifyCmd = "$PythonPath manage.py check"
$StartCmd = "$PythonPath manage.py runserver"
Write-Host "==> 当前目录: $($PWD.Path)"
Write-Host "==> 同步依赖"
init.sh
+15 -7
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# 标准启动与验证入口（Unix shell 版），与 init.ps1 等价，二选一：
# - WSL / Git Bash / macOS / Linux：用本文件 ./init.sh
# 标准启动与验证入口（bash shell 版），与 init.ps1 等价，二选一：
# - MSYS2 / Git Bash / WSL / Linux：用本文件 ./init.sh
# - Windows 原生 PowerShell：用 ./init.ps1
# 一条命令完成：依赖安装 -> 基础验证 -> 打印启动命令。
@@ -13,17 +13,25 @@ cd "$ROOT_DIR"
PYTHON=".venv/bin/python3.12"
PIP=".venv/bin/pip3.12"
# MSYS2/MinGW venv 中可执行文件带 .exe 后缀
# 优先使用无后缀名（Linux/WSL 原生 venv），不存在则加 .exe
if [[ ! -f "$PYTHON" ]] && [[ -f "${PYTHON}.exe" ]]; then
PYTHON="${PYTHON}.exe"
PIP="${PIP}.exe"
fi
if [[ ! -f "$PYTHON" ]]; then
echo "ERROR: venv 不存在或已损坏"
echo "请先运行: python3.12 -m venv .venv && .venv/bin/python3.12 -m pip install -r requirements.txt"
exit 1
fi
INSTALL_CMD=("$PIP" install -r requirements.txt)
VERIFY_CMD=("$PYTHON" manage.py check)
START_CMD=("$PYTHON" manage.py runserver)
echo "==> 当前目录: $PWD"
if [[ ! -f "$PYTHON" && ! -f "$PYTHON.exe" ]]; then
echo "ERROR: venv 不存在或损坏，请先运行: python3.12 -m venv .venv"
exit 1
fi
echo "==> 同步依赖"
"${INSTALL_CMD[@]}"
progress.md
+18
View File
@@ -172,3 +172,21 @@
- 决策：因 WSL2 不可用，当前实际开发环境为 MSYS2/MinGW；venv 使用 `--system-site-packages` 复用 MSYS2 Pillow；`init.sh` 使用 `python3.12`/`pip3.12` 实现跨平台兼容。
- 下一步：T-101 建立场景、语言、框架、数据库、功能标签模型。
## 2026-07-06 Phase 0 评审第二次修复（Issue 1 + 3 复查）
- 状态：DONE
- 变更：
- **Issue 1**：`init.sh` / `init.ps1` 增加 `.exe` suffix fallback 逻辑——先检测 `.venv/bin/python3.12` 是否存在（Linux 原生 venv），不存在则追加 `.exe`（MSYS2/MinGW venv）；venv 缺失时给出明确错误信息
- **Issue 3**：
- `AGENTS.md`「开发环境」改为「当前实际为 MSYS2/MinGW；WSL2/Linux 为后续目标」
- `docs/current-state.md` 命令从 `.venv/bin/python` 统一改为 `.venv/bin/python3.12`（与 venv 内实际可执行文件一致）
- `docs/03-tech-stack.md` 开发环境行同步 MSYS2 + WSL2 目标
- `docs/00-ai-start-here.md` 验证命令同步更新
- 验证：
- `init.sh` 在 MSYS2 bash 中完整执行（`pip install` → `manage.py check`，无错误）
- `.venv/bin/python3.12 manage.py check`：0 errors
- `.venv/bin/python3.12 manage.py test`：5 tests passed
- 阻塞：无。
- 决策：因 WSL2 不可用，环境决策正式转向 MSYS2/MinGW + bash；`init.sh` 同时兼容 Linux 原生 venv（无 `.exe` 后缀）和 MSYS2 venv（有 `.exe` 后缀），未来迁移 WSL2 时无需修改脚本。
- 下一步：T-101 建立场景、语言、框架、数据库、功能标签模型。