Skip to content

feat(wiki-kg): Wiki 站点按 Publication 切片发布与浏览知识图谱 - #558

Merged
ThreeFish-AI merged 5 commits into
feature/1.x.xfrom
ThreeFish-AI/wiki-static-knowledge-graph
May 17, 2026
Merged

feat(wiki-kg): Wiki 站点按 Publication 切片发布与浏览知识图谱#558
ThreeFish-AI merged 5 commits into
feature/1.x.xfrom
ThreeFish-AI/wiki-static-knowledge-graph

Conversation

@ThreeFish-AI

@ThreeFish-AI ThreeFish-AI commented May 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

背景

  • 本次变更要解决的问题：当前 Legendgen Wiki 站点（apps/negentropy-wiki，Next.js SSG + ISR）只发布文档 Markdown，没有任何知识图谱视图；用户希望在 Wiki 浏览文档时能在一处汇总查看这些文档涉及的实体与关系。同时必须满足两个硬约束：① Wiki 站点保持无状态（不引入数据库 / 缓存层 / 文件持久化）；② 保持静态部署（SSG + ISR，不引入 SSR/独立后端）。
  • 关联上下文：docs/wiki-knowledge-graph.md · docs/negentropy-wiki-ops.md · 后端既有 knowledge/routes/graph.py（单 corpus 维度） + knowledge/routes/wiki.py（Publication 生命周期）。

核心变更

设计取向（一句话）：沿用现有 Markdown 发布数据流 —— Wiki SSG 通过 HTTP 从后端拉取按 Publication 切片的图谱 JSON，与拉取 Markdown 完全同构。所有切片在后端单一 SQL 反查中完成（单一事实源），Wiki 端零持久化。

  • 后端 API（apps/negentropy/）

    • 新增 knowledge/lifecycle/wiki_graph_service.py：切片查询服务，正交分解于发布生命周期。反查链路：wiki_publication_entries → kg_entity_mentions → kg_entities；剔除悬挂边、支持按 importance_score 截断
    • 新增 knowledge/routes/wiki_graph.py：4 个 endpoint（/wiki/publications/{id}/graph[/entities[/{eid}]] + /wiki/entries/{eid}/graph），仅 status='published' 暴露，响应携带 ETag={pub_id}:{version} + max-age=300
    • 新增 schemas.py 中 WikiGraphNode/Edge/Response 等 6 个 Pydantic 模型；节点附 entry_slugs[] + mention_count_in_pub 用于点击跳转
    • knowledge/api.py 追加 router 注册

  • Wiki 站点（apps/negentropy-wiki/）

    • 新增路由 src/app/[pubSlug]/graph/page.tsx：SSR generateStaticParams + 服务端 fetch 注入到 client component；按 status 分支 ok / no_kg / empty / error 四态降级
    • 新增 src/components/WikiGraphCanvas.tsx（Sigma WebGL，≤ 500 节点）：复用主站 apps/negentropy-ui 的 buildGraph / nodeSize / nodeColor / ForceAtlas2 策略并精简为只读浏览
    • 新增 src/components/WikiForceGraphCanvas.tsx（react-force-graph-2d Canvas 2D，> 500 节点）：自动降级渲染器；交互模型与 Sigma 版本一致（节点点击 → router.push(entry_slugs[0])）
    • 修改 wiki-api.ts：追加 getPublicationGraph / getPublicationEntities / getPublicationEntityDetail / getEntryGraph；fetch<T> 支持 ISR tags 透传
    • 修改 WikiHeader.tsx：tabs 末尾追加"知识图谱"入口（仅 entries_count > 0 时显示）；同步传 graphTab 到 [pubSlug]/page.tsx 与 [pubSlug]/[...entrySlug]/page.tsx
    • 修改 api/revalidate/route.ts：追加 /${pubSlug}/graph 路径与 wiki-graph:${pubSlug} tag 的 revalidatePath/Tag（webhook 在 Wiki 端的接收侧处理；未触及后端 lifecycle/revalidate.py 的 payload schema，功能上等价）
    • 新增 styles/components/graph.css：解决容器高度坍缩 + Sigma WebGL canvas 像素尺寸不跟随的 CSS 问题（实机联调发现）
    • 新增依赖：sigma / graphology / graphology-layout-forceatlas2 / react-force-graph-2d（与主站 apps/negentropy-ui 版本对齐）

  • 文档与索引：新增 docs/wiki-knowledge-graph.md（设计文档 + Mermaid 时序图 + API 契约 + 大图降级策略 + 风险缓解）；更新 docs/negentropy-wiki-ops.md 路由表 + docs/agents/knowledge-map.md 索引

风险与回滚

  • 主要风险：
    1. 大 publication（>1000 实体）SQL 反查慢 → 后端已有 ix_kg_mentions_document 索引 + 硬上限 1000 节点 + 按 importance_score DESC 截断
    2. Sigma WebGL 在低端设备渲染慢 → 节点 > 500 自动降级 ForceGraph2D（Canvas 2D），且组件均通过 "use client" 自动切分进 graph 路由独立 chunk
    3. 跨 corpus publication 同名实体未合并 → 阶段一文档明确"按 corpus 切片"，节点 metadata.corpus_id 着色区分；阶段二可走 canonical 合并
  • 回滚方式：所有改动均为追加（不修改既有 endpoint / 路由 / 组件签名）；如需回滚，删除 wiki_graph_service.py / routes/wiki_graph.py / [pubSlug]/graph/ 即可，现有 Markdown 发布流水线不受影响

验证证据

  • 单元测试：apps/negentropy-wiki/tests/lib/wiki-api-graph.test.ts 7 个 vitest 用例覆盖查询参数序列化、ISR tag 透传、错误透传，全部通过
  • 集成测试：apps/negentropy/tests/integration_tests/knowledge/test_wiki_graph_service.py 10 个用例覆盖空 publication / 切片正确性 / 悬挂边过滤 / max_nodes 截断 / 实体详情邻居范围 / 单 entry 局部图，全部通过
  • E2E/Workflow：本工作树后端（3492）+ Wiki dev（3192）端到端联调，通过 chrome_devtools 实机验证：
    • ✅ Sigma WebGL 渲染 13 节点 17 边按社区配色（.context/wiki-graph-render-4.png）
    • ✅ max_nodes=5 截断时显示橙色横幅"已按 importance 截断（共 13 个实体，仅显示 top-5）"，悬挂边自动剔除（17→4）（.context/wiki-graph-truncated.png）
    • ✅ 大图降级：562 节点 800 边自动切到 ForceGraph2D，徽章显示 "562 节点 · 800 边 · ForceGraph 2D"，Canvas 2D 渲染无卡顿（.context/wiki-graph-forcegraph2d.png）
    • ✅ 节点点击 → router.push(/wiki/{entry_slug}) 跳转到对应文档详情页
    • ✅ 后端 publish 触发 webhook → Wiki dev 收到 POST /api/revalidate 200 → 页面 版本 vN 同步刷新（v2→v3→v4）
    • ✅ 未构建 KG 时 status='empty'，前端显示友好空态
  • 关键截图：.context/wiki-graph-render-4.png（完整图谱）/ .context/wiki-graph-truncated.png（截断横幅）/ .context/wiki-graph-forcegraph2d.png（ForceGraph2D 降级）

影响范围

  • 前端：apps/negentropy-wiki/ 新增 1 个路由 + 2 个客户端组件（Sigma + ForceGraph2D）+ 1 个类型文件 + 1 个 CSS；wiki-api.ts / WikiHeader.tsx / revalidate route.ts 追加方法，不修改既有签名
  • 后端：apps/negentropy/ 新增 1 个 service + 1 个 routes 文件 + 6 个 Pydantic schema；knowledge/api.py 追加 router 注册
  • GitHub Actions / 文档：无 CI 改动；新增 docs/wiki-knowledge-graph.md 设计文档，更新 docs/negentropy-wiki-ops.md 路由表与 docs/agents/knowledge-map.md 索引

Next Best Action

  • 合并前：① 在 staging 环境对一个真实有 KG 的 publication 跑端到端验证；② 触发一次 publish 确认 webhook 在生产配置下正常 dispatched
  • 合并后：① 阶段二可走 kg_entity_canonical 合并跨 corpus 同名实体；② 后续可新增"实体面板/搜索"侧边栏复用现有 getPublicationEntities 端点；③ 用户文档 docs/user-guide 补充"如何在 Wiki 查看知识图谱"

@ThreeFish-AI
feat(wiki-kg-api): 新增按 Publication 切片的知识图谱查询服务与 API
05bb8b4 
通过 wiki_publication_entries → kg_entity_mentions → kg_entities 反查链路，
在后端 SQL 中完成按 Wiki Publication 维度切片，剔除悬挂边并支持按
importance_score 截断，让 Wiki SSG 站点能通过同构 HTTP 拉取该 Publication
覆盖的实体/关系子图，无需引入额外持久化或部署形态。

- schemas.py: 新增 WikiGraphNode/Edge/Response 等 6 个 Pydantic 模型；
  节点额外携带 entry_slugs 与 mention_count_in_pub 支撑前端点击跳转。
- lifecycle/wiki_graph_service.py: 切片查询服务（正交分解，与 wiki_service
  发布生命周期解耦），覆盖整图 / 实体列表 / 实体详情 / 单 entry 局部图。
- routes/wiki_graph.py: 4 个 endpoint 暴露给 /knowledge/wiki/* 前缀，仅
  status='published' 暴露；响应携带 ETag={pub_id}:{version} 与 max-age=300。
- knowledge/api.py: 注册新 router。
- tests/integration_tests/.../test_wiki_graph_service.py: 10 个集成用例覆盖
  空 publication / 切片正确性 / 悬挂边过滤 / max_nodes 截断 / 实体详情邻
  居范围 / 单 entry 局部图等核心不变量。

🤖 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
feat(wiki-kg-ui): 新增按 Publication 切片的知识图谱页面与 Sigma 可视化
b042c81 
在 Wiki SSG 站点新增 /[pubSlug]/graph 路由，让用户浏览文档时可在同一
Publication 内汇总查看其涉及的实体/关系。严格保持 Wiki 无状态 + 静态
部署约束：数据通过运行时 fetch 拉取（同现有 Markdown），SSG + ISR
5min + webhook 主动 revalidate；Sigma WebGL 由 "use client" 组件自动
切分进路由 chunk，非图谱页面零体积影响。

- src/lib/wiki-graph-types.ts: 与文档类型解耦的图谱类型声明（正交分解）。
- src/lib/wiki-api.ts: 追加 4 个 graph 方法，不修改既有签名；fetch<T>
  支持 ISR tag 透传（'wiki-graph:${pubSlug}'）。
- src/app/[pubSlug]/graph/page.tsx: SSR 入口，按 status 分支处理 ok /
  no_kg / empty / error 四态，全部友好降级。
- src/components/WikiGraphCanvas.tsx: 'use client' Sigma WebGL 渲染器，
  复用主站 ForceAtlas2/buildGraph 策略，剥离增量加载/双击展开，节点
  点击 → router.push 到 entry_slugs[0]，>500 节点显示截断横幅。
- src/components/WikiHeader.tsx: tabs 末尾追加"知识图谱"入口（仅
  entries_count > 0 时显示），与现有 active 反查复用 resolveSectionView。
- src/app/api/revalidate/route.ts: 追加 /${pubSlug}/graph 路径与
  'wiki-graph:${pubSlug}' tag 的 revalidate。
- src/app/[pubSlug]/{page,[...entrySlug]/page}.tsx: 同步传 graphTab。
- package.json + pnpm-lock.yaml: 新增 sigma/graphology/forceatlas2
  依赖（与主站版本对齐）。
- tests/lib/wiki-api-graph.test.ts: 7 个 vitest 用例覆盖查询参数序列化、
  ISR tag 透传与错误透传。

🤖 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
docs(wiki-kg): 新增 Wiki 知识图谱设计文档并更新运维与索引
7ce9dfe 
- docs/wiki-knowledge-graph.md: 新增设计文档，覆盖数据流（含 Mermaid 时序
  图）、按 Publication 维度切片算法、API 契约、复用策略、性能与降级、
  验证方案与风险缓解。
- docs/negentropy-wiki-ops.md: 路由表追加 /:pubSlug/graph 条目并指向设
  计文档。
- docs/agents/knowledge-map.md: 在"系统能力概览"挂载新文档跳转链接。

🤖 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
fix(wiki-kg-ui): 修复 Sigma WebGL 容器不撑高 + canvas 像素尺寸未跟随
769e0da 
实机联调发现两处导致图谱页空白：
1. `WikiGraphCanvas` 根容器原使用 Tailwind 风格 `h-full w-full` 但本工程未启用
   Tailwind，类名不生效 → 内层 div 高度坍缩为 0，Sigma canvas 默认 300×150；
2. Sigma 在 dynamic import 异步落地时容器可能为 0 尺寸，且 Sigma 不自动监听
   resize；容器后续撑开后 WebGL canvas 像素尺寸未更新。

修复：
- 新增 `styles/components/graph.css`，给 `.wiki-graph-canvas-wrap` 计算 viewport
  剩余高度（`calc(100vh - 200px)` + `min-height: 480px`），覆盖空态/错误/加载
  三种降级 UI 样式；新增 `.wiki-graph-canvas-root/stage/overlay/badge[-warn]`
  替换原 Tailwind 类名。
- `WikiGraphCanvas` 改用语义化 className，新增 `ResizeObserver` + Sigma
  `resize()/refresh()` 双调用，并在初始化末尾同步 `resize()` 一次，保证容器
  从 0×0 撑开时 WebGL 像素尺寸跟随更新（与主站 SigmaGraphCanvas 同策略）。

浏览器实机验证（mcp__chrome_devtools__*）：
- 13 节点 17 边按社区配色渲染，节点 label 可读，可拖拽缩放；
- `max_nodes=5` 截断时显示橙色横幅"已按 importance 截断（共 13 个实体，仅
  显示 top-5）"，并自动剔除悬挂边；
- Sigma `clickNode` 触发 router.push 跳转到 entry_slugs[0] 对应文档详情页；
- 后端 publish 时 webhook → `/api/revalidate` 200 → 页面 `版本 vN` 同步刷新
  （v2 → v3 → v4），ISR + revalidatePath 链路闭环。

🤖 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
fix(wiki-kg-api): 统一 total/total_entities 与候选实体查询的过滤口径;
d3a2160 
- get_publication_entities：total 走与 items_stmt 相同的 JOIN KgEntity + is_active=True
  路径，避免存在已下线实体时 total 偏大、前端分页出现「最后一页空」或页码错位；
- _load_candidate_node_ids：count_stmt 复用 is_active 与 min_importance 过滤条件，避免
  truncated 横幅「共 X 个实体，仅显示 top-N」把失活/低权重实体计入分母而误导用户；
- 新增 3 条集成回归用例覆盖：失活实体不计入 total_entities、min_importance 应用于
  total_entities、get_publication_entities 的 total 排除失活实体。

🤖 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 52c78db into feature/1.x.x May 17, 2026
7 checks passed
ThreeFish-AI added a commit that referenced this pull request May 17, 2026
@ThreeFish-AI
chore(merge): 合并 origin/feature/1.x.x（解决与 wiki-kg #558 的 3 处冲突）;
bd02de1 
合并 base 上的 commit 52c78db "feat(wiki-kg): Wiki 站点按 Publication 切片
发布与浏览知识图谱 (#558)" 到 ThreeFish-AI/wiki-agents-widget，解锁 PR #557
的 mergeable 状态。

冲突解决:
- apps/negentropy-wiki/package.json：保留双方 deps（base 的 graphology/sigma
  + 我们的 @ag-ui/* / @negentropy/agents-chat-core / rxjs / zod / @types/mdast）
- apps/negentropy-wiki/src/styles/index.css：保留双方 @import
  （base 的 components/graph.css + 我们的 components/agent-chat.css）
- apps/negentropy-wiki/pnpm-lock.yaml：保留删除（PR-1 已将子级 lockfile
  上提到根级 pnpm-lock.yaml，sigma / graphology 已记录其中）

合并后验证:
- pnpm install --no-frozen-lockfile：根 lockfile 已包含 sigma/graphology
- pnpm --filter negentropy-ui test：92 文件 / 722 用例通过
- pnpm --filter negentropy-wiki test：8 文件 / 73 用例通过（base 新增的
  wiki-api-graph 单测自动纳入）
- pnpm --filter @negentropy/agents-chat-core test：2 文件 / 15 用例通过

PR #557 期望 mergeable 状态：MERGEABLE。

🤖 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>
This was referenced May 17, 2026
Merged
Merged
Merged
Merged
Merged
ThreeFish-AI added a commit that referenced this pull request Sep 6, 2026
@ThreeFish-AI
fix(security): 核销 104 条 Dependabot 告警——五处依赖升级 + perceives 锁定根因纠偏 (#1126)
cbbb501 
* build(deps): travel-agent-ui 升级 next 16.2.12 并补齐 workspace 隔离声明，修复 9 项 alert;

- next / eslint-config-next 16.2.6 → 16.2.12，核销 Dependabot #574-582：
  SSRF（GHSA-89xv-2m56-2m9x / GHSA-p9j2-gv94-2wf4）、中间件绕过（GHSA-6gpp-xcg3-4w24）、
  Server Actions DoS（GHSA-m99w-x7hq-7vfj）等 9 条；修复门槛为 16.2.11，取 16.2 线
  最新补丁 16.2.12 以多带一版累积修复，不跨 minor 避免无关框架行为变更
- 补齐 `packages: []` 的 pnpm-workspace.yaml——本工程已从根 workspace 解耦但缺失隔离
  声明，是 ISSUE-175 所列同款入口中全仓最后一个敞口。本次恰好改动其 manifest，正是
  事故链第一环（改嵌套 manifest → 顺手 install → 根 lockfile 静默被覆写），故一并钉死
- 本工程无 lockfile、不被任何 workflow 构建，改 manifest 即生效：本批未执行任何
  pnpm install/add/update，根 pnpm-lock.yaml sha1 校验前后一致（06e898b1，13098 行）

🤖 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): 根 workspace 三 importer 升级 next 16.2.12 + faker 10，修复 28 项 alert;

- next / eslint-config-next 16.2.6 → 16.2.12（negentropy-ui / negentropy-wiki /
  cognizes-ui）：核销 #583-591 / #592-600 / #565-573 共 27 条，覆盖 SSRF、中间件绕过、
  Server Actions DoS、缓存混淆、Image Optimization DoS 等；修复门槛 16.2.11，取 16.2 线
  最新补丁多带一版累积修复
- @faker-js/faker ^9.0.0 → ^10.5.0（实解 10.6.0），核销 #687（GHSA-qxc2-j82w-r537，
  helpers.fake 可被利用为任意代码执行，<=10.4.0 全线受影响故 9.9.0 亦在范围内）。
  跨大版本但唯一调用点 tests/ui/helpers/factory.ts 仅用 string.uuid / person.fullName /
  helpers.arrayElement / date.* / number.int / lorem.*，与 v10 移除清单零交集
- lockfile 完整性核对（ISSUE-175 教训）：overrides 块 17 条全在、importers 5 个不变、
  next 两条 @babel/core peer 变体链（7.29.7 / 8.0.1）均保留、`@babel/core` override
  上界 `>=7.29.6 <8.0.0` 未放宽；净减 70 行系 @babel/core 获得 (supports-color) peer
  后缀导致的键合并，非依赖丢失；`pnpm install --frozen-lockfile` 通过

验证：cognizes-ui lint 0 error + tsc --noEmit 通过 + test:coverage 28 passed（含
faker 三个消费测试）+ build 通过；negentropy-ui lint（--max-warnings=0）+ typecheck +
build 通过；negentropy-wiki lint 0 error + build（含 pagefind 索引）通过。

🤖 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): cognizes 九包定向升级消 47 项 alert，新增四条传递依赖地板;

- 直接依赖抬地板：pypdf 6.13.3→6.17.0（10 条 DoS/无限循环/内存耗尽）、
  pillow 12.2.0→12.3.0（13 条堆越界写/解压炸弹/命令注入）
- gpu 组抬地板：transformers 5.8.1→5.16.1（CVE-2026-9856 save_pretrained 路径穿越）、
  torch 2.12.0→2.14.0（CVE-2025-3000 torch.jit.script 内存破坏）。无上界阻断：
  sentence-transformers 5.5.0 仅要求 transformers<6.0.0 且不约束 torch
- constraint 抬升 cryptography 49.0.0→50.0.1（GHSA-g6cj-pr64-35w5 Bleichenbacher oracle）
- constraint 新增四条传递依赖地板：gitpython 3.1.50→3.1.61（18 条 git option/配置注入
  RCE 与任意文件读写；travel-agent-demo → streamlit 传递，本仓零 `import git`）、
  pyasn1 0.6.3→0.6.4（3 条 BER/CER/DER 解码器 DoS）、httplib2 0.31.2→0.32.0
  （解压炸弹 DoS）、setuptools 81.0.0→84.0.0（CVE-2026-59890 MANIFEST.in 绕过）
- 定向升级（--upgrade-package ×9）而非全量 --upgrade：lock 仅动 435 行且 docs 组
  零位移（mkdocs/pymdown 变更 0 行），保持可 review 与可归因

验证：ruff check/format 通过（207 文件）；pytest tests/unittests/ 225 passed 2 skipped、
覆盖率 30.98% 过 20% 门；uv build + import cognizes 通过；六包运行时版本实测达标。
integration 套件 13 failed/110 passed —— 已用 git stash 在同一环境对拍确认与本次改动
无关（干净树同为 13 failed/110 passed，根因是 TracingManager.span 属性缺失与
tests/integration/mind 下 test_e2e.py 同名 basename 收集冲突，均为既存问题）。

已知验证边界：transformers/torch 的一手调用在 engine/perception/reranker.py，该模块
无单测。已尽力覆盖到 API 契约层——模块本身导入通过，且逐项验证 rerank() 实际调用的
AutoTokenizer/AutoModelForSequenceClassification.from_pretrained、tokenizer 四个 kwargs
(padding/truncation/max_length/return_tensors)、SequenceClassifierOutput.logits 路径与
torch.no_grad/sigmoid 在 5.16.1 下均存在；未验证真实模型推理（需下载 bge-reranker-base）。

🤖 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): 删除 cognizes 死配置 docs 依赖组，从根消除 3 项 alert;

- 移除 [dependency-groups] docs（mkdocs / mkdocs-material / mkdocstrings），核销
  #692（mkdocs-material DOM XSS）与 #618/#663（pymdown-extensions 路径穿越 + ReDoS）
- 判定为死配置的三项证据：① 全仓零 mkdocs.yml；② CI 从不安装该组
  （setup-python-uv 仅 `uv sync --group dev`），亦无任何 workflow/脚本引用；
  ③ src/ + tests/ + scripts/ 零 mkdocs 引用。项目文档站实为 negentropy-wiki（Docusaurus）
- 相较升版本，删组从根消除这两个包及其 12 个传递依赖，同类告警不再复发
- lock 为纯删除（-215 行、0 插入），移除项全部属 mkdocs 依赖闭包，无其它包位移

验证：uv sync --frozen --group dev 通过；import cognizes 通过；
pytest tests/unittests/ 225 passed 2 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>

* build(deps): negentropy 四包定向升级消 8 项 alert，补 setuptools 传递依赖地板;

- override 抬升 aiohttp 3.14.1→3.14.3：新增修复 GHSA-cq5v-8q36-5273（C 响应解析器
  堆越界读）与 GHSA-mfx4-hv73-q22v / GHSA-mq44-7p77-q5h7（WebSocket 请求走私/未协商
  压缩帧），核销 #641/#643/#645。override 机制不变：microsandbox==0.1.8 锁死 <3.11.0
  仍需强制覆盖，只抬地板版本
- constraint 抬升 cryptography 49.0.0→50.0.1：GHSA-g6cj-pr64-35w5（PKCS#7
  EnvelopedData 解密暴露 Bleichenbacher oracle，high），核销 #648。全仓零一手 import
  （authlib/google-auth/joserfc/presidio/pyjwt/pyopenssl 传递），且 perceives 已在
  50.0.1 上验证过同构依赖者集合
- constraint 抬升 pyasn1 0.6.3→0.6.4：BER/CER/DER 解码器 3 条 DoS
  （GHSA-m4p7-r5rc-7g4j / GHSA-hm4w-wwcw-mr6r / GHSA-8ppf-4f7h-5ppj），核销 #559/#560/#626
- constraint 新增 setuptools>=83.0.0（82.0.1→84.0.0）：CVE-2026-59890（MANIFEST.in
  排除规则被 Unicode 归一化绕过），核销 #558。此前无任何声明，经 spacy/thinc 传递
- 定向升级：lock 仅动 6 行；pyopenssl 26.3.0→26.4.0 随 cryptography 联动

验证：alembic 单 head（0099）；pytest tests/unit_tests/ 2941 passed、覆盖率 57.04%
过 50% 门；四包 import smoke 版本达标。integration 套件本地 116 failed/115 passed/
90 errors——已对拍干净树基线逐项一致（共享 negentropy_test 累积脏数据所致的既存
环境问题，见记忆 test-db-accumulates；CI 每次起新容器不受影响），与本次改动无关。

🤖 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): negentropy mcp 1.26.0→1.29.1，修复 3 项 http-transport alert;

- mcp 地板 >=1.6.0 → >=1.28.1,<2.0.0：核销 #501/#503/#505（CVE-2026-52869/52870/
  59950，MCP SDK http-transport 攻击面）。上界 <2.0.0：2.x 拆出 mcp-types/truststore
  属未验证 major 迁移（uv 默认解 2.1.1，已退回 1.x 线）；alert 门槛 1.28.1，perceives
  实跑 1.28.1，本批实解 1.29.1（1.x 线最新）。idna 3.16→3.19 随 mcp 子树联动
- 一手调用面 3 处（interface/mcp_client.py 三种传输、knowledge/mcp_server.py 的
  FastMCP/StreamableHTTPSessionManager/TransportSecuritySettings、engine/sandbox/mcp.py），
  依赖要求逐条核对全部满足，与 aiohttp 完全解耦（mcp 走 httpx）

三层验证（对齐 ISSUE-092 的 CVE-2026-4372 验收范式）：
① 符号 + 真实构造——stdio 私有 API 7 符号（mcp_client.py 8 处引用）全在；
FastMCP 四 kwargs（stateless_http/json_response/streamable_http_path/transport_security）
真实构造出 Starlette app；get_kb_mcp() 与 sandbox 构造路径不 mock 直接过
② 定向单测 22 用例（test_mcp_client 5 + test_mcp_client_resources 4 +
test_kb_mcp_server 13）全过；全量单测 2941 passed、覆盖率 57.04% 过门（与升级前逐项一致）
③ 真实 MCP 往返（合入前置）——httpx.ASGITransport 直打 create_kb_mcp_asgi_app()：
tools/list 返回 200 且含 kb_search 工具清单；错误 bearer 401 拒绝。覆盖单测完全
mock 掉的 StreamableHTTPSessionManager.run() + stateless 路径（1.28+ 改动最多处）

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

* fix(perceives): 纠偏 transformers/torch/setuptools 锁定根因，裁剪 6 条失效 ignore 并升级 datasets;

- transformers 锁定根因纠偏（pyproject [tool.uv] 注释）：旧述「marker-pdf 1.10.2 /
  surya-ocr 0.17.1 在 5.x 崩（transformers.onnx）」已不成立——marker-pdf 2.0.0 /
  surya-ocr 0.22.1 均已适配 transformers>=5.12.1。真实阻断是二者同时要求 pillow<11，
  与本项目 pillow>=12.3.0（修 8 条图像解析 CVE）直接冲突；perceives 直接解析不可信
  PDF/图片故 Pillow 攻击面可达，而 transformers 零直接 import、仅加载第一方 artifact
  故不可达——升级属负收益交换。mineru 3.0.9 的 transformers<5.0.0 仅 vlm/pipeline
  extra 生效，不构成约束
- 解锁条件迁移：从「等 marker/surya 适配 transformers 5.x」改为「等二者放开
  pillow<11 上界」——跟踪对象不同，否则后来者会困惑「已适配为何仍锁」
- torch CVE-2025-3000 纠偏：upstream fix 2.13.0 已发布（原注释「暂无 fix」过时），
  改述为「有 fix 但受 marker/surya/docling-ibm-models/torchvision 四方联动约束」
- setuptools pin 注释纠偏：原述「undetected-chromedriver 依赖 pkg_resources」已证伪
  ——实测 82.0.1 与 83.0.0 皆无 pkg_resources（上游早于 82 移除，复核 ISSUE-092
  隔离结论）。维持 82.0.1：不为不可达 build-time 低危变更 build 后端版本
- 裁剪 6 条失效 ignore：fastmcp（CVE-2025-64340/CVE-2026-27124）与 litellm
  （CVE-2026-35029/35030、GHSA-69x8-hrgq-fjj8、CVE-2026-42271）注释停留在 3.1.1/1.80.0，
  实锁已 3.2.4/1.85.0。实跑 pip-audit 确认两包零命中后删除，非凭版本号推断
- datasets 4.8.5→5.0.1：本次裁剪后暴露的新 advisory CVE-2026-66007（PYSEC-2026-3716，
  folder-based dataset builder 路径穿越任意文件读）。mlx-vlm 仅要求 >=2.19.1 无上界，
  故直接升级而非新增 ignore 债

验证：ignore 数组经 bash -n 语法校验（56 条）；以 CI 原样命令复跑 pip-audit
退出 0——「No known vulnerabilities found, 10 ignored」；CI 参数复跑测试
（-n auto -m "not slow"）2130 passed，docling/mineru/marker 三引擎 worker 均真实
启动；mlx-vlm 在 datasets 5.0.1 下 import 通过。3 个 test_config 失败已对拍干净树
基线一致（本地 .env 使 concurrent_requests=32≠默认 16，CI 无该文件），与本次无关。

🤖 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 增补 perceives 4 条 dismiss 依据与 transformers 解锁条件迁移;

- 记录 104 条 alert 人工核销的收口：100 条经升级消除，perceives 4 条走 dismiss
- transformers 锁定根因纠偏：marker-pdf 2.0.0 / surya-ocr 0.22.1 已适配
  transformers>=5.12.1（旧「transformers.onnx 崩溃」不再成立），真实阻断是二者
  要求 pillow<11 与本项目 pillow>=12.3.0 冲突；附攻击面可达性对比论证
  （Pillow 可达 vs transformers 不可达）说明升级为负收益交换
- 解锁条件从「等适配 transformers 5.x」迁移为「等放开 pillow<11 上界」，
  避免后来者按旧条件追踪而困惑
- torch CVE-2025-3000 状态迁移留档：upstream fix 2.13.0 已发布，原「暂无 fix」
  记录作废；此例印证本 Issue 既有防范条款「四元注释便于季度 review 识别可移除项」
- 记录本次 ignore 清单 review 结果（62→56 条）与 datasets 升级替代新增 ignore 的处理
- 沉淀三条方法论：「上游已适配≠可升级」须核对全部约束维度、安全债决策应比较
  攻击面可达性而非 CVSS 分数、ignore 注释的「阻断原因」腐化快于 CVE 本身

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

* fix(travel-agent-ui): 补 allowBuilds 修复隔离 workspace 下 pnpm install 退出 1;

上一提交把本工程钉成独立 pnpm workspace 根以阻断根 lockfile 覆写，但漏声明
allowBuilds——原生构建许可原本继承自根 workspace，隔离后不再传递。

实测（pnpm 12.2.1，本目录完整 pnpm install）：Error: ERR_PNPM_IGNORED_BUILDS，
被拦 @scarf/scarf / esbuild / sharp / unrs-resolver，退出码 1，且 pnpm 会往
pnpm-workspace.yaml 回写 "set this to true or false" 占位；根 pnpm-workspace.yaml
所载的 `cd … && pnpm install && pnpm dev` 因此卡在第一步。

注：作者侧大概率以 --lockfile-only 验证，该模式不执行构建脚本故退出 0，恰好掩盖此失败。

- 补齐四条许可，取值与根 workspace 一致（@scarf/scarf 保持 false，同为隐私考虑）
- 未纳入根侧 msw：本工程不依赖，遵循最小声明
- 注释指向修正：原「运行方式见同目录 README.md」——该 README 为 create-next-app
  原始样板，无 install 步骤亦未提隔离 workspace，改为就地写明安装运行命令

验证：修复后 pnpm install 退出 0、IGNORED_BUILDS 零命中；根 pnpm-lock.yaml 逐字节未变，
隔离目标保持有效；YAML 解析通过。

🤖 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(perceives): 同步 pip-audit ignore 注释至纠偏后口径并订正 ISSUE-092 计数;

本分支已论证 transformers 锁定 <5.0.0 的真实阻断是 marker-pdf 2.0.0 / surya 0.22.1
要求 pillow<11，而非旧记的「marker-pdf / docling 兼容交集」；setuptools 保持 82.0.1
的理由亦已由「undetected-chromedriver 依赖 pkg_resources」改写为「已证伪」。但 CI
ignore 清单中的四处注释仍停留在旧口径，与 pyproject、issue.md 相互矛盾。

CVE-2026-9856 条已承载完整根因，其余三处改为指针式引用，避免同一结论多处维护：

- PYSEC-2025-211..218 / CVE-2026-4372 / PYSEC-2026-2290：删除「docling 兼容交集」
  归因，统一指向 CVE-2026-9856 条；CVE-2026-4372 的「待交集支持 5.3.0+ 后升级」
  同步改为「待 marker-pdf / surya 放开 pillow<11 上界」
- PYSEC-2026-3447：交叉引用由「见 pyproject，undetected-chromedriver 相关」改为
  「见 pyproject setuptools 注释与 ISSUE-092 2026-09-06 增补」——照旧文跳转只会
  读到相反结论
- ISSUE-092：「ignore 条目 62→56」订正为 34→28。negentropy-perceives-ci.yml 是
  全仓唯一 --ignore-vuln 来源，实测本分支前 34 条、后 28 条（差值 6 正确，绝对值错位）

纯注释与文档变更，ignore 条目与 pip-audit 行为零改动。验证：YAML 解析通过；
--ignore-vuln 实测 28 条，与订正后的 issue.md 记载一致；注释行宽与既有块保持齐平。

🤖 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

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

@ThreeFish-AI