Skip to content

docs(review): 专家团队评估（非在途面）—— 2 P0 + 5 P1 + 10 P2 + 重构候选清单 - #138

Merged
ROM4n2 merged 4 commits into
masterfrom
chore/swarm-audit-master
Oct 16, 2026
Merged

docs(review): 专家团队评估（非在途面）—— 2 P0 + 5 P1 + 10 P2 + 重构候选清单#138
ROM4n2 merged 4 commits into
masterfrom
chore/swarm-audit-master

Conversation

@ROM4n2

@ROM4n2 ROM4n2 commented Oct 15, 2026

Copy link
Copy Markdown
Owner

概要

对 **master 上「非在途面」**做一次专家团队评估（分支从 master 新开，不触碰在途的 feat/judge-gaming-experiment）。本 PR 只新增两份评估报告，零代码改动 —— 修复与重构会另开分支（避免与在途面撞文件）。

报告 内容
docs/reviews/2026-10-15-swarm-audit-master.md 3 席位并行评估：2 P0 + 5 P1 + 10 P2（原始 35 条 → 合并后 16 条），含对抗式质疑复核
docs/reviews/2026-10-15-refactor-candidates.md 重构候选：LOC 实测 + 两席定性排序（含「不该动」清单与打包面成本）

席位与裁剪（跳过席位附 artifact 证据，不是"不相关"）

席位 状态 依据
dba-optimizer 派 core/database.py 2,809 行（schema/WAL/迁移/事务/备份）+ 内联 SQL
sre-resilience 派 TTS WSS / 抓取 / 更新 / 同步 / Go 侧重试等外部边界
code-reviewer 派 死测、YAGNI、密钥暴露
frontend-architect 跳过 在途前端（writer.js）已排除，余前端本轮无改动窗口
perf-profiler 跳过 无新增热路径/内存池；to_thread 与信号量由 sre/dba 覆盖
product-ux 跳过 无旅程/CLI 变更面（在途旅程全在 ai-polish，已排除）

🚨 P0（两条都是静默失败）

P0-1 · /api/backup/restore 静默清空训练记录（CONFIRMED，已用真实 _replace_tables 复现）
_BACKUP_TABLES 实际 10 张表 vs RestoreReq 只声明 8 个字段 ⇒ pydantic v2 默认 extra=ignore 丢掉两键 ⇒ _replace_tables（database.py:1901）对清单中每张表无条件 DELETE，随后 payload.get() or [] 为空 ⇒ 删光零回灌，接口仍返回 ok、UI 弹「还原成功」。
⚠️ 这是 database.py:1492-1496 修过的同类 bug 第二次发生 —— 缺的是「清单 ↔ 还原模型」一致性守卫，不是再补一次字段。

P0-2 · 退出挂死 + 假成功（CONFIRMED，机制经质疑席纠正）
席位原报"uvicorn wait_for(None)"不成立（本仓压根没调 Server.shutdown()）。真因：start.py:180 thread.join() 无超时 + 非 daemon 线程 + 丢弃 shutdown() 返回值 + 无条件打印「服务已停止」+ 裸调 main() 无 SystemExit ⇒ 进程挂住、8000 仍占 ⇒ 下次启动连到旧实例（与历史「孤儿 uvicorn 假绿」同形）。
⚠️ 请按纠正后的机制修，别照席位原说法改。

⚠️ P1

  • P1-1（CONFIRMED，两席合并）：备份 JSON 带走 wb.pair.v1（长期 wb_sync_key + 内网 host），后端白名单被 localStorage 侧门绕过，还原还会写回本机。⚠️ 修法必须同步改 tests/test_server.py:1031（它把"原样透传"钉成了契约）。
  • P1-2（CONFIRMED）：备份不是跨表一致快照（无 BEGIN、两库独立连接）；质疑席补注"窗口毫秒级、严重性低"。
  • P1-3~P1-5（UNVERIFIED）：抓取无总截止 / Go supervisor 无累积重启上界 / DeepSeek 退避无 jitter —— 未做对抗复核，已标注，不得据此下阻塞结论。
  • 质疑席推翻 1 条：原 P1「桌面壳 os._exit 导致正常退出也报 exit 1」不成立（仅在超时分支硬杀）⇒ 降 P2。

🧹 重构候选：最大的文件恰恰最不该动

  • 不该动：core_dict_ext.py(3,978) / official_vocab.py(3,064) / official_vocab_rich.py(3,049) / encounter_seed_dict.py(1,493) / prep_dict.py(933) 全是 DATA-BLOB（0 def、auto-generated 已标注）；拆数据需同步 3 个交付配置面 + data_dict_modules 硬编码守卫（漏登记 = 本地全绿、打包后 ModuleNotFoundError）。
  • 最该动：core/database.py（86 def / 9 组职责 / 32 处被 import，且与 nlp_engine/processor 有已知双向耦合）⇒ 但须在 P0-1 修完并补契约测试之后再切。
  • 前端最高价值且低风险：cards.js 与 workbench.html 的备份逻辑是同一关注点两套实现、各自硬编码 wb. 前缀 ⇒ 正是 P1-1 的结构性成因 ⇒ 键集合单点化（不是拆文件）。
  • 前端最痛但别先动：workbench.html（4,730 行单文件 PWA）拆文件会让 4 个测试文件全红（含全文位置断言与按行号钉 wbsync.push() 的探针）⇒ 先把探针改成按段读入。
  • 在途冲突：routes/main.py(3,115 / 70 routes)、services/writing.py(1,424)、writer.js(ai-polish 段) 一律等各自计划落地。

建议的后续（本 PR 不含）

  1. 另开修复分支做 P0-1 + P0-2（按纠正后的机制）。
  2. 同批做 前端键集合单点化（与 P1-1 同源）。
  3. 补证 P1-3~P1-5；再按 §4 顺序推进重构。

说明

  • 本 PR 零代码改动：只加 docs/reviews/ 两份报告。
  • 评估分支从 master 新开（chore/swarm-audit-master），全程未触碰在途分支 feat/judge-gaming-experiment（另一 agent 正在其上开发）。

ROM4n2 added 4 commits October 15, 2026 23:49
@ROM4n2
docs(review): 专家团队评估（非在途面）—— 2 P0 + 5 P1 + 10 P2，含质疑复核
64e2fc8 
- 席位：dba-optimizer / sre-resilience / code-reviewer 三席并行；跳过 frontend-architect（在途前端已排除、余前端无改动窗口）、perf-profiler（无新增热路径）、product-ux（无旅程变更），均附 artifact 证据。
- P0-1（CONFIRMED，已复现）：/api/backup/restore 静默清空 listen_trials 与 hard_sentence_trials —— _BACKUP_TABLES 10 表 vs RestoreReq 8 字段 + pydantic extra=ignore + _replace_tables 无条件 DELETE ⇒ 删光零回灌且返回 ok。与 database.py:1492-1496 修过的同类 bug 是第二次发生。
- P0-2（CONFIRMED，机制经质疑席纠正）：退出挂死 + 假成功 —— 真因是 start.py:180 thread.join() 无超时 + 非 daemon uvicorn 线程 + 丢弃 shutdown() 返回值 + 无条件打印「服务已停止」+ 裸调 main() 无 SystemExit；不是席位原报的 Server.shutdown() 无限等待。
- P1-1（CONFIRMED，两席合并）：备份 JSON 带走 wb.pair.v1（长期 wb_sync_key + 内网 host），后端白名单被 localStorage 侧门绕过；还原侧还会写回本机。修法需同步改 tests/test_server.py:1031（它把原样透传钉成了契约）。
- 质疑席推翻 1 条：原 P1「桌面壳 os._exit 导致正常退出也报 exit 1」不成立（仅在超时分支硬杀）⇒ 降级 P2。
- 3 条 sre P1 未做对抗复核，标记 UNVERIFIED 并给出补证命令，不得据此下阻塞结论。
- 本评估在 master 新分支 chore/swarm-audit-master 上做，不触碰在途分支。
@ROM4n2
docs(review): 重构候选评估（LOC 实测 + 两席定性排序）
bb70c5f 
- 核心结论：最大的文件恰恰最不该动 —— core_dict_ext(3978)/official_vocab(3064)/official_vocab_rich(3049)/encounter_seed_dict(1493)/prep_dict(933) 全是 DATA-BLOB（0 def、auto-generated 已标注）；拆数据需同步 3 个交付配置面 + tests/test_server.py 的 data_dict_modules 硬编码守卫（漏登记 = 本地全绿、打包后 ModuleNotFoundError）。
- 真正该动：core/database.py（2809 / 86 def / 9 组职责 / 32 处被 import，且与 nlp_engine/processor 有已知双向耦合）⇒ 但须在 P0-1 修完并补契约测试后再切。
- 前端最高价值且低风险：cards.js 的备份+LS 键扫描 与 workbench.html:4347-4472 是同一关注点的两套实现、两边各自硬编码 wb. 前缀 ⇒ 正是 P1-1（密钥经前端备份绕过后端白名单）的结构性成因 ⇒ 键集合单点化（不是拆文件）。
- 前端最痛但别先动：workbench.html（4730 单文件 PWA，塞了种子数据/g2p/存储/wbsync/WebRTC/IndexedDB/TTS/FSRS/短码同步/导入导出/PWA）—— 拆文件会让 4 个测试文件全红（含整文件位置断言与按行号钉 wbsync.push 的探针）⇒ 先把探针改成按段读入。
- 在途冲突：routes/main.py(3115/70 routes)、services/writing.py(1424)、writer.js(ai-polish 段) 一律等各自计划落地。
- 不建议动还含：encounter.js/reader.js（内聚）、listen-lab.js/hard-sentences.js（被模块图守卫三重钉死 + 有意为之的复制）、a1_cards.js（拆标记=重写渲染）、core.js（是收敛目标）。
@ROM4n2
docs(review): 项目结构与文档质量评估（4 P1 + 9 P2，无 P0）
d93089b 
两席并行（code-explorer 结构 + code-reviewer 文档），只读未改码；18 条原始发现合并为 13 条。

P1-1 测试库写进仓库根：conftest.py:30-31 与 tests/test_get_endpoints_with_writes.py:37-38 用裸相对文件名 ⇒ 落 CWD；而 db_cleanup.py:72 的 ROOT_DB_NAMES 只比 delector.db/progress.db ⇒ test_*.db 在守卫视野外（*.db 被 ignore ⇒ 可无限期无人发现），且根目录有库会让 test_save_wb_state_cost.py 拒绝运行 ⇒ 本地红/CI 绿的迁移闸假象。
P1-2 docs/agents/ops.md:53-57 数据目录口径与 v5.17.0 事实相悖（且与本文件 47-51 自相矛盾）⇒ agent 会被误导在仓库里跑 start.py，触发 bootstrap_data_dir 把真实 delector.db 改名 .bak 并复制走。
P1-3 architecture.md:202/:93-94 宣称 POST /api/settings 无鉴权，实测 routes/main.py:1500-1502 第一行就是 _require_localhost ⇒ 会造成重复加固或误报安全结论。
P1-4 门禁基线停在 2026-08/09（352 / 719 / 10 探针 vs 实测 122 文件 / 1986 条 / 29 探针）+ 前端模块数三处三个数（README 11 / architecture 10 / 实测 23）。

P2 含：CLAUDE.md 是缺路由短桩（AGENTS.md:3 自称同形态但 GEMINI.md 才指 AGENTS）、Inbox 路径两套写法（99-Inbox vs 08-Inbox 四文件两地址）、archive 4 份文件违反命名规则、design-system.md 全仓零入口且 7 token/5 色值与 CSS 逐个 grep 零命中、README Python badge 3.10 无支撑、根目录/包结构描述缺项、scratch 50MB 无修剪、agent/ 一词三义、WORKMEMORY INDEX:16 vs :39 矛盾、README Tests 徽章口径未定义。

合理部分（两席共识）：README 版本面最健康且有机械闸、单一真相源纪律到位、docs/README.md 是单一契约、.gitignore 分层设防带理由、未发版功能诚实用限定表述、测试隔离基础设施方向正确（唯一漏口即 P1-1）。
@ROM4n2
docs(review): commit 节奏与 git 管理评估（2 P1 + 8 P2，无 P0）
8303c99 
两席 code-reviewer 并行（commit 节奏与历史纪律 / git 管理与仓库卫生），只读未写。

节奏结论：健康 —— 447 提交/30 天 ≈ 3 PR/天 × PR 内任务级原子提交（平均 2.3/PR）+ 协议驱动的簿记事件；空泛消息 0；90 个 merge 全为 --no-ff 且合并信息带 PR 号与验收数据；版本面六件套 + tag 硬闸；规则生效后（2026-10-14 起）直推 master 的 20 条只碰 WORKMEMORY/ 与 docs/。

P1-1 分支纪律无机械闸：2026-10-09~10-14 有 25 个 feat/fix/ci/test/perf 提交直推 master（含生产代码与 CI 定义），已有实发事故 f49d359（直推把 master 推红后回头补）；规则 2026-10-14 才进可见文档，此前 agent 读不到。修法：pre-push hook 或 CI job 断言 master 非 merge 提交改动面 ⊆ 簿记/文档白名单。
P1-2 ignore 覆盖缺口（编排者已独立复核）：launch.log / launch.log.1 / lan-address.txt 均 NOT-IGNORED，确由 desktop.py:46/51/58 产生，便携模式（data_dir_bootstrap.py:118-129 return program_dir()）下落在仓库根 ⇒ 一次 git add -A 会把运行态日志（启动堆栈/端口冲突）与内网 IP 提交进历史，正是 .gitignore:21-24 自述的威胁模型；pre-commit 文件名黑名单也不含 .log/.txt。历史从未进过这三个文件。修法 3 行根级忽略规则。

P2 含：实现与簿记混装 7 个提交、批量子提交多事揉一团（59ac353 11 文件/+1448）、行号锚点缺席、.superpowers/ 缺根级兜底、松散对象 49.10 MiB、9 个文件工作区行尾 w/mixed、CRLF 纪律依赖本机 core.autocrlf 而非 .gitattributes 契约、.env.example 注释与代码矛盾（与结构评估 P1-2 同源）、gradle-wrapper.jar 未入库待确认。

合理部分：PR 内任务级原子提交 + 每提交带回归锁与变异自证；--no-ff 可读合并信息；簿记一个事件一提交；密钥与历史卫生干净（HEAD 高熵扫描 0 命中）；.gitignore 按类别+理由分层；DeLector.spec 由显式 skip 钉住非死绿。
@ROM4n2
ROM4n2 merged commit 40d8f18 into master Oct 16, 2026
4 checks passed
@ROM4n2
ROM4n2 deleted the chore/swarm-audit-master branch October 16, 2026 09:46
@ROM4n2 ROM4n2 mentioned this pull request Oct 16, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ROM4n2