Armor/KSP_project

Fork 0

Files

T

Armor e6be6058a5 docs: add project handover guides

2026-05-28 11:33:19 +08:00

20 KiB

Raw Permalink Blame History

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 条目通常按以下顺序生产：

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

4.1 Brainstorming 阶段

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

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

写作时先确定：

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

4.2 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

导入脚本：

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 模型。示例只展示方法，不包含任何凭据：

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() 会读取：

PGHOST
PGPORT
PGUSER
PGPASSWORD
WIKIDATABASE 或 PGDATABASE

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

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

6.2 Wiki.js 登录配置

发布脚本读取：

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：

http://192.168.195.241:38353

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

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，结束后自动移除权限。

常用发布命令模板：

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 发布涉及两层权限：

用户组 permissions。
Page Rule roles。

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

write:pages
manage:pages

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

--temporary-manage-system

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

temporary_manage_system_removed=True

8. 图片资产上传和验证

核心脚本：scripts/wiki_upload_assets.py

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

示例：

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 设置为：

/wiki/data/storage

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

10. 资产清理与应急嵌图

10.1 清理错放资产

脚本：scripts/wiki_cleanup_misplaced_assets.py

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

Dry-run：

python scripts/wiki_cleanup_misplaced_assets.py

执行：

python scripts/wiki_cleanup_misplaced_assets.py --delete

验证：

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。

嵌入：

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

恢复为资产 URL：

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

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

11. 本地验证清单

发布前至少检查：

# 诊断 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：

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

常见 must_contain：

回声级航天飞机
进取级航天飞机
秃鹫航天飞机
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 页面更新但前台不变

处理顺序：

确认 pages.update 成功。
确认 pages.render 成功。
确认 pages.flushCache 成功。
用 cache-bust URL 访问。
必要时重启 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. 新人接手建议

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

20 KiB Raw Permalink Blame History Unescape Escape