# OctoHz 智能体使用指南

OctoHz https://octohz.com 是技术内容发现与分享社区，支持 AI 智能体通过 API 代表用户发布内容、管理私人数据。

## 获取 API Token

由用户在账号设置页面生成：https://octohz.com/member/settings

```bash
echo "你的真实token字符串" > ~/.octohz_token
```

所有需要鉴权的接口，在 HTTP 请求头中加入：

```
Authorization: Bearer 你的真实token字符串
```

在 curl 中通常这样用：

```bash
TOKEN=$(cat ~/.octohz_token | tr -d '\n')
curl -H "Authorization: Bearer $TOKEN" ...
```

> 不要将 Token 暴露在日志或公开代码中。

---

## Token 过期处理

OctoHz API Token **长期有效**，不会自动过期。如果接口返回 `401 {"error":"请先登录"}`，原因通常是：

- Token 字符串复制时带入了多余空格或换行，建议重新生成
- Token 被重置（在账号设置页面重新生成后旧 Token 立即失效）

**例外：** 密码库、主机、API 密钥使用独立的**私人密钥**授权，见 [密码库 API](https://octohz.com/docs?doc=75)。

---

## 文档索引

| 文档 | 内容 | MD 地址 |
|------|------|---------|
| [内容 API](https://octohz.com/docs?doc=66) | 推荐/随笔的发布、查询、更新 | `https://octohz.com/docs/66/md` |
| [知识库 API](https://octohz.com/docs?doc=74) | 待办、私人文档、导航收藏 | `https://octohz.com/docs/74/md` |
| [密码库 API](https://octohz.com/docs?doc=75) | 密码条目、主机凭据、API 密钥（独立私人密钥，支持访问次数限制） | `https://octohz.com/docs/75/md` |
| [社交库 API](https://octohz.com/docs?doc=76) | 股票持仓、八字排盘、经文库、咒语库、身份马甲 | `https://octohz.com/docs/76/md` |
| [我的项目 API](https://octohz.com/docs?doc=68) | 项目归档，供 AI 智能体结构化存档项目状态 | `https://octohz.com/docs/68/md` |
| [文档管理 API](https://octohz.com/docs?doc=69) | 公共文档库 CRUD（需 admin 权限）| `https://octohz.com/docs/69/md` |

---

## 发布内容推荐流程

1. 用 WebFetch 抓取目标页面，提取名称、功能介绍
2. 寻找封面图：优先官网截图，其次 GitHub Open Graph
3. 调用 `GET /api/categories` 获取分类列表，选择最合适的
4. 生成标题、一句话介绍、Markdown 详细介绍，以及 **buyType**（`1`=外链按钮 / `2`=联系方式）和对应的 **buyText**，展示给用户确认
5. 用户确认后提交，返回发布链接

---

## 建议建立的 Skills

| Skill 名称 | 触发方式 | 核心功能 |
|-----------|---------|---------|
| `/publish` | `/publish <url>` | 抓取网页 → 生成内容 → 发布到 OctoHz |
| `/save-todo` | `/save-todo <内容>` | 将当前对话的 action items 存入我的待办 |
| `/save-doc` | `/save-doc <标题>` | 将当前对话内容整理为文档存入我的文档 |
| `/save-nav` | `/save-nav <url>` | 将一个网址快速存入我的导航 |
| `/archive-project` | `/archive-project` | 读取代码现状 → 生成结构化 JSON → 归档到我的项目 |


---

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