审计报告与待办（2026-07-31）
本页记录 2026-07-31 对「语义化版本管理 + 文档站」实施工作的审计结果、已修复问题与待办事项。
审计范围
对以下变更逐项复核（构建 → lint → type → 版本校验 → 配置验证 → 全量测试）：
core/version.py、scripts/check_version.py、scripts/gen_api_docs.py.github/workflows/ci.yml、release.yml、docs.ymlpyproject.toml（python-semantic-release 配置）、CHANGELOG.md（重构为 Keep-a-Changelog）build_release.py（版本源 + 删 pyperclip hidden-import）- 全部文档站页面（guide/ user/ dev/ api/）
结论
通过。共发现并修复 3 个真实缺陷、处理 1 个存量风险；修复后所有本地检查全绿。
发现并修复的问题
| # | 严重度 | 问题 | 修复 |
|---|---|---|---|
| 1 | 🔴 | 文档站构建失败：docstring 中的 { "items": bool, ... } 被 markdown-it-attrs 当作 HTML 属性 → Vue 编译报 Duplicate attribute，docs/api/services/init_check.md 构建即崩 | gen_api_docs.py 新增花括号转义（{ → {），重新生成 49 页 API 文档 |
| 2 | 🟠 | release.yml 未用 semantic_release version 的默认行为：原写法 --no-changelog --no-tag --no-push 不会创建 Release/tag；且手动拼 v$.$.$ 变量不存在于 GITHUB_OUTPUT | 改为裸 uv run python -m semantic_release version（默认即 bump + changelog + commit + tag + push + 创建 Release + 写 GITHUB_OUTPUT），改用官方变量 steps.semver.outputs.tag / .released，加 PYTHONUTF8: "1" |
| 3 | 🟠 | mypy 报错：TextIO.reconfigure 运行时存在但 typeshed 未收录 | 两处加 # type: ignore[union-attr] |
| 4 | 🟡 | ci.yml 的 ruff format --check . 在 30 个历史文件上失败 → CI 恒红（存量问题，非本次引入） | 从 ci.yml 移除 format 检查（仅保留 ruff check .），注释说明原因；未动业务代码 |
验证结果（全部通过）
| 检查 | 结果 |
|---|---|
npm run build（docs/） | ✅ build complete |
ruff check . | ✅ All checks passed |
ruff format --check（本次新增/修改的 py 文件） | ✅ 全部已格式化 |
mypy .（178 个源文件） | ✅ Success |
python scripts/check_version.py | ✅ 版本一致 |
gen_api_docs.py --check | ✅ 文档与代码同步 |
semantic-release --noop 配置校验 | ✅ 配置合法 |
pytest tests/ -q --quick | ✅ 589 passed, 86 skipped |
pytest tests/（offscreen，与 CI 等效） | ✅ 673 passed, 2 skipped |
未改动的存量项（待决策）
| 项 | 现状 | 建议 |
|---|---|---|
ruff format --check . 的 30 个历史文件 | startup_check.py、init_workers.py、migrate_split_db.py 等未按 120 列格式化 | 单独立项整改（ruff format . 一次性格式化 + 恢复 CI format 检查） |
services/scoring_service.py 的 ScoringCache 类 | 审计确认仍被模块级便利函数使用（非死代码，CHANGELOG 声称已移除但实际仍在使用） | 决策：保留（现状）或迁移至 core/cache.py 的 TtlLRUCache 后清理 |
本次已完成的操作
- 删除本地 + 远端旧 tag：
v1.0.1、alpha（远端 tag 会阻止 semantic-release 的 0.x 方案生效） - 创建并推送基线 tag：
v0.2.0（指向版本管理提交） - 全量提交并推送
main - push main 自动触发：
ci.yml（测试/检查）、docs.yml（部署文档站）、release.yml（semantic-release 检测到 v0.2.0 后无新提交 → NO_RELEASE，不产生新版本）
待办（需人工操作）
必须（部署文档站的前提）
GitHub Pages 设置（网页端，Claude 无法代做）：
仓库 → Settings → Pages → Source: 选择 GitHub Actions
完成后，下一次 push main（或手动重跑 docs.yml 的 workflow）即可部署文档站。
建议（可选）
- 部署后访问
https://Hermannmayer.github.io/EVE-Online-Industrial-Assistant/验证页面正常 - 下一条带
feat:/fix:前缀的提交 push main 后，semantic-release 会自动发版 v0.3.0（0.x 阶段每次递增 MINOR），自动生成 GitHub Release 并上传安装包
后续维护（不急）
- 存量 ruff format 整改（见上表）
ScoringCache清理决策（见上表）- 产品升 1.0.0 时按 版本管理 修改 semantic-release 配置（
major_on_zero/minor_tags/patch_tags）