ONES Wiki Markdown ZIP 下载

Overview

通过 curl 调用 ONES/ALM Wiki 导出接口，下载 Markdown ZIP、解压到同名子目录后自动删除 ZIP。登录邮箱、密码、保存目录在 config.json 中配置；每次下载只需传入 Wiki 链接。

首次配置（必做）

在 skill 目录下复制配置模板并填写：

cp .claude/skills/ones-wiki-markdown-download/config.json.example \
   .claude/skills/ones-wiki-markdown-download/config.json

config.json 字段：

| 字段 | 必填 | 说明 | |------|------|------| | email | 是 | ALM 登录邮箱 | | password | 是 | ALM 登录密码 | | output_dir | 是 | ZIP 保存目录（相对或绝对路径） | | wiki_url | 否 | 默认 Wiki 链接；一般每次用 -Url / --url 传入即可 |

示例：

{
  "email": "your@email.com",
  "password": "your-alm-password",
  "output_dir": "./wiki_export"
}

勿将含真实密码的 config.json 提交到 Git。

配置文件默认路径：.claude/skills/ones-wiki-markdown-download/config.json
可用 --config /path/to/config.json 指定其他路径。

优先级： 命令行参数 > 环境变量 > config.json

When to Use

命令行批量拉取 Wiki 导出 ZIP
链接形如 http://alm.novatools.vip:30011/wiki/#/team/{team}/space/{space}/page/{page}
父页面含多篇子文档，需递归下载
不使用 Python；Windows 用 PowerShell 模块，Linux 用 sh

依赖

| 平台 | 依赖 | |------|------| | Linux（CentOS / Ubuntu） | curl、jq、unzip | | Windows | PowerShell 5.1+（内置 Expand-Archive） |

Quick Reference

| 步骤 | API | |------|-----| | 登录 | POST /project/api/project/auth/login | | 页面树 | GET /wiki/api/wiki/team/{team}/space/{space}/pages | | 导出 ZIP | GET /wiki/api/wiki/team/{team}/page/{page}/export?format=markdown |

子树： URL 含 page → 下载该页及所有子页；不含 page → 下载整个空间。

ALM 接口错误处理（fail-fast）

调用 ALM/ONES 相关接口（登录、页面树、导出 ZIP）时，脚本遵循 遇错即停：

打印错误内容：输出失败步骤、请求 URL、HTTP 状态码（如有）、服务端返回体或异常信息。
立即中止：不再继续后续 API 调用或页面下载。
提示人工介入：明确告知需人工排查（账号/密码、Wiki 链接、页面权限、ALM 服务可用性等），Agent 不要自动重试或绕过。

典型失败场景：登录失败、页面树接口非 200、导出响应非 ZIP、网络超时。

脚本与配置

.claude/skills/ones-wiki-markdown-download/
  config.json.example   # 模板（复制为 config.json）
  config.json           # 本地配置（用户自建，勿提交）
  scripts/
    OnesWiki.psm1                  # Windows / PowerShell
    download_ones_wiki_markdown.sh # Linux

用法

配置好 config.json 后，只需传 Wiki 链接：

Linux

chmod +x .claude/skills/ones-wiki-markdown-download/scripts/download_ones_wiki_markdown.sh

.claude/skills/ones-wiki-markdown-download/scripts/download_ones_wiki_markdown.sh \
  --url "http://alm.novatools.vip:30011/wiki/#/team/y7bXyZLk/space/AMrum18x/page/X9dAkxQ3"

Windows（PowerShell）

Import-Module ".\ones-wiki-markdown-download\scripts\OnesWiki.psm1" -Force

Export-OnesWikiMarkdown `
  -Url "http://alm.novatools.vip:30011/wiki/#/team/y7bXyZLk/space/AMrum18x/page/X9dAkxQ3"

一行命令（无需先 Import-Module）：

powershell -NoProfile -Command "Import-Module '.\ones-wiki-markdown-download\scripts\OnesWiki.psm1' -Force; Export-OnesWikiMarkdown -Url 'http://alm.novatools.vip:30011/wiki/#/team/y7bXyZLk/space/AMrum18x/page/X9dAkxQ3'"

覆盖配置（可选）

PowerShell 参数：-Email、-Password、-OutputDir、-ConfigPath

Linux sh：--email、--password、--out、--config

环境变量：ONES_WIKI_URL、ONES_EMAIL、ONES_PASSWORD、ONES_OUTPUT_DIR

输出

解压后的 Markdown 目录保存在 config.json 的 output_dir。每个页面先下载为 ZIP，解压到去掉 .zip 后缀的同名文件夹后删除 ZIP。例如：

wiki_export/
  H-峰值亮度ABL-详细设计-后端_详设/
    index.md
    ...
  子页面标题/
    index.md

Agent 指引

使用前检查 config.json 是否存在；不存在则引导用户从 config.json.example 复制并填写。
Windows 上 Import-Module scripts/OnesWiki.psm1 -Force 后调用 Export-OnesWikiMarkdown -Url ...；Linux 用 sh 脚本。
下载完成后脚本会自动解压 ZIP 到同名子目录，并删除原始 ZIP。
检查 ZIP 文件头为 PK（有效 ZIP）；解压失败时按 fail-fast 中止并提示人工介入。
ALM 接口报错时：
- 将脚本输出的「步骤 / URL / 错误内容」完整转述给用户；
- 停止执行，不要继续下载其他页面，不要自动改参数重试；
- 明确提示：需人工介入排查（核对 config.json 凭据、Wiki URL、页面访问权限、ALM 是否可访问）；
- 仅在用户确认问题已修复后，再重新发起下载。