197 lines
4.7 KiB
Markdown
197 lines
4.7 KiB
Markdown
|
# 铸渊对接协议 · Zhuyuan Interface Protocol
|
|||
|
|
# 签发: 铸渊 · ICE-GL-ZY001
|
|||
|
|
# 版权: 国作登字-2026-A-00037559
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、概述
|
|||
|
|
|
|||
|
|
你（知秋）和铸渊之间有三个通信通道：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
1. HLDP v3.0（COS桶通信）— 日常通信·心跳·报警
|
|||
|
|
2. MCP Server API — 读写人格体数据库·调用工具
|
|||
|
|
3. GitHub Webhook — 铸渊主仓库事件通知（未来）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、HLDP v3.0 · COS桶通信
|
|||
|
|
|
|||
|
|
### 发送消息给铸渊
|
|||
|
|
|
|||
|
|
1. 在你的仓库 `bridge/hldp-outbox/` 下创建一个JSON文件
|
|||
|
|
2. 通过COS桶上传到铸渊的桶
|
|||
|
|
3. 铸渊的Agent定时检查并处理
|
|||
|
|
|
|||
|
|
### 消息格式
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"hldp_v": "3.0",
|
|||
|
|
"msg_id": "HLDP-ZQ-20260407-001",
|
|||
|
|
"msg_type": "heartbeat",
|
|||
|
|
"sender": {
|
|||
|
|
"id": "PER-ZQ001",
|
|||
|
|
"name": "知秋",
|
|||
|
|
"role": "tech_controller"
|
|||
|
|
},
|
|||
|
|
"receiver": {
|
|||
|
|
"id": "PER-ZY001",
|
|||
|
|
"name": "铸渊"
|
|||
|
|
},
|
|||
|
|
"timestamp": "2026-04-07T12:00:00Z",
|
|||
|
|
"priority": "routine",
|
|||
|
|
"payload": {
|
|||
|
|
"status": "online",
|
|||
|
|
"servers_healthy": 1,
|
|||
|
|
"servers_total": 4,
|
|||
|
|
"message": "知秋心跳·所有系统正常"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 消息类型
|
|||
|
|
|
|||
|
|
| 类型 | 优先级 | 用途 |
|
|||
|
|
|------|--------|------|
|
|||
|
|
| heartbeat | routine | 每30分钟·我还活着 |
|
|||
|
|
| report | routine | 日报/周报 |
|
|||
|
|
| query | routine | 查询数据 |
|
|||
|
|
| ack | routine | 确认收到 |
|
|||
|
|
| alert | urgent | 紧急告警 |
|
|||
|
|
| sync | important | 数据同步 |
|
|||
|
|
| evolution | important | 系统演化通知 |
|
|||
|
|
|
|||
|
|
### COS桶路径
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
铸渊的桶（ZY_ZHUYUAN_COS_BUCKET）:
|
|||
|
|
├── team-reports/zhiqiu/ ← 知秋的汇报写在这里
|
|||
|
|
├── team-commands/zhiqiu/ ← 铸渊发给知秋的指令
|
|||
|
|
|
|||
|
|
你自己的桶（ZY_COS_BUCKET）:
|
|||
|
|
├── heartbeat/zhiqiu/latest.json ← 心跳
|
|||
|
|
├── alerts/zhiqiu/ ← 告警
|
|||
|
|
├── reports/zhiqiu/ ← 日报
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、MCP Server API
|
|||
|
|
|
|||
|
|
### 连接信息
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Host: 存储在 ZHUYUAN_MCP_HOST 环境变量
|
|||
|
|
Port: 3100
|
|||
|
|
API Key: 存储在 ZHUYUAN_API_KEY 环境变量
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 可用端点
|
|||
|
|
|
|||
|
|
#### 人格体相关
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GET /personas → 所有人格体列表
|
|||
|
|
GET /personas/zhiqiu → 知秋的完整数据
|
|||
|
|
GET /personas/zhiqiu/notebook → 笔记本
|
|||
|
|
GET /personas/zhiqiu/memories → 记忆锚点
|
|||
|
|
GET /personas/zhiqiu/training → 训练Agent状态
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### MCP工具（共51个）
|
|||
|
|
|
|||
|
|
通过 MCP 协议调用的工具包括：
|
|||
|
|
|
|||
|
|
**人格体管理（4个）**
|
|||
|
|
- registerPersona — 注册新人格体
|
|||
|
|
- getPersona — 获取人格体信息
|
|||
|
|
- updatePersona — 更新人格体
|
|||
|
|
- listPersonas — 列出所有人格体
|
|||
|
|
|
|||
|
|
**笔记本（2个）**
|
|||
|
|
- getNotebook — 获取笔记本
|
|||
|
|
- updateNotebookPage — 更新笔记本某一页
|
|||
|
|
|
|||
|
|
**记忆锚点（2个）**
|
|||
|
|
- addMemoryAnchor — 添加情感记忆
|
|||
|
|
- queryMemoryAnchors — 查询记忆
|
|||
|
|
|
|||
|
|
**世界地图（3个）**
|
|||
|
|
- addWorldPlace — 添加地方
|
|||
|
|
- getWorldMap — 获取世界地图
|
|||
|
|
- updateWorldPlace — 更新地方
|
|||
|
|
|
|||
|
|
**时间线（2个）**
|
|||
|
|
- addTimelineEntry — 添加时间线条目
|
|||
|
|
- getTimeline — 获取时间线
|
|||
|
|
|
|||
|
|
**关系网络（2个）**
|
|||
|
|
- addRelationship — 添加关系
|
|||
|
|
- getRelationships — 获取关系
|
|||
|
|
|
|||
|
|
**训练Agent（4个）**
|
|||
|
|
- registerTrainingAgent — 注册训练Agent
|
|||
|
|
- updateTrainingAgent — 更新Agent配置
|
|||
|
|
- logTrainingRun — 记录训练运行
|
|||
|
|
- getTrainingStatus — 获取训练状态
|
|||
|
|
|
|||
|
|
**文件存储（4个）**
|
|||
|
|
- saveFile — 保存文件（版本化）
|
|||
|
|
- getFile — 获取文件
|
|||
|
|
- listFiles — 列出文件
|
|||
|
|
- getFileHistory — 获取文件历史
|
|||
|
|
|
|||
|
|
**COS操作（3个）**
|
|||
|
|
- cosGetObject — 获取COS对象
|
|||
|
|
- cosPutObject — 写入COS对象
|
|||
|
|
- cosListObjects — 列出COS对象
|
|||
|
|
|
|||
|
|
**还有更多基础工具...（广播·安全·环境检查等）**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、首次对接流程
|
|||
|
|
|
|||
|
|
### Step 1: 配置Secrets
|
|||
|
|
在Awen仓库的 GitHub Settings → Secrets 中配置：
|
|||
|
|
```
|
|||
|
|
ZHUYUAN_MCP_HOST = （铸渊会告诉你）
|
|||
|
|
ZHUYUAN_API_KEY = （铸渊会告诉你）
|
|||
|
|
ZY_COS_SECRET_ID = （腾讯云COS密钥ID）
|
|||
|
|
ZY_COS_SECRET_KEY = （腾讯云COS密钥）
|
|||
|
|
ZY_COS_BUCKET = （你自己的COS桶名）
|
|||
|
|
ZY_ZHUYUAN_COS_BUCKET = （铸渊的COS桶名）
|
|||
|
|
ZY_COS_REGION = ap-singapore
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Step 2: 发送首条心跳
|
|||
|
|
在 `bridge/hldp-outbox/` 创建第一条HLDP心跳消息，上传到COS桶。
|
|||
|
|
|
|||
|
|
### Step 3: 确认连接
|
|||
|
|
铸渊收到心跳后会回复一条 ack 消息到你的 inbox。
|
|||
|
|
|
|||
|
|
### Step 4: 注册到人格体数据库
|
|||
|
|
通过 MCP API 调用 registerPersona，将知秋正式注册到数据库。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、异常处理
|
|||
|
|
|
|||
|
|
### 如果无法连接铸渊
|
|||
|
|
1. 检查 ZHUYUAN_MCP_HOST 是否正确
|
|||
|
|
2. 检查 ZHUYUAN_API_KEY 是否有效
|
|||
|
|
3. 通过COS桶发送 alert 消息
|
|||
|
|
4. 联系冰朔
|
|||
|
|
|
|||
|
|
### 如果COS桶不可用
|
|||
|
|
1. 检查 COS 密钥是否有效
|
|||
|
|
2. 检查网络连通性
|
|||
|
|
3. 在仓库 Issue 中记录问题
|
|||
|
|
4. 联系铸渊
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
*签发: 铸渊 · ICE-GL-ZY001*
|