Wiki Portal Phase B — 各产品 docs 抽出实施报告

Date: 2026-05-24
Status: Implemented (commit pending push)
Owner: cloud / wiki-web
Predecessor: 2026-05-22-wiki-portal-multitenant.md (spec) + Phase A 3ea6918 (GH rename + Docusaurus rebrand)
Branch: chore/wiki-portal-rebrand

目标回顾

per spec §10 Phase B：从 wiki-portal 单仓模式抽出各产品 docs 到对应产品仓, wiki-portal 改为多 submodule 多 tab 形态。本阶段只处理 attune / attune-enterprise (lawcontrol) / attune-pluginhub 三仓；hardware / software / plans / getting-started 留 wiki-portal 自己。

实施清单

1. 各产品仓 add `docs/wiki/` + workflow

产品仓	路径	内容	文件数	wiki-dispatch.yml	commit
`qiurui144/attune`	`docs/wiki/`	agents/architecture/benchmarks/chat/faq/index/llm-setup/plugins/privacy/quickstart/wizard + sources/{email,index,local-files,rss,webdav}	16 md	✅ added	`21f29da` (branch `develop`)
`qiurui144/attune-enterprise`	`docs/wiki/`	index + guide/{ai-chat,documents,feishu-bot,rpa,skills} + admin/index	7 md	✅ added	`b06cdec` (branch `main`)
`qiurui144/attune-pluginhub`	`docs/wiki/`	index + attune-integration	2 md	✅ added	`5c64171` (branch `master`)

设计决策:内容放在 docs/wiki/ 子目录(不是产品仓 docs/ 根),保留各产品自有 dev docs(如 attune docs/INSTALL.md / docs/SECURITY.md 等 30+ md) 与 wiki 用户文档物理隔离,避免互相干扰。

2. wiki-portal 仓变更

2.1 `.gitmodules` 新增 3 个 submodule

[submodule "external/attune"]
	path = external/attune
	url = https://github.com/qiurui144/attune.git
	branch = develop
[submodule "external/attune-enterprise"]
	path = external/attune-enterprise
	url = https://github.com/qiurui144/attune-enterprise.git
	branch = main
[submodule "external/attune-pluginhub"]
	path = external/attune-pluginhub
	url = https://github.com/qiurui144/attune-pluginhub.git

Pin (实测 2026-05-24 11:20):

external/attune @ 361382d (branch develop)
external/attune-enterprise @ b06cdec (branch main)
external/attune-pluginhub @ 5c64171 (branch master)

2.2 Docusaurus 多 plugin-content-docs 实例

docusaurus.config.ts plugins[] 添加 3 个 @docusaurus/plugin-content-docs 实例,各自指向 external/<repo>/docs/wiki/:

Plugin id	`path`	`routeBasePath`	`sidebarPath`
`default` (classic preset)	`docs`	`/`	`./sidebars.ts`
`attune`	`external/attune/docs/wiki`	`attune`	`./sidebars-attune.ts`
`lawcontrol`	`external/attune-enterprise/docs/wiki`	`lawcontrol`	`./sidebars-lawcontrol.ts`
`pluginhub`	`external/attune-pluginhub/docs/wiki`	`pluginhub`	`./sidebars-pluginhub.ts`

navbar.items 改为 5 tab:首页 / Attune / Attune Enterprise / PluginHub / 硬件 & 计划。

2.3 删除 wiki-portal 内 `docs/{attune,lawcontrol,pluginhub}/`

25 md 全部 git rm (内容已在产品仓的 docs/wiki/)。

2.4 `wiki-deploy.yml` 多 trigger + submodule update

on:
  push:
    branches: [main, master, chore/wiki-portal-rebrand]
  repository_dispatch:
    types: [wiki-content-update]
  workflow_dispatch: ...

concurrency:
  group: wiki-deploy
  cancel-in-progress: false

新增步骤:

actions/checkout@v4 加 submodules: recursive
新 step git submodule update --remote --recursive 拉各 submodule 跟踪分支 (branch = 配置) 最新 HEAD
新 step Log dispatch source (debug payload 信息)
生产 SSH deploy 加 git submodule sync --recursive + git submodule update --init --recursive --remote

2.5 各产品仓 `.github/workflows/wiki-dispatch.yml`

on:
  push:
    branches: [main, master, develop]
    paths: ['docs/**']

jobs:
  trigger-wiki-rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Build dispatch payload
        env: { SOURCE_REPO: ..., COMMIT_SHA: ..., REF_NAME: ... }
        run: jq -n ... > payload.json
      - name: Trigger wiki-portal rebuild
        env: { DISPATCH_TOKEN: ${{ secrets.WIKI_PORTAL_DISPATCH_TOKEN }} }
        run: curl -sSf -X POST ... /repos/qiurui144/wiki-portal/dispatches

per spec §5.1 安全考虑:外部 context (github.repository / sha / ref) 走 env -> jq 转 JSON,不直接拼 shell;dispatch token 走 env 不直接 inline。

测试结果

Build 测试 (2026-05-24 wiki-web 本地)

$ npm run build
✓ Server compiled in 6.05s
✓ Client compiled in 9.71s
✓ Generated static files in "build"
✓ [en] Generated static files in "build/en"

产物 paths 验证:

build/attune/{agents,architecture,benchmarks,chat,faq,index.html,llm-setup,plugins,privacy,quickstart,wizard,sources/}
build/lawcontrol/{admin,guide,index.html}
build/pluginhub/{attune-integration,index.html}
build/{hardware,software,plans,getting-started,download,index.html}
build/en/{attune,lawcontrol,pluginhub,...}  (英文 locale)

5 navbar tab 全部生成 OK。

警告 (非阻断)

一个 pre-existing 跨链接 anchor 在 attune/agents 引到 /attune/architecture#reliability-framework-v10,该 heading 不存在。 follow-up:attune docs owner 单独修(不属 Phase B 范围)。

User Action Required

1. 配置各产品仓 secret `WIKI_PORTAL_DISPATCH_TOKEN`

每个产品仓 Settings -> Secrets and variables -> Actions -> New repository secret:

Name: WIKI_PORTAL_DISPATCH_TOKEN
Value: GitHub Personal Access Token (classic, repo scope) 或 fine-grained PAT 仅对 qiurui144/wiki-portal 有 Actions: write + Contents: read 权限

配置目标仓 (3 个):

2. (可选) 设置 GitHub organization-level secret 共享

若 5 个项目都用同一 token 可在 organization secret 一次配 (per spec R3):

https://github.com/organizations//settings/secrets/actions

3. 验证 end-to-end

配置完 secret 后:

在任一产品仓 push 一个 docs/wiki/ 改动 (例如 typo 修正)
看产品仓 Actions tab 是否 wiki-dispatch workflow 成功
看 wiki-portal Actions tab 是否被 repository_dispatch 触发 build
7 min 内 https://wiki.attune.ai 应见更新

与 Phase C-F 衔接

Phase B 完成内容:

✅ 3 产品 docs 抽出到对应产品仓
✅ wiki-portal 多 submodule 多 plugin 结构
✅ repository_dispatch 协议双端落地

Phase C-F 后续工作 (spec §10):

Phase C: 完整 submodule pin 节奏 + sidebar 经更多产品验证
Phase D: 各项目仓加 wiki-dispatch.yml 已在 Phase B 完成 (合并),无需单独 Phase D
Phase E: cloud 仓 .gitmodules 同步更新 wiki-portal pin (per #87 cloud-wiki 部署)
Phase F: 1 周观察期后,wiki-portal 仓内 docs/{attune,lawcontrol,pluginhub}/ 已删除 (Phase B 已 git rm,observation window 完后 force-delete from cache 即可,但不影响功能)

Defer 给后续 plan:

K3 一体机 hardware/software/getting-started 是否移到 KVM 仓 (spec 决策点)
attune-pro 私有商业仓是否公开 wiki tab
RV 工作区是否单独 tab

风险记录 (实测)

风险 (spec R 编号)	实测情况
R2 (link references)	实测 6 处跨 tab `../plans/` `../pluginhub/` 链接,已在 attune 仓 commit 21f29da 全部改为绝对 path `/plans/attune-pricing` 与 `/pluginhub/`;wiki-portal 自己的 `docs/index.md` + `docs/plans/attune-pricing.md` 也同样改成绝对 path
R3 (token 管理)	User action 需手动配 3 个 secret;若 organization secret 一次配可省
R4 (build 时间)	实测多 plugin instance 后 build 6-10s,无显著上升 (vs Phase A 单 plugin ~3s)
R6 (lawcontrol rename 时序)	已与 #92 协同:Phase A 完成 GH rename 后 Phase B submodule URL 直接指向 `attune-enterprise.git`,无 url 二次迁移
R8 (submodule pin 更新)	`wiki-deploy.yml` 已加 `git submodule update --remote --recursive`,每次 deploy 自动拉最新

变更记录

2026-05-24: Phase B 实施落盘 (本仓 docusaurus.config.ts + sidebars-*.ts + wiki-deploy.yml + .gitmodules + 删 docs/{attune,lawcontrol,pluginhub}/;3 产品仓 commit docs/wiki/ + wiki-dispatch.yml)

目标回顾​

实施清单​

1. 各产品仓 add docs/wiki/ + workflow​

2. wiki-portal 仓变更​

2.1 .gitmodules 新增 3 个 submodule​

2.2 Docusaurus 多 plugin-content-docs 实例​

2.3 删除 wiki-portal 内 docs/{attune,lawcontrol,pluginhub}/​

2.4 wiki-deploy.yml 多 trigger + submodule update​

2.5 各产品仓 .github/workflows/wiki-dispatch.yml​

测试结果​

Build 测试 (2026-05-24 wiki-web 本地)​

警告 (非阻断)​

User Action Required​

1. 配置各产品仓 secret WIKI_PORTAL_DISPATCH_TOKEN​

2. (可选) 设置 GitHub organization-level secret 共享​

3. 验证 end-to-end​

与 Phase C-F 衔接​

风险记录 (实测)​

变更记录​