检索与下载 Wiki
这条接入路径面向外部检索、归档和下游处理系统。通常只需要三个端点：
GET /integrations/wikis检索 Wiki；HEAD /integrations/wikis/{wiki_id}/artifact获取版本和完整性信息；GET /integrations/wikis/{wiki_id}/artifact下载完整包。
标识不要混用
wiki_id 是不可变标识，用于详情和下载；slug 用于展示、预览和部分站内 Wiki 接口。外部系统应持久化 wiki_id。
1. 检索可下载 Wiki
curl --fail-with-body \
-H "Authorization: Bearer $MEMEX_TOKEN" \
"$MEMEX_HOST/api/v1/integrations/wikis?preset=publishable&page_size=50"
preset=publishable 会筛选已完成、公版、允许发布且完成度达到 100% 的 Wiki。响应核心字段：
{
"ok": true,
"items": [
{
"id": "019...",
"slug": "example-wiki",
"name": "Example Wiki",
"status": 1,
"page_count": 126,
"updated_at": "2026-07-31T08:00:00+00:00",
"artifact": {
"download_url": "/api/v1/integrations/wikis/019.../artifact"
}
}
],
"has_more": true,
"next_cursor": "..."
}
继续翻页时，保留原来的筛选条件并传入服务端返回的 next_cursor：
curl --fail-with-body \
-H "Authorization: Bearer $MEMEX_TOKEN" \
"$MEMEX_HOST/api/v1/integrations/wikis?preset=publishable&page_size=50&cursor=$NEXT_CURSOR"
不要自行解析或修改 cursor；它带签名、绑定筛选条件并且会过期。
2. 下载前检查版本
curl --fail-with-body --head \
-H "Authorization: Bearer $MEMEX_TOKEN" \
"$MEMEX_HOST/api/v1/integrations/wikis/$WIKI_ID/artifact"
成功响应提供：
| Header | 用途 |
|---|---|
Content-Length | 完整 tar.gz 的字节数 |
ETag | 基于包内容 SHA-256 的缓存标识 |
X-Artifact-SHA256 | 下载后完整性校验 |
X-Artifact-Snapshot | 本次源目录快照标识 |
X-Wiki-Version | Wiki 的 Git SHA 或更新时间版本 |
X-Wiki-ID / X-Wiki-Slug | 标识核对 |
HEAD 与随后 GET 指向同一份不可变缓存快照。若本地已经持有某个 ETag，可发送 If-None-Match；未变化时返回 304。
3. 下载并校验
仓库提供了带完整性校验的参考客户端：
export MEMEX_ADMIN_KEY="$MEMEX_TOKEN"
python3 scripts/wiki_query_download.py download "$WIKI_ID" \
--output-dir ./wiki-downloads
客户端会：
- 以 1 MiB 分块写入
.partial文件； - 校验
Content-Length； - 校验
X-Artifact-SHA256； - 全部成功后原子改名为最终
.tar.gz。
直接使用 curl 时也应完成校验：
URL="$MEMEX_HOST/api/v1/integrations/wikis/$WIKI_ID/artifact"
curl --fail-with-body --location \
-H "Authorization: Bearer $MEMEX_TOKEN" \
--dump-header artifact.headers \
--output wiki.tar.gz.partial \
"$URL"
EXPECTED=$(awk 'BEGIN{IGNORECASE=1} /^x-artifact-sha256:/{gsub("\r","",$2); print $2}' artifact.headers)
ACTUAL=$(sha256sum wiki.tar.gz.partial | awk '{print $1}')
test "$EXPECTED" = "$ACTUAL"
mv wiki.tar.gz.partial wiki.tar.gz
包里有什么
包以 Wiki 原始目录为根，保留 .git/、local/、corpus/、docs/ 等普通文件和目录。
明确排除任意层级的：
logs/.env*- symlink 和 hardlink
包根目录包含 manifest.json，记录 wiki_id、slug、源版本和 snapshot ID。
失败与重试
| 状态码 | 含义 | 客户端处理 |
|---|---|---|
304 | ETag 未变化 | 使用本地已有包 |
409 | Wiki 未就绪或打包期间持续变化 | 延迟后重新检索状态并重试 |
413 | 源目录超过配置的包大小上限 | 不要重试，联系服务管理员 |
429 | 下载频率超限 | 按 Retry-After 等待 |
500 | 服务端无法生成完整包 | 保留错误信息，退避重试 |
任何长度或 SHA-256 不一致都应视为下载失败，不能把临时文件交给下游。