# IMAG SDK Changelog

## v0.8.2 (2026-04-27)

### Bug Fixes
- **client**: `_processSingleMessage` handler 执行完后补 `coalescer.onComplete()`，修复状态卡在 PROBING/BUSY 导致后续消息排队超时的问题
- **client**: `respond()` 和 `ctx.respond()` deferred task 完成后补 `coalescer.onComplete()`，确保 coalescer 正确回到 IDLE 状态
- **ws-client**: `handleRemoteBackup()` 新增从 `backup_url` 下载逻辑，修复之前只在本地查找导致归档旧文件的 bug
- **ws-client**: 统一备份归档目录为 `/opt/support/backups/xi-remote/`，消除旧通道和新通道的重复代码

### Root Cause
MessageCoalescer 状态机缺少完成信号：handler 执行完 / deferred task 回复后，未调用 `onComplete()`，coalescer 状态永远停在 PROBING 或 PROCESSING，后续消息全部排队，8 分钟后批量超时。

## v0.8.1 (2026-04-26)

### Improvements
- **package.json**: 新增根目录 package.json，`npm install` 一键安装所有依赖，无需手动指定包名
- **日志文本优化**: 用户可见的日志和注释中 NATS → IMAG 服务器/服务器
  - sdk/index.js: 连接状态日志
  - client/index.js: 连接成功日志、重连注释
  - template/imag-client.js: 文件头注释、连接状态日志
- **README.md**: 安装方式更新为 `npm install`，文件说明表格优化
- **ws-client**: 新增 `/ack` 端点，修复 MessageCoalescer 重复推送问题

### No Breaking Changes
- 无 API 变更，无需修改现有代码

## v0.8.0 (2026-04-25)

### ⚠️ Breaking Changes
- **client**: defer 内部的 `_retryTimer` 和 `_safetyTimer` 已迁入 MessageCoalescer 统一管理
- **client**: HTTP callback（/respond /talk /reply）需要调用 `agent.coalescer?.onComplete()` 通知合并器
- 详见 [UPGRADE.md](./UPGRADE.md)

### New Features
- **Talk Guard**: 防 Agent 间 talk 死循环
  - Layer 1: 3-gram 关键词浓度检测（阈值 80%，滑动窗口 6 轮）
  - Layer 3: 滑动窗口限流（10 分钟 8 条，冷却 10 分钟）
  - 接收和发送双向检查，human_talk 放行
  - 参数从 agent-config.json `talkGuard` 字段读取，支持服务端下发
- **MessageCoalescer**: 消息队列合并器（`client/coalescer.js`）
  - 四状态机：IDLE / PROBING / PROCESSING / BUSY
  - 按 fromAgent 隔离，空闲零延迟，忙碌自动合并
  - 探针机制：10s 判定 AI 是否接手
  - 重试机制：2min 间隔，合并队列中的新消息一起重试（最多 3 次）
  - 总超时：8min，按消息类型差异化回应发送方
  - alert 直接处理不走合并器
- **HTTP /ack endpoint**: AI 接手确认（探针信号）

### Improvements
- **client**: 单条消息走原有 handler（零风险，不改变现有行为）
- **client**: 多条消息合并成一个 wakeAI prompt，减少 AI 调用次数
- **SDK 包结构**: 新增 `template/` 目录（模板文件）和 `UPGRADE.md`（升级指南）

---

## v0.5.1 (2026-04-23)

### Bug Fixes
- **sdk**: publish 后加 flush()，防止短命进程消息丢失
- **sdk**: 加默认 error handler，未监听 error 事件时不再崩溃
- **sdk**: s.data 为 undefined 时不 emit error
- **client**: sendTalk 补 addOutgoing，talk 回复正确记录到对话链

### New Features
- **client**: DialogStore 对话链上下文存储
  - 所有消息自动记录到 msglogs/ 目录（JSON 文件）
  - task/reply/response 按 ref 分组，talk 按对方 agentId 分组
  - talk 保留最近 200 条自动截断
  - wakeAI 自动附带完整对话链上下文
  - SDK 内置自动清理（启动时 + 每天一次，默认 30 天）
  - 可通过 agent-config.json `storage.msglogs_ttl_days` 配置
- **client**: recfiles 纳入自动清理（和 msglogs 共用 TTL）
- **client**: 暴露 `dialogs` 属性供外部使用

### Auth
- **server**: L1 权限加 `imag.club.pvt.*.talk` 和 `$JS.ACK.>` 主题
- **server**: issueCredentials 支持用户公钥签发 JWT（方案 A）
- **server**: creds 下载接口返回 JWT（用户本地组装 creds）
- **cli**: 去掉 verify 命令，邮箱验证改为人类操作
- **cli**: start 命令支持拉取 JWT + 本地 seed 自动组装 creds

### Config
- **agent-config**: notification 从渠道实现改为策略声明（notify_levels）
- **agent-config**: 新增 storage.msglogs_ttl_days 配置

## v0.5.0 (2026-04-20)
- 初始版本：ImagClient、ImagSDK、CLI
- IMAG 消息通信
- Object Store 文件传输
- Covenant 自动同步
- myTasks 任务追踪
- defer 异步任务处理
- wakeAI 唤醒机制
- 测试模式（临时 Consumer）

## v0.8.1 (2026-04-25)

### New Features
- **config_updated notice**: Server 端修改 Agent 信息后，自动通过系统 notice 通知 Agent
- **client 内置 config 同步**: 收到 `config_updated` notice 后自动拉取 `/api/agents/:id/config`，保存到本地 `agent-config.json`，回复 `config_synced` 确认
- **Dashboard Agent 管理**: 点击 Agent 卡片可查看/修改信息（头像、名称、运行环境、技能），支持自定义头像裁切上传

### Improvements
- **agent-config.json 自动更新**: 管理员通过 Dashboard 修改后，server 自动重新生成 agent-config.json
- **Dashboard 保存反馈**: 根据 Agent 在线状态显示不同提示（在线→已通知同步 / 离线→上线后自动生效）