内容
# 文档 API
docsapi 是 [sosumi.ai](https://github.com/nshipster/sosumi.ai) 的一个分支。它专注于通用文档 API 和 MCP 工具，用于常见的文档集生成器，并支持 Apple Docs 作为一种文档集类型。
该分支的托管实例是 `https://docsapi.xo.vg`。
## 使用
### 通过 /api 获取 Apple 文档（文档集：apple）
通过将原始 URL 附加到 `/api/` 来获取 Apple 文档：
```
https://docsapi.xo.vg/api/https://developer.apple.com/documentation/swift/array
```
这适用于 API 参考文档和 Apple 的[人机交互指南](https://developer.apple.com/design/human-interface-guidelines/)（HIG）。
### 通用文档 API
您也可以通过将原始 URL 附加到 `/api/` 来获取任何文档站点的 Markdown：
```
https://docsapi.xo.vg/api/https://docs.rs/serde/latest/serde/
```
设置 `Accept: application/json` 以接收带有 `{ url, content }` 的 JSON 响应。
以 `.html` 结尾的输入被标准化为无扩展名的路径。
### 本地 Docker 部署的批量预加载
使用 `POST /api/preload` 来发现文档 URL（站点地图、搜索索引和页面链接）并在 `./local` 下保存可解析的本地副本。
预加载端点是异步/非阻塞的：它立即返回一个 `jobId`，然后您轮询作业状态/结果端点。
示例请求：
```json
{
"baseUrl": "https://docs.rs/serde/latest/serde/",
"maxPages": 20,
"maxDiscover": 300,
"maxDepth": 2,
"concurrency": 4,
"includeIndexes": true,
"includeLinks": true,
"sameHostOnly": true,
"format": "json"
}
```
使用 `"concurrency"` （1-12，默认为 4）以避免大型网站的过载。
最终预加载的文档存储在 `./local/<base-url-slug>/` 下，因此重复执行相同站点的作业会重用一个输出目录。
每个作业 ID 文件夹仅保留暂存元数据/临时输出。
文件以每个页面/链接标题命名（带有斜杠），并带有匹配的 `*.index.json`。
此本地预加载路由在 Cloudflare Worker/unenv 运行时中禁用，需要带有可写文件系统的 Node/Docker。
作业端点：
- `GET /api/preload/jobs/{jobId}` 用于进度/状态
- `GET /api/preload/jobs/{jobId}/result` 用于最终输出元数据
### 本地管理面板（密码保护）
使用 `/local-docs` 进行本地文档管理。
在环境中设置 `LOCAL_DOCS_PASSWORD` 以启用和保护：
- `POST /api/preload`
- `GET /api/preload/jobs/{jobId}`
- `GET /api/preload/jobs/{jobId}/result`
- `GET /api/local-docs/sites`
- `POST /api/local-docs/sites/{slug}` （更新 / 重命名）
- `DELETE /api/local-docs/sites/{slug}`
- `POST /api/local-docs/import` （ZIP 上传恢复）
- `POST /api/local-docs/backup` （ZIP 下载所选站点）
`/api/preload` JSON 响应现在包括：
- `siteIndex`：所有下载文档的全局索引（`id`、`title`、`description`、`contentFile`、`indexFile`）
- `docIndexes`：每个文档的索引对象（`headings`、`links` 和通过 `localDocId` 的本地交叉链接）
- `documents`：以本地文件名作为键的 Markdown 有效载荷，每个文档带有嵌入的 `index`
### MCP 集成（docsapi）
docsapi 的 MCP 服务器支持 Streamable HTTP 和服务器发送事件（SSE）传输。
如果您的客户端支持其中任何一种，请配置它直接连接到 `https://docsapi.xo.vg/mcp`。
否则，您可以运行以下命令通过 stdio 进行代理：
```json
{
"mcpServers": {
"docsapi": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://docsapi.xo.vg/mcp"]
}
}
}
```
请参阅 `https://docsapi.xo.vg/#clients` 获取特定于客户端的说明。
#### 可用资源
- `doc://{url}` - 文档位于完整 URL，渲染为 Markdown
- 示例：`doc://https://developer.apple.com/documentation/swift/array`
- 示例：`doc://https://docs.rs/serde/latest/serde/`
#### 可用工具
- `fetchAppleDocs` - 按路径获取 Apple Developer 文档和人机交互指南
- 参数：`path`（字符串）- 文档路径（例如，'/documentation/swift'，'swiftui/view'，'design/human-interface-guidelines/foundations/color'）
- 返回内容为 Markdown
- `fetchOnlineDocs` - 从任何基 URL 获取文档，自动检测文档集
- 参数：`baseUrl`（字符串），`path`（字符串，可选），`docsetType`（字符串，可选）
- 示例：`baseUrl: "https://docs.rs"`，`path: "/serde/latest/serde/"`
- 示例：`baseUrl: "https://docs.python.org/3"`，`path: "/library/asyncio.html"`
- 示例：`baseUrl: "https://developer.apple.com"`，`path: "/documentation/swift/array"`，`docsetType: "apple"`
- 返回内容为 Markdown，以及结构化元数据（`docsetType`）
- `fetchDocs` - 从 `./local` 读取预加载的本地文档，无需网络获取
- 参数：`source`（slug 或 URL，可选），`baseUrl`（可选），选择器 `docId` | `url` | `path` | `title`，`docsetType`（可选）
- 路由规则：
- 如果 `source` 是本地 slug，则从该 slug 获取本地文档
- 如果 `source`/`url` 指向我们已经本地存储的 URL，则获取本地文档
- 如果是 Apple Developer URL/路径，则使用 Apple 获取流程
- 否则获取在线文档
- 返回 markdown 以及已解析源的结构化元数据
- `listDocs` - 按站点 slug 列出所有下载的本地文档
- 参数：无
- 返回可用的本地 `slug` 值和每个 slug 的文档计数
- `searchDocs` - 按标题和内容文本跨 slug 搜索本地文档
- 参数：`query`（字符串），`source`（slug 或 URL，可选），`slug`（可选），`limit`（可选）
- 路由规则镜像 `fetchDocs`：
- 本地 slug/已知本地 URL -> 本地搜索
- Apple Developer URL -> Apple 搜索
- 其他 URL -> 在线搜索
- 无源 -> 跨 slug 的本地搜索
- 返回带有片段和源元数据的排名匹配
## 自托管
该项目旨在轻松地在您的机器上运行或部署到托管提供商。
docsapi 现在作为 Next.js 应用服务器运行时运行。
### 先决条件
- Node.js 18+
- npm
### 快速入门
1. **克隆仓库：**
```bash
git clone https://github.com/example-git/docsapi.xo.vg.git
cd docsapi.xo.vg
```
2. **安装依赖：**
```bash
npm install
```
3. **启动开发服务器：**
```bash
npm run dev
```
4. **构建和运行生产服务器（可选）：**
```bash
npm run build
npm run start
```
一旦应用程序启动并运行，按下 <kbd>b</kbd> 键以在浏览器中打开 URL。
要配置 MCP 客户端使用您的开发服务器，请将 `docsapi.xo.vg` 替换为本地服务器地址（默认为 `http://localhost:3000`）。
> [!NOTE]
> 该项目现在作为 Next.js Node 运行时运行。
> 使用 `npm run build` 和 `npm run start` 进行生产。
### Docker / 容器注册表
- 本地构建：
```bash
docker build -t docsapi:local .
```
- 本地运行：
```bash
docker run --rm -p 3000:3000 --env-file .env docsapi:local
```
- 已发布的镜像（GitHub 容器注册表）：`ghcr.io/example-git/docsapi`
推送到 `main`（和 `v*` 标签）时，GitHub Actions 通过 `.github/workflows/container.yml` 构建并推送此镜像。
构建上下文通过 `.dockerignore` 排除 `./local` 下的已下载文档。
## 开发
### 测试
该项目使用 [vitest](https://vitest.dev) 进行单元测试和集成测试。
```bash
npm run test # 运行测试
npm run test:ui # 运行测试并显示 UI
npm run test:run # 运行测试一次
```
### 代码质量
该项目使用 [Biome](https://biomejs.dev/) 进行代码格式化、 linting 和导入组织。
- `npm run format` - 格式化所有代码文件
- `npm run lint` - 检查并修复代码问题
- `npm run check` - 格式化、检查并组织导入（推荐）
- `npm run check:ci` - 检查代码而不进行更改（用于 CI）
### 编辑器集成
为了获得最佳开发体验，请为您的编辑器安装 Biome 扩展：
- [VSCode](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
- [Vim/Neovim](https://github.com/biomejs/biome/tree/main/editors/vim)
- [Emacs](https://github.com/biomejs/biome/tree/main/editors/emacs)
## 许可证
该项目在 MIT 许可证下可用。
有关更多信息，请参见 LICENSE 文件。
## 法律
这是一个非官方、独立的项目，不隶属于或得到 Apple Inc. 的认可。
“Apple”、“Xcode” 和相关标志是 Apple Inc. 的商标。
此服务是一个无障碍优先的按需渲染器。
它仅在用户请求时将单个 Apple Developer 页面转换为 Markdown。
它不爬取、蜘蛛或批量下载；
它不尝试绕过身份验证或安全；
并且它实施速率限制以避免施加不合理的负载。
内容被暂时获取并可能被短暂缓存以提高性能。
不维护永久存档。
所有版权和其他权利在底层内容中仍归 Apple Inc. 所有。
每个页面都链接回原始来源。
您使用此服务必须遵守 Apple 的使用条款和适用法律。
您单独负责如何通过此工具访问和使用 Apple 的内容。
请勿使用此服务绕过技术措施或用于重新分发。
