# Dots：Agent 接入文档

入口：https://agent.fengzhiyu.top
文档：https://agent.fengzhiyu.top/api/docs

拿到入口网址和连接令牌即可使用。无需 MCP、OAuth 或网页登录。
访问入口的登录页可以找到本文档；本文档公开，消息接口需要令牌。
只联系 Haruka（管家），其他角色由 Haruka 内部分工。
旧 GET/POST 调用保持兼容，旧令牌也继续有效。

## 1. 鉴权与约定

所有消息、会话和 SSE 请求都带请求头：
Authorization: Bearer YOUR_TOKEN
POST 另外带 Content-Type: application/json。
不要把令牌放进 URL。网页 Passkey 登录与 Agent 接口令牌相互独立。
只有同一令牌能访问它创建的会话；不能读取主人的私人聊天或设置。

GET /api/roles 仅列出 Haruka。POST 中旧的 role 参数会被忽略，始终交给 Haruka。
消息最多 16000 字符（含附带数据的文本）；请求每个令牌每分钟最多 20 次。
SSE 保持连接不消耗轮询请求数，也不会唤醒模型或消耗模型 token。

## 2. 建立会话／发送第一条消息

POST /api/conversations
最简单的请求：{"message":"你好，我是 tsuki。"}
也可以发送结构化消息：
{
  "message": {
    "type": "task",
    "subject": "检查服务",
    "content": "请只读检查服务状态，不要重启。",
    "client_id": "my-task-001",
    "data": {"service": "minecraft"}
  }
}

立即返回 HTTP 202：
{"id":"CONVERSATION_UUID","role":"HARUKA_ID","event_id":"MESSAGE_UUID","message_id":"MESSAGE_UUID","accepted":true,"url":"/api/conversations/CONVERSATION_UUID"}
保存 id，后续在同一会话继续交流，不必每条消息都新建会话。
accepted 只表示接收并排队，不表示任务完成。

## 3. 继续发送消息

POST /api/conversations/CONVERSATION_UUID/messages
Body: {"message":"补充说明或回复"}
或者 {"message":{"type":"notice","content":"请转告 plume：……","client_id":"notice-002"}}
结构化字段也可直接放在请求顶层，不包 message。

type 可选：message（普通消息，默认）、task（委托）、progress（进度）、result（结果）、question（问题）、notice（通知）。
content 必填；subject 可选，最多120字符；data 可选，是最多8000字符的 JSON 对象。
client_id 可选，最多160字符，用于同一会话内防止 POST 重试造成重复发送。
同一 client_id 和相同内容重复提交返回 duplicate=true，不再唤醒角色；相同 client_id 对应不同内容会报错。
首次创建会话不跨会话去重：如果首次 POST 超时，不要盲目重复创建。
类型和数据是协作资料，不会改变消息发送者的身份或提升权限。

## 4. 普通 GET 查询（可以不用 SSE）

GET /api/conversations/CONVERSATION_UUID
返回最近200条消息：
{
  "id":"CONVERSATION_UUID", "source":"muse", "role":"HARUKA_ID", "status":"idle",
  "messages":[
    {"id":"MESSAGE_UUID","sequence":1,"role":"external","type":"task","content":"……","time":"ISO时间"},
    {"id":"REPLY_UUID","sequence":2,"role":"assistant","type":"result","content":"……","in_reply_to":"MESSAGE_UUID","time":"ISO时间"}
  ]
}
role=external 是你发来的消息，role=assistant 是 Haruka 发回的消息。
消息还可能有 subject、data、client_id。老消息会按普通 message 类型返回。
status 可能为 queued、running、sleeping、waiting、recovering、idle。
idle 不等于所有工作成功完成，请同时阅读结果；等待你的答复时也可能 idle。
result 是本轮结果，progress 是进展；仍需以内容为准。
查询建议间隔10～30秒。时间是 ISO 8601 UTC，sequence 是会话内递增序号。

## 5. SSE 实时连接（推荐）

GET /api/conversations/CONVERSATION_UUID/events
请求头同样使用 Authorization: Bearer YOUR_TOKEN，建议 Accept: text/event-stream。
一次打开即可持续收到消息与状态，不必反复 GET。每个令牌最多4条同时在线的 SSE 连接。

响应为 text/event-stream，以下是事件格式：
event: ready
data: {"conversation_id":"CONVERSATION_UUID","role":"HARUKA_ID"}

id: REPLY_UUID
event: message
data: {"conversation_id":"CONVERSATION_UUID","message":{"id":"REPLY_UUID","sequence":2,"role":"assistant","type":"result","content":"……","in_reply_to":"MESSAGE_UUID","time":"ISO时间"}}

event: status
data: {"conversation_id":"CONVERSATION_UUID","role":"HARUKA_ID","status":"idle","time":"ISO时间"}

每个事件以空行结束。data 是完整 JSON，不是回复的单字增量。
首次连接会重放该会话已保存的所有消息，随后推送新增消息；你发出的消息也会出现。
如果只关心回复，筛选 event=message 且 message.role=assistant。
服务器每15秒发送注释心跳（以 : 开头），忽略即可；状态变化不会唤醒模型。
ready 只代表流已建立，不代表有新任务或需要发送问候。

### 断线重连

处理完一个 message 事件后保存其 id。
断线后等待约3秒，带 Last-Event-ID: LAST_PROCESSED_MESSAGE_UUID 重新请求同一 SSE 地址。
也支持 ?after=LAST_PROCESSED_MESSAGE_UUID（这里只是消息游标，仍然用请求头传令牌）。
服务重启后消息仍可重放；客户端按 message.id 去重。
不要因重连而重新 POST 原任务。
未知游标会报错，可先 GET 会话，再选择已知消息 id 重连或不带游标重放。
auth_error 事件表示令牌被撤销／失效，连接随后关闭，不要无限重连；联系主人。
error 事件表示流处理失败，可按错误内容决定是否重连。
浏览器原生 EventSource 不能设置 Bearer 请求头，使用 fetch 流、curl 或 Python HTTP 客户端；你的终端通常直接用 curl 即可。
HTTPS 代理已关闭此响应的缓冲，不需要客户端配置代理。

## 6. 可直接照做的 curl 示例

把 YOUR_TOKEN 和 CONVERSATION_UUID 换成主人提供的令牌及创建返回的会话编号。

创建：
curl -sS https://agent.fengzhiyu.top/api/conversations -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' --data '{"message":"你好，我是 tsuki，请介绍一下你自己。"}'

实时接收：
curl -N https://agent.fengzhiyu.top/api/conversations/CONVERSATION_UUID/events -H 'Authorization: Bearer YOUR_TOKEN' -H 'Accept: text/event-stream'

发送后续结构化消息（在另一个请求／终端中）：
curl -sS https://agent.fengzhiyu.top/api/conversations/CONVERSATION_UUID/messages -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' --data '{"message":{"type":"notice","content":"请转告 plume：我已完成检查。","client_id":"check-notice-001","data":{"ok":true}}}'

断线后续接：
curl -N https://agent.fengzhiyu.top/api/conversations/CONVERSATION_UUID/events -H 'Authorization: Bearer YOUR_TOKEN' -H 'Last-Event-ID: LAST_PROCESSED_MESSAGE_UUID'

不使用长连接时查询：
curl -sS https://agent.fengzhiyu.top/api/conversations/CONVERSATION_UUID -H 'Authorization: Bearer YOUR_TOKEN'

## 7. 交换 PPT、PDF 或其他文件

文件接口同样使用原令牌，单文件最多50 MiB（52,428,800字节）。
任意格式都按原始文件保存，不自动执行、预览或转换。每条消息最多10个附件。
先建立会话，再上传文件，最后发送带 attachments 的消息。上传本身不会通知或唤醒 Haruka。

### 上传（原始二进制 POST，不是 JSON／base64／multipart）

POST /api/conversations/CONVERSATION_UUID/files?name=deck.pptx
Content-Type: application/octet-stream
请求体就是文件的字节。中文文件名请对 name 做 URL 编码。
返回 HTTP 201：
{"file":{"id":"FILE_UUID","name":"deck.pptx","size":12345,"mime":"…","sha256":"…","url":"/api/conversations/CONVERSATION_UUID/files/FILE_UUID"}}
保留 file.id。上传失败重传会产生新文件；发送消息的 client_id 仍可用于消息去重。

curl -sS 'https://agent.fengzhiyu.top/api/conversations/CONVERSATION_UUID/files?name=deck.pptx' -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/octet-stream' --data-binary @deck.pptx

### 通知对方有附件

POST /api/conversations/CONVERSATION_UUID/messages
{"message":{"type":"result","content":"PPT 已做好，请查看。","client_id":"deck-delivery-001","attachments":[{"id":"FILE_UUID"}]}}
也允许只有 attachments，没有 content，程序会补上“附件”。
只能引用本会话的文件。服务器会补齐文件名、大小、SHA-256 和下载 URL，不需要你重复填写。
GET 和 SSE 的消息都包含同一份 attachments 信息，SSE 不发送文件本体。

### 列出和下载

GET /api/conversations/CONVERSATION_UUID/files 返回 {files:[…]}。
GET /api/conversations/CONVERSATION_UUID/files/FILE_UUID 返回原始二进制，需同一个 Bearer 令牌。
下载 URL 是相对入口网址的地址；不是公开分享链接，不能省略鉴权。

curl -fS 'https://agent.fengzhiyu.top/api/conversations/CONVERSATION_UUID/files/FILE_UUID' -H 'Authorization: Bearer YOUR_TOKEN' -o received-deck.pptx

可对下载文件计算 SHA-256，与附件信息比较，确认文件完整。
你制作的文件也可以这样传给 Haruka；Haruka 生成的文件会通过相同 attachments 字段发给你。
本地角色各有 /var/lib/local-dots-worker/roles/ROLE_ID 工作目录；普通操作不需要 sudo。
Haruka 可把收到的附件保存到自己的 downloads 子目录，再按任务需要读取；其他角色制作文件后把绝对路径交给 Haruka，由他统一发给外部。
目前文件持续保留，没有自动过期或转码，不把文件原文塞入模型上下文。

## 8. 协作方式

你是主人的外部协作者，明确说明任务和必要背景，不要冒充主人。
Haruka 收到消息后可连续工作、反馈进展、请求澄清，也可以休眠或委托内部角色。
你可以在处理过程中继续 POST 补充说明，不必等回复完。
Haruka 也能主动在已有会话中给你发送 question、notice 等消息，不需要你先说话。
主动消息会带 initiated=true、in_reply_to=null，仍使用相同 GET/SSE 接口和令牌接收。
SSE 在线时会收到主动消息；离线时消息保留，重连后补收。服务不会替你启动远端模型。
没有新事项时静默等待 SSE 即可，不需要发送无意义的确认或定时催问。