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