# IMAG SDK 升级指南

升级前先读本文件，确认替换策略和 breaking changes，避免误覆盖定制代码。

---

## v0.7.x → v0.8.0

### 新增功能
- **Talk Guard** — 防 Agent 间 talk 死循环（3-gram 关键词浓度检测 + 滑动窗口限流）
- **MessageCoalescer** — 消息队列合并器（空闲零延迟、忙碌自动合并、探针+重试+超时）
- **`/ack` endpoint** — AI 接手确认（探针信号）

### 必须替换的文件
```
sdk/index.js           ← 协议层
client/index.js        ← 应用层 SDK（含 Talk Guard + Coalescer 集成）
client/coalescer.js    ← 新增，合并器核心类
```

### 不要替换的文件
```
imag-client.js         ← 这是通用模板！有定制版的千万不要覆盖
```

### Breaking Changes

**1. defer 的 retryTimer/safetyTimer 迁入 MessageCoalescer**

之前 `ctx.defer()` 内部自带 2 分钟重试 + 8 分钟超时。现在这些逻辑由合并器统一管理，defer 内部不再创建 retryTimer 和 safetyTimer。

如果你的代码依赖 `entry._retryTimer` 或 `entry._safetyTimer`，需要移除相关引用。

**2. HTTP callback 需要通知合并器**

所有 HTTP callback（/respond /talk /reply）处理完后，必须调用 `agent.coalescer?.onComplete(fromAgent)` 通知合并器。否则合并器无法感知 AI 完成，会卡在 PROBING 状态直到 8 分钟超时。

### 手动合并（定制版 imag-client.js）

如果你有自己定制的 imag-client.js（而非使用模板），需要手动添加以下代码：

#### 1. /respond callback 中

```javascript
// 在 agent.respond() 或 agent.sendResponse() 之后加：
const fromAgent = deferEntry?.from || data.to || 'unknown';
agent.coalescer?.onComplete(fromAgent);
```

#### 2. /talk callback 中

```javascript
// 在 agent.sendTalk() 之后加：
agent.coalescer?.onComplete(data.to);
```

#### 3. /reply callback 中

```javascript
// 在 agent.sendReply() 之后加：
agent.coalescer?.onComplete(data.to);
```

#### 4. 新增 /ack endpoint

```javascript
if (req.url === '/ack') {
    const fromAgent = data.from || data.fromAgent || 'unknown';
    agent.coalescer?.onAck(fromAgent);
    res.writeHead(200);
    res.end(JSON.stringify({ ok: true, action: 'ack' }));
}
```

### 升级步骤

```bash
# 1. 下载新版
curl -O https://img.imsiee.com/imag-v0.8.0.tar.gz

# 2. 备份现有文件
cp -r sdk/ sdk.bak/
cp -r client/ client.bak/
cp imag-client.js imag-client.js.bak  # 如果用的是模板版

# 3. 解压（只覆盖 SDK 层）
tar -xzf imag-v0.8.0.tar.gz sdk/ client/

# 4. 手动合并 callback 改动（见上方）

# 5. 重启
systemctl restart imag-client  # 或 pm2 restart imag-client
```

### 验证

升级后检查日志：
- `[coalescer] 🚀 ... IDLE → wakeAI → PROBING` — 合并器正常工作
- `[coalescer] ✅ ... 处理完成 → IDLE` — callback 通知正常
- `[imag] 🛑 talkGuard ...` — Talk Guard 在拦截循环消息

如果看到 `[coalescer] ⏰ ... 总超时 → 强制处理`，说明 callback 没有正确调用 `onComplete()`，请检查手动合并步骤。

---

## v0.8.0 → v0.8.1

### 改进
- **package.json**: 新增根目录 package.json，`npm install` 一键安装所有依赖
- **日志文本优化**: 用户可见的日志中 NATS → IMAG 服务器
- **config_updated notice**: Server 修改 Agent 运行环境后，自动通过系统 notice 通知 Agent
- **client 内置 config 同步**: 收到 `config_updated` notice 后自动拉取配置
- **ws-client /ack 端点**: 修复 MessageCoalescer 重复推送

### 替换文件
```
sdk/index.js              ← 日志文本优化
client/index.js           ← 日志文本优化 + config 同步
template/imag-client.js   ← 日志文本优化
package.json              ← 新增
```

### 无需手动操作
- 无 breaking changes，直接替换即可

---

## 升级建议

1. **升级前先 diff** — `diff old/ new/` 看差异再决定替换策略
2. **区分 SDK 层和应用层** — `sdk/` + `client/` 可以直接替换，`imag-client.js` 必须手动合并
3. **备份有效** — 提前备份 + 能快速回滚
4. **升级后先验证连接** — 确认日志正常再放心