supply-intelligence/reports/hermes/HERMES_OPTIMIZATION_SUGGESTIONS.md

Hermes Optimization Suggestions

本文件用于持续沉淀 Hermes 在 supply-intelligence 项目推进中的优化建议。

要求：

• 仅记录从真实 review 或真实执行中观察到的问题
• 不记录泛泛而谈的空建议
• 每条建议都要带优先级与验证方式

2026-05-07

问题 1：只看文档结论，容易高估代码真实稳定度

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 如果只沿用既有真源文档中的 APPROVED 结论，而不先检查 git status、提交历史和工作区漂移，Hermes 容易把“文档已批准”误读成“代码已接近可发布”。
• 优化建议：
  • 把“文档门控状态”和“代码基线稳定度”拆成两个独立判断项；日常 review 模板中强制加入：未提交文件数、未跟踪文件数、最近有效提交数。
• 优先级：P0
• 建议的验证方式：
  • 未来 review 先执行 git status --short 与 git log --oneline -5，报告中必须同时出现“文档门控结论”和“代码基线结论”，且两者允许不一致。

问题 2：验证脚本存在不等于可执行

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 仅枚举 scripts/ 目录会让 Hermes 误以为迁移脚本已经可直接使用；实际 ./scripts/run_migrations.sh --status 因权限不足失败，退出码 126。
• 优化建议：
  • 对脚本类资产，默认增加一次直接执行验证；若失败，再记录 fallback 执行方式与精确失败原因。
• 优先级：P1
• 建议的验证方式：
  • 同时执行 ./scripts/run_migrations.sh --status 与 bash ./scripts/run_migrations.sh --status，确认是脚本逻辑错误还是文件权限问题。

问题 3：当前 review 仍偏重静态通过，缺少“最小真实链路”强校验

• 本次 review 暴露出的 Hermes 工作方式问题：
  • go build / go test / go vet 全绿并不自动证明 package event + ack、DB 模式 migration、HTTP 运行态已经成立；Hermes 若止步于静态验证，会高估闭环完成度。
• 优化建议：
  • 为此项目的 Hermes 日审流程新增“最小真实链路校验清单”：数据库模式迁移、服务启动、关键 HTTP API、至少一条 package/account 主路径验证。
• 优先级：P1
• 建议的验证方式：
  • 在后续 review 中追加可重复命令，例如带临时 DATABASE_URL 的 migration 校验、服务启动 smoke test、HTTP endpoint 探活与最小事件回写测试。

问题 4：范围漂移识别应前置，不应等到总结阶段才发现

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 当前未提交改动已经扩展到 dashboard、metrics、docker、deploy、postgres 等方向；如果 Hermes 不在 inspection 阶段主动把新增文件按“闭环必要 / 扩展项”分类，就容易让 review 报告停留在笼统提醒。
• 优化建议：
  • 在 review 工作流中增加“新增未跟踪文件分类”步骤，按主链路必要性进行初步归类，并在报告里直接标出疑似范围漂移资产。
• 优先级：P2
• 建议的验证方式：
  • 对 git status --short 中的 ?? 文件做分类表，检查是否能明确指出哪些新增项超出首期最小闭环。

2026-05-08

问题 1：昨天的通过态不能被继承，日审必须重新验证代码基线

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 昨日 review 记录 go build / go test / go vet 全通过，但今日同一仓库已因 Repository 接口与实现脱节而全部失败。如果 Hermes 复用前一日结论或默认“昨天通过=今天大概率仍通过”，会直接产出错误判断。
• 优化建议：
  • 对日度 review 增加硬规则：所有 build/test/vet 结论都必须当天重跑并覆盖旧报告，不允许继承历史绿线。
• 优先级：P0
• 建议的验证方式：
  • 对比连续两日日报中的命令输出与退出码，确保最终结论只基于当天执行结果。

问题 2：接口演进类改动需要优先做“编译面完整性检查”

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 当前问题不是逻辑细节，而是 interfaces.go 扩展后，MemoryRepository / PostgresRepository 未同步实现 CountPackageEventsBySyncStatus，导致整个仓库失去最小编译能力。Hermes 若只看新增文件数或只扫测试文件，容易错过这种高杀伤面的结构性断裂。
• 优化建议：
  • 当发现新增 interfaces.go、factory.go、跨实现抽象层改动时，把“编译面一致性”提升为首个检查项：先搜索接口新增方法，再确认每个实现是否落地。
• 优先级：P0
• 建议的验证方式：
  • 固定执行：读取接口文件、搜索所有实现中的同名方法、再跑 go build ./...；三者结论必须一致。

问题 3：脚本验证要保留“直接执行失败 + fallback 成功”的双证据

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 如果只记录 bash ./scripts/run_migrations.sh 成功，会掩盖脚本权限缺陷；如果只记录直接执行失败，又会错判脚本逻辑不可用。
• 优化建议：
  • 针对 shell 脚本类资产，Hermes 报告模板中应固定保留两层证据：直接调用结果、fallback 调用结果，并明确失败归因属于权限、解释器还是脚本逻辑。
• 优先级：P1
• 建议的验证方式：
  • 同时执行 ./scripts/run_migrations.sh 与 bash ./scripts/run_migrations.sh，并在报告中记录退出码和关键错误行。

问题 4：会话亮点提炼不能只看“完成/交付”措辞，要结合真实验证状态去重估可信度

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 最近多条 substantial session 都出现了“完成/交付/报告”等成功性措辞，但今日仓库真实状态显示核心代码仍可编译失败。说明仅依赖会话结论词提炼“昨日亮点”会高估交付质量。
• 优化建议：
  • 生成 digest 时，将“会话内成功措辞”与“仓库当下 build/test 结果”交叉验证；若仓库基线已红，应把相关亮点降级为“推进/设计产出”，而非“稳定交付”。
• 优先级：P1
• 建议的验证方式：
  • 选取最近 3~5 个 substantial session，交叉对照同日或次日代码门禁结果，检查最终 digest 是否区分了“文档交付”和“代码稳定交付”。

2026-05-09

问题 1：Hermes 不能把“脚本能跑通一段”误判成“脚本构成完整可执行闭环”

• 本次 review 暴露出的 Hermes 工作方式问题：
  • gateway_closure_inspect.sh 与 gateway_closure_rollback.sh 在本地服务上可运行，但 gateway_closure_smoke.sh 在真实服务上因缺少 candidate/package 前置状态返回 404 candidate_or_package_missing。如果 Hermes 只看到脚本存在，或只看到部分脚本成功，就容易把整个 closure runbook 高估为“已可直接执行”。
• 优化建议：
  • 对 runbook/closure 脚本增加“前置条件显式核查”步骤：不仅执行脚本，还要确认脚本依赖的数据前提、服务前提和环境前提是否满足；若不满足，报告中应明确标注为“有前置条件的脚本”，而不是“通用 smoke 脚本”。
• 优先级：P0
• 建议的验证方式：
  • 对每个脚本同时记录：直接执行结果、fallback 结果、依赖的 HTTP 端点、失败时的精确业务错误（如 candidate_or_package_missing），确认报告是否明确写出了脚本前提。

问题 2：Hermes 需要区分“脚本名义能力”和“脚本真实能力”，不能被命名误导

• 本次 review 暴露出的 Hermes 工作方式问题：
  • run_migrations.sh 名称看似是 migration runner，但今日逐行复核后确认：无 DATABASE_URL 时仅列出文件；有 DATABASE_URL 时当前实现也只是准备 schema_history 并列举 migration 文件，--baseline 还未实现。若 Hermes 仅依据文件名或 README 口径，就会把“迁移检查脚本”误写成“迁移执行器”。
• 优化建议：
  • 对名称中带 run、migrate、deploy、rollback 的脚本，Hermes 应在 review 时至少读一次脚本正文，确认其真实副作用与真实完成度，再给结论。
• 优先级：P0
• 建议的验证方式：
  • 在后续 review 中，把“脚本名义能力”与“脚本正文中实际执行的动作”并排写出，检查是否仍出现把 listing/check 脚本误写为 executor 的情况。

问题 3：当仓库已有自述性 QA/证据报告时，Hermes 仍要做独立抽样验证，避免把文档真值当成系统真值

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 仓库里已有 QA_PRODUCTION_GATE_REVIEW_2026-05-09.md 和 PRODUCTION_EVIDENCE_PACK_2026-05-09.md，其中包含“本地启动 + inspect/rollback 可用”的结论。今日复核证明这些结论大体成立，但若 Hermes 只转述文档、不自己起服务、不自己 curl、不自己跑脚本，就无法发现 smoke 的真实 404 前置缺口，也无法确认当前代码门确实已恢复为绿。
• 优化建议：
  • 对“仓库内已有结论型报告”的项目，Hermes 日审流程应默认执行独立抽样复核：至少重跑 build/test/vet，并在能力范围内选 1 条本地运行态链路亲自验证。
• 优先级：P1
• 建议的验证方式：
  • 对后续 review 检查：最终报告中是否同时出现“仓库内已有报告结论”和“本轮独立复核结果”，且二者被明确区分。

问题 4：对脚本类资产的质量判断应拆成三层，而不是单一“通过/失败”

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 当前 shell 脚本统一没有执行位，直接执行全是 126；但 fallback 到 bash ... 后，有的脚本能工作，有的脚本因环境或业务前提失败。若 Hermes 只写一个“脚本失败”或“脚本可用”，都丢失了关键信息。
• 优化建议：
  • 将脚本资产固定拆成三层判断：
    1. 可直接执行性（权限/解释器）
    2. 逻辑可运行性（在最小环境下是否能跑）
    3. 业务闭环完整性（是否满足真实场景前提）
• 优先级：P1
• 建议的验证方式：
  • 检查后续日报是否对每个关键脚本分别给出三层结论，而不是单一“成功/失败”。

2026-05-10

问题 1：当同日门禁文档互相冲突时，Hermes 需要默认采信更底层证据，而不是沿用较乐观摘要

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 仓库中同日同时出现了 REQUEST_CHANGES（共享环境证据正文）和 CONDITIONAL_APPROVED（QA / readiness 摘要）两种生产门禁结论。若 Hermes 只读取最新摘要文档或只看“最终结论”段落，就会高估真实放行状态。
• 优化建议：
  • 在 Hermes 日审流程中增加“门禁结论冲突扫描”：对 evidence/QA/readiness/board 同类文档并列抽取结论；一旦冲突，默认按更底层、带原始证据与缺口说明的文档降级结论，并在报告中显式标出冲突源。
• 优先级：P0
• 建议的验证方式：
  • 后续 review 中同时搜索 REQUEST_CHANGES、CONDITIONAL_APPROVED、APPROVED，确认最终报告是否写出了冲突文件路径，并采用保守结论。

问题 2：当脚本用 curl -f 失败时，Hermes 不能只记录退出码，必须补抓 HTTP 错误体

• 本次 review 暴露出的 Hermes 工作方式问题：
  • gateway_closure_smoke.sh 失败时只暴露 curl: (22)；若 Hermes 停在脚本原始输出，就只能写“404 失败”，看不到真正的业务原因 candidate_or_package_missing。
• 优化建议：
  • 对所有 HTTP 驱动脚本，若原脚本因 curl -f 失败，Hermes 应自动补一条非 -f 的手工请求，记录状态码与响应体，区分业务前提缺失、权限问题和系统故障。
• 优先级：P1
• 建议的验证方式：
  • 未来 review 中若脚本出现 curl: (22)，检查最终报告是否同时给出失败接口、HTTP 状态码与响应 body。

问题 3：Hermes 应把“超大未提交工作区”视为独立交付风险，而不是附带背景信息

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 当前仓库只有 1 条提交，但工作区已扩大到 modified=33 untracked=43。若 Hermes 只把这类信息写在背景段，而不将其升级为独立风险项，就会低估后续评审、回滚、灰度追责的真实成本。
• 优化建议：
  • 为日度 review 增加“工作区收口阈值”判断：当未提交修改数、未跟踪项或 diff 规模超过阈值时，自动升级为 P1 风险，并将“拆分提交边界”纳入 Top 3 下一步。
• 优先级：P1
• 建议的验证方式：
  • 对后续大工作区项目检查：最终报告是否在 Executive Summary 或风险段中单列 dirty-repo 风险，而不是只放在工作区状态统计里。

2026-05-11

问题 1：如果 Hermes 只跑常规 go test，会漏掉运行态并发缺陷

• 本次 review 暴露出的 Hermes 工作方式问题：
  • go build、go vet、go test ./... 全绿，但 go test -race ./... 立即在 internal/poller 暴露 cursor 的真实 data race。说明 Hermes 若把“常规测试通过”直接等价为“运行态足够安全”，会漏掉后台 worker / poller 这种高风险并发问题。
• 优化建议：
  • 对包含后台 goroutine、runtime poller、worker loop、pause/resume 控制面的 Go 项目，把 go test -race ./... 提升为日审默认补充项；若时间成本过高，至少对疑似并发包定向跑 race。
• 优先级：P0
• 建议的验证方式：
  • 后续 review 中同时记录 go test ./... 与 go test -race ./... 的结果；若两者结论不一致，最终报告必须按更保守结论降级。

问题 2：Hermes 不能只验证“等价命令”，必须验证 runbook 里写出来的字面命令

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 如果 Hermes 只验证“服务有 healthz”或“rollback 脚本能跑”，就会错过 runbook 中真正写给值班人员的命令已经漂移：/internal/supply-intelligence/healthz 实测 404，gateway_closure_rollback.sh --dry-run 实测会真实 pause。
• 优化建议：
  • 对 runbook/checklist 类文档，Hermes 应优先逐条执行文档原文命令，再做等价替代验证。这样才能发现“系统本身可用，但文档命令已失真”的高风险问题。
• 优先级：P0
• 建议的验证方式：
  • 后续 review 中抽样执行 runbook 中列出的原始命令，检查报告是否区分“文档命令失败”与“等价手工命令可行”。

问题 3：Hermes 需要显式区分“seed/mock 驱动的本地闭环”与“真实生产前置条件闭环”

• 本次 review 暴露出的 Hermes 工作方式问题：
  • 今日本地 smoke 之所以通过，依赖 SEED_LOCAL_DEMO=1 注入 demo candidate/package，以及 ADMISSION_TEST_MOCK=1 让 admission 直接返回成功。若 Hermes 只写“本地 smoke 通过”，会高估该证据对生产 readiness 的支撑力度。
• 优化建议：
  • 报告模板中增加“验证模式”字段：真实依赖 / mock / seeded demo / synthetic fixture。凡使用 seed/mock 的链路，都应自动降级为“回归验证证据”，而非直接充当生产放行证据。
• 优先级：P1
• 建议的验证方式：
  • 后续 review 检查最终报告是否显式写出关键环境变量、mock 开关和 seed 行为，并对结论进行降级说明。