skelet/docs/review/phase0-review.md

Phase 0 评审

评审日期：2026-07-06
评审视角：全栈开发工程师
评审范围：T-000 至 T-003 的文档、项目骨架、环境配置、启动脚本和验证基线。

结论

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 前，建议先修复：

1. init.sh / venv 与标准 bash 环境不匹配。
2. production settings 缺少强制 SECRET_KEY。
3. 当前状态文档存在过期和自相矛盾内容。

主要问题

1. High：标准启动入口 init.sh 在 bash 下不可用

复查状态：未达标。

仓库规则规定标准环境是 WSL2 / Linux + bash，且 init.sh 是标准启动与验证入口：

• AGENTS.md：标准开发环境是 WSL2 / Linux。
• AGENTS.md：init.sh 是标准启动与验证入口。

但当前 init.sh 调用：

.venv/bin/pip install -r requirements.txt
.venv/bin/python manage.py check

实际 .venv/bin/ 下只有 Windows / MSYS2 风格可执行文件：

pip.exe
python.exe
python3.12.exe

没有：

.venv/bin/pip
.venv/bin/python

验证命令：

bash -lc './init.sh'

结果：

./init.sh: line 20: .venv/bin/pip: No such file or directory

这会导致每轮开工流程中的“运行标准验证”失败，因此 T-001 / T-003 的标准入口验收不能算通过。

建议修复：

• 优先按 WSL / Linux 重新创建 .venv，确保 .venv/bin/python 和 .venv/bin/pip 存在。
• 或者正式修改项目开发环境决策为 MSYS2，但这会偏离当前仓库文档，不建议。

2026-07-06 复查结果：

init.sh 已改为调用：

.venv/bin/pip3.12
.venv/bin/python3.12

但实际 .venv/bin/ 下仍只有：

pip3.12.exe
python3.12.exe

脚本虽然检查了 .exe 是否存在，但执行命令时仍使用无后缀路径。

验证命令：

bash -lc './init.sh'

结果：

./init.sh: line 28: .venv/bin/pip3.12: No such file or directory

手动执行文档中的标准命令也失败：

bash -lc '.venv/bin/python3.12 manage.py check'

结果：

/bin/bash: .venv/bin/python3.12: No such file or directory

2. High：production settings 会回退到开发 SECRET_KEY

复查状态：已达标。

当前 skelet/settings/base.py 中：

SECRET_KEY = os.environ.get("SECRET_KEY", "django-insecure-dev-key-change-me")

skelet/settings/production.py 没有覆盖或强制校验 SECRET_KEY。

验证命令：

DJANGO_SETTINGS_MODULE=skelet.settings.production .venv/bin/python manage.py check --deploy

结果包含：

security.W009: Your SECRET_KEY has less than 50 characters, less than 5 unique characters, or it's prefixed with 'django-insecure-'

进一步读取 settings，生产配置实际值仍为：

DEBUG False
SECRET_KEY django-insecure-dev-key-change-me
ALLOWED_HOSTS ['']

这不是 Phase 0 本地开发的直接阻断项，但它是上线前安全风险。既然 T-002 已经涉及基础配置与环境样例，应尽早改成 production 缺少 SECRET_KEY 时 fail fast。

建议修复：

• 在 production.py 中强制读取 SECRET_KEY。
• 缺少或仍为开发默认值时抛出 ImproperlyConfigured。
• 同时清理 ALLOWED_HOSTS=[''] 的空字符串问题。

2026-07-06 复查结果：

skelet/settings/production.py 已改为：

• 缺少 SECRET_KEY 或仍以 django-insecure- 开头时抛出 ImproperlyConfigured。
• ALLOWED_HOSTS 会过滤空字符串。

验证命令：

DJANGO_SETTINGS_MODULE=skelet.settings.production .venv/bin/python3.12.exe manage.py check --deploy

在未设置 SECRET_KEY 时，结果为预期失败：

django.core.exceptions.ImproperlyConfigured: SECRET_KEY 环境变量缺失或仍为开发默认值。

设置合法环境变量后读取结果：

DEBUG False
ALLOWED_HOSTS ['example.com', 'www.example.com']

原 security.W009 风险已消除。剩余 SECURE_HSTS_SECONDS、SECURE_SSL_REDIRECT 警告属于上线前 HTTPS 策略，不是本项原问题。

3. Medium：当前状态文档存在过期和自相矛盾内容

复查状态：未达标。

AGENTS.md 仍写：

当前仓库处于 harness 文档初始化阶段，生产代码尚未初始化。
下一步 ... T-001

但任务看板中 Phase 0 已标为 DONE，实际代码也已初始化。

docs/current-state.md 中也存在矛盾：

当前 blocker：无；下一步执行 T-002

同一文件后文又写：

已完成：T-000、T-001、T-002、T-003
下一个可领取任务：T-101

这会误导后续 agent 的任务领取流程。

建议修复：

• 更新 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 写：

复制为 .env 并填入真实值

但当前项目没有加载 .env 的代码，也没有 python-dotenv 依赖。用户只复制 .env 并不会自动影响 Django settings。

建议二选一：

• 接入 dotenv，并明确加载路径。
• 或者修改说明，写明这些变量需要通过 shell / systemd / hosting environment 注入。

2026-07-06 复查结果：

.env.example 已明确说明：

• 本文件不直接加载到 Django settings。
• 部署时需通过 shell、systemd、托管平台或 Docker 注入环境变量。
• 真实 .env 被 .gitignore 忽略。

该项已达标。

已通过项

以下内容经检查或命令验证通过：

.venv/bin/python --version
# Python 3.12.12

.venv/bin/python manage.py check
# 0 errors，3 个 treebeard 兼容 warning

.venv/bin/python manage.py test
# 5 tests passed

其他通过项：

• Wagtail / Django 项目骨架已生成。
• manage.py、skelet/、home/、search/、core/ 已存在。
• SQLite 数据库已 migrate。
• requirements.txt 已精确 pin 依赖版本。
• home/tests.py 有 smoke test，访问 / 返回 200。
• .gitignore 已忽略 .venv/、db.sqlite3、media/、.env、deploy/ 和 *.pem。
• 当前 git 工作区干净。

是否允许进入 Phase 1

不建议直接进入 Phase 1。

最低修复门槛：

1. 修复 init.sh，确保在标准 bash / WSL 环境下可运行。
2. 修复 production SECRET_KEY 默认值风险。
3. 同步 AGENTS.md 和 docs/current-state.md，确保下一步任务明确为 T-101。

当前仍未满足最低修复门槛中的第 1 项和第 3 项。完成后，Phase 0 才可以视为达标，再进入 T-101。