export WIKIJS_URL="https://your-wiki.example.com"
export WIKIJS_TOKEN="your_api_key_here"
export WIKIJS_LOCALE="de"  # Optional, default: de

Wiki.js V3 技能 – 全方位 Wiki 管理

替代: wiki-js-v2 (仅页面 + 资源)

🎯 功能特性

功能	V2	V3
页面 (增删改查)	✅	✅
资源 (上传/列表)

✅ | ✅ | | 移动/复制页面 | ❌ | ✅ | | 页面历史 | ❌ | ✅ | | 版本恢复 | ❌ | ✅ | | 渲染 (HTML/PDF) | ❌ | ✅ | | 搜索 (全文 + 标签) | ❌ | ✅ | | 页面树/层级结构 | ❌ | ✅ | | 标签 (增删改查) | ❌ | ✅ | | 资源文件夹 | ✅ | ✅ | | 资源删除 | ❌ | ✅ | | 多语言 | ✅ | ✅ | | 重试 + 退避 | ✅ | ✅ | | 路径优先 + ID | ✅ | ✅ |

---

📦 安装

bash

技能已安装于:

~/.openclaw/workspace/skills/wiki-js-v3/

CLI 包装器 (可选，用于直接终端访问):

chmod +x ~/.openclaw/workspace/skills/wiki-js-v3/bin/wiki.js ln -s ~/.openclaw/workspace/skills/wiki-js-v3/bin/wiki.js ~/.local/bin/wiki

环境变量:
bash
export WIKIJS_URL=https://your-wiki.example.com
export WIKIJSTOKEN=yourapikeyhere
export WIKIJS_LOCALE=de # 可选，默认: de

---

🔧 API 覆盖范围

GraphQL 操作

类别	操作
页面	single, singleByPath, list, create, update, delete, move, render, history, restoreVersion
搜索

search(query, limit) | | 标签 | list, create, delete | | 资源 | list, createFolder, delete |

REST 操作

端点	使用场景
POST /u	文件上传 (multipart/form-data)
GET /f/:hash/:filename

静态资源服务 |

---

📝 CLI 参考

页面

bash

创建或更新 (幂等)

wiki upsert docs/setup Setup Guide @content.md setup,wiki
wiki upsert docs/api API Reference ## Overview\n... api,docs

获取页面内容

wiki get docs/setup wiki get 42 # 按 ID

删除页面

wiki delete docs/old-page wiki delete 42

移动页面 (更改路径)

wiki move docs/old docs/new

复制页面 (创建新页面)

wiki copy docs/template docs/new-page

显示页面历史

wiki history docs/setup

恢复特定版本

wiki restore docs/setup --version=3

渲染页面

wiki render docs/setup --format=html wiki render docs/setup --format=pdf > setup.pdf

搜索

bash

全文搜索

wiki search docker

带标签过滤

wiki search kubernetes --tags=devops,cloud

限制结果数量

wiki search api --limit=50

树形结构 / 层级

bash

列出所有页面

wiki tree

按路径前缀过滤

wiki tree --path=docs

控制深度

wiki tree --depth=5

标签

bash

列出所有标签

wiki tags

创建标签

wiki tags create new-feature

删除标签

wiki tags delete deprecated

资源

bash

列出资源

wiki assets
wiki assets --folder=images
wiki assets --kind=IMAGE

上传文件

wiki upload screenshot.png wiki upload doc.pdf --folder=documents --name=manual.pdf

删除资源

wiki asset-delete 42

创建文件夹

wiki mkdir 0 images Bilder

选项

bash
--pretty, -p 人类可读输出 (默认: JSON)
--locale, -l de 语言覆盖
--private 创建私有页面
--draft 创建未发布页面

---

🔄 错误处理

错误	处理方式
413 Payload Too Large	抛出描述性错误 (页面不会自动分块)
401 Unauthorized

清晰的令牌错误信息 |
| ECONNREFUSED | 自动重试，指数退避 (3次尝试) |
| Timeout | 默认30秒，可通过 WIKIJS_TIMEOUT 配置 |

---

📐 架构

bin/wiki.js
├── GraphQL 客户端 (query, mutation)
├── REST 上传 (form-data)
├── 路径解析 (singleByPath)
├── CLI 解析器 (参数解析)
└── 输出格式化器 (JSON / Pretty)

依赖:

• - 仅 Node.js 内置模块
• form-data 用于文件上传 (按需安装)

---

🔐 安全

• - 令牌仅通过环境变量 (WIKIJS_TOKEN)
• 不记录令牌
• 输入验证 (空字节、大小限制)
• 路径清理 (去除前导 /)

---

📤 示例

创建文档页面

bash

将内容写入文件

cat > /tmp/api.md << EOF

API 参考

认证

所有请求都需要 Bearer 令牌...

端点

• - GET /api/v1/pages - 列出页面
• POST /api/v1/pages - 创建页面

EOF

更新到 Wiki

wiki upsert docs/api API Reference @/tmp/api.md api,reference --pretty

上传截图并嵌入

bash

上传图片

wiki upload screenshot.png --folder=images --name=api-auth-flow.png

输出: {id:47,url:/f/a3f9b2/api-auth-flow.png,...}

创建包含嵌入图片的页面

wiki upsert docs/api-auth API Authentication api

通过脚本批量更新

bash
#!/bin/bash
for file in docs/*.md; do
name=$(basename $file .md)
wiki upsert docs/$name $name Documentation @$file docs
done

---

🆚 从 V2 迁移

V2 命令	V3 命令
wiki-v2 upsert ...	wiki upsert ...
wiki-v2 get ...

wiki get ... |
| wiki-v2 delete ... | wiki delete ... |
| wiki-v2 search ... | wiki search ... |
| wiki-v2 upload ... | wiki upload ... |
| wiki-v2 assets ... | wiki assets ... |
| wiki-v2 mkdir ... | wiki mkdir ... |
| – | wiki move ... |
| – | wiki copy ... |
| – | wiki history ... |
| – | wiki restore ... |
| – | wiki render ... |
| – | wiki tree ... |
| – | wiki tags ... |
| – | wiki asset-delete ... |

---

🐛 故障排除

问题	解决方案
WIKIJSTOKEN not set	export WIKIJSTOKEN=...
Page not found

检查路径 (无前导 /) |
| GraphQL Error: Unauthorized | 令牌无效或已过期 |
| GraphQL Error: Forbidden | API 密钥缺少写入权限 – 在管理界面创建具有写入权限的新密钥 |
| Upload failed: 413 | 文件过大 (>10MB) |
| Timeout after 30s | 增加 WIKIJS_TIMEOUT=60000 |
| Cannot read properties of undefined (reading map) | 已在 V3.1 修复 – 更新操作中始终包含 tags: [] |

⚠️ API 密钥权限

Wiki.js API 密钥具有按密钥的权限，而非按组的权限。

JWT 声明	含义
api:1

API 密钥 ID 1 – 可能与密钥 2 具有不同权限