feat: add wiki publishing tooling

2026-05-28 11:32:36 +08:00
parent fee9b13ada
commit cda0db06db
10 changed files with 1558 additions and 0 deletions
@@ -0,0 +1,80 @@
+---
+name: wiki-backend-update
+description: "Use when: updating Wiki.js pages from local Markdown/HTML, writing Wiki.js pages through backend/database workflows, fixing stale Wiki.js frontend cache after direct DB edits, refreshing pages.update/pages.render/pages.flushCache, or publishing KSP wiki articles. Requires scripts/wiki_update_page.py and final frontend verification."
+argument-hint: "path=<wiki path> content-file=<local file> title=<title>"
+---
+
+# Wiki Backend Update
+
+## 使用场景
+
+当任务涉及 Wiki.js 页面后台更新、直接写库后的页面刷新、把本地 Markdown/HTML 发布到 Wiki.js、或处理“编辑/历史记录已更新但前台仍显示旧内容”的问题时，必须使用此流程。
+
+## 必走流程
+
+1. 先确认本地内容文件是最终版本，并运行适合该文件的基本检查。
+2. 使用 `.env` 读取 Wiki.js PostgreSQL 与登录信息；不要打印密码、JWT 或完整账号信息。
+3. 不要只改 `pages.content/render/toc` 就结束。直接 DB 更新后必须走官方 GraphQL 刷新链路。
+4. 确认登录账号所在组的命中 Page Rule 包含 `write:pages` 和 `manage:pages`。组级权限有这两个值但 Page Rule 没有时，`pages.update` 仍会返回 `PageUpdateForbidden`。
+5. 调用官方 `pages.update` 时必须传 `tags`，即使页面没有标签也传 `tags: []`，否则 Wiki.js resolver 可能报 `Cannot read properties of undefined (reading 'map')`。
+6. `pages.render` 与 `pages.flushCache` 需要 `manage:system`。使用前必须 ask user；若获准，临时授予，完成后立即移除。
+7. 前台验证必须检查普通页面 URL 已包含新内容且不包含旧占位文本。若工具返回疑似缓存结果，用终端无缓存抓取复核。
+8. 上传图片等资产后，必须直接验证资源 URL 返回 200 和正确 Content-Type；不要只依赖 `assets` / `assetData` 数据库记录。
+9. 清理所有 `_tmp_` 临时脚本或输出文件。
+10. 任务收尾必须使用 ask user，确认页面状态或下一步。
+
+## 固化脚本
+
+使用仓库脚本 [scripts/wiki_update_page.py](../../../scripts/wiki_update_page.py)。它会：
+
+- 读取 `.env` 中的 `PGHOST`、`PGUSER`、`PGPASSWORD`、`WIKIDATABASE`/`PGDATABASE` 和 Wiki 登录信息。
+- 解析目标页面并保留现有 tags。
+- 检查命中 Page Rule 是否具备 `write:pages` / `manage:pages`。
+- 通过官方 GraphQL 执行 `pages.update`、`pages.render`、`pages.flushCache`。
+- 对 HTML 页面使用 `--extract-style-to-script-css`，把本地 `<style>` 发布到 Wiki.js 页面 CSS 字段，避免 Wiki.js 过滤正文中的样式。
+- 如果 HTML 页面包含交互脚本，使用 `--extract-script-to-script-js`，把第一个 `<script>` 发布到 Wiki.js 页面 JavaScript 字段，避免内联脚本留在正文中。
+- 可在用户授权后临时添加 `manage:system`，并在 `finally` 中移除。
+- 抓取前台页面并验证 `--must-contain` / `--must-not-contain`。
+
+上传 Wiki.js 资产使用 [scripts/wiki_upload_assets.py](../../../scripts/wiki_upload_assets.py)。它会通过 `/u` 上传端点写入既有资源文件夹，并验证 `assets` / `assetData` 记录。上传后仍需单独抓取资源 URL；当前实例存在部分 DB-backed assets 直连 500 的情况，页面交付前必须确认图片在前台实际可见。若资源端未修好，可临时使用压缩图片 `data:` URI，并保留 `data-wiki-asset` 标记以便之后切回正式资源 URL。
+
+## 示例命令
+
+```powershell
+python scripts\wiki_update_page.py `
+  --path home/Space_Shuttles/Vulture_Shuttle/html_test `
+  --content-file vulture_shuttle_html_test.html `
+  --title "HTML version" `
+  --editor code `
+  --extract-style-to-script-css `
+  --extract-script-to-script-js `
+  --temporary-manage-system `
+  --must-contain "秃鹫航天飞机" `
+  --must-not-contain "# Title" `
+  --must-not-contain "Some text here"
+```
+
+如果命中 Page Rule 缺少写权限，先 ask user，再使用：
+
+```powershell
+python scripts\wiki_update_page.py `
+  --path home/Space_Shuttles/Vulture_Shuttle/html_test `
+  --content-file vulture_shuttle_html_test.html `
+  --title "HTML version" `
+  --editor code `
+  --extract-style-to-script-css `
+  --extract-script-to-script-js `
+  --patch-page-rule `
+  --temporary-manage-system `
+  --must-contain "秃鹫航天飞机" `
+  --must-not-contain "# Title" `
+  --must-not-contain "Some text here"
+```
+
+## 失败判断
+
+- `PageUpdateForbidden`: 命中 Page Rule 仍缺少 `write:pages` 或路径规则没匹配。
+- `Cannot read properties of undefined (reading 'map')`: `pages.update` 没有传 `tags`。
+- `pages.render` 或 `pages.flushCache` 为 `Forbidden`: 缺少 `manage:system`，或权限缓存未刷新。
+- 上传资产后数据库记录存在但 URL 返回 500：资源服务/cache 层异常，DB 验证不够；先直接验证图片 URL，必要时临时使用 `data:` URI 保证页面可见。
+- 编辑页/历史记录正确但前台旧内容：必须执行 render/flushCache，必要时重启 Wiki.js 容器。