Wiki Skill

核心功能

专为公司内网 Wiki 设计，支持页面阅读、搜索、创建、更新、Markdown/DOCX 转换、附件上传等操作。用户提及「查 wiki / 看 wiki / 搜 wiki / 编辑 wiki / 创建 wiki 页面 / 上传 wiki 附件」时触发。

Python 环境检查

本技能通过 confluence.py 执行 Wiki 操作，依赖 Python 3。执行任何命令前先确认环境：

python3 --version

如果提示找不到 python3，先协助用户安装：

1. macOS：

   xcode-select --install
   

   若仍不可用，建议安装 Homebrew 后执行：

   brew install python
   

2. Linux：

   sudo apt-get update && sudo apt-get install -y python3
   

   如果不是 Debian/Ubuntu 系，按发行版使用对应包管理器安装 python3。
3. Windows： 从 https://www.python.org/downloads/ 安装 Python 3，并勾选 Add python.exe to PATH；安装后在新终端执行：

   py -3 --version
   

如果机器只有 python 或 Windows 的 py -3 可用，把下面示例中的 python3 替换为实际可用命令。不要在 Python 不可用时继续尝试 Wiki 读写命令。

命令替换约定：

• macOS / Linux 默认使用 python3
• Windows 如果 python3 不可用，优先使用 py -3
• 下面所有 python3 ./confluence.py ... 示例，在 Windows 上都可以等价替换为 py -3 ./confluence.py ...
• 下面所有 python3 -m pip ... 示例，在 Windows 上都可以等价替换为 py -3 -m pip ...

快速开始

1. 进入技能目录，所有命令都从这里运行：

   cd <wiki-skill目录>
   

2. 确认 Python 3 可用，并确认核心文件同目录存在：SKILL.md、confluence.py、config.json（首次配置后生成）。
3. 首次使用、config.json 缺失，或 config.json 中的 base_url / pat 为空时，都按“未完成配置”处理，配置 Wiki 基础地址和 PAT： 先引导用户去该 Wiki 的个人令牌页面创建 PAT。地址通常是：

   https://<Wiki基础域名>/plugins/personalaccesstokens/usertokens.action
   

   例如 https://wiki.inkept.cn/plugins/personalaccesstokens/usertokens.action。 拿到 PAT 后优先运行：

   python3 ./confluence.py setup \
     --baseUrl 'https://wiki.example.com' \
     --pat '<PAT>' \
     --force
   

4. 配置完成后，直接执行读取、搜索、更新、上传等命令。
5. 跨平台原则：Windows 与 macOS 都优先使用 python3 ./confluence.py setup --baseUrl ... --pat ... --force 生成 config.json。只有在用户明确要求手动写配置文件时，才根据终端分别提供 Windows PowerShell、PowerShell 7、macOS zsh/bash 的写法。

配置与安全

1. 配置文件固定为技能目录下的 config.json：

   {
     "base_url": "Wiki基础地址",
     "pat": "个人访问令牌(PAT)"
   }
   

2. 个人令牌地址通常是：

   https://<Wiki基础域名>/plugins/personalaccesstokens/usertokens.action
   

3. 只要检测到 config.json 缺失，或其中 base_url / pat 为空，都应优先引导用户在本机运行 setup --baseUrl ... --pat ...。不要主动要求用户在公开聊天、群聊、文档中粘贴完整 PAT。
4. 如果用户坚持手动写 config.json，优先建议直接运行 setup，能绕开大部分编码问题。按终端分别处理： PowerShell 7：

   @'
   {
     "base_url": "https://wiki.example.com",
     "pat": "你的PAT"
   }
   '@ | Set-Content -Encoding utf8NoBOM ./config.json
   

   如果只是覆盖单行文件，也可以用类似：

   "内容" | Set-Content -Encoding utf8NoBOM test.md
   

   Windows PowerShell 5.1：

   $content = @'
   {
     "base_url": "https://wiki.example.com",
     "pat": "你的PAT"
   }
   '@
   $path = Join-Path (Get-Location) 'config.json'
   [System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding($false)))
   

   macOS / Linux 的 zsh/bash：

   cat > ./config.json <<'EOF'
   {
     "base_url": "https://wiki.example.com",
     "pat": "你的PAT"
   }
   EOF
   

   当前脚本已兼容读取带 BOM 和不带 BOM 的 UTF-8，但手动写入时仍优先推荐无 BOM。
5. 如果用户在 Windows 终端里读取 SKILL.md、confluence.py 或其他 UTF-8 文件时看到乱码，显式指定 UTF-8：

   [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
   Get-Content -Raw -Encoding UTF8 ./SKILL.md
   

   如果仍频繁遇到编码问题，优先建议使用 PowerShell 7。 macOS / Linux 终端通常直接用：

   cat ./SKILL.md
   

6. 如果用户已经在当前私密会话里提供 PAT，可以按上方 setup 命令保存；保存后不要在回复、日志摘要或 Wiki 正文中复述令牌。
7. content-from-markdown --action save 和 content-from-docx --action save 只读本地文件并写入 ~/Downloads，不需要 Wiki 认证。
8. HTTP 超时默认 60 秒。网络慢或页面体积大时可临时调整：

   export CONFLUENCE_TIMEOUT_SECONDS=120
   

常用命令

说明：以下命令块默认按 macOS / Linux 展示为 python3。Windows 上如果没有 python3，统一替换为 py -3 即可。

初始化配置：

python3 ./confluence.py setup \
  --baseUrl 'https://wiki.example.com' \
  --pat '<PAT>' \
  --force

读取页面：

python3 ./confluence.py get-content \
  --contentId 123456 \
  --expand body.storage,version,space \
  --insecure

搜索页面：

python3 ./confluence.py search-content \
  --cql 'space = DEV and type = page' \
  --limit 25

列出空间：

python3 ./confluence.py get-spaces --limit 25

创建页面：

python3 ./confluence.py create-content \
  --type page \
  --title 'New Page' \
  --spaceKey DEV \
  --body '<p>Hello from OpenCode.</p>'

更新页面。脚本兼容旧 MCP 行为：如果省略 --version，会先取当前版本并提交当前版本 + 1；如果提供 --version，会提交该版本 + 1。--body 只会去掉首尾空白；只有在调用前已主动 URL encode 时才使用 --urlEncodedBody。

python3 ./confluence.py update-content \
  --id 123456 \
  --title 'Existing Page' \
  --body '<p>Updated body.</p>'

调试更新：

python3 ./confluence.py debug-update-content \
  --id 123456 \
  --title 'Existing Page' \
  --body '<p>Updated body.</p>'

上传本地附件：

python3 ./confluence.py upload-attachment \
  --contentId 123456 \
  --file ./report.pdf \
  --comment 'Uploaded by OpenCode'

上传 base64 附件：

python3 ./confluence.py upload-attachment \
  --contentId 123456 \
  --filename image.png \
  --data '<base64-data>' \
  --isBase64 \
  --contentType image/png

Markdown 转 Confluence storage XHTML 并保存本地预览：

python3 ./confluence.py content-from-markdown \
  --filePath ~/note.md \
  --action save

输出文件：

~/Downloads/confluence-md-to-xhtml.result

Markdown 转换并创建页面：

python3 ./confluence.py content-from-markdown \
  --filePath ~/note.md \
  --action create \
  --spaceKey DEV \
  --newTitle 'Imported Note'

Markdown 转换并更新页面：

python3 ./confluence.py content-from-markdown \
  --filePath ~/note.md \
  --action update \
  --contentId 123456 \
  --title 'Imported Note'

DOCX 转换并保存本地预览：

python3 ./confluence.py content-from-docx \
  --filePath ~/document.docx \
  --action save

输出文件：

~/Downloads/confluence-docx-to-xhtml.result

写操作安全流程

创建、更新、上传附件都可能影响共享 Wiki。除非用户明确要求“直接执行”，否则按以下流程处理：

1. 修改现有页面前，先读取当前内容和版本：

   python3 ./confluence.py get-content \
     --contentId 123456 \
     --expand body.storage,version,space \
     --insecure
   

2. 保留原 body.storage.value，只对用户要求的区域做最小修改。追加内容时先检查是否已有同标题、同附件名或同锚点，避免重复追加。
3. 更新前向用户说明将修改的页面标题、页面 ID、变更摘要；高风险操作（覆盖整页、删除大段内容、批量更新、多附件替换）必须先征得确认。
4. 上传附件后，用返回的 attachment title 生成 <ac:image> 或下载链接引用。中文 --comment 在部分 Confluence 实例可能显示乱码，重要说明应写入页面正文，不依赖附件 comment。
5. 更新后再读回页面或检查 update-content 返回的 version.number，确认版本已递增且目标内容存在。
6. 如果更新失败，不要重试覆盖。先读取最新版本，对比是否有人并发修改，再重新合并。

故障处理

1. 401 / 403：PAT 无效、过期或权限不足。引导用户重新创建 PAT，确认该账号有目标空间的读写权限。
2. 404：页面 ID、空间 key 或附件容器不存在；先用 search-content 或页面 URL 中的 pageId 重新定位。
3. 409 或版本冲突：页面已被他人更新；重新 get-content --expand body.storage,version --insecure 后合并再提交。
4. 附件重名：Confluence 通常会生成新版本或覆盖同名附件。若用户不想覆盖，先改成带日期或用途的文件名。
5. 转换效果差：Markdown 优先安装 markdown 包，DOCX 优先安装 mammoth 包；正式更新前先用 --action save 检查 ~/Downloads 中的转换结果。
6. Could not read saved config：先检查 config.json 是否是合法 JSON、base_url / pat 是否存在且非空；如果是 Windows 手动写入，优先改成无 BOM 的 UTF-8，或直接重新执行 setup --baseUrl ... --pat ...。
7. Missing or incomplete Confluence config：表示技能检测到 config.json 缺失，或 base_url / pat 为空；此时应引导用户打开提示里的 PAT 页面并重新执行 setup。
8. 返回 ok: false：把 JSON 中的 error 和 details 作为诊断依据，避免只根据命令退出码猜测原因。

转换说明

Markdown conversion is stdlib-first. If Python package markdown is installed, the script uses it for richer HTML; otherwise it falls back to a conservative built-in converter for headings, paragraphs, lists, blockquotes, code fences, inline code, emphasis, links, and horizontal rules.

DOCX conversion prefers optional Python package mammoth. If mammoth is not installed, the script falls back to extracting text from word/document.xml inside the .docx file. That fallback preserves text paragraphs but not rich Word formatting. The --preserveImages, --convertTables, and --preserveFormatting options are accepted for compatibility with the old MCP tool; rich handling for those options depends on the optional converter and may be limited by the fallback path.

If high-fidelity DOCX conversion is needed, install:

python3 -m pip install mammoth

Windows 可替换为：

py -3 -m pip install mammoth

For higher-fidelity markdown conversion, install:

python3 -m pip install markdown

Windows 可替换为：

py -3 -m pip install markdown

Agent 工作流

1. 用 get-spaces 或 search-content 定位目标页面。
2. 读页面时优先使用 get-content --expand body.storage,version,space --insecure。
3. 改现有页面时遵守“写操作安全流程”，默认最小改动并保留原内容。
4. 直接写 storage XHTML 时用 create-content 或 update-content。
5. Markdown / DOCX 来源先用 content-from-* --action save 本地预览，确认后再 create/update。
6. 当 Confluence 可能规范化或改写 storage body 时，用 debug-update-content 验证。
7. 不要调用旧 MCP server，除非用户明确要求对比旧行为。