Skip to content

refactor(scripts): 正交分解 scripts/ 目录,提取共享模块消除三轴重复; - #549

Merged
ThreeFish-AI merged 2 commits into
feature/1.x.xfrom
ThreeFish-AI/taipei-v2
May 16, 2026
Merged

refactor(scripts): 正交分解 scripts/ 目录,提取共享模块消除三轴重复;#549
ThreeFish-AI merged 2 commits into
feature/1.x.xfrom
ThreeFish-AI/taipei-v2

Conversation

@ThreeFish-AI

@ThreeFish-AI ThreeFish-AI commented May 16, 2026

Copy link
Copy Markdown
Owner

背景

  • 本次变更要解决的问题:apps/negentropy/scripts/ 目录中 4 个脚本(471 行)存在三轴正交重复——DB 引擎生命周期(create_async_engine + dispose 在 4 个脚本中各重复一次)、异步入口点(asyncio.run + try/except 样板重复 4 次)、清理算法(cluster_by_time/check_index_completeness 在 CLI 脚本、API 端点、单元测试三处逐字重复)
  • 关联上下文/文档:CLAUDE.md 熵减原则(正交分解、单一事实源、复用驱动)

核心变更

  • 新建 scripts/_db.py(45 行):提取 script_engine(async context manager,自动 dispose)、script_connection(引擎+连接快捷方式)、run_script(asyncio.run 封装 + 统一错误处理)三个共享工具
  • 新建 src/negentropy/knowledge/cleanup.py(133 行):将聚类算法(cluster_by_time/check_index_completeness)及异步 DB 操作(scan_source_uris/get_chunks_for_source/delete_chunks)收敛为单一事实源,CLI 脚本、API 端点、单元测试均从此模块导入
  • 重构 cleanup_orphan_chunks.py:从 330 行减至 195 行,删除 5 个本地函数定义,改为导入 cleanup 模块 + _db 工具
  • 重构 find_dup_arxiv_ids.py(79→55 行)、force_reset_db.py(39→22 行)、init_test_db.py(26→14 行):使用 _db 共享工具消除连接样板
  • 更新 test_cleanup_orphans.py:删除 25 行内联函数副本,改为从 negentropy.knowledge.cleanup 导入
  • 消除 api.py L5764-5792 的重复算法:替换内联聚类循环和完整性检查为 cluster_by_time/check_index_completeness 调用

风险与回滚

  • 主要风险:API 端点中 Row→dict 转换引入额外列表推导开销,性能影响可忽略不计
  • 回滚方式:git revert 单次提交即可完整回滚

验证证据

  • 单元测试:pytest tests/unit_tests/knowledge/test_cleanup_orphans.py — 7/7 全部通过
  • 集成测试:N/A(纯重构,无新功能)
  • E2E/Workflow:各脚本 --help 入口正常输出
  • 覆盖率/关键截图:ruff check 全部通过,pre-commit hooks(lint + format)通过

影响范围

  • 前端:无
  • 后端:negentropy.knowledge.api 中 cleanup-orphans 端点的聚类逻辑改为从模块导入(外部行为不变)
  • GitHub Actions / 文档:无

Next Best Action

  • 考虑为 cleanup.py 中的异步 DB 函数补充单元测试(当前测试仅覆盖纯函数)

- 新建 scripts/_db.py:提取 DB 引擎生命周期(script_engine/script_connection)
  与异步入口点(run_script),消除 4 个脚本中的连接样板重复
- 新建 src/negentropy/knowledge/cleanup.py:将聚类算法(cluster_by_time/
  check_index_completeness)及 DB 操作(scan_source_uris/get_chunks_for_source/
  delete_chunks)收敛为单一事实源
- 重构 cleanup_orphan_chunks.py:从 330 行减至 195 行,导入 cleanup 模块函数
- 重构 find_dup_arxiv_ids.py/force_reset_db.py/init_test_db.py:使用 _db 共享工具
- 更新 test_cleanup_orphans.py:删除 25 行内联函数,改用 cleanup 模块导入
- 消除 api.py 中 L5764-5792 的聚类/完整性检查内联实现,复用 cleanup 模块

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI ThreeFish-AI changed the title refactor(scripts): 正交分解 scripts/ 目录,提取共享模块消除三轴重复 refactor(scripts): 正交分解 scripts/ 目录,提取共享模块消除三轴重复; May 16, 2026
cluster_by_time() 返回 list[list[dict]],但 kept_ids 仍使用 ORM 属性语法 c.id
遍历 latest,运行时抛出 AttributeError,改为 dict 键访问 c["id"]。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant