KSP_project/handover/ksp_wiki_handover.md

# KSP Wiki.js 工作流交接文档

最后更新：2026-05-28

本文档介绍 KSP Wiki 内容生产与 Wiki.js 发布工作流。后台项目本身、数据库模型和 Mission Ops 功能见 `handover/operation_hangar_handover.md`。

## 1. 这套工作流是什么

KSP Wiki 工作流用于把 KSP Operation Hangar 中整理出的航天器设定、任务记录和运营数据，转化为 Wiki.js 上的百科条目。它不是单纯写 Markdown，而是一套从设定讨论、本地 HTML 编写、图片资产上传、页面发布、缓存刷新到前台验证的完整流程。

当前主要维护对象包括：

- 航天飞机条目：秃鹫、回声、进取。
- 星际探索母舰条目：羲和、万星源 / Stellaria。
- 航天器图片资产。
- Wiki.js 页面 CSS、页面 JS 和图片点击放大 lightbox。

核心原则：

- 本地 HTML 是事实来源，先在仓库内修改，再发布到 Wiki.js。
- 发布必须通过脚本走 Wiki.js GraphQL `pages.update`/`pages.create`，并执行 render/flushCache。
- 发布后必须做前台验证，不只看数据库。
- 涉及临时 `manage:system` 权限时必须先向用户确认，并确保脚本结束后移除。
- 不打印 `.env`、密码、JWT 或数据库连接串。

## 2. 本地内容文件

主要 Wiki HTML 位于 `data/wiki/`：

| 文件 | 语言 | 页面 |
| --- | --- | --- |
| `data/wiki/vulture_shuttle_zh.html` | zh | 秃鹫航天飞机 |
| `data/wiki/vulture_shuttle_en.html` | en | Vulture Shuttle |
| `data/wiki/echo_shuttle_zh.html` | zh | 回声级航天飞机 |
| `data/wiki/echo_shuttle_en.html` | en | Echo Shuttle |
| `data/wiki/enterprise_shuttle_zh.html` | zh | 进取级航天飞机 |
| `data/wiki/enterprise_shuttle_en.html` | en | Enterprise Shuttle |
| `data/wiki/xihe_mothership_zh.html` | zh | 羲和级星际探索母舰 |
| `data/wiki/xihe_mothership_en.html` | en | Xihe-class interplanetary exploration mothership |
| `data/wiki/wanxingyuan_mothership_zh.html` | zh | 万星源级星际探索母舰 |
| `data/wiki/stellaria_mothership_en.html` | en | Stellaria-class interplanetary exploration mothership |

根目录还有早期/参考文件：

- `vulture_shuttle.md`：秃鹫中文长稿参考。
- `vulture_shuttle_html_test.html`：早期 HTML 测试稿。

图片和资源通常位于 `data/KSP/` 下的 wiki 上传目录，例如：

- `data/KSP/wiki-upload/`
- `data/KSP/wiki-upload-echo-current/`
- `data/KSP/wiki-upload-enterprise-current/`
- `data/KSP/wiki-upload-png/`
- `data/KSP/wiki-embed-current/`

## 3. 当前已经完成的内容

### 3.1 航天飞机页面

已完成并发布的主要页面：

| 页面 | Locale | 已知 Page ID | 路径 |
| --- | --- | --- | --- |
| 秃鹫航天飞机 | zh | 18 | `home/Space_Shuttles/Vulture_Shuttle` |
| Vulture Shuttle | en | 21 | `home/Space_Shuttles/Vulture_Shuttle` |
| 回声级航天飞机 | zh | 8 | `home/Space_Shuttles/Echo_Shuttle` |
| Echo Shuttle | en | 22 | `home/Space_Shuttles/Echo_Shuttle` |
| 进取级航天飞机 | zh | 7 | `home/Space_Shuttles/Enterprise_Shuttle` |
| Enterprise Shuttle | en | 23 | `home/Space_Shuttles/Enterprise_Shuttle` |

内容状态：

- Vulture 中文页已扩展为大型百科条目，包含设计、系统组成、任务剖面、运用历史、飞行次数、安全事件、机队、成本和技术参数。
- Vulture 英文页已修正旧稿措辞，去掉 `English draft`、`local Chinese article` 等草稿痕迹，并补齐 Xihe/Stellaria 互链。
- Echo/Enterprise 中文页已扩写到 Vulture 级别的丰富度，包含背景、设计需求、系统组成、推进、电源、整备、任务剖面、母舰支援、运用历史、机队编号、安全事件、经济性和评价。
- Echo/Enterprise 中文页当前有本地润色版，用户要求先本地保存，暂不发布云端。

### 3.2 母舰页面

已完成并发布的主要页面：

| 页面 | Locale | 已知 Page ID | 路径 |
| --- | --- | --- | --- |
| 羲和级星际探索母舰 | zh | 13 | `home/Exploration_Motherships/Xihe/XH-01` 或相关 Xihe 路径 |
| Xihe-class interplanetary exploration mothership | en | 24 | `home/Exploration_Motherships/Xihe` |
| 万星源级星际探索母舰 | zh | 15 | `home/Exploration_Motherships/Stellaria` |
| Stellaria-class interplanetary exploration mothership | en | 25 | `home/Exploration_Motherships/Stellaria` |

关键设定：

- XH-02 是太白 / Taibai。
- XH-03 是常曦 / Changxi，不是 Zhuque。
- Stellaria 是万星源级英文名。
- ST-01 与 ST-02 是万星源级早期高速度增量构型。
- 当前中文统一 ST-02 为“万星源NEXT号（ST-02）”。

### 3.3 术语和设定统一

已清理过的错误或旧稿词：

- `English draft`
- `local Chinese article`
- `XH-03 Zhuque`
- `Zhuque` / `朱雀`
- `克里斯滕号（ST-02）`

当前推荐术语：

| 中文 | 英文 | 说明 |
| --- | --- | --- |
| 秃鹫航天飞机 | Vulture Shuttle | 重载航天飞机主线 |
| 秃鹫航天飞机改进乙型 | Vulture Shuttle Block 2 | 高能推进重载干线 |
| 回声级航天飞机 | Echo Shuttle | 母舰随舰摆渡航天飞机 |
| 进取级航天飞机 | Enterprise Shuttle | 中型客货运输与母舰近程支援 |
| 羲和级星际探索母舰 | Xihe-class interplanetary exploration mothership | 第一代探索母舰 |
| 万星源级星际探索母舰 | Stellaria-class interplanetary exploration mothership | 后续大型探索母舰 |
| 摆渡航天飞机 | ferry shuttle | 母舰目标系统末端运输载具 |

## 4. 从 brainstorming 到 HTML 的写作流程

Wiki 条目通常按以下顺序生产：

1. 与用户确认设定定位。
2. 建立条目骨架。
3. 从 KSP Operation Hangar 后台读取任务日志和运营上下文。
4. 写本地 HTML。
5. 本地润色和术语一致性扫描。
6. 用户确认。
7. 发布到 Wiki.js。
8. 前台验证。

### 4.1 Brainstorming 阶段

先确认页面的百科定位，而不是直接堆设定。例如 Echo 与 Enterprise 的分工：

- Echo：随舰远征、双艇互备、大气天体探索、卫星间摆渡、小型样品和应急撤离。
- Enterprise：中型节点、25 吨级货运、22 人短期运输、母舰建造/改装/补给、返港卸载。
- Vulture Block 2：重载地月干线，不是 Echo/Enterprise 的简单替代。

写作时先确定：

- 它属于哪一代技术路线。
- 与前代或并行型号的关系。
- 在航天运输体系中的层级。
- 不承担哪些任务。
- 与任务日志中的运营记录如何对应。

### 4.2 HTML 结构

本地 HTML 通常包含：

```html
<style>
  ...页面 CSS...
</style>
<article class="mw-parser-output wiki-article">
  <h1>...</h1>
  <table class="infobox">...</table>
  <nav class="toc">...</nav>
  ...正文...
</article>
<script>
  ...lightbox JS...
</script>
```

发布时使用 `--extract-style-to-script-css` 和 `--extract-script-to-script-js`，脚本会把第一个 `<style>` 提取到 Wiki.js 页面 CSS，把第一个 `<script>` 提取到页面 JS。

注意：`scriptJs` 必须保留完整 `<script>...</script>` 包裹。Wiki.js 会把它原样注入页面 body。

### 4.3 常用条目章节

航天飞机页面建议包含：

- 导语。
- 背景与发展。
- 设计需求与方案取舍。
- 设计。
- 推进与电源。
- 地面设施与整备。
- 任务剖面。
- 星际探索母舰支援。
- 运营与任务分工。
- 与相关型号的关系。
- 运用历史。
- 机队与编号。
- 安全与飞行事件。
- 成本与经济性。
- 技术参数。
- 评价。
- 图片。
- 相关条目。

母舰页面建议包含：

- 导语。
- 发展背景。
- 设计。
- 推进、电源、生命保障。
- Ferry shuttles and external berthing。
- 任务运营体系。
- 建造与服役。
- 安全与运行约束。
- 舰队与后续发展。
- 技术参数。
- 相关条目。

### 4.4 文风要求

中文稿应尽量接近百科风格：

- 使用“该级”“该型号”“该系统”代替过多“它”。
- 少用“因此、事实上、本质上、可以说、最适合、发现空位”等解释腔。
- 以定位、任务、约束、适用场景和限制组织内容。
- 不写“本文”“本稿”“英文草稿”“中文文章”等编辑过程词。
- 避免口语化转折，如“不是 A，而是 B”反复出现。

## 5. 如何从 KSP Operation Hangar 读取日志和运营上下文

Wiki 内容中的任务史、母舰定位和运营流程应尽量来自后台数据库或后台页面，不只凭设定脑补。

### 5.1 数据来源

后台相关模型：

- `Asset`
- `AssetLogEntry`
- `AssetStateNode`

导入脚本：

```powershell
python scripts/import_log_book.py
```

该脚本读取 `log_book.xlsx`，将每个资产 sheet 导入数据库。导入后可在后台查看：

- `/assets`
- `/assets/<asset_id>`
- `/missions`
- `/mission-preview/status-board`
- `/mission-preview/location-board`
- `/mission-preview/timeline`

### 5.2 后台页面读取方式

常用读取路径：

- `/assets`：看资产清单、当前状态、未来事件。
- `/assets/<uuid>`：看单个资产全部日志和 State Nodes。
- `/missions`：按 mission label 分组。
- `/mission-preview/timeline`：按模拟时间看状态区间与事件节点。
- `/mission-preview/status-board`：看当前状态分组。
- `/mission-preview/location-board`：看地点/区域分组。

撰写 Wiki 时，先在这些页面确认：

- 资产名称和编号。
- 任务时间窗口。
- 任务地点。
- 任务标签。
- 当前/未来状态。
- 是否存在 State Nodes 细节。

### 5.3 代码层读取方式

如果需要在 Flask 环境中直接查数据，可使用应用上下文与 SQLAlchemy 模型。示例只展示方法，不包含任何凭据：

```python
from app import create_app
from app.extensions import db
from app.models import Asset

app = create_app()
with app.app_context():
    assets = Asset.query.order_by(Asset.name.asc()).all()
    for asset in assets:
        print(asset.name, asset.asset_type, len(asset.log_entries))
```

注意：查询真实数据库前确认 `.env` 指向正确的 `PGDATABASE`。不要把真实查询结果中的敏感配置、账号或连接串写入文档。

### 5.4 当前从后台继承到 Wiki 的典型设定

- XH-02 Taibai：火星一号补给转移。
- XH-03 Changxi：星港木星中继部署改装。
- ST-01 / ST-02：万星源级早期高速度增量构型。
- Echo：母舰常用随舰摆渡航天飞机，可两艘外部停泊。
- Enterprise：母舰建造、改装、补给和近程接驳，不作为标准远征 ferry shuttle。

## 6. Wiki.js 配置读取方式

Wiki 发布脚本读取根目录 `.env`，不是 `.env.example`。示例键名在 `.env.example` 中。

### 6.1 Wiki.js 数据库配置

`scripts/wiki_update_page.py` 的 `connect_info()` 会读取：

```text
PGHOST
PGPORT
PGUSER
PGPASSWORD
WIKIDATABASE 或 PGDATABASE
```

优先使用 `WIKIDATABASE`，若不存在则退回 `PGDATABASE`。

这意味着同一个 `.env` 可以同时服务后台数据库和 Wiki 数据库，但要特别注意不要把后台业务库和 Wiki.js 库混淆。

### 6.2 Wiki.js 登录配置

发布脚本读取：

```text
wiki_useremail
wiki_username
wiki_password
```

脚本会依次尝试 `wiki_useremail`、`wiki_username` 登录 Wiki.js GraphQL，成功后得到 JWT。脚本输出只显示 `token_received=True/False`，不要打印 JWT。

### 6.3 Wiki URL

默认 Wiki URL：

```text
http://192.168.195.241:38353
```

也可通过环境变量或参数指定：

```text
WIKI_URL=http://...
--wiki-url http://...
```

## 7. 页面发布脚本

核心脚本：`scripts/wiki_update_page.py`

功能：

- 从 `.env` 读取 Wiki.js DB 和登录信息。
- 解析本地 HTML/Markdown。
- 提取 `<style>` 到页面 CSS。
- 提取 `<script>` 到页面 JS。
- 保留现有 tags。
- 检查 Page Rule 是否匹配页面路径。
- 通过 GraphQL 执行 `pages.update` 或 `pages.create`。
- 调用 `pages.render`。
- 调用 `pages.flushCache`。
- 前台 HTTP GET 验证 must/must_not 文本。
- 如使用 `--temporary-manage-system`，结束后自动移除权限。

常用发布命令模板：

```powershell
python scripts/wiki_update_page.py `
  --path home/Space_Shuttles/Echo_Shuttle `
  --content-file data/wiki/echo_shuttle_zh.html `
  --locale zh `
  --title "回声级航天飞机" `
  --description "全可重复使用轻型航天飞机" `
  --editor markdown `
  --create-if-missing `
  --extract-style-to-script-css `
  --extract-script-to-script-js `
  --temporary-manage-system `
  --must-contain "回声级航天飞机" `
  --must-not-contain "English draft" `
  --must-not-contain "Zhuque"
```

发布前必须确认：

- 用户同意发布。
- 用户同意临时 `manage:system` 权限。
- 本地 HTML 已通过结构检查。
- must/must_not 包含足够关键文本。

### 7.1 关键参数说明

| 参数 | 说明 |
| --- | --- |
| `--path` | Wiki.js 页面路径，不带 locale |
| `--content-file` | 本地 HTML/Markdown 文件 |
| `--locale` | `zh` 或 `en` |
| `--title` | Wiki 页面标题 |
| `--description` | Wiki 页面描述 |
| `--editor` | 通常用 `markdown` |
| `--create-if-missing` | 页面不存在时创建 |
| `--extract-style-to-script-css` | 提取 `<style>` 到页面 CSS |
| `--extract-script-to-script-js` | 提取 `<script>` 到页面 JS |
| `--temporary-manage-system` | 临时授予 render/flush 所需系统权限 |
| `--must-contain` | 前台必须存在的文本，可重复 |
| `--must-not-contain` | 前台不得存在的文本，可重复 |

### 7.2 权限流程

Wiki.js 发布涉及两层权限：

1. 用户组 permissions。
2. Page Rule roles。

`wiki_update_page.py` 会检查匹配 Page Rule 是否有：

```text
write:pages
manage:pages
```

`pages.render` 和 `pages.flushCache` 需要 `manage:system`。如果用户授权，使用：

```text
--temporary-manage-system
```

脚本会在 finally 中移除该权限。发布后要看输出是否有：

```text
temporary_manage_system_removed=True
```

## 8. 图片资产上传和验证

核心脚本：`scripts/wiki_upload_assets.py`

用途：上传图片到 Wiki.js，并验证 URL 可访问。

示例：

```powershell
python scripts/wiki_upload_assets.py `
  --source-dir data/KSP/wiki-upload-echo-current `
  --file echo_mk2_cross_section.png `
  --folder-slug echo `
  --skip-existing
```

常用 folder slug：

| slug | 用途 | 已知文件夹 ID |
| --- | --- | --- |
| `enterprise` | Enterprise 图片 | 1 |
| `echo` | Echo 图片 | 2 |
| `vulture` | Vulture 图片 | 4 |

验证原则：

- 上传后必须用 HTTP GET 验证。
- 不要只用 HEAD。
- 不要只查 Wiki.js DB。
- 需要确认 HTTP 200 和 `Content-Type: image/*`。

已知资产问题：Wiki.js disk storage target 的 `config.path` 曾为空，导致资产 URL 500。修复方式是把 disk path 设置为：

```text
/wiki/data/storage
```

然后执行 storage dump。该操作属于系统级维护，需要临时 `manage:system` 并在完成后移除。

## 9. Lightbox 工作流

相关脚本：

- `scripts/wiki_apply_image_lightbox.py`
- `scripts/wiki_verify_lightbox.py`

### 9.1 注入 Lightbox

`wiki_apply_image_lightbox.py` 会处理 6 个航天飞机页面：

- Vulture zh/en。
- Echo zh/en。
- Enterprise zh/en。

它查找：

```html
<img data-wiki-asset="...">
```

并注入统一 CSS/JS，使图片点击后出现放大预览。

### 9.2 验证 Lightbox

运行：

```powershell
python scripts/wiki_verify_lightbox.py
```

验证步骤：

- 打开页面。
- 检查 article 是否安装 lightbox。
- 点击第一张 `img[data-wiki-asset]`。
- 检查 `.wiki-image-lightbox` 显示。
- 检查 preview image 和 caption。
- 按 Escape 关闭。

## 10. 资产清理与应急嵌图

### 10.1 清理错放资产

脚本：`scripts/wiki_cleanup_misplaced_assets.py`

用途：删除误放到 `/vulture` 下的 Echo/Enterprise 图片。

Dry-run：

```powershell
python scripts/wiki_cleanup_misplaced_assets.py
```

执行：

```powershell
python scripts/wiki_cleanup_misplaced_assets.py --delete
```

验证：

```powershell
python scripts/wiki_verify_asset_cleanup.py
```

验证内容：

- `/vulture/echo_*` 和 `/vulture/enterprise_*` 不再存在。
- `/echo/...` 和 `/enterprise/...` 正常返回 image。
- `automation` 组不保留 `manage:system`。

### 10.2 应急 base64 图片嵌入

脚本：`scripts/wiki_embed_image_fallbacks.py`

用途：当 Wiki.js 资产服务异常时，把图片转为 data URI 临时嵌入 HTML。

嵌入：

```powershell
python scripts/wiki_embed_image_fallbacks.py `
  --embed-dir data/KSP/wiki-embed-current `
  --max-dimension 1600 `
  --quality 82
```

恢复为资产 URL：

```powershell
python scripts/wiki_embed_image_fallbacks.py --restore-asset-src
```

应急嵌图不是常规发布方式，只在资产服务异常时使用。

## 11. 本地验证清单

发布前至少检查：

```powershell
# 诊断 HTML 文件
# 在 VS Code 中看 Problems，或调用 get_errors

# 风险词搜索
rg "English draft|local Chinese article|Zhuque|朱雀|克里斯滕" data/wiki

# 结构检查
rg "<article|</article>|<script>|</script>" data/wiki/echo_shuttle_zh.html
```

常见 must_not：

```text
English draft
local Chinese article
Zhuque
朱雀
克里斯滕
TODO
placeholder
```

常见 must_contain：

```text
回声级航天飞机
进取级航天飞机
秃鹫航天飞机
XH-03 常曦
万星源NEXT号（ST-02）
Stellaria-class interplanetary exploration mothership
```

## 12. 发布后验证清单

发布脚本自带前台验证，但最好再做一次独立验证：

- 打开带 cache-bust 的前台 URL。
- 确认新段落存在。
- 确认旧词不存在。
- 确认图片显示。
- 点击图片测试 lightbox。
- 确认页面目录、信息框和表格结构正常。

如果工具返回旧内容，但发布脚本显示成功，可用直接 HTTP cache-bust 验证。之前曾出现网页抓取工具返回缓存片段，而真实前台已经更新的情况。

## 13. 常见失败与处理

### 13.1 `PageUpdateForbidden`

原因：

- 用户组权限不足。
- Page Rule 没有命中路径。
- Page Rule 缺 `write:pages` 或 `manage:pages`。

处理：

- 先检查 Wiki.js Groups / Page Rules。
- 如需脚本修补，必须先问用户，再使用 `--patch-page-rule`。

### 13.2 `Forbidden` during render/flush

原因：缺少 `manage:system`。

处理：

- 先问用户。
- 使用 `--temporary-manage-system`。
- 检查输出是否移除权限。

### 13.3 页面更新但前台不变

处理顺序：

1. 确认 `pages.update` 成功。
2. 确认 `pages.render` 成功。
3. 确认 `pages.flushCache` 成功。
4. 用 cache-bust URL 访问。
5. 必要时重启 Wiki.js 容器。

### 13.4 图片 500

可能原因：storage target `disk` 的 `config.path` 为空或存储 dump 不完整。

处理：

- 修复 disk storage path。
- 执行 storage dump。
- 用 GET 验证资产。

### 13.5 Windows PowerShell 中文编码问题

复杂中文命令不要直接写长 here-string。优先：

- 把中文写在 UTF-8 文件中，由脚本读取。
- 或减少命令行中文。
- 避免输出 `.env` 和 token。

## 14. 当前待办

### 内容待办

- 用户当前要求：Echo/Enterprise 中文 HTML 已本地再润色，先不发布，等待用户审阅。
- Echo/Enterprise 英文页可能需要按中文新版再次同步扩写。
- Vulture 英文页仍比中文短很多，后续可按中文结构扩写。
- 母舰页面后续可补充更多图片资产。

### 工程待办

- 为 Wiki 发布命令沉淀更短的 Make/PowerShell wrapper。
- 给 HTML 结构检查写自动脚本。
- 为风险词建立固定检查清单。
- 给 Wiki 页面与本地文件建立 manifest，记录 path、locale、page id、title、description、content-file。
- 将 `LOG_BOOK_ASSET_SPECS` 与 Wiki 内容中资产名称做一致性校验。

## 15. 新人接手建议

1. 先读本文件，再读 `handover/operation_hangar_handover.md`。
2. 打开 `data/wiki/echo_shuttle_zh.html` 和 `data/wiki/enterprise_shuttle_zh.html`，理解当前中文百科风格。
3. 在后台 `/assets`、`/missions`、`/mission-preview/timeline` 查任务日志和模拟时间状态。
4. 修改本地 HTML，不直接改 Wiki.js 数据库。
5. 本地检查 HTML 结构、风险词和图片路径。
6. 发布前向用户确认，尤其是临时 `manage:system`。
7. 使用 `wiki_update_page.py` 发布。
8. 发布后检查 `pages.update`、`pages.render`、`pages.flushCache`、frontend must/must_not。
9. 独立打开前台页面验证内容和图片。
10. 确认临时权限已经移除。