Files

T

Armor cda0db06db feat: add wiki publishing tooling

2026-05-28 11:32:36 +08:00

4.9 KiB

Raw Blame History

name, description, argument-hint

name	description	argument-hint
wiki-backend-update	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.	path=<wiki path> content-file=<local file> title=<title>

Wiki Backend Update

使用场景

当任务涉及 Wiki.js 页面后台更新、直接写库后的页面刷新、把本地 Markdown/HTML 发布到 Wiki.js、或处理“编辑/历史记录已更新但前台仍显示旧内容”的问题时，必须使用此流程。

必走流程

先确认本地内容文件是最终版本，并运行适合该文件的基本检查。
使用 .env 读取 Wiki.js PostgreSQL 与登录信息；不要打印密码、JWT 或完整账号信息。
不要只改 pages.content/render/toc 就结束。直接 DB 更新后必须走官方 GraphQL 刷新链路。
确认登录账号所在组的命中 Page Rule 包含 write:pages 和 manage:pages。组级权限有这两个值但 Page Rule 没有时，pages.update 仍会返回 PageUpdateForbidden。
调用官方 pages.update 时必须传 tags，即使页面没有标签也传 tags: []，否则 Wiki.js resolver 可能报 Cannot read properties of undefined (reading 'map')。
pages.render 与 pages.flushCache 需要 manage:system。使用前必须 ask user；若获准，临时授予，完成后立即移除。
前台验证必须检查普通页面 URL 已包含新内容且不包含旧占位文本。若工具返回疑似缓存结果，用终端无缓存抓取复核。
上传图片等资产后，必须直接验证资源 URL 返回 200 和正确 Content-Type；不要只依赖 assets / assetData 数据库记录。
清理所有 _tmp_ 临时脚本或输出文件。
任务收尾必须使用 ask user，确认页面状态或下一步。

固化脚本

使用仓库脚本 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。它会通过 /u 上传端点写入既有资源文件夹，并验证 assets / assetData 记录。上传后仍需单独抓取资源 URL；当前实例存在部分 DB-backed assets 直连 500 的情况，页面交付前必须确认图片在前台实际可见。若资源端未修好，可临时使用压缩图片 data: URI，并保留 data-wiki-asset 标记以便之后切回正式资源 URL。

示例命令

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，再使用：

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 容器。

4.9 KiB Raw Blame History