Skip to content

refactor: 全仓熵减进化——死代码清减、正交分解与路由遮蔽缺陷修复(净 -3,761 行) - #1131

Merged
ThreeFish-AI merged 14 commits into
feature/1.x.xfrom
ThreeFish-AI/preening-substrate-entropy-reduction
Sep 10, 2026
Merged

ThreeFish-AI merged 14 commits into
feature/1.x.xfrom
ThreeFish-AI/preening-substrate-entropy-reduction

Conversation

@ThreeFish-AI

Copy link
Copy Markdown
Owner

概述

对全仓执行「清减 + 重点分解」级结构性熵减:三路并行取证(backend / Python 卫星域 / 前端域)→ 主线程对高危断言独立复核 → 13 个主题化 commit 逐批验证。完整留痕见 全仓熵减审计 2026-09

总账:135 文件,+8,962 / −12,723(净 −3,761 物理行);其中生产代码净减 2,605 行(口径内 0.92%),测试侧净 +226 行(新增契约/路由/集成测试 529 行 − 死测试清理 303 行)。

⚠️ 行为变更声明(唯一一处)

修复 /interface 三域 reorder 路由被 {id} 参数路由遮蔽的历史缺陷PATCH /interface/{mcp/servers,tools,skills}/reorder 注册序落后于各自 {id: UUID} 路由,字面量 reorder 被当作 UUID 解析返回 422,handler 自注册起不可达——三域拖拽排序持久化此前从未生效(agents 域注册序正确幸免)。修复后由常驻静态遮蔽 lint 防再发(ISSUE-183)。

批次清单

commit 内容
B1 aab8d56 backend 死代码 4 项(prf_expander+PRF 旋钮 / lifecycle_types / get_db / numpy·scipy)
B2 c413d4c perceives skills/ 孤儿包 + benchmark 一次性脚本 + setup.sh 坏 cp + 文档死链
B3 59edc59 cognizes 死入口/死配置 + 陈旧测试树 + sandbox 归位 + Chunker 改名 + cognizes-ui 清减
B4 a6da817 ui 死簇 15 文件(hooks/monitoring/adk guards/组件/conversation/空壳 barrel)
B5 dbb58ad interface 路由测试先行:49 路由契约快照 + 遮蔽 lint + 鉴权 sweep + CRUD 冒烟
B6 d257b66 修 reorder 遮蔽 422(上表行为变更)
B7 c0b7f88 interface/api.py 3,197 行 → 六域路由模块 + 25 行聚合器(bootstrap 零改动)
B8 434b4e4 knowledge-api.ts 3,429 行/211 export → 11 模块目录(符号集编译期锁定,消费方零改动)
B9 52ac45f 后端重复收敛六项(_utcnow×8 / _require_admin×3 / env-falsy / 日志统一 → 单一事实源)
B10 f9b98dc knowledge/service.py 12 个 execute_*_pipeline 骨架抽取(日志键序与 HEAD 12/12 全等)
B11 5c365be 审计文档 + knowledge-map + ISSUE-183/184 + CHANGELOG
B12 21b5790+cba8fc69 三份 BFF 代理合一(1,178→756)+ 契约测试;adk.ts 下线经取证中止

执行纪律(审计文档 §9 摘要)

  • 删除硬门:所有删除标的执行日重 grep(含函数内延迟导入)——7 项探索期「死代码」结论被证伪并保留(rocchio 活路径 / rxjs AGUI 运行时 / cognizes-ui 跨包测试宿主 / adk.ts 系 620 行 SSOT 本体等)
  • alembic 迁移历史文件零触碰;influence「复制+校验」SSOT 与 wiki/agents-chat-core 不在清减口径
  • 已知偏差:两次暂存区交错由后续提交补齐终态(aab8d566→434b4e46、21b5790a→cba8fc69),PR 终态树完整一致

验证矩阵

结果
backend 全量(unit+integration,deselect test_migrations) 3,343 passed;失败集 ⊆ 已知基线 10 集(共享库数据污染型,CI 空库全绿,见 ISSUE-184),零新增
backend ruff check+format 零告警
backend performance_tests 7 passed / 1 skipped(顺修既有 kwarg 漂移)
interface 路由契约 + 全目录 232 passed(拆分前后一致)
perceives 全量 2,131 passed,失败集与基线完全一致
cognizes unittests + 全树收集 225 passed/2 skipped;收集 3 ERROR→0
ui typecheck / vitest / build / lint 全绿(1015 用例,含新增 9 例 BFF 契约)
ui e2e chat-smoke 1 passed(真实浏览器路径)
孪生校验 check_twin_files

eval_tests(需 LLM key)未入本地门。测试基线方法论与已知失败集定义见审计文档 §5。

🤖 Generated with Claude Code

删除双重 grep 验证零引用的死文件:hooks×3(useSessionManager/@deprecated、
useEventProcessor、useUIState)、lib/monitoring、lib/adk/guards.{ts,js}、
components/ui/{ErrorMessage,ToolCallBubble,Page}、conversation/ 整目录、
5 个空壳 feature barrel(connection/debug/hitl/messaging/session);
连带清理 eslint 中 useSessionManager 专属死护栏与 a2ui.md 死链。
dashboard/_lib/api.ts 因存在活消费方(TaskDetailDrawer/useSchedulerData)
按硬门跳过。验证:typecheck + vitest 122 文件 1006 用例 + build 全绿。

🤖 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>
- 删 pyproject 死入口 cognizes.cli:main(cli.py 不存在);修 Dockerfile/compose/README
  三处 agents.api.main 死模块路径为 cognizes.api.main;compose 剔除不存在挂载与死服务
- 删 tests/integration/mind/ 陈旧分叉测试树(硬编码假连接串、不可运行、
  致全量 pytest 收集中断)298 行;addopts 增 --import-mode=importlib 消解
  同名测试 basename 冲突,全树收集 3 ERROR → 0
- sandbox 从 adapters/postgres/ 归位顶层(沙箱与 postgres 无关,对齐 backend 布局),
  git mv 保历史,11 处引用同步
- ChunkingStrategy(ABC) 改名 Chunker,消解与 backend Enum 同名异物
- cognizes-ui 删 8 个零引用模板残骸与死依赖/死 tsconfig;vitest 基建经查为
  跨包测试宿主(CI 生产依赖)予以保留;pnpm-workspace 清除个人绝对路径注释
验证:unittests 225 passed/2 skipped 维持;全树收集零错;ruff/build/tsc/lint 全绿。

🤖 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>
- 删 skills/ 死特性层(5 文件 230 行,src/tests/CI 全域零引用,
  registry 自注册后无任何消费方)
- 删 scripts/benchmark/{parse_pdf_matrix,parse_pdf_bench}.py 一次性
  基准编排器(1049 行,服务 PR #163 数据回填,历史见 git);
  同步清理 docs/reference/perceives 三处文档死链
- 修 scripts/dev/setup.sh 坏 cp(.env.example 不存在时 set -e 必炸
  → 容忍式跳过,双场景实测)
- __init__.py tagline 由"web scraping MCP server"校正为 PDF/网页
  提取管线实际职责
验证:基线-回归完全一致(2131 passed / 4 既有失败 / 69 skipped),
ruff check+format 通过。

🤖 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>
- 删 prf_expander.py + prf_top_k/prf_alpha 配置旋钮(全仓零引用;
  rocchio_reweighter 为 memory_automation 活路径,保留)
- 删 knowledge/lifecycle_types.py(335 行,符号零外部引用且
  SourceKind/QueryIntent 在别处有 Literal 活版)
- 删 db/deps.py get_db(Depends 零使用)及 conftest 配套 patch、
  孤儿测试用例、3 处过时注释
- 删直接依赖 numpy/scipy(零 import;numpy 降级为 spacy 栈传递依赖,
  scipy 物理移除)
验证:ruff 零告警;全量门 3235 passed,失败集 ⊆ 已知基线 10 集,零新增。

🤖 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>
interface/api.py 的 MCP/Skills/Agents/Permissions CRUD 此前零路由测试。
新增两文件为后续机械拆分立行为基线:契约快照+遮蔽 lint(现红 3 例精确
命中遮蔽路由)与鉴权 sweep+CRUD 冒烟+reorder 可达性(三域红=422 实证
reorder 被 {id} 参数路由捕获);配套直绑 AsyncSessionLocal 镜像 patch。

🤖 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>
PATCH /interface/{mcp/servers,tools,skills}/reorder 原注册在各自
{id: UUID} 路由之后,Starlette 首序全匹配把字面量段 "reorder" 当作
{id} 做 UUID 解析 → 422,reorder handler 不可达——三域拖拽排序
持久化自注册即静默损坏(agents 域注册序正确故未受影响)。
修复:三组「路由+schema」区块上移至各自 {id} 路由之前,并加防遮蔽
注释;契约测试快照同步至新注册序(遮蔽 lint 转绿、集成 reorder×4
全部 200)。B5 交付的 3 个暴露测试全部红转绿。

🤖 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>
3,429 行 / 211 export 的 churn 第一热文件 → utils/knowledge-api/
目录 11 模块:errors(183) chunking-config(438) pipelines(235)
corpus(242) model-configs(207) documents(822) search(161) graph(584)
catalog(315) wiki(272) + index.ts 门面(270)。
- index.ts 显式逐名 re-export 全部 211 符号(106 值 + 105 类型),
  编译期锁定外部可见符号集不变;type 形态 re-export 与仓库 barrel 风格一致
- 全仓 24 处导入说明符零改动(文件→目录解析自动命中 index.ts);
  21 处直连不收敛(记录为有意决策)
- 模块间依赖无环;跨域类型一律 import type;原文内容行逐字节保全
注:本文件删除因并行批次的暂存区交错先入 aab8d56,本提交补齐目录
使终态完整(工作树自拆分完成后始终一致,验证均在此树通过)。
验证:符号集 diff 为空、typecheck、vitest 122 文件 1006 用例、
build 97 页、lint 零告警全绿。

🤖 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>
3,197 行 / 49 路由 / 45 内联 schema 的单体 → 六域自持路由文件:
stats_api(144) mcp_api(1077) builtin_tools_api(522) skills_api(906)
agents_api(657) permissions_api(193),api.py 收敛为 25 行聚合器并按
原注册序 include(permissions 通配路由置末位);interface/__init__ 与
bootstrap 聚合点零改动。零使用死副本 _resolve_app_name 随拆分消亡。
- 每文件 logger 名沿用 "negentropy.interface.api"(日志消费方按名过滤)
- ruff 自动修剪各文件未用 import(184 处)+ format
- 三个测试文件模块引用重定向(patch.object 目标随别名互换保持语义)
验证:路由表契约 50 断言全绿(注册序逐项一致);interface 全目录
232 passed 与拆分前一致;全量门 8 failed ⊆ 已知基线 10 集,零新增。

🤖 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>
app/api/{knowledge,interface,memory}/_proxy.ts(639+378+161 行,
注释自称同构参考、能力已漂移)→ app/api/_lib/proxy.ts 参数化核心
(650 行,方法族能力并集 Get/Post/PostFormData/Patch/Put/Delete/
GetBinary)+ 三个薄绑定层(53/30/23),130+ 消费方 import 与
导出名零改动;隐藏消费方(routine/scheduler 通配路由)一并覆盖。
- 行为增强点 8 项逐数论证(memory 增 30s 超时、interface 保守
  保持无默认超时——后端 tools:execute 上限 120s、错误透传族内统一、
  {data} 安全降级扩展、204 短路扩展)
- 新增 bff-proxy-core.test.ts(137 行 9 用例)锁定上述契约
- lib/adk.ts 下线经取证中止:非兼容 re-export 层,系 620 行
  ADK→AG-UI 流归一化 SSOT 本体,维持现状
验证:typecheck + vitest 123 文件 1015 用例(含新增)+ build + lint 全绿。

🤖 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>
app/api/_lib/proxy.ts 参数化核心(650 行)+ 三个薄绑定层,
上提交 21b5790 因暂存路径失误仅含 bff-proxy-core.test.ts,
本提交补齐实现使树完整。内容详见上提交说明。

🤖 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>
- _utcnow ×8(另发现 2 个隐藏跨模块消费者)→ timeutil.utcnow
  零依赖叶子模块,8 处定义逐一验证语义一致后合并
- _require_admin ×3 → auth/deps.require_admin 权威版(逐字符一致
  + Depends 默认值惰性验证)
- _resolve_app_name ×2 → config.resolve_app_name(settings.app_name
  权威源所在域,避免 engine→knowledge 跨域 import)
- _get_knowledge_service ×3 → agents/tools/common.py 共享惰性单例
  (knowledge/_shared._get_service 因构造参数不同按硬约束不合并)
- env-falsy ×5 → config.parse_env_bool;SKILLS_LAYER2 双读统一;
  agent_factory 的 off/strip 逃生开关口径不同,保留原样
- 日志三惯用法 ×8 文件统一 get_logger(__name__);alembic 集成点与
  logging 基础设施自身保留;修正 catalog_dao 测试 patch 因字面量
  logger 名共用而打错发射模块的隐性耦合
验证:ruff 零告警;定向单测 2745 passed;全量门 7 failed ⊆ 已知
基线集,零新增。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
12 个 execute_*_pipeline 方法(ingest_text/url/url_document/file/
import_url_document/import_file/ingest_document/replace_source/
sync_source/sync_document/rebuild_source/translate)共享的 8 步
执行样板(dao 守卫→tracker 构造→resume→started 日志→业务体→
取消分支→失败分支→finally 收尾)收敛为泛型 helper:
body 回调 + started_log 差异字段 + failure_result 兜底 + 可选
on_error 钩子(仅 import_file 的 markdown_extract_status 回写)。
- 行为零变更保真:started/completed 日志键名与顺序脚本比对
  与 HEAD 12/12 全等;sync_document 的 tracker op 历史怪癖保留;
  异常捕获顺序(Cancelled 先于 Exception)不变
- service.py 4099→3928(净 -171);resume/unregister/日志对/
  取消分支 12→1
验证:knowledge 域定向 1143 passed(4 failed 为已知 catalog 污染
基线);全量门 7 failed ⊆ 已知基线集,零新增;ruff 零告警。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
- 新增 codebase-entropy-reduction-2026-09.md:B1-B12 批次清单与验证
  证据、执行期勘误表(7 项探索结论被证伪)、reorder 行为变更声明、
  后端共享测试库基线方法论、跨模块重复决策记录与 backlog 全登记
- knowledge-map 同步「工程经验沉淀」条目
- ISSUE-183(字面量路由遮蔽)与 ISSUE-184(test_migrations 砸坏
  共享测试库的破窗根因链)沉淀
- CHANGELOG Unreleased 增熵减批次 Fixed/Changed/Removed/Added 组
- 顺带修复 performance_tests 的 get_subtree 既有 kwarg 签名漂移
  (性能套件归零:7 passed / 1 skipped)

🤖 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>
… Audit 归零;

新披露的路径遍历漏洞(load_checkpoint_in_model/load_checkpoint_and_dispatch
的 weight map 路径遍历,影响 ≤1.14.0,1.15.0 修复)使 perceives CI 的
pip-audit 作业新命中一项未登记漏洞。本仓对该 API 零调用(accelerate 系
docling-ibm-models 传递依赖,模型均自官方源加载,无可信边界外 checkpoint),
可达性低;上游已有修复版,按 0f68672 先例走真升级而非 ignore 登记。
验证:uv 解析 313 包零冲突;perceives 全量回归 2131 passed /
4 failed(与基线完全一致,同 4 个既有失败);本地 pip-audit 复核
CVE-2026-69112 消失,仅剩 ignore 清单既有登记项。

🤖 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 merged commit 8e7c59e into feature/1.x.x Sep 10, 2026
29 checks passed
@ThreeFish-AI
ThreeFish-AI deleted the ThreeFish-AI/preening-substrate-entropy-reduction branch September 10, 2026 07:41
ThreeFish-AI added a commit that referenced this pull request Sep 14, 2026
…扫描分支错位 (#1143)

* build(deps): next 升至 16.3.5 核销 4 条 critical 告警,js-yaml 地板抬至 4.3.2 并补闭区间;

ui / wiki 的 next 停在 16.2.12,命中两条未认证 RCE:GHSA-p293-qw3h-jr36
(CVSS 9.0,Windows 宿主)与 GHSA-2xp9-vwfh-vxw4(Image Optimization API 的
AVIF 路径)。16.2 线无回溯补丁,升 16.3.x 是唯一路径;目标取 16.3.5 而非最低
修复版 16.3.3——16.3.3 是以停用 AVIF 图像优化换来的修复,16.3.4 才把 AVIF
正确恢复,停在 16.3.3 等于用功能退化换安全。

同时把根 workspace 的 js-yaml 地板由 >=4.2.0 抬至 >=4.3.2(GHSA-2883-xcg3-v3hh,
空 merge 源致 CPU 耗尽;根 lock 原解到 4.2.0,落在受影响区间但尚未被 Dependabot
标出)。地板须写闭区间:首次只写 >=4.3.2 时 pnpm 当场解到 5.4.2,而消费方
@eslint/eslintrc 声明的是 ^4.1.0——同 @babel/core / undici 的既有处置补齐 <5.0.0。

随附两处升级暴露的门禁回归(均非本仓代码缺陷):
- @next/eslint-plugin-next 16.3.x 新增 no-location-assign-relative-destination
  规则,命中 AuthProvider 的 login / logout。二者都是必须的整页跳转——
  /api/auth/login 是 302 到外部 IdP 的 Route Handler,router.push() 无法承接
  跨源跳转;登出须整页重载以丢弃客户端状态。故加带理由的定向豁免,不改认证行为。
- 16.3 的 next build 扩大了构建期类型检查范围,暴露 WikiToc.test.tsx 一条已失效
  的 @ts-expect-error(TS2578)。该错误在基线上跑裸 tsc 同样报,属被暴露的存量债。

验证:ui lint / typecheck / typecheck:test / test(123 文件 1015 用例)/ build /
test:e2e(70 passed 1 skipped)全绿;wiki lint / test(14 文件 122 用例)/ build 全绿。

🤖 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>

* build(deps): 11 个视频工程 js-yaml 地板抬至 4.3.2,核销 9 条 high 告警;

GHSA-2883-xcg3-v3hh(CVSS 7.5):js-yaml < 4.3.2 的 maxTotalMergeKeys 对空
merge 源不限流,致 CPU 耗尽。各 Remotion 视频工程经 cosmiconfig@8.3.6 传递
引入 4.3.1,直接依赖零位移,故只落在 override 层,package.json 一行不动。

video/pnpm-workspace.yaml 属 skeleton.toml 的 frozen 档(逐字节相同),11 份
追加内容完全一致,verify_skeleton.py --strict 保持「未登记漂移 0 处」。模板
与 10 个已发布集同步升级:模板不升会让日后 scaffold 出的新集从第一天起就带着
旧漏洞,且 Dependabot 尚未扫到的两集(context-layer / horizon-context)也一并
消因,避免 master 同步后再冒出两条新告警。

重锁经 pnpm install --lockfile-only 逐工程执行,每次之后比对仓库根
pnpm-lock.yaml 的 md5,全程零变更(ISSUE-175 第 ④ 坑:嵌套安装会静默覆写根
lockfile 并丢失全部 overrides)。模板目录只有 package.json.tmpl 没有
package.json,pnpm 会以「Scope: all 0 workspace projects」静默空跑,须临时渲染
出 package.json 重锁后再删除。

🤖 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>

* docs(issue): ISSUE-092 追加 2026-09-14 轮次,记录 Dependabot 扫描分支错位这一前提;

本轮 19 条 open 告警里有 6 条在 feature/1.x.x 上早已不存在(cognizes 双项目
随 #1132 整体删除、accelerate 随 #1131 升到 1.15.0 超出受影响区间),仍挂 open
只因 Dependabot 只扫默认分支 master,而 master 停在 2026-09-06、落后 15 个提交。
这条前提此前从未被记录,会让接手者对着已修好的东西反复「修」。

一并留档:13 条真实受影响告警的消除路径与版本取舍依据;这 6 条刻意不 dismiss
的理由(dismiss 的适用面是「不能修」,不是「已修但未发布」);安全地板 override
须写闭区间的教训;以及区分「升级引入」与「升级暴露」的取证方法——用
git worktree add --detach 出基线树分别跑 tsc 与 build 对照。

🤖 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