跳到主要内容

KVM 接入诊断 + Hold-vs-Generalize 决策矩阵

状态：2026-05-25 落档。 触发：用户「KVM 项目想进行接入，但是貌似还需要改动 wiki 的代码，并且建立了分支」。 关联：docs/INTEGRATION-GUIDE.md（接入规范 SSOT）+ spec 2026-05-25-pattern-e-independent-docs-repo.md + plan 2026-05-25-pattern-e-impl.md。

目录 (Table of Contents)​

0. 诊断结论摘要​

问题现状
wiki 接入规范定了吗？定了（spec 02273c9 718 行 + plan 51d4a6f 1795 行 + 现在 INTEGRATION-GUIDE.md SSOT），但 Pattern E zero-code 阶段尚未实施（v1.0.1 sprint）
KVM 接入改了 wiki 代码吗？改了（docusaurus.config.ts plugin instance + sidebars-kvm.ts + .gitmodules）。在 Pattern A 模式下必然要改，不是 KVM 特殊
建立了分支吗？chore/wiki-portal-rebrand（已 push origin + github），ahead master 6 commits
KVM docs 内容在哪里？已独立到 https://github.com/qiurui144/kvm-docs.git（Pattern E 部分预演 — docs 仓独立但 wiki-portal 侧仍 Pattern A）
5/26 上架可以吗？可以（KVM-only build verified 7 pages OK，per commit 0a5c776 msg）。其他 tenant（attune / attune-enterprise / pluginhub）的 sidebar entry 在该分支被删，需先 Pattern E 实施才能恢复

1. 当前 KVM 接入分支改动清单​

chore/wiki-portal-rebrand ahead master 6 commits（按时间正序）：

Commit描述是否 KVM 特定
f784827chore(brand): 替换 favicon + logo 为 wiki-portal 中立 SVG❌ 通用 rebrand
02273c9spec: Pattern E 独立 docs 仓架构❌ 跨项目 spec
2a88f1achore(wiki): sidebars.ts 重命名 LawControl → Attune Enterprise❌ 不相关
97b6344chore(wiki): 删 wiki-portal 内 docs/{attune,lawcontrol,pluginhub} 重复内容（25 files）❌ Pattern E 准备
51d4a6fplan(pattern-e): v1.0.1 implementation plan❌ 跨项目 plan
0a5c776wiki: integrate kvm-docs (Pattern E independent docs repo)✅ KVM 接入核心 commit

KVM 接入实际改动仅 0a5c776 一个 commit（其他 5 个是 rebrand / Pattern E spec / 清理）。

1.1 0a5c776 改动文件清单​

.gitmodules                                            ★ external/kvm 改指向 qiurui144/kvm-docs branch=main
external/kvm                                           ★ submodule pin 到 kvm-docs initial commit
docusaurus.config.ts                                   ★ 加 kvm plugin instance + navbar entry
sidebars-kvm.ts                                        ★ 新建（7 page list）

总改动 = 4 文件。

2. 每项改动分类​

按"是否在理想 Pattern E 下仍需改"分三类：

2.1 必改（Pattern A + Pattern E 都需改）​

  • ✅ .gitmodules — 加 submodule entry（Pattern E 同样需要，只是 URL 指向独立 docs 仓而非项目仓）
  • ✅ external/<project>/ — submodule pin（Pattern E 同）

结论：这两项是任何接入模式都必然要改，非反模式。

2.2 应该规范化（Pattern A 下硬编码，Pattern E 下读 metadata）​

  • ⚠️ docusaurus.config.ts plugin instance — 当前每接一个项目就新增一个 plugin-content-docs 实例
    • 可规范化方案：写一个 helper 函数 loadProjectPlugins()，从 external/*/wiki.yaml 读 metadata 自动注入，wiki-portal 代码 0 改动
  • ⚠️ docusaurus.config.ts navbar items — 当前每接一个项目就加一项
    • 可规范化方案：同上，themeConfig.navbar.items 从 metadata 派生
  • ⚠️ sidebars-<project>.ts — 当前每个项目一个独立 ts 文件
    • 可规范化方案：external/<project>/wiki.yaml 含 sidebar 顺序 → Docusaurus autogenerated sidebar 或动态读 yaml

结论：当前 KVM 接入"硬编码"，下一次接入仍需手改 ts。可一次性 generalize 让后续 0 改动。

2.3 应该 zero-code-change（Pattern E v1.0.1 后无需改）​

  • ❌ wiki-portal admin 改 ts + commit + redeploy 这个动作本身
    • Pattern E 通过 5 个 submodule 槽位 + webhook + GitHub App 完全自动化
    • 但 Pattern E 实施前必然有这个环节

结论：彻底零改动需 v1.0.1 Pattern E 实施完成（5/27-5/30 sprint）。

3. Hold-vs-Generalize 决策矩阵​

针对 5/26 上架窗口期，三个候选路径：

路径描述5/26 上架窗口wiki-portal 后续改动风险
A. Hold KVM 接入到 v1.0.1当前 chore/wiki-portal-rebrand 分支不 merge，5/27-5/30 sprint 完成 Pattern E 后接入❌ 5/26 KVM 文档不在线0（Pattern E zero-code）KVM 用户找不到文档
B. 当前模式接入 KVM（不动 wiki 代码 generalize）merge chore/wiki-portal-rebrand 当前内容到 master，5/26 部署✅ 5/26 KVM 文档上线每接新项目仍需改 ts当前 KVM 接入是"硬编码示范"，下次接 attune 时仍走旧反模式
C. 一次性 generalize + 接入 KVM ⭐在 chore/wiki-portal-rebrand 改 docusaurus.config.ts 写 loadProjectsFromYaml() 通用 helper + 给 KVM 加 wiki.yaml metadata + merge✅ 5/26 KVM 文档上线后续接 attune-pro / attune-enterprise / pluginhub 0 ts 改动（只加 submodule + wiki.yaml）5/26 前要再写 helper + 测试（半天工作量）

3.1 推荐 C 的理由​

per 全局 CLAUDE.md「文档体系铁律」+「架构设计铁律」+ § 简洁原则：

  1. 这次改 wiki 代码 = 一次性 generalization（非 KVM 特定），后续接 4 个 tenant 全部 0 改动
  2. 不阻塞 5/26 上架（KVM 仍按时上线）
  3. 与 Pattern E plan #161 衔接（generalize 后再切 Pattern E webhook 时仅替换 loadProjectsFromYaml() 数据源即可，从本地 submodule path → 远端 docs 仓）
  4. 当前 KVM 接入是"硬编码示范"，merge 进 master 等于把反模式标准化，与「文档体系铁律」相悖
  5. 半天工作量（写 helper + 1 个 wiki.yaml schema + 测试 build 通），5/25 内可完成

3.2 C 的具体改动预览​

// docusaurus.config.ts（generalize 后）
import {loadProjectsFromYaml} from './scripts/load-projects';

const projects = loadProjectsFromYaml('./external/*/wiki.yaml');
// projects = [{id:'kvm', label:'KVM', sidebar:[...], path:'external/kvm/wiki'}, ...]

const config: Config = {
  // ...
  plugins: projects.map(p => ['@docusaurus/plugin-content-docs', {
    id: p.id, path: p.path, routeBasePath: p.id, sidebarPath: p.sidebarPath
  }]),
  themeConfig: {
    navbar: {
      items: [
        {type: 'docSidebar', sidebarId: 'wiki', position: 'left', label: '文档'},
        ...projects.map(p => ({
          type: 'docSidebar', sidebarId: p.id, docsPluginId: p.id,
          position: 'left', label: p.label
        })),
        {type: 'localeDropdown', position: 'right'},
      ],
    },
  },
};
# external/kvm/wiki.yaml（项目侧维护，每项目一份）
id: kvm
label: KVM
path: wiki   # 相对 external/kvm/
sidebar:
  - index
  - quickstart
  - hardware
  - api
  - security
  - architecture
  - faq

4. 推荐路径​

推荐 C — 一次性 generalize + 接入 KVM：

  1. 5/25 下午（今天）：在 chore/wiki-portal-rebrand 加 scripts/load-projects.ts + 重写 docusaurus.config.ts 用 helper + 给 KVM 加 wiki.yaml（推到 kvm-docs 仓）
  2. 5/25 晚：测试 build，确认 KVM 7 pages 仍 OK
  3. 5/26 上午：chore/wiki-portal-rebrand → master merge，触发 wiki-deploy.yml，wiki.attune.com/kvm/ 上线
  4. 5/27-5/30：Pattern E plan #161 实施时，仅需替换 loadProjectsFromYaml() 数据源（local submodule → GitHub App fetched docs 仓），其他 0 改动

回退方案：若 5/25 半天写不完 helper，回退 B 路径（当前硬编码 merge），后续接入仍走旧反模式但 5/26 KVM 文档准点上线。

5. user 决策项​

Q1：KVM 接入选哪个路径？​

  • A. Hold KVM 接入到 v1.0.1（5/26 KVM 文档不在线）
  • B. 当前模式接入 KVM（5/26 上线但反模式 merge 进 master）
  • C. 一次性 generalize + 接入 KVM（5/26 上线 + 后续 0 改动）⭐推荐

Q2：chore/wiki-portal-rebrand 分支何时 merge 到 master？​

  • 5/25 晚（C 路径 generalize 完成后）
  • 5/26 上架前最后一刻
  • Hold 等 v1.0.1 Pattern E 实施完成

Q3：Pattern E v1.0.1 实施时间窗​

per plan 2026-05-25-pattern-e-impl.md 估算 4.5 day / 12 commit / 5 phase。

  • 5/27-5/30 sprint（与 v1.0.1 升级策略 sprint 并行）
  • 5/30-6/2 sprint（错开 v1.0.1 升级策略）
  • 推到 v1.1 sprint（6 月）

Q4：是否需要把 chore/wiki-portal-rebrand 分支重命名/拆分？​

  • 当前分支名 chore/wiki-portal-rebrand 含义模糊，混了 brand 改 + Pattern E prep + KVM 接入。
  • 维持现状
  • 拆为 chore/brand-update + feat/kvm-integration + chore/pattern-e-prep 三个分支
  • 重命名为 feat/kvm-integration-pattern-a 单一目的