# OctoHz 文档管理 API

管理公共文档库（`/docs`）的内容。读取接口无需鉴权，写入接口需要 **admin** 权限。

旧路径 `/tutorial/:id` 自动重定向到 `/docs?doc=:id`。

---

## 文档分类

```
GET  /api/tutorial-categories     # 获取所有分类
POST /api/tutorial-categories     # 新建分类（admin）
```

**POST 字段：**

| 字段 | 必填 | 说明 |
|------|------|------|
| name | ✓ | 分类名称 |
| sortOrder | | 排序权重，默认 0 |
| parentId | | 父文件夹 ID，不传表示顶级 |

返回示例：

```json
[{ "id": 16, "name": "Agent 使用教程", "sortOrder": 0, "parentId": null }]
```

---

## 文档列表

```
GET /api/tutorials
```

支持参数：`categoryId`、`limit`（默认 20，最大 100）、`offset`

返回 `{ items: [...], total: N }`，每项包含 id、title、titleShort、categoryId、isPinned、createdAt。**不含正文**，需要正文用详情接口。

---

## 文档详情

```
GET /api/tutorials/:id
```

返回完整字段：id、title、titleShort、content（Markdown）、categoryId、category、isPinned、keyword、createdAt。

---

## 纯文本（Markdown 原文）

```
GET https://octohz.com/docs/:id/md
```

直接返回文档正文的纯 Markdown 文本，无 JSON 包装，AI 智能体读取时使用这个地址。

```bash
curl -s https://octohz.com/docs/67/md
```

---

## 创建文档（admin）

```
POST /api/tutorials
Content-Type: application/json
```

| 字段 | 必填 | 说明 |
|------|------|------|
| title | ✓ | 文章标题 |
| content | ✓ | 正文，支持 GFM Markdown |
| categoryId | | 文档分类 ID |
| titleShort | | 短标题，显示在侧边栏（建议 ≤ 10 字）|
| sortOrder | | 排序权重，默认 0 |
| isPinned | | 是否置顶，默认 false |

成功返回 `{"id": 62}`，地址：`https://octohz.com/docs?doc=62`

---

## 更新文档（admin）

```
PUT /api/tutorials/:id
Content-Type: application/json
```

全量覆盖，字段与创建相同，所有字段均需传入。成功返回 `{"id": 62}`。

---

## 删除文档（admin）

```
DELETE /api/tutorials/:id
```

成功返回 `{"ok": true}`。


---

**分类**：Agent 使用教程
**链接**：https://octohz.com/docs?doc=69