Wiki Portal 多租户架构 mini-spec

Date: 2026-05-22
Status: Draft (spec only, no implementation)
Owner: cloud / wiki-web
Trigger: 用户拍板架构变更 — wiki-portal = Docusaurus 部署壳, 0 业务内容, 各项目 docs/ via submodule

节 1: 目标定位
节 2: 范围边界
节 3: 架构数据流
节 4: 模块边界
节 5: API 契约
节 6: 扩展点 / 插件接口
节 7: 错误处理 + 边界 case
节 8: 成本契约
节 9: 测试矩阵
节 10: 向后兼容 + 迁移路径
节 11: 风险登记
附录 A: 当前 wiki-web docs 内容 inventory
附录 B: 5 项目仓 docs/ 现状评估

节 1: 目标定位

用户痛点

当前 qiurui144/attune-wiki-web 仓集中维护所有项目文档(attune / lawcontrol / pluginhub / hardware / plans / getting-started 等), 但各项目代码在独立仓 (qiurui144/attune, qiurui144/lawcontrol, qiurui144/attune-pluginhub 等)。产生 3 个问题:

内容漂移: 项目 owner 改代码 + 改本仓 docs/ 但不知道要同步去 wiki-web 仓 → wiki 内容滞后
责任不清: wiki-web 仓没有明确 owner per 项目, 内容质量参差不齐
认知负担: 项目 owner 要在两个仓之间切换才能更新文档, 提高维护成本

目标定位

将 wiki-portal 改造为纯 Docusaurus 部署壳 (0 业务内容):

顶部导航 1 tab per 项目
各 tab 下挂载该项目仓 docs/ 目录 (via git submodule)
项目 owner 只在自己仓 push 即可触发 wiki-portal rebuild

与产品 positioning 对齐

去 attune 品牌化: 仓名从 attune-wiki-web → wiki-portal, Docusaurus title 改为中立 ("EngiStack Wiki" 已经是中立标题, 保留)
多产品矩阵: 当前已有 attune (OSS) + attune-pro + lawcontrol 三产品矩阵, 加上 KVM / RV / pluginhub 等共 5+ 产品线, 都能在同一门户展示
降低维护门槛: 各项目 owner 不需了解 Docusaurus, 写 markdown 即可

节 2: 范围边界

做什么 (in scope)

#	项	备注
1	仓改名 `attune-wiki-web` → `wiki-portal`	GH repo rename
2	Docusaurus rebrand (title 已 "EngiStack Wiki" 保留; logo / 默认入口页 → 中立)	不再引导到 attune.ai
3	多 tab 多 submodule 结构	每项目 docs/ 一个 submodule (`external/<project>/docs/`)
4	`repository_dispatch` 跨仓触发机制	各项目 push docs/ → wiki-portal CI
5	`wiki-deploy.yml` 改造支持 `repository_dispatch` event	加 `on: repository_dispatch: types: [wiki-content-update]`
6	`sidebars.ts` 改造为 per-project tabs (按 submodule 分组)	每 tab 1 个项目, 内部树状目录
7	wiki-portal 仓保留入口页 + 通用导航	`docs/index.md` + 各 tab 入口, 不放业务内容

不做什么 (out of scope, 同时不允许扩散)

#	项	备注
1	不引入新 SSG (仍 Docusaurus, 不换 mkdocs / hugo / starlight)	保留已有迁移成果
2	不动 cloud-wiki 容器配置 (per #87)	nginx 静态 serve 不变
3	不动各项目代码, 仅他们 `docs/` 目录	项目仓只新增 GH Action workflow
4	不动 GH repo 名 (本 spec 阶段只设计, 不执行 rename)	spec only, 实施留给后续 plan
5	不动 `.gitmodules` (spec only)	留 plan 阶段做
6	不强制各项目 docs/ 结构	允许各项目自由组织, sidebar 单独配置每 tab

后续版本才做 (defer)

#	项	备注
1	各 tab 独立搜索 scope	当前 Docusaurus 全局搜索即可
2	docs versioning (vX.Y.Z 历史快照)	submodule pin commit 已能解决
3	i18n per project	当前 zh/en 全局, 先 ship 中文

节 3: 架构数据流

数据流图 (ASCII)

┌─────────────────────────────────────────────────────────────────┐
│  项目仓 (5+)                                                     │
│  ─────────                                                       │
│  [attune repo]            ──┐                                    │
│   └ docs/                   │                                    │
│  [lawcontrol/enterprise] ──┤                                    │
│   └ docs/                   │                                    │
│  [attune-pluginhub]      ──┼─→  push 到 docs/* 触                │
│   └ docs/                   │   peter-evans/repository-dispatch │
│  [KVM repo]              ──┤                                    │
│   └ docs/                   │                                    │
│  [attune-pro]            ──┘                                    │
│   └ docs/                                                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ (repository_dispatch event)
                              │  type: wiki-content-update
                              │  payload: { source_repo, commit }
                              │
┌─────────────────────────────▼────────────────────────────────────┐
│  wiki-portal 仓 (Docusaurus)                                     │
│  ───────────────────────                                          │
│  - .gitmodules:                                                  │
│      external/attune/docs/         → pin commit                  │
│      external/lawcontrol/docs/     → pin commit                  │
│      external/pluginhub/docs/      → pin commit                  │
│      external/kvm/docs/            → pin commit                  │
│      external/attune-pro/docs/     → pin commit                  │
│  - docs/                                                         │
│      index.md          (中立门户首页)                              │
│      attune/           → symlink → external/attune/docs/         │
│      lawcontrol/       → symlink → external/lawcontrol/docs/     │
│      pluginhub/        → symlink → external/pluginhub/docs/      │
│      kvm/              → symlink → external/kvm/docs/            │
│      attune-pro/       → symlink → external/attune-pro/docs/     │
│  - sidebars.ts (per-tab 配置)                                    │
│  - .github/workflows/wiki-deploy.yml                             │
│      on:                                                         │
│        push: [main]                                              │
│        repository_dispatch: [wiki-content-update]                │
│        workflow_dispatch:                                        │
└───────────────────────────────┬──────────────────────────────────┘
                                │
                                ▼ (CI run)
                                │  1. checkout (含 submodules)
                                │  2. submodule update --remote (拉最新)
                                │  3. npm ci && npm run build
                                │  4. verify build/ 非空
                                │  5. SSH 到 cloud-wiki 主机
                                │     git pull + docker-compose build
                                │
┌───────────────────────────────▼──────────────────────────────────┐
│  生产 cloud-wiki nginx 容器 (per #87, 不变)                       │
│  ──────────────────────────                                       │
│  serve build/ static                                              │
│  https://wiki.attune.ai (or 中立域名后续)                          │
└──────────────────────────────────────────────────────────────────┘

关键数据契约

submodule URL: HTTPS (e.g. https://github.com/qiurui144/attune.git), public read 即可, push 不需要
submodule path 约定: external/<project>/ (整个项目仓 submodule, sidebars.ts 引用 external/<project>/docs/<file>)
submodule pin: 默认 main/master HEAD, CI 跑 submodule update --remote 拉最新

DB / cache 层

无。wiki-portal 是纯静态 site, 不需 DB。生产容器 nginx 自带文件 cache。

节 4: 模块边界

wiki-portal 仓 (本仓)

内容	角色
`docusaurus.config.ts`	中立配置 (title / logo / nav / footer)
`sidebars.ts`	per-project tab + 树状目录
`docs/index.md`	中立门户首页 (产品矩阵图 + 各 tab 入口卡片)
`.gitmodules`	submodule 索引 (5+ 项目仓)
`external/<project>/`	各项目仓 submodule (整仓 mount, sidebar 引用其 `docs/`)
`.github/workflows/wiki-deploy.yml`	CI build + deploy
`src/`, `static/`, `i18n/`	Docusaurus 主题 / 资源 / 国际化

强制约束: 本仓 docs/ 目录除 index.md + 各 tab 入口外, 0 业务内容。所有业务 md 通过 submodule 引入。

各项目仓 (5+)

内容	角色
`docs/`	项目自己 owns 的文档 (markdown, 自由组织)
`.github/workflows/wiki-dispatch.yml` (新增)	检测 docs/ 变更 → 发 repository_dispatch event

强制约束: 各项目仓只新增 1 个 workflow 文件, 不动其他代码。

cloud 仓 (per Phase 4 已完成)

内容	角色
`.gitmodules`	wiki-portal 仍 pin commit 进 cloud (per #87)

不变。

生产 cloud-wiki 容器

内容	角色
`nginx.conf`	静态 serve `/usr/share/nginx/html`

不变。

跨仓边界

跨仓	数据流	权限
项目仓 → wiki-portal	repository_dispatch event	各项目仓 secret: `WIKI_PORTAL_DISPATCH_TOKEN` (GH PAT, 只 `repo:write` to wiki-portal)
wiki-portal → 项目仓	submodule HTTPS clone (read-only)	公开 read, 无需 token
wiki-portal → cloud-wiki	SSH deploy (per existing workflow)	wiki-portal secret: `PRODUCTION_*` (不变)

节 5: API 契约

5.1 各项目仓 → wiki-portal: repository_dispatch event

项目仓 workflow (.github/workflows/wiki-dispatch.yml):

name: wiki-dispatch
on:
  push:
    branches: [main, master]
    paths:
      - 'docs/**'
      - '*.md'  # 顶级 README 等 (可选, 视项目自由)
jobs:
  trigger-wiki-rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger wiki-portal rebuild
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.WIKI_PORTAL_DISPATCH_TOKEN }}
          repository: qiurui144/wiki-portal
          event-type: wiki-content-update
          client-payload: |
            {
              "source_repo": "${{ github.repository }}",
              "commit": "${{ github.sha }}",
              "ref": "${{ github.ref }}"
            }

event 协议:

event-type: wiki-content-update (固定字符串, wiki-portal workflow 监听这个)
client-payload:
- source_repo (string): 触发仓 (e.g. qiurui144/attune)
- commit (string): 触发 commit SHA
- ref (string): 触发 ref (e.g. refs/heads/main)

5.2 wiki-portal workflow trigger 配置

# .github/workflows/wiki-deploy.yml
on:
  push:
    branches: [main]
  repository_dispatch:
    types: [wiki-content-update]   # ← 新增
  workflow_dispatch:
    inputs:
      reason:
        required: false
        default: 'manual deploy'

5.3 CI 关键步骤 (新增)

steps:
  - name: Checkout (含 submodules)
    uses: actions/checkout@v4
    with:
      submodules: recursive
      fetch-depth: 1

  - name: Update submodules to latest main
    run: |
      git submodule foreach --recursive 'git fetch origin main 2>/dev/null || git fetch origin master'
      git submodule update --remote --recursive

  - name: Log dispatch source (debug)
    if: github.event_name == 'repository_dispatch'
    run: |
      echo "Triggered by: ${{ github.event.client_payload.source_repo }}"
      echo "Commit: ${{ github.event.client_payload.commit }}"

  # ... 后续 npm ci / build / deploy 与现有一致

const sidebars: SidebarsConfig = {
  attune: [
    'attune/index',
    'attune/quickstart',
    // ... 等同当前 attune tab 内容
  ],
  lawcontrol: [
    'lawcontrol/index',
    // ...
  ],
  pluginhub: ['pluginhub/index', 'pluginhub/attune-integration'],
  kvm: ['kvm/index', /* ... */],
  attune-pro: ['attune-pro/index', /* ... */],
};

navbar 配置:

navbar: {
  items: [
    {to: '/', label: '首页', position: 'left'},
    {type: 'docSidebar', sidebarId: 'attune', position: 'left', label: 'Attune'},
    {type: 'docSidebar', sidebarId: 'lawcontrol', position: 'left', label: 'LawControl'},
    {type: 'docSidebar', sidebarId: 'pluginhub', position: 'left', label: 'PluginHub'},
    {type: 'docSidebar', sidebarId: 'kvm', position: 'left', label: 'KVM'},
    {type: 'localeDropdown', position: 'right'},
  ],
},

节 6: 扩展点 / 插件接口

加新项目流程

5 步即可:

项目仓建 docs/ 目录 (若没有), 至少 1 个 index.md
项目仓加 .github/workflows/wiki-dispatch.yml (复制现有模板)
项目仓 secrets 加 WIKI_PORTAL_DISPATCH_TOKEN
wiki-portal 仓 git submodule add https://github.com/qiurui144/<new-project>.git external/<new-project>
wiki-portal 仓 sidebars.ts 新增 sidebar key + docusaurus.config.ts navbar 加 tab

sidebars.template.ts 提供 boilerplate, 各项目 owner 复制后改路径即可。

入口页模板

docs/template-project-index.md 给项目入口页 (overview / 快速链接 / changelog 入口) 标准结构。

节 7: 错误处理 + 边界 case

错误处理矩阵

场景	行为	错误码
项目 docs/ 目录不存在 (submodule 内)	`git submodule update` 成功但 sidebar 引用 fail → Docusaurus build warn	`MISSING-DOCS-DIR` (warn, 不阻断)
repository_dispatch token 失效	项目仓 workflow fail → wiki-portal 不触发	项目仓 CI 红 (可见信号)
submodule URL 404 (项目仓改名 / 删)	`submodule update` fail → wiki-portal CI fail	`SUBMODULE-FETCH-FAIL` (abort)
Docusaurus build fail (markdown 语法错)	npm run build fail → CI abort, 不触 deploy	`BUILD-FAIL` (abort, 生产 last-known-good 保留)
多项目同时 push (5 个项目同 1 分钟内 push)	5 个 dispatch event → wiki-portal CI 用 `concurrency: wiki-deploy` 串行	后到的 supersede 前面排队的
SSH deploy 阶段 cloud-wiki 不可达	appleboy/ssh-action timeout → CI fail	生产保留旧版本

Graceful degradation

submodule 一个 fail 不影响其他: 用 --recursive 但加 || true 让单个失败不阻 build (仅对 fetch 阶段, build 阶段仍严格)
build 失败不替换生产: CI 在 build 验证后才 SSH deploy, build fail → 生产保留旧产物
CI 失败通知: GH Actions 自带 email notification 给 commit author + workflow trigger

边界 case

submodule pin commit 与 main HEAD 落后 → update --remote 自动拉最新, 但 wiki-portal commit 不更新 .gitmodules pin (每周 1 次手动 git submodule update --remote && git commit 同步 pin)
项目仓改名 (e.g. lawcontrol → attune-enterprise per #92) → 需手动改 .gitmodules URL + 项目仓的 wiki-dispatch.yml 不变 (event-type 不变)
一项目 docs/ 占用 sidebar key 冲突 (两个项目都有 index) → 通过 external/<project>/ 路径前缀天然隔离, sidebar 里写 external/attune/docs/index 不冲突

节 8: 成本契约

per 全局 CLAUDE.md 三层成本契约:

层级	资源	此 spec 中的体现
🆓 零成本	CPU 毫秒级	sidebar 渲染 / nginx 静态 serve / submodule 元数据查询
⚡ 本地算力	CI build (Docusaurus + Node)	每次 dispatch trigger 1 次 build, 5-7 min/次, GH Actions free tier 内
💰 时间/金钱	用户显式触发	不适用 (本 spec 无 LLM / AI 计算路径)

CI minutes 估算

场景	估算
项目 docs push 频率	5 项目 × 平均 2 次/天 = 10 次/天
每次 wiki-portal build	5-7 min (含 submodule update + npm build + SSH deploy)
月度 CI 用量	10 次/天 × 7 min × 30 天 = 2100 min/月
GH free tier (private)	2000 min/月 free; 公开仓 unlimited

风险: wiki-portal 若 private 会接近 free tier 边界, 建议保持 public (反正内容公开)。

人力维护成本

角色	工作	频率
各项目 owner	写 markdown + push	日常
wiki-portal owner	审 submodule pin / 改 sidebar / 加新项目	每月 1 次
整体 doc 协调 (优化 cross-link 等)	季度 review	每 3 月 1 次

节 9: 测试矩阵

per 6 类下限 (本 spec 是基础设施改造, 不是 agent, 但仍套用):

类型	下限	实例
Golden case (E2E)	≥5	5 项目都有 submodule pin → wiki-portal build OK, 5 tab 都显示
属性测试	≥3	(1) 任 1 项目仓 push docs/ → wiki-portal 在 10 min 内 rebuild (2) sidebar key 唯一性 (3) submodule URL 都是 HTTPS 公开仓
边界 case	≥5	(1) 项目 docs/ 空目录 → build 不 fail (2) submodule pin 落后 main 10+ commit → `--remote` 能拉最新 (3) 同时 5 dispatch → concurrency 串行 (4) 项目改名 → submodule URL 改 (5) docs/ 含中文文件名 → URL 编码正确
异常 / 错误	≥3	(1) WIKI_PORTAL_DISPATCH_TOKEN 失效 → 项目仓 CI 红 (2) submodule fetch 404 → wiki-portal CI 红 (3) Docusaurus build 语法错 → CI 红 + 生产保留
集成 E2E	≥1	attune 仓 push docs/quickstart.md → 7 min 内 wiki.attune.ai 看到更新
回归 fixture	per bug	每次 build fail 加 fixture (sidebar 配置错 / submodule URL 错 / event 协议 mismatch 等)

验收清单 (GA 前必跑)

5 项目仓都加 wiki-dispatch.yml + secret 配置
wiki-portal 仓有 5 个 submodule + 5 个 sidebar 配置
navbar 显示 5 tab + 中立首页
各项目 push docs/ → wiki-portal 在 10 min 内 rebuild (实测每项目至少 1 次)
5 tab 都能正常导航, 内部链接不死
中立首页有产品矩阵图 + 各 tab 入口卡片
cloud-wiki 容器健康 (per #87 cluster status 不变)

节 10: 向后兼容 + 迁移路径

Phase 切片

Phase	内容	风险	rollback
A	GH repo rename `attune-wiki-web` → `wiki-portal`	URL 变化 → cloud `.gitmodules` 失效	GH 自动 redirect 旧 URL, 但 .gitmodules 仍需更新
B	抽出各项目 docs 到对应项目仓 (见下表)	链接断裂 + content 重定位	抽出过程 wiki-portal 本仓保留 docs/ 副本作 fallback (后续 phase 删除)
C	wiki-portal 配 5 个 submodule + 改 sidebar 引用 submodule path	sidebar 路径错 → 死链	同时保留旧 docs/ 副本, sidebar 改完 verify 后再删
D	各项目仓加 `wiki-dispatch.yml` + secret	dispatch event 不触 → wiki 不更新	保留 `workflow_dispatch` 手动触发 fallback
E	cloud submodule pin wiki-portal 新 commit	cloud .gitmodules URL 失效	跟随 Phase A 同步更新
F	删除 wiki-portal 仓内 docs/ 副本 (除入口页)	不可逆, 内容已在项目仓	保留 1 周观察期再删

Phase B 详解: docs 内容归属

当前 wiki-web 7 个 top-level 目录 + 47 md 文件, 重新归属:

当前位置	内容主题	归属去向	备注
`docs/attune/` (16 md)	Attune 产品: quickstart / wizard / chat / sources / llm-setup / plugins / agents / architecture / privacy / benchmarks / faq	→ `qiurui144/attune` 仓 `docs/`	attune 已有 22 个 root md, 需检查重复 + 合并 (避免双份)
`docs/lawcontrol/` (7 md)	LawControl: index / guide/* / admin/*	→ `qiurui144/lawcontrol` (待改名 attune-enterprise per #92) 仓 `docs/`	lawcontrol 已有 24 root md, 重复检查
`docs/pluginhub/` (2 md)	PluginHub: index / attune-integration	→ `qiurui144/attune-pluginhub` 仓 `docs/`	pluginhub 已有 1 root md, 合并
`docs/hardware/` (2 md) + `docs/software/` (2 md)	K3 一体机硬件规格 / 软件镜像 / 烧录	→ `qiurui144/KVM` 仓 `docs/` 或新建 `qiurui144/attune-k3-form-factor`	KVM 已有 14 root md; 决策点: K3 一体机内容是否独立仓 (defer 给 plan 阶段)
`docs/plans/` (1 md: attune-pricing)	Attune 定价	→ `qiurui144/attune` 仓 `docs/plans/pricing.md` 或留 wiki-portal	决策点: 定价是产品级内容, 可留 wiki-portal 入口页
`docs/getting-started/` (3 md)	K3 入门: install / first-boot	→ 跟随 hardware/software 一起去 KVM 仓	与硬件文档绑定
`docs/index.md` + `docs/download.md`	wiki 门户首页 + 下载页	留 wiki-portal (重写为中立入口)	不属于任何单一项目

Phase B 风险: link references

当前 docs 内有 cross-tab 引用 (e.g. attune 文档引用 lawcontrol/index)
抽出后这些 link 需改为 wiki-portal 的 absolute path (/lawcontrol/index) 而非相对 path
工具: grep -rn "\.\./" docs/ 找所有跨目录引用, 抽出前批量改

schema versioning

无 schema 变更。markdown 是文件格式, submodule pin 是 git 原语, 不引入新 schema。

老 client 行为

cloud-wiki nginx 容器对 client 是黑盒 (只 serve build 产物)。client (浏览器) 看到的是新版静态文件, 与基础设施改造无感。

节 11: 风险登记

ID	风险	概率	影响	缓解
R1	GH repo rename 后 cloud `.gitmodules` URL 不更新 → submodule init fail	高	高 (cloud build 红)	rename 后立即手动更新 cloud `.gitmodules` + verify CI
R2	Phase B 抽 docs 时漏 link references → 渲染 404	中	中 (用户体验下降)	抽出前 grep 全部 cross-link + 写 link redirect 表; 抽出后 link-check CI 步骤
R3	repository_dispatch token 跨仓 secret 管理复杂	中	低 (单次配置)	用 GH organization-level secret 一次配 5 项目共享, 或写 README 步骤清单
R4	Docusaurus 多 submodule build 时间显著上升	中	低 (CI 慢, 不阻 deploy)	submodule shallow clone (`--depth 1`) + 并行 fetch; 当前估算 5-7 min, 上升到 10 min 内可接受
R5	各项目 owner 维护 docs/ 节奏不齐, 内容质量不一致	高	中 (用户认知割裂)	wiki-portal 提供 docs 模板 + 季度 review 流程; 不强制结构, 但提供 best practice 指南
R6	`docs/lawcontrol/` 迁出与 #92 lawcontrol → attune-enterprise rename 时序	中	中 (双重 rename, link 易断)	二者协同, 先 #92 rename → 再本 spec Phase A; 或 #92 先 hold, 本 spec 用 `lawcontrol` 旧名先 ship, 之后 #92 再追 rename
R7	5 项目同时 push 触 5 个 CI run → CI minute 燃料	低	低	concurrency group 串行 + free tier 内
R8	submodule pin 长期不更新 (没人 review .gitmodules pin) → wiki 一直显示旧内容	中	中	CI `submodule update --remote` 自动拉最新 (build 时不依赖 pin), pin 仅用于 reproducible build; 季度 1 次手动 commit pin
R9	中立化首页内容空洞 (失去 attune 品牌入口)	中	中 (营销 SEO)	中立首页保留 attune 推广 (作为 1 个 tab 而非主品牌); 营销页另在 `https://attune.ai`
R10	submodule 是整仓 mount, 含项目仓非 docs/ 内容 → wiki-portal 占盘膨胀	低	低	submodule shallow clone + sparse-checkout 限 `docs/` 目录 (后续优化)

附录 A: 当前 wiki-web docs 内容 inventory

实测 2026-05-22:

docs/
├── attune/                  16 md (quickstart / wizard / chat / sources/* / llm-setup / plugins / agents / architecture / privacy / benchmarks / faq / index)
├── getting-started/         3 md (index / install / first-boot)
├── hardware/                2 md (specs / interfaces)
├── lawcontrol/              7 md (index / guide/* / admin/index)
├── plans/                   1 md (attune-pricing)
├── pluginhub/               2 md (index / attune-integration)
├── software/                2 md (images / flash)
├── download.md              1 md
└── index.md                 1 md (门户首页)
─────────────────────────────────
Total: 35 md, 7 top-level 主题目录

git 状态:

分支: refactor/docusaurus-migration (working tree clean)
远端: github (qiurui144/attune-wiki-web) + origin (private gitea mirror)

CI:

.github/workflows/wiki-deploy.yml (push main/master + workflow_dispatch)

附录 B: 5 项目仓 docs/ 现状评估

实测 2026-05-22 在 /data/company/project/ 下:

#	项目	路径	docs/ 存在?	已有 md 数	评估加入难度
1	attune	`/data/company/project/attune/docs/`	✅	22 root md	低: 已有完整 docs/, 加 wiki-dispatch.yml 即可。注意与 wiki-web `docs/attune/` 16 md 合并去重
2	lawcontrol (将 rename attune-enterprise per #92)	`/data/company/project/lawcontrol/docs/`	✅	24 root md	中: 已有 docs/ 但 #92 rename 协同; 等 #92 完成再加 wiki-dispatch.yml
3	attune-pro	`/data/company/project/attune-pro/docs/`	✅	10 root md	低: 已有 docs/。但决策点: attune-pro 是私有商业仓, 是否 wiki 公开? 若公开仅 OSS-friendly 部分, 需要 docs/ 内分目录权限隔离
4	attune-pluginhub	`/data/company/project/attune-pluginhub/docs/`	✅	1 root md	低: docs/ 已有但内容稀, 需补充
5	KVM	`/data/company/project/KVM/docs/`	✅	14 root md	低: 已有 docs/, KVM 接收 hardware/software/getting-started 内容 (Phase B 迁移)
-	RV (`/data/RV/`)	N/A	❌	仅 root README/CONTRIBUTORS/CLAUDE	中: 若加入 wiki-portal 需新建 docs/; 但 RV 是工作区根 (含多 rv-* 子项目), 是否单独 1 tab 还是按 rv-* 拆分多 tab 是决策点

总体评估

5 主要项目 docs/ 全部已存在 ✅ — 基础条件满足
主要工作集中在 (1) wiki-web 现有 35 md 拆分迁移 (Phase B) + (2) 各项目仓加 wiki-dispatch.yml workflow (Phase D)
决策点 (defer 给 plan 阶段):
- K3 一体机内容归 KVM 还是新独立仓?
- attune-pro 商业仓是否公开 wiki?
- RV 工作区是否 1 tab 还是 N tab?
- lawcontrol → attune-enterprise rename (#92) 与本 spec Phase A 时序如何协同?

变更记录

2026-05-22: 初稿落盘 (用户拍板架构变更, 11 节 + 2 附录)

目录​

节 1: 目标定位​

用户痛点​

目标定位​

与产品 positioning 对齐​

节 2: 范围边界​

做什么 (in scope)​

不做什么 (out of scope, 同时不允许扩散)​

后续版本才做 (defer)​

节 3: 架构数据流​

数据流图 (ASCII)​

关键数据契约​

DB / cache 层​

节 4: 模块边界​

wiki-portal 仓 (本仓)​

各项目仓 (5+)​

cloud 仓 (per Phase 4 已完成)​

生产 cloud-wiki 容器​

跨仓边界​

节 5: API 契约​

5.1 各项目仓 → wiki-portal: repository_dispatch event​

5.2 wiki-portal workflow trigger 配置​

5.3 CI 关键步骤 (新增)​

5.4 sidebars.ts (per-tab 多 sidebar)​

节 6: 扩展点 / 插件接口​

加新项目流程​

sidebar 模板​

入口页模板​

节 7: 错误处理 + 边界 case​

错误处理矩阵​

Graceful degradation​

边界 case​

节 8: 成本契约​

CI minutes 估算​

人力维护成本​

节 9: 测试矩阵​

验收清单 (GA 前必跑)​

节 10: 向后兼容 + 迁移路径​

Phase 切片​

Phase B 详解: docs 内容归属​

Phase B 风险: link references​

schema versioning​

老 client 行为​

节 11: 风险登记​

附录 A: 当前 wiki-web docs 内容 inventory​

附录 B: 5 项目仓 docs/ 现状评估​

总体评估​

变更记录​

目录