forked from niuniu/llm-intelligence
docs: add Hermes project review report
This commit is contained in:
root
235
reports/review/2026-05-20-hermes-project-review.md
Normal file
235
reports/review/2026-05-20-hermes-project-review.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# LLM Intelligence 项目 Review 报告
|
||||
|
||||
- 审查时间：2026-05-20
|
||||
- 审查人：Hermes Agent
|
||||
- 审查对象：D:\project\llm-intelligence
|
||||
- 审查方式：仓库结构盘点 + 关键代码抽样 + 配置/验证链路审查 + counter-evidence/calibration
|
||||
|
||||
## 1. 结论摘要
|
||||
|
||||
总体判断：这是一个“文档/规划活跃，但工程闭环和验证闭环明显不足”的项目。
|
||||
|
||||
成熟度判断：
|
||||
- 当前级别：demo-grade
|
||||
- 不建议给出 production-candidate 或“可稳定上线”的结论
|
||||
|
||||
主导问题：
|
||||
1. 基线不稳定
|
||||
2. 运行/验证环境不自洽
|
||||
3. 文档声称的完成度高于当前可复现度
|
||||
4. 前后端/脚本/部署链路存在多处断裂
|
||||
|
||||
## 2. 审查范围与限制
|
||||
|
||||
已检查：
|
||||
- git 基线状态
|
||||
- 顶层文档与 truth-map 候选
|
||||
- Go 服务端主入口与主要查询逻辑
|
||||
- 前端 Explorer / Dashboard / models 辅助库
|
||||
- docker-compose.yml / Dockerfile / nginx.conf / healthcheck.sh
|
||||
- verify 脚本与 verification_executor.go
|
||||
- 前端测试执行结果
|
||||
|
||||
受限项：
|
||||
- 当前环境中 go 不存在，因此 Go 测试未能实际跑通
|
||||
- 数据库验证未完整复现，因为 verify shell 脚本先被行尾格式问题拦住
|
||||
|
||||
## 3. 基线稳定性
|
||||
|
||||
git status 显示当前工作区存在大面积修改，覆盖：
|
||||
- 顶层文档
|
||||
- Go 服务端
|
||||
- migration
|
||||
- frontend
|
||||
- scripts
|
||||
- tests
|
||||
|
||||
这意味着：
|
||||
- 任何历史“验证通过”“Phase 1 完成”的说法，都不能直接当作当前真相
|
||||
- 当前 review 只能对当前工作区快照负责，不能继承旧报告的高置信结论
|
||||
|
||||
判定：P1 级问题。
|
||||
|
||||
## 4. Truth Map / Source of Truth
|
||||
|
||||
仓库顶层没有 README.md。
|
||||
|
||||
当前 truth candidates 主要包括：
|
||||
- PRD.md
|
||||
- TECHNICAL_DESIGN.md
|
||||
- IMPLEMENTATION_PLAN.md
|
||||
- IMPLEMENTATION_PLAN_v1.1.md
|
||||
- RUNBOOK.md
|
||||
- DEPLOYMENT.md
|
||||
- TASKS.md
|
||||
- GOALS.md
|
||||
- VERIFICATION_REPORT_Sprint1-3.md
|
||||
|
||||
判断：
|
||||
- PRD.md / TECHNICAL_DESIGN.md：更像 target design + 部分当前叙述混合体
|
||||
- RUNBOOK.md / DEPLOYMENT.md：试图充当 current ops truth，但可信度不足
|
||||
- VERIFICATION_REPORT_Sprint1-3.md：更像历史验证叙事，不足以代表当前 truth
|
||||
- 代码与当前可执行环境，优先级高于历史报告
|
||||
|
||||
问题：source-of-truth fragmented。
|
||||
|
||||
## 5. 五层成熟度判断
|
||||
|
||||
### 5.1 文档成熟度
|
||||
|
||||
优点：
|
||||
- 文档密度高，主题覆盖广
|
||||
- 技术设计、产品需求、部署、运维、验收、验证报告较齐全
|
||||
|
||||
问题：
|
||||
- current truth 与 target design 混杂
|
||||
- 顶层缺少统一入口文档
|
||||
- 文档中仍有明显历史/Linux 路径痕迹，如 /home/long/project/llm-intelligence
|
||||
|
||||
结论：
|
||||
- 文档本身：中上
|
||||
- 文档作为当前真相载体：中下
|
||||
|
||||
### 5.2 执行成熟度
|
||||
|
||||
后端锚点：cmd/server/main.go
|
||||
|
||||
优点：
|
||||
- API 入口清晰：/health、/api/v1/models、/api/v1/subscription-plans
|
||||
- 查询结构整体直白
|
||||
|
||||
问题：
|
||||
- 健康检查把“进程活着”和“数据库可用”混在一起
|
||||
- 数据库未配置时整个 API 直接 503
|
||||
- 与前端 fallback 的产品语义不统一
|
||||
- 服务端缺少更完整的超时与边界处理
|
||||
|
||||
前端锚点：
|
||||
- frontend/src/pages/Explorer.tsx
|
||||
- frontend/src/pages/Dashboard.tsx
|
||||
- frontend/src/lib/models.ts
|
||||
|
||||
优点：
|
||||
- Explorer 支持筛选/排序/分页
|
||||
- Dashboard 对模型和套餐做了分开展示
|
||||
- 有静态 fallback 数据方案
|
||||
|
||||
问题：
|
||||
- Explorer 对 fetch 未先检查 response.ok
|
||||
- modality 筛选口径与设计不一致
|
||||
- Dashboard 的“国内厂商”文案与真实统计口径不一致
|
||||
|
||||
结论：执行成熟度中下。
|
||||
|
||||
### 5.3 验证成熟度
|
||||
|
||||
反证非常明显：
|
||||
|
||||
1. Go 测试不可复现
|
||||
- 实测：go test ./...
|
||||
- 结果：go: command not found
|
||||
|
||||
2. 前端测试当前失败
|
||||
- 实测：npm test -- --run
|
||||
- 结果：缺失 @rollup/rollup-linux-x64-gnu
|
||||
|
||||
3. verify shell 脚本当前直接失败
|
||||
- 实测：bash scripts/verify_phase1.sh
|
||||
- 结果：$'\r': command not found、pipefail\r: invalid option name
|
||||
|
||||
结论：
|
||||
- 验证设计意图：中上
|
||||
- 当前可复现性：低
|
||||
- 不能给出“验证闭环成熟”的结论
|
||||
|
||||
### 5.4 运维成熟度
|
||||
|
||||
检查文件：
|
||||
- docker-compose.yml
|
||||
- Dockerfile
|
||||
- nginx.conf
|
||||
- healthcheck.sh
|
||||
- RUNBOOK.md
|
||||
|
||||
问题：
|
||||
- docker-compose.yml 中 DATABASE_URL 看起来像遮罩占位值，不像真实可运行配置
|
||||
- Dockerfile 中前端产物与 compose/nginx 实际消费路径脱节
|
||||
- healthcheck.sh 将“日报存在”混入基础健康判定
|
||||
- RUNBOOK.md 仍带个人化/历史路径
|
||||
|
||||
结论：有雏形，但未形成可信部署闭环。
|
||||
|
||||
### 5.5 生产成熟度
|
||||
|
||||
综合结论：
|
||||
- 文档成熟度：中上
|
||||
- review/治理成熟度：中
|
||||
- 执行成熟度：中下
|
||||
- 验证成熟度：低
|
||||
- 生产成熟度：低
|
||||
|
||||
最终成熟度带：demo-grade
|
||||
|
||||
主导 drift 类型：
|
||||
- validation drift
|
||||
- execution drift
|
||||
- source-of-truth drift
|
||||
|
||||
## 6. 最高风险的假成熟信号
|
||||
|
||||
1. 文档很多、报告很多，但当前环境下基础验证链路并不稳
|
||||
2. 前端 fallback 可能掩盖后端/数据库不可用问题
|
||||
3. RUNBOOK / DEPLOYMENT / compose / healthcheck 存在，但没有形成可一键复现的统一现实
|
||||
4. verification_executor 看起来成熟，但底层 shell 验证资产自身未持续通过
|
||||
|
||||
## 7. 问题清单
|
||||
|
||||
### P1
|
||||
1. 工作区大面积脏修改，导致历史验证/完成度结论失去当前高置信度
|
||||
2. 验证链路不可复现：当前环境无 go，前端测试失败，verify shell 脚本 CRLF 不兼容
|
||||
3. docker-compose.yml 中 app 的 DATABASE_URL 形态可疑，像占位值，不像可运行配置
|
||||
4. Dockerfile 产物路径与 compose/nginx 消费路径脱节，前端部署闭环不完整
|
||||
5. 顶层缺 README，source-of-truth 分散，文档与代码现实存在漂移
|
||||
6. 健康检查、前端 fallback、后端 503 策略未形成一致服务语义
|
||||
|
||||
### P2
|
||||
1. Explorer 未显式检查 response.ok
|
||||
2. modality 筛选与设计模型不一致
|
||||
3. Dashboard 文案“国内厂商”与真实统计口径不符
|
||||
4. writeJSON 错误处理不干净
|
||||
5. 服务端缺少更完整的超时配置
|
||||
6. RUNBOOK.md 中路径/环境信息陈旧
|
||||
|
||||
### P3
|
||||
1. 上下文窗口展示粗糙
|
||||
2. 部分前端/文案细节仍有占位感
|
||||
|
||||
## 8. 建议整改顺序
|
||||
|
||||
第一阶段：先修真相和验证，不要先补新功能
|
||||
1. 补顶层 README.md
|
||||
2. 统一 shell 脚本为 LF，并增加环境 preflight
|
||||
3. 前端依赖重装并跑通 npm test / npm build
|
||||
4. 修复 compose 的数据库配置
|
||||
5. 打通前端构建/运行链路
|
||||
|
||||
第二阶段：修服务语义
|
||||
6. 拆分 liveness / readiness
|
||||
7. 统一“API 不可用时前端是否允许 fallback”的产品语义
|
||||
8. 明确“无 DB 时系统是否仍算部分可用”
|
||||
|
||||
第三阶段：再继续扩展功能
|
||||
9. 修正 modality / 搜索 /指标口径等一致性问题
|
||||
10. 再扩展多源采集与更复杂报告能力
|
||||
|
||||
## 9. 最终 plain-language verdict
|
||||
|
||||
一句话评价：
|
||||
|
||||
这是一个“文档和治理意图明显超前于工程闭环”的项目。
|
||||
|
||||
更直白地说：
|
||||
- 它不像一堆随手拼的代码，说明作者有产品化和治理意识；
|
||||
- 但它还没有进入“可以被高置信度地认定为稳定可运行、稳定可验证、稳定可部署”的阶段。
|
||||
|
||||
最终评级：demo-grade
|
||||
Reference in New Issue
Block a user