Skip to content

refactor(knowledge+wiki): 合并 Catalog 与 Wiki 为统一管理入口 + negentropy-wiki 站点视觉四阶段升级 - #556

Merged
ThreeFish-AI merged 4 commits into
feature/1.x.xfrom
ThreeFish-AI/merge-catalog-wiki
May 17, 2026
Merged

refactor(knowledge+wiki): 合并 Catalog 与 Wiki 为统一管理入口 + negentropy-wiki 站点视觉四阶段升级#556
ThreeFish-AI merged 4 commits into
feature/1.x.xfrom
ThreeFish-AI/merge-catalog-wiki

Conversation

@ThreeFish-AI

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

Copy link
Copy Markdown
Owner

背景

  • 本次变更要解决的问题：Knowledge 模块下 Catalog（编目编辑态）和 Wiki（发布管理态）分属两个独立页面，用户需在导航 tab 间来回切换，两页面共享 useSingletonCatalog 数据源但各自独立调用导致冗余。negentropy-wiki 公共站点存在 836 行单一 globals.css、三套主题无切换 UI、a11y 不完整等体验短板。
  • 关联上下文/Issue/文档：用户要求合并 knowledge 下 catalog 和 wiki 页面消除冗余，同时优化 negentropy-wiki 站点显示效果。

核心变更

  • 合并 Catalog + Wiki 页面：将两个页面合并为单一 /knowledge/wiki 路由，左栏始终显示 Catalog 树（含拖拽排序、右键菜单、搜索），右栏通过 ModeToggle 在 edit（节点编辑）和 publish（发布管理）间切换。旧 /knowledge/catalog 自动重定向到 /knowledge/wiki?mode=edit。catalog 组件通过 git mv 移入 wiki 目录，消除 useSingletonCatalog 重复调用。
  • Wiki 站点 CSS 模块拆分：将 836 行 globals.css 拆为 14 个模块文件（tokens/themes/base/typography/layout/components），零观感变化。
  • 主题切换 UI：新增 ThemePreference 组件（三主题 + 明暗模式），layout.tsx 注入 FOUC-free 初始化脚本避免闪烁。
  • Markdown 增强：CodeBlock（语言徽章 + 复制按钮）、AnchorHeading（hover 锚点链接）、ResponsiveTable（斑马纹）、Callout、MarkdownRenderer。
  • 首页升级：KPI 条（Publication 数 / 文档数 / 最近更新）、彩色 dot avatar、相对日期、描述截断。
  • 新组件：WikiBreadcrumb、WikiPager、WikiReadingMeta、reading-time 纯函数。
  • a11y + 移动端：Skip link、WikiNavTree ARIA roles（tree/treeitem/group）、WikiMobileNav 抽屉式侧边栏、统一 focus-visible 焦点环。

风险与回滚

  • 主要风险：LibraryShell 中 useCatalogTree 实例在模式切换时不 remount 以保留选中状态；旧 URL deep link 通过 redirect + ?mode= 透传。
  • 回滚方式：两个提交独立可分别 revert；CSS 拆分保留老 --wiki-* 变量名作 alias；Wiki 站点路由结构未变。

验证证据

  • 单元测试：negentropy-ui tsc --noEmit 零错误通过；negentropy-wiki pnpm build 成功（7 个页面静态生成）。
  • 集成测试：既有测试文件未受影响（API 路径不变）。
  • E2E/Workflow：待浏览器实机验证 Catalog 树交互、ModeToggle 切换、主题切换、移动端抽屉。
  • 覆盖率/关键截图：两个项目构建零错误，JS 包大小仅微增（109kB vs 107kB）。

影响范围

  • 前端：apps/negentropy-ui knowledge 模块（wiki + catalog 页面 + KnowledgeNav）；apps/negentropy-wiki 全站样式、组件、布局。
  • 后端：无影响（API 路由和数据契约未变更）。
  • GitHub Actions / 文档：无影响。

Next Best Action

  • 浏览器实机验证 /knowledge/wiki 页面的 Catalog 树拖拽、右键菜单、edit/publish 模式切换。
  • 浏览器实机验证 negentropy-wiki 站点的主题切换、明暗模式、首页卡片、Markdown 代码块复制。

🤖 Generated with Claude Code

@ThreeFish-AI
refactor(knowledge): 合并 Catalog 与 Wiki 页面为统一 Wiki 管理入口
01f5a37 
将 knowledge/catalog 和 knowledge/wiki 两个独立页面合并为单一 `/knowledge/wiki` 路由，
左栏始终显示 Catalog 树（含拖拽排序、右键菜单、搜索），右栏通过 ModeToggle 在 edit（节点编辑）
和 publish（发布管理）间切换。旧 `/knowledge/catalog` 自动重定向到 `/knowledge/wiki?mode=edit`。
消除 useSingletonCatalog 重复调用和 CatalogNodeSelectorDialog 的二次拉树冗余。

🤖 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): negentropy-wiki 站点视觉与体验四阶段升级
7fc2069 
阶段 1：CSS 模块拆分 — 将 836 行 globals.css 拆为 14 个模块文件（tokens/themes/base/typography/layout/components）；
阶段 2：主题切换 UI — 新增 ThemePreference 组件（三主题+明暗切换），layout.tsx 注入 FOUC-free 初始化脚本；
阶段 3：Markdown 增强 + 首页升级 — CodeBlock（语言徽章+复制按钮）、AnchorHeading（hover 锚点链接）、
ResponsiveTable（斑马纹）、Callout、MarkdownRenderer；首页添加 KPI 条和彩色 dot avatar；
WikiBreadcrumb/WikiPager/WikiReadingMeta/reading-time 新组件；
阶段 4：a11y + 移动端 — Skip link、WikiNavTree ARIA roles（tree/treeitem/group）、
WikiMobileNav 抽屉式侧边栏、统一 focus-visible 焦点环。

🤖 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(knowledge): 合并 Catalog 与 Wiki 页面 + negentropy-wiki 站点视觉升级 refactor(knowledge+wiki): 合并 Catalog 与 Wiki 为统一管理入口 + negentropy-wiki 站点视觉四阶段升级 May 17, 2026
ThreeFish-AI and others added 2 commits May 17, 2026 12:26
@ThreeFish-AI @claude
fix(wiki): 修复深色模式 CSS 语法错误与主题下拉菜单点击外部不关闭
b990833 
- themes.css: 将无效的 `[data-color-scheme="dark"], @media(...)` 逗号分隔语法
  拆分为两条独立规则，恢复深色模式变量生效
- ThemePreference: 添加 pointerdown 事件监听实现 click-outside 关闭下拉菜单

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@ThreeFish-AI
test(wiki): 修复 catalog 组件迁移后单测 import 路径;
2084b7f 
PR #556 中 commit 01f5a37 将 catalog 组件迁移至 wiki/_components/catalog/，
但 catalog-create-node-dialog 与 catalog-tree-node-icons 两个单测的 import
路径未同步更新，导致 ui-quality 工作流的 UI Type Checks 与 UI Unit And
Integration Tests 双 Job 失败。

- catalog-create-node-dialog.test.tsx: CreateNodeDialog 路径
  @/app/knowledge/catalog/_components/ → @/app/knowledge/wiki/_components/catalog/
- catalog-tree-node-icons.test.tsx: CatalogTreeNode 路径同上调整

本地验证：pnpm typecheck、pnpm typecheck:test、目标两测试 7/7 通过。

🤖 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 dc90de6 into feature/1.x.x May 17, 2026
11 checks passed
@ThreeFish-AI
ThreeFish-AI deleted the ThreeFish-AI/merge-catalog-wiki branch May 17, 2026 06:02
This was referenced May 17, 2026
Merged
Merged
ThreeFish-AI added a commit that referenced this pull request May 19, 2026
@ThreeFish-AI
refactor(wiki): Catalog 与 Publish 子视图合并为单页一体化发布工作台 (#576)
58becef 
* refactor(wiki): Catalog 与 Publish 子视图合并为单页一体化发布工作台;

PR #556 引入的 ModeToggle 把发布相关 UI 折叠到第二个视图后，发布入口的发现性显著下降——用户在默认 Catalog 视图下找不到「把编排好的 Wiki 发布到 negentropy-wiki 站点」的操作入口。本次彻底去除「模式」概念，改为单页一体化：顶部粘性发布工具栏（Publication 选择器 + 状态徽章 + 操作按钮组 + Pipeline 状态条）+ 左栏 Catalog 树 + 右栏节点详情 + 底部可折叠的条目预览。后端 API、ISR webhook 链路、数据模型零改动。

- 新增 WikiPublishToolbar 承载 publish/unpublish/sync/delete 全部 handlers + Pipeline 透传；切换发布对象时 useEffect([pubId]) 复位 Pipeline 状态避免上次回执遗留
- 新增 WikiEntriesPreview 作为底部折叠区，forwardRef + useImperativeHandle 暴露 refresh()，从 Catalog 同步成功后由 LibraryShell 触发刷新
- 重构 LibraryShell 移除 viewMode/handleModeChange/ModeToggle，主区固定为 NodeDetailPanel
- 删除 ModeToggle/WikiPublicationDetail/WikiPublicationList 三个已被替代的组件
- 简化 page.tsx 去掉 ?mode 参数与 Suspense+useSearchParams 间接层，旧 URL ?mode=publish 仍可正常打开（参数被忽略）
- KnowledgeNav 移除 dead prop modeToggle 与对应渲染分支，同步移除 KnowledgeNav.test.tsx 中相关 case
- 新增 WikiPublishToolbar.test.tsx 7 例覆盖 disabled 态/状态切换/publishWiki/unpublishWiki/deleteWikiPublication/同步并发布/仅同步双路径
- docs/wiki/user-guide/publishing.md 新增 §8.2.1 实操指南，覆盖前置条件/第一次发布 5 步/日常增量发布/取消发布与回滚/配置说明/FAQ，交叉引用 docs/wiki/ops.md §8 与 §12.3
- CHANGELOG 在 [Unreleased]/Changed 顶部新增条目，详尽记录改动半径与契约

本地静态验证：typecheck/typecheck:test/lint 全绿，vitest 730 例全通过，Next.js build 成功且 /knowledge/wiki 路由保持 Static 预渲染。浏览器实机回归留作 PR 阶段人工验收清单。

🤖 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(wiki): 评审修复：清理死查询串、补回 description 回显、修正文档死链;

- catalog/page.tsx 移除 ?mode=edit 死查询串（wiki/page.tsx 已不再读取该参数）
- WikiPublishToolbar 状态徽章区补回 publication.description 截断显示，闭环信息回显
- publishing.md §8.2.1 死链占位符替换为指向 CHANGELOG.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 ThreeFish-AI mentioned this pull request May 19, 2026
Merged
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