# 和谐汇一内部资料库 API — Agent 使用指南

给研究员个人 Agent 调用内部会议 / 内部报告 / 研究分享。
只读。返回元数据 + AI 摘要，不提供原文、不提供 PPT/PDF 下载。

当前线上地址：`https://www.findaily.xyz`（以此处显示的协议为准，http 与 https 会随站点配置变化）。

本机 curl、Python、WorkBuddy、自己电脑上的 agent 用 HTTP 即可。
**推荐：WorkBuddy 用 MCP + Skill**（Key 放环境变量 `VISIONE_LIBRARY_KEY`，不要写进 Skill 文件）。
下载：`/api/v1/library/mcp.py` 、`/api/v1/library/skill.md` 、`/api/v1/library/workbuddy.md`
ChatGPT 网页版仍要公网 HTTPS，当前未开通。

---

## 你能做什么

- 按关键词、股票、日期、组别、类型检索内部资料
- 按股票代码列出该标的相关会议/报告
- 用条目 id 拉取单条详情（标题、作者、建议、关联股票、AI 摘要）
- 用这些摘要做：覆盖梳理、观点对比、会前准备、研报索引

## 你不能做什么

- 不能下载或预览原始文件（pptx/pdf/docx）
- 不能拿到报告全文 / 会议逐字稿
- 不能写入、修改、删除任何资料
- 不能越权看其他组（普通研究员 Key 仅本组；投资经理/管理员可看全库）
- 不要尝试扫描全库分页扒数；有限流，违规 Key 会被吊销

---

## 鉴权

每个研究员一把 Key，格式 `vis_live_...`。

所有业务接口必须带：

```
Authorization: Bearer vis_live_xxxxxxxx
```

等价 Header：`X-Api-Key: vis_live_xxxxxxxx`

不要把 Key 写进仓库、聊天或 prompt 明文日志。Key 丢失请让研究员重新申请，旧 Key 会在新 Key 通过时自动作废。

本说明文件无需 Key：`GET /api/v1/library/readme`

---

## 接口

### 1. 检索列表

`GET /api/v1/library/search`

Query：

| 参数 | 说明 |
|------|------|
| q | 关键词，匹配标题/作者/摘要 |
| stock | 股票名称或代码（模糊） |
| category | `内部会议` / `内部报告` / `研究分享` |
| type | 类型，如 `组会` `深度` `专题` `晨会` |
| group | 组别 `TMT` `周期` `医药` `消费` `高端制造`（普通研究员会被强制成自己的组） |
| date_from | `YYYY-MM-DD` |
| date_to | `YYYY-MM-DD` |
| page | 页码，从 1 开始，默认 1 |
| page_size | 每页条数，默认 20，最大 50 |

响应：

```json
{
  "success": true,
  "data": [ { "...条目对象..." } ],
  "total": 55,
  "page": 1,
  "page_size": 20,
  "scope_group": "TMT"
}
```

`scope_group` 为 `all` 表示该 Key 可看全库。

### 2. 按股票

`GET /api/v1/library/by_stock?code=300750`

`code` 也可写成 `stock`。支持代码（含/不含 .SZ .HK 后缀）或中文名。最多 50 条。

### 3. 单条详情

`GET /api/v1/library/items/{id}`

`id` 来自列表：`m123` 表示会议/资料主记录，`r456` 表示未挂会议的旧报告。

---

## 条目字段

每个 data 元素：

| 字段 | 类型 | 含义 |
|------|------|------|
| id | string | 稳定 id，详情接口用，如 `m332` |
| category | string | 内部会议 / 内部报告 / 研究分享 |
| group | string | TMT / 周期 / 医药 / 消费 / 高端制造 |
| type | string | 组会、深度、专题、晨会等 |
| title | string | 标题 |
| date | string | `YYYY-MM-DD` |
| presenter | string | 主讲/作者 |
| uploader | string | 上传人 |
| advice | string | 主建议（买入/加仓/关注/中性/减仓...），可能为空 |
| stocks | array | 关联标的，见下表 |
| ai_summary | string | AI 摘要，可能为空（尚未生成） |
| summary | string | 人工/会议纪要摘要，可能为空 |
| files | array | 仅文件名/类型/大小，无下载地址 |

`stocks[]`：

| 字段 | 含义 |
|------|------|
| code | 股票代码 |
| name | 股票名称 |
| advice | 该标的建议，可能为空 |

`files[]`：`name` / `type` / `size`（字节）。**没有 url、没有 path。** 不要据此拼下载链接。

---

## 推荐调用顺序

1. 用户问某家公司或某个主题时，先 `search?q=` 或 `by_stock?code=`。
2. 浏览 `title` `date` `presenter` `advice` `ai_summary`。
3. 需要对某一条展开时，用返回的 `id` 调 `items/{id}`。
4. 回答时注明来源：日期、作者、标题。摘要为空就说资料库没有摘要，不要编造正文。
5. 不要循环翻页拉取全部历史；按问题缩小 `q` / `date_from`。

---

## 错误

| HTTP | error | 含义 |
|------|--------|------|
| 401 | unauthorized | 缺少/错误/已吊销的 Key |
| 403 | forbidden | 这条不在你的组权限内 |
| 404 | not_found | id 不存在 |
| 400 | bad_request | 缺参数（如 by_stock 未给 code） |
| 429 | rate_limit | 超过 60 次/分钟 或 1000 次/天 |
| 500 | server | 服务端异常 |

错误体：`{"success": false, "error": "...", "msg": "..."}`

---

## 限流

- 每把 Key：60 次/分钟，1000 次/天
- 超限返回 429，请退避后重试
- 调用会被后台记账（谁、哪个接口、查询词、IP、耗时）

---

## 调用示例

下面示例中的 `BASE` 请照抄本文档开头给出的线上地址：

```bash
export LIB_KEY="vis_live_你的key"
BASE="https://www.findaily.xyz"

# 关键词检索
curl -s "$BASE/api/v1/library/search?q=宁德时代&page_size=5" \
  -H "Authorization: Bearer $LIB_KEY"

# 按代码
curl -s "$BASE/api/v1/library/by_stock?code=300750" \
  -H "Authorization: Bearer $LIB_KEY"

# 单条
curl -s "$BASE/api/v1/library/items/m332" \
  -H "Authorization: Bearer $LIB_KEY"

# 本说明（无需 Key）
curl -s "$BASE/api/v1/library/readme"
```

Python：

```python
import os, requests
KEY = os.environ["LIB_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
base = "https://www.findaily.xyz/api/v1/library"
r = requests.get(base + "/search", params={"q": "组会", "page_size": 5}, headers=H, timeout=20)
print(r.json())
```

接 ChatGPT GPT Actions 需要公网 HTTPS 域名；若上面地址仍是纯 IP 的 http，会被 OpenAI 拒绝。