migrate-honcho-ts

Name: migrate-honcho-ts
Author: plastic-labs

github.com/plastic-labs开发7.8k332 次安装今天更新

代码仓库

关于 migrate-honcho-ts

migrate-honcho-ts 是将 Honcho TypeScript SDK 从 v1.6.0 迁移到 v2.1.1 的开发技能，面向维护现有集成的开发者。它梳理破坏性 API 变更并给出代码更新示例。

主要功能

01汇总版本间破坏性变更
02展示配置与列表方法改名
03说明流式聊天与表示接口更新
04指出队列轮询模式已移除

适用场景

01升级现有 Honcho TypeScript 集成
02排查升级后的类型或运行错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/plastic-labs/honcho --skill migrate-honcho-ts

安装后在 Claude Code 中输入/migrate-honcho-ts确认已加载。

附带文件DETAILED-CHANGES.mdMIGRATION-CHECKLIST.md

详细介绍

Honcho TypeScript SDK 迁移（v1.6.0 → v2.1.1）

概述

此技能将代码从 @honcho-ai/sdk v1.6.0 迁移到 v2.1.1（Honcho 3.0.0+ 所需）。

主要破坏性变更：

移除 @honcho-ai/core 依赖
术语从“Observation”改为“Conclusion”
术语从“Deriver”改为“Queue”
getConfig/setConfig → getConfiguration/setConfiguration
全面从 snake_case 改为 camelCase
使用 chatStream() 进行流式传输，而非 chat({ stream: true })
移除 Representation 类（现在返回字符串）

快速迁移

1. 更新依赖

从 package.json 中移除 @honcho-ai/core。SDK 现在自带 HTTP 客户端。

2. 将 `.core` 替换为 `.http`

// Before
const workspace = await client.core.workspaces.getOrCreate({ id: 'my-workspace' })

// After
const response = await client.http.post('/v3/workspaces', { body: { id: 'my-workspace' } })

3. 重命名配置方法

// Before
await honcho.getConfig()
await honcho.setConfig({ key: 'value' })
await peer.getConfig()
await session.getConfig()

// After
await honcho.getConfiguration()
await honcho.setConfiguration({ reasoning: { enabled: true } })
await peer.getConfiguration()
await session.getConfiguration()

4. 重命名列表方法

// Before
const peers = await honcho.getPeers()
const sessions = await honcho.getSessions()
const workspaces = await honcho.getWorkspaces()  // string[]

// After
const peers = await honcho.peers()
const sessions = await honcho.sessions()
const workspaces = await honcho.workspaces()  // Page<string>

5. 更新流式传输

// Before
const stream = await peer.chat('Hello', { stream: true })

// After
const stream = await peer.chatStream('Hello')

6. 将 observations 更新为 conclusions

// Before
peer.observations
peer.observationsOf('bob')
maxObservations: 50
includeMostDerived: true

// After
peer.conclusions
peer.conclusionsOf('bob')
maxConclusions: 50
includeMostFrequent: true

7. 更新队列状态方法

// Before
await honcho.getDeriverStatus({ observer: peer })
await honcho.pollDeriverStatus({ timeoutMs: 60000 })  // REMOVE - see note below

// After
await honcho.queueStatus({ observer: peer })
// pollDeriverStatus() has no replacement - see note below

重要：pollDeriverStatus() 及其轮询模式已被完全移除。不要依赖队列变为空。队列是一个持续处理系统——新消息可能随时到达，等待“完成”并非有效模式。如果你的代码之前会轮询队列是否处理完成，请重新设计，使其不再依赖这一假设。

8. 将 snake_case 转换为 camelCase

// Before
message.peer_id
message.session_id
message.created_at
message.token_count
{ observe_me: true, observe_others: false }
{ created_at: '2024-01-01' }

// After
message.peerId
message.sessionId
message.createdAt
message.tokenCount
{ observeMe: true, observeOthers: false }
{ createdAt: '2024-01-01' }

9. 更新 representation 调用

// Before
const rep = await peer.workingRep(session, target, options)
console.log(rep.explicit)  // ExplicitObservation[]
console.log(rep.deductive) // DeductiveObservation[]

// After
const rep = await peer.representation({ session, target, ...options })
console.log(rep)  // string

10. 将 updateMessage 移至 session

// Before
await honcho.updateMessage(message, metadata, session)

// After
await session.updateMessage(message, metadata)

11. 将 card() 更新为 getCard()（v2.0.1+）

// Before
const card = await peer.card(target)

// After (v2.0.1+)
const card = await peer.getCard(target)  // Returns string[] | null

// peer.card() still works but is deprecated — use getCard()

// New: setPeerCard / setCard
await peer.setCard(['Prefers dark mode', 'Located in US'])

12. 严格输入验证（v2.0.2+）

客户端构造函数和所有输入模式现在都会通过 .strict() Zod 验证拒绝未知选项。

// Before (v2.0.1 and earlier) — silently ignored
const honcho = new Honcho({ baseUrl: 'http://...' })  // typo: baseUrl vs baseURL — silently fell back to default

// After (v2.0.2+) — throws ZodError
const honcho = new Honcho({ baseUrl: 'http://...' })  // ZodError! Use baseURL

13. peer() 和 session() 始终会调用 API（v2.1.0+）

破坏性变更：peer() 和 session() 现在始终会调用 API 执行获取或创建操作。此前，如果调用时未提供元数据/配置，则会返回一个不会调用 API 的惰性对象。

// Before (v2.0.x) — no API call without options
const session = honcho.session('my-session')  // Lazy, no network request

// After (v2.1.0+) — always hits the API
const session = await honcho.session('my-session')  // Makes POST to /sessions (get-or-create)

14. 新属性和方法（v2.1.0+）

// createdAt on Peer and Session
const peer = await honcho.peer('user-123')
console.log(peer.createdAt)  // string | undefined

const session = await honcho.session('sess-1')
console.log(session.createdAt)  // string | undefined

// isActive on Session
console.log(session.isActive)  // boolean | undefined

// getMessage() on Session
const msg = await session.getMessage('msg-id')

15. 列表方法的分页参数（v2.1.0+）

所有列表方法现在都接受 page、size 和 reverse 参数：

// Before (v2.0.x) — only filters
const peers = await honcho.peers({ metadata: { role: 'admin' } })

// After (v2.1.0+) — pagination controls via options object
const peers = await honcho.peers({
  filters: { metadata: { role: 'admin' } },
  page: 2,
  size: 25,
  reverse: true
})

// Legacy raw-filter form still works:
const peers = await honcho.peers({ metadata: { role: 'admin' } })

// Works on: honcho.peers(), honcho.sessions(), honcho.workspaces(),
// peer.sessions(), session.messages(), scope.list()

16. searchQuery 在 context() 中的位置变更（v2.1.0+）

破坏性变更：searchQuery 已从顶层 context() 选项中移除。请改用 representationOptions.searchQuery。

// Before (v2.0.x)
await session.context({ searchQuery: '...' })

// After (v2.1.0+)
await session.context({ representationOptions: { searchQuery: '...' } })

17. 扩展 fetch 重试逻辑（v2.1.1+）

SDK 现在会针对所有 TypeError 网络故障（连接重置、DNS 错误等）进行重试，而不再仅针对消息中包含 'fetch' 的故障。无需更改代码——此变更会自动生效。

快速参考表

v1.6.0	v2.0.0
`client.core`	`client.http`
`getConfig()`	`getConfiguration()`
`setConfig()`	`setConfiguration()`
`getPeers()`	`peers()`
`getSessions()`	`sessions()`
`getWorkspaces()`	`workspaces()`
`getDeriverStatus()`	`queueStatus()`
`pollDeriverStatus()`	已移除 — 请勿轮询
`peer.chat(q, { stream: true })`	`peer.chatStream(q)`
`peer.workingRep()`	`peer.representation()`
`peer.getContext()`	`peer.context()`
`peer.observations`	`peer.conclusions`
`peer.observationsOf()`	`peer.conclusionsOf()`
`session.getPeers()`	`session.peers()`
`session.getMessages()`	`session.messages()`
`session.getSummaries()`	`session.summaries()`
`session.getContext()`	`session.context()`
`session.workingRep()`	`session.representation()`
`session.peerConfig()`	`session.getPeerConfiguration()`
`session.setPeerConfig()`	`session.setPeerConfiguration()`
`{ timeoutMs: 60000 }`	`{ timeout: 60000 }`
`{ maxObservations: 50 }`	`{ maxConclusions: 50 }`
`{ includeMostDerived }`	`{ includeMostFrequent }`
`{ lastUserMessage }`	`{ searchQuery }`
`{ config: ... }`	`{ configuration: ... }`
`message.peer_id`	`message.peerId`
`message.created_at`	`message.createdAt`
`peer.card()`	`peer.getCard()` (card() 已弃用)
(新增)	`peer.setCard(string[])`
`Observation`	`Conclusion`
`ObservationScope`	`ConclusionScope`
(v2.1.0 新增)	`peer.createdAt` / `session.createdAt`
(v2.1.0 新增)	`session.isActive`
(v2.1.0 新增)	`session.getMessage(id)`
(v2.1.0 新增)	列表方法中的 `page`、`size`、`reverse`
`context({ searchQuery })`	`context({ representationOptions: { searchQuery } })`

详细参考

如需了解各项变更的详细信息，请参阅：

DETAILED-CHANGES.md - 完整的 API 变更文档
MIGRATION-CHECKLIST.md - 分步检查清单

新错误类型

import {
  HonchoError,
  AuthenticationError,
  BadRequestError,
  NotFoundError,
  PermissionDeniedError,
  RateLimitError,
  ConflictError,
  UnprocessableEntityError,
  ServerError,
  ConnectionError,
  TimeoutError
} from '@honcho-ai/sdk'

新配置类型

配置现在采用强类型：

await honcho.setConfiguration({
  reasoning: {
    enabled: true,
    customInstructions: 'Be concise'
  },
  peerCard: { use: true, create: true },
  summary: {
    enabled: true,
    messagesPerShortSummary: 20,
    messagesPerLongSummary: 60
  },
  dream: { enabled: true }
})

支持 Markdown

登录后评论

基本信息

作者: plastic-labs
仓库: plastic-labs/honcho
分类: 开发
安装次数: 332
GitHub Stars: 7,807

报告问题