用途
migrate-ts 用于将 Honcho TypeScript SDK 代码从 v1.6.0 迁移到 v2.0.0。v2.0.0 是使用 Honcho 3.0.0+ 所必需的版本。当需要升级 @honcho-ai/sdk、修复升级后的破坏性变更,或错误信息涉及相关 API 时,可使用此技能。
主要能力
该技能覆盖以下破坏性变更的迁移:
依赖变更:移除 @honcho-ai/core 依赖,SDK 现在拥有自己的 HTTP 客户端,将 .core 替换为 .http。
术语替换:"Observation" 改为 "Conclusion","Deriver" 改为 "Queue"。
方法重命名:getConfig/setConfig 改为 getConfiguration/setConfiguration;getPeers/getSessions/getWorkspaces 分别改为 peers/sessions/workspaces;getDeriverStatus 改为 queueStatus;peer.workingRep 改为 peer.representation;peer.getContext 改为 peer.context;peer.observations 改为 peer.conclusions;session.getPeers 改为 session.peers 等。
命名风格:snake_case 改为 camelCase,例如 message.peer_id 改为 message.peerId,message.created_at 改为 message.createdAt,message.token_count 改为 message.tokenCount,observe_me 改为 observeMe,created_at 改为 createdAt。
流式调用:peer.chat(q, { stream: true }) 改为 peer.chatStream(q)。
Representation 类移除:representation 相关调用现在返回 string,不再返回包含 explicit、deductive 等字段的对象。
updateMessage 位置调整:从 honcho.updateMessage(message, metadata, session) 改为 session.updateMessage(message, metadata)。
参数重命名:{ timeoutMs: 60000 } 改为 { timeout: 60 };{ maxObservations: 50 } 改为 { maxConclusions: 50 };{ includeMostDerived } 改为 { includeMostFrequent };{ lastUserMessage } 改为 { searchQuery };{ config: ... } 改为 { configuration: ... }。
pollDeriverStatus 完全移除:该轮询模式不再存在,不应依赖队列为空。队列是持续处理系统,新消息可能随时到达,等待"完成"不是有效模式。如果原有代码轮询队列完成,需要重新设计以移除该假设。
新增错误类型:包括 HonchoError、AuthenticationError、BadRequestError、NotFoundError、PermissionDeniedError、RateLimitError、ConflictError、UnprocessableEntityError、ServerError、ConnectionError、TimeoutError。
强类型配置:Configuration 现在支持强类型,例如 reasoning、peerCard、summary、dream 等配置项。
使用方式
按照快速迁移步骤操作:更新依赖、替换 .core 为 .http、重命名配置方法、重命名列表方法、更新流式调用、更新 observations 为 conclusions、更新队列状态方法、转换 snake_case 为 camelCase、更新 representation 调用、移动 updateMessage 到 session。技能提供前后代码对照和快速参考表。更详细的变更可参考 DETAILED-CHANGES.md 和 MIGRATION-CHECKLIST.md。
适用场景
适用于升级 Honcho TypeScript SDK 版本、处理升级后的编译或运行时错误、以及将旧版 API 调用更新为新版 API。
限制
本资料仅涉及 TypeScript SDK 的版本迁移,未提供其他语言 SDK 的迁移说明。部分具体行为细节(如队列处理的具体机制)暂未提供。