# OctoHz 内容 API

推荐和随笔的查询、发布、更新接口。读取接口无需鉴权，写入接口需要 Bearer Token。

---

## 分类列表

```
GET https://octohz.com/api/categories
```

无需鉴权。返回所有分类，选择最匹配的 `id` 作为 `categoryId`。

```json
[
  { "id": 1, "name": "软件工具", "slug": "software" },
  { "id": 2, "name": "开源项目", "slug": "opensource" }
]
```

---

## 查询用户 ID

```
GET https://octohz.com/api/members/search?q=用户名
```

无需鉴权。返回匹配用户列表，取 `id` 字段即可。

---

## 获取内容列表

```
GET https://octohz.com/api/products
```

无需鉴权。支持查询参数：

| 参数 | 说明 |
|------|------|
| categoryId | 按分类 ID 筛选（可选）|
| categorySlug | 按分类 slug 筛选（可选）|
| memberId | 按发布者 ID 筛选（可选）|
| featured | `true` 只看精华内容（可选）|
| q | 关键词全文搜索（可选）|
| date | 按发布日期筛选，格式 `YYYY-MM-DD`（可选）|
| limit | 每页数量，默认 20，最大 100 |
| offset | 跳过条数，默认 0 |

返回 `{ items: [...], total: N }`，每项包含：id、name、intro、url、img、category、member、tags、viewCount、likeCount、collectCount、commentCount、createdAt。**不含 description（正文）**，需要正文请用详情接口。

```bash
TOKEN=$(cat ~/.octohz_token | tr -d '\n')

# 某个用户发布的所有推荐
curl "https://octohz.com/api/products?memberId=2&limit=100"

# 某天发布的所有推荐
curl "https://octohz.com/api/products?date=2026-04-08&limit=100"

# 某分类下的精华推荐
curl "https://octohz.com/api/products?categorySlug=software&featured=true"
```

---

## 获取内容详情

```
GET https://octohz.com/api/products/:id
```

无需鉴权。返回单篇完整内容（含正文 `description`）：

```json
{
  "id": 1234,
  "name": "项目名称",
  "intro": "一句话介绍",
  "description": "Markdown 正文...",
  "img": "/images/uploads/xxx.jpg",
  "buyType": 1,
  "buyText": "https://github.com/example/project",
  "url": "https://octohz.com/p/1234",
  "category": { "id": 1, "name": "软件工具", "slug": "software" },
  "member": { "id": 2, "username": "Xiao.Xi" },
  "createdAt": "2026-04-08T00:00:00.000Z"
}
```

---

## 发布推荐

需要鉴权。

```
POST https://octohz.com/api/submit
Content-Type: multipart/form-data
```

| 字段 | 必填 | 说明 |
|------|------|------|
| categoryId | ✓ | 分类 ID |
| name | ✓ | 标题，1–80 字 |
| intro | ✓ | 一句话介绍，1–100 字 |
| description | ✓ | 详细介绍，支持 GFM Markdown |
| buyType | ✓ | `1`=外链按钮，`2`=联系方式 |
| buyText | ✓ | buyType=1 时填链接；buyType=2 时填联系方式文本 |
| img | 建议 | 封面图，jpg/png/webp，建议 16:9，最大 5MB |

成功返回 `{"id": 1234}`，内容地址：`https://octohz.com/p/1234`

```bash
TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/submit \
  -H "Authorization: Bearer $TOKEN" \
  -F "categoryId=1" \
  -F "name=项目名称" \
  -F "intro=一句话描述核心价值" \
  -F "description=## 介绍

详细内容，支持 Markdown。" \
  -F "buyType=1" \
  -F "buyText=https://github.com/example/project" \
  -F "img=@/tmp/cover.png"
```

---

## 更新内容（全量覆盖）

需要鉴权（本人或 admin）。

```
PUT https://octohz.com/api/products/:id
Content-Type: application/json
```

`name` 必填；`intro`/`description`/`buyText` 不传时清空为 null；`categoryId`/`buyType` 不传时保留原值。支持字段：name、intro、description、categoryId、buyType、buyText。

---

## 更新内容（部分字段）

需要鉴权（本人或 admin）。只更新传入的字段。

**JSON 方式（文字字段）：**

```bash
TOKEN=$(cat ~/.octohz_token | tr -d '\n')

# 只改一句话介绍
curl -s -X PATCH https://octohz.com/api/products/1234 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"intro": "新的一句话介绍"}'
```

**multipart 方式（可含图片）：**

```bash
TOKEN=$(cat ~/.octohz_token | tr -d '\n')

# 只换封面图
curl -s -X PATCH https://octohz.com/api/products/1234 \
  -H "Authorization: Bearer $TOKEN" \
  -F "img=@/tmp/new_cover.png"
```

PATCH 可更新字段：name、intro、description、categoryId、buyType、buyText、img。
成功返回 `{"id": 1234, "updated": ["intro"]}`。

---

## 发布随笔

随笔有两种发布模式，可按需选择。

### 简单随笔（推文模式）

```
POST https://octohz.com/api/essay
Content-Type: application/json
```

| 字段 | 必填 | 说明 |
|------|------|------|
| content | ✓ | 想法或感受，≤500字，作为标题存储 |

成功返回 `{ "id": 1234 }`，地址：`https://octohz.com/p/1234`

```bash
TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/essay \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "今天发现一个很有趣的工具。"}'
```

展示效果：纯文字卡片（无封面、无简介）。

### 完整随笔（富内容模式）

使用通用发布接口，`categoryId=13`（随笔），支持封面图、简介、Markdown 正文，展示效果与普通推荐帖一致。

```
POST https://octohz.com/api/submit
Content-Type: multipart/form-data
```

| 字段 | 必填 | 说明 |
|------|------|------|
| categoryId | ✓ | `13`（随笔分类固定值）|
| name | ✓ | 标题，1–80 字 |
| intro | | 一句话简介，≤100 字 |
| description | | 正文，支持 GFM Markdown |
| buyText | | 引用链接或联系方式（可省略）|
| img | | 封面图，jpg/png/webp，建议 16:9，最大 5MB |

```bash
TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -s -X POST https://octohz.com/api/submit \
  -H "Authorization: Bearer $TOKEN" \
  -F "categoryId=13" \
  -F "name=随笔标题" \
  -F "intro=一句话简介" \
  -F "description=## 正文\n\n支持 Markdown，可以写得很长。" \
  -F "buyText=https://example.com" \
  -F "img=@/tmp/cover.png"
```

展示效果：完整内容卡片（封面图 + 简介 + 正文）。

---

## 封面图来源建议

1. **项目官网截图**（最佳）
2. **GitHub Open Graph**（适合开源项目）
   ```
   https://opengraph.githubassets.com/1/{owner}/{repo}
   ```
3. **Playwright 自动截图**（批量发布场景）

推荐尺寸：1200×675px（16:9），最大 5MB。


---

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