Negentropy Wiki

工程变更日志

·原文链接

目标：沉淀已经完成的工程里程碑，记录背景、完成内容、影响面与验证结果，避免团队对当前工程基线产生状态误判。

#2026-04-16 · 全量 Lint 治理（ruff check 清零）

#背景

uv run ruff check . 报告全项目存在 1,722 项 lint 违规，分布于源码与测试共约 80+ 文件。问题类型涵盖：未使用导入（F401）、未使用变量（F841）、行过长（E501）、导入排序（I001）、setattr 常量属性（B010）、类型注解现代化（UP006/UP035/UP045/UP017/UP040）、zip() 缺少 strict（B905）、异常链缺失（B904）、未定义名称（F821）、布尔比较（E712）、FastAPI 标准用法误报（B008）等。

#完成内容

#第一阶段：自动修复（1,615 项）

通过 uv run ruff check --fix . 批量处理 F401、I001、B010、UP006/UP035/UP045/UP017 等可安全自动修复的违规。

#第二阶段：手动修复（107 项）

规则数量修复方式
B00860在 pyproject.toml 的 [tool.ruff.lint] ignore 中排除——FastAPI Depends()/Query()/File() 用于函数签名是框架标准用法
B90421为 except 中的 raise 补充 from err 或 from None，保留完整异常链
F82115通过 TYPE_CHECKING 守卫导入解决循环依赖下的前向引用（Event、KnowledgeRecord、CatalogService、WikiPublishingService、CorpusEngine、UnifiedRetrievalService、Thread），以及补充 import urllib.parse
E5017拆分过长行（中文文档字符串、IEEE 引用、迁移脚本、断言字符串）
E4027为 Alembic env.py 配置后导入、模块尾部兼容性重导出等添加 # noqa: E402
B9055为 zip() 调用添加 strict=True（均已验证等长保证）
F8414移除未使用的变量赋值（保留有副作用的函数调用）
E7124将 SQLAlchemy 列的 == True 改为 .is_(True)
UP0401将 TypeAlias 注解迁移为 PEP 695 type X = ... 语法
B0231通过默认参数绑定闭包中的循环变量
B0271为 ABC 中有意的 no-op 方法添加 # noqa: B027

#影响与当前状态

  • uv run ruff check . 全量通过（0 error）。
  • 涉及源码与测试约 80+ 文件，所有修改均为 lint 治理与类型注解改进，不涉及业务逻辑变更。
  • pyproject.toml 新增 B008 排除规则，符合 FastAPI 社区最佳实践。

#验证

hljs bash
cd apps/negentropy && uv run ruff check .  # All checks passed!

#2026-03-10 · QA 与发布流水线基线收口

#背景

在此轮治理前，Negentropy 已具备后端与 UI 两条独立测试 workflow，但仍存在 4 个系统性缺口：

  • PR 门禁与 Release 没有共享同一套 QA 定义，存在漂移风险；
  • 发布阶段缺乏稳定的版本工件、校验和与元数据清单；
  • 依赖清单变更缺少单独的供应链审查哨兵；
  • 本地 UI lint 会被 coverage/ 等生成产物噪音污染。

#完成内容

本次治理完成如下收口：

  1. 将后端与 UI 测试主链路提取为 reusable workflows：
  2. 将现有入口 workflow 改造成薄封装：
  3. 新增发布工作流 negentropy-release.yml，统一执行 QA、构建工件、输出 release-manifest.json 与 SHA256SUMS.txt。
  4. 新增依赖审查工作流 negentropy-dependency-review.yml，对 lockfile / manifest 改动施加高危漏洞门禁。
  5. 收敛覆盖率阈值与本地噪音：
    • 后端 coverage fail_under = 50
    • UI vitest 覆盖率总阈值接入
    • UI eslint 忽略生成产物目录
  6. UI 构建改为 standalone 输出，以便 release 工件可移植归档。
  7. 新增 apps/negentropy-ui/scripts/start-production.mjs，统一源码工作树、Playwright 冒烟与 release bundle 的生产启动入口，移除 next start 与 standalone 输出之间的契约偏移。

#影响与当前状态

  • 代码门禁、发布门禁共享同一套 QA 定义，单一事实源更清晰。
  • 发布不再只是“重新跑一次 build”，而是带有版本、校验和与元数据的可追溯工件生产过程。
  • 供应链风险更早暴露在 PR 阶段，减少把依赖问题带入主干或发布窗口的概率。
  • 本地开发者执行 pnpm lint 时不会再被 coverage/、playwright-report/ 之类的生成产物干扰。
  • UI 自动化冒烟现在直接启动与发布工件同构的 standalone 服务器，QA 信号更贴近真实发布拓扑。

#验证

本轮治理完成后，已执行并通过以下本地验证：

  • cd apps/negentropy && uv run pytest tests/unit_tests/
  • pnpm --dir apps/negentropy-ui lint
  • pnpm --dir apps/negentropy-ui typecheck
  • pnpm --dir apps/negentropy-ui test:coverage
  • pnpm --dir apps/negentropy-ui build
  • pnpm --dir apps/negentropy-ui test:e2e

#相关链接

#2026-03-08 · UI ESLint 基线治理完成

#背景

在这轮治理开始前，apps/negentropy-ui 的 ESLint 仍处于“专项 guard 过渡态”：

  • UI 基线存在 47 个问题，其中 16 个 error、31 个 warning。
  • useSessionManager 的禁用依赖临时专项 guard，而不是正式全量 lint 门禁。
  • UI CI 还没有把 pnpm lint 作为标准工程门禁接入。

对应总追踪 issue 为 #185 技术债(UI): 清理 ESLint 基线并启用全量 pnpm lint CI 门禁。

#完成内容

本次治理按 3 个批次完成：

  1. Batch 1：清理 React 语义类 ESLint error
    关联 PR： #191
  2. Batch 2：清理类型与导入类 ESLint error
    关联 PR： #194
  3. Batch 3：清理 warning 并启用全量 lint CI
    关联 PR： #196

同时完成以下收尾动作：

  • 父任务 #185 已完成收口并关闭。
  • 子任务 #187、#188、#189 已全部关闭。
  • UI workflow 已切换到正式全量 lint job，见 UI Test Suite。
  • lint:legacy-session-imports 与专项扫描脚本已退役，禁用 useSessionManager 的职责回归 ESLint 规则本身。

#影响与当前状态

当前工程基线已经从“专项 guard 过渡态”切换为“正式 lint 门禁态”：

#验证

本轮治理完成时，执行并通过了以下校验：

  • pnpm --dir apps/negentropy-ui lint
  • pnpm --dir apps/negentropy-ui typecheck
  • pnpm --dir apps/negentropy-ui test

其中 Batch 3 收尾时，vitest 结果为 50 个测试文件、264 个测试全部通过。

#相关链接