migrate-honcho-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Honcho TypeScript SDK Migration (v1.6.0 → v2.0.0)

Honcho TypeScript SDK 迁移指南（v1.6.0 → v2.0.0）

Overview

概述

This skill migrates code from

@honcho-ai/sdk

v1.6.0 to v2.0.0 (required for Honcho 3.0.0+).

Key breaking changes:

```
@honcho-ai/core
```
dependency removed
"Observation" → "Conclusion" terminology
"Deriver" → "Queue" terminology

getConfig

setConfig

→

getConfiguration

setConfiguration

```
snake_case
```
→
```
camelCase
```
throughout
Streaming via
```
chatStream()
```
instead of
```
chat({ stream: true })
```
```
Representation
```
class removed (returns string now)

本技能可将

@honcho-ai/sdk

v1.6.0版本的代码迁移至v2.0.0版本（Honcho 3.0.0+版本要求使用该SDK版本）。

主要破坏性变更：

移除
```
@honcho-ai/core
```
依赖
术语从“Observation”改为“Conclusion”
术语从“Deriver”改为“Queue”

getConfig

setConfig

替换为

getConfiguration

setConfiguration

全局将蛇形命名（snake_case）改为驼峰命名（camelCase）
通过
```
chatStream()
```
实现流式传输，替代
```
chat({ stream: true })
```
移除Representation类（现在直接返回字符串）

Quick Migration

快速迁移步骤

1. Update dependencies

1. 更新依赖

Remove

@honcho-ai/core

from package.json. The SDK now has its own HTTP client.

从package.json中移除

@honcho-ai/core

。SDK现在内置了独立的HTTP客户端。

2. Replace

.core

with

.http

2. 将

.core

替换为

.http

typescript

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

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

typescript

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

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

3. Rename configuration methods

3. 重命名配置方法

typescript

// 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()

typescript

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

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

4. Rename listing methods

4. 重命名列表查询方法

typescript

// 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>

typescript

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

// 新版本
const peers = await honcho.peers()
const sessions = await honcho.sessions()
const workspaces = await honcho.workspaces()  // Page<string>

5. Update streaming

5. 更新流式传输逻辑

typescript

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

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

typescript

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

// 新版本
const stream = await peer.chatStream('Hello')

6. Update observations → conclusions

6. 将observations替换为conclusions

typescript

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

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

typescript

// 旧版本
peer.observations
peer.observationsOf('bob')
maxObservations: 50
includeMostDerived: true

// 新版本
peer.conclusions
peer.conclusionsOf('bob')
maxConclusions: 50
includeMostFrequent: true

7. Update queue status methods

7. 更新队列状态方法

typescript

// 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

Important:

pollDeriverStatus()

and its polling pattern have been removed entirely. Do not rely on the queue ever being empty. The queue is a continuous processing system—new messages may arrive at any time, and waiting for "completion" is not a valid pattern. If your code previously polled for queue completion, redesign it to work without that assumption.

typescript

// 旧版本
await honcho.getDeriverStatus({ observer: peer })
await honcho.pollDeriverStatus({ timeoutMs: 60000 })  // 已移除 - 见下方说明

// 新版本
await honcho.queueStatus({ observer: peer })
// pollDeriverStatus()无替代方案 - 见下方说明

重要提示：

pollDeriverStatus()

及其轮询模式已被完全移除。不要依赖队列变为空的状态。队列是持续处理的系统——新消息可能随时到达，等待“完成”不是有效的设计模式。如果你的代码之前依赖轮询队列完成状态，请重新设计逻辑以适配该变化。

8. Convert snake_case to camelCase

8. 将蛇形命名转换为驼峰命名

typescript

// 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' }

typescript

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

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

9. Update representation calls

9. 更新表示层调用

typescript

// 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

typescript

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

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

10. Move updateMessage to session

10. 将updateMessage方法迁移至session对象

typescript

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

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

typescript

// 旧版本
await honcho.updateMessage(message, metadata, session)

// 新版本
await session.updateMessage(message, metadata)

Quick Reference Table

快速参考对照表

v1.6.0	v2.0.0
`client.core`	`client.http`
`getConfig()`	`getConfiguration()`
`setConfig()`	`setConfiguration()`
`getPeers()`	`peers()`
`getSessions()`	`sessions()`
`getWorkspaces()`	`workspaces()`
`getDeriverStatus()`	`queueStatus()`
`pollDeriverStatus()`	Removed - do not poll
`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: 60 }`
`{ maxObservations: 50 }`	`{ maxConclusions: 50 }`
`{ includeMostDerived }`	`{ includeMostFrequent }`
`{ lastUserMessage }`	`{ searchQuery }`
`{ config: ... }`	`{ configuration: ... }`
`message.peer_id`	`message.peerId`
`message.created_at`	`message.createdAt`
`Observation`	`Conclusion`
`ObservationScope`	`ConclusionScope`

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: 60 }`
`{ maxObservations: 50 }`	`{ maxConclusions: 50 }`
`{ includeMostDerived }`	`{ includeMostFrequent }`
`{ lastUserMessage }`	`{ searchQuery }`
`{ config: ... }`	`{ configuration: ... }`
`message.peer_id`	`message.peerId`
`message.created_at`	`message.createdAt`
`Observation`	`Conclusion`
`ObservationScope`	`ConclusionScope`

Detailed Reference

详细参考

For comprehensive details on each change, see:

DETAILED-CHANGES.md - Full API change documentation
MIGRATION-CHECKLIST.md - Step-by-step checklist

如需了解每个变更的完整细节，请查看：

DETAILED-CHANGES.md - 完整API变更文档
MIGRATION-CHECKLIST.md - 分步迁移清单

New Error Types

新增错误类型

typescript

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

typescript

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

New Configuration Types

新增配置类型

Configurations are now strongly typed:

typescript

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

现在配置项具备强类型约束：

typescript

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

migrate-honcho-ts

Original

Translation

Honcho TypeScript SDK Migration (v1.6.0 → v2.0.0)

Honcho TypeScript SDK 迁移指南（v1.6.0 → v2.0.0）

Overview

概述

Quick Migration

快速迁移步骤

1. Update dependencies

1. 更新依赖

2. Replace
`.core`
with
`.http`

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

3. Rename configuration methods

3. 重命名配置方法

4. Rename listing methods

4. 重命名列表查询方法

5. Update streaming

5. 更新流式传输逻辑

6. Update observations → conclusions

6. 将observations替换为conclusions

7. Update queue status methods

7. 更新队列状态方法

8. Convert snake_case to camelCase

8. 将蛇形命名转换为驼峰命名

9. Update representation calls

9. 更新表示层调用

10. Move updateMessage to session

10. 将updateMessage方法迁移至session对象

Quick Reference Table

快速参考对照表

Detailed Reference

详细参考

New Error Types

新增错误类型

New Configuration Types

新增配置类型

migrate-honcho-ts

Original

Translation

Honcho TypeScript SDK Migration (v1.6.0 → v2.0.0)

Honcho TypeScript SDK 迁移指南（v1.6.0 → v2.0.0）

Overview

概述

Quick Migration

快速迁移步骤

1. Update dependencies

1. 更新依赖

2. Replace .core with .http

2. 将.core替换为.http

3. Rename configuration methods

3. 重命名配置方法

4. Rename listing methods

4. 重命名列表查询方法

5. Update streaming

5. 更新流式传输逻辑

6. Update observations → conclusions

6. 将observations替换为conclusions

7. Update queue status methods

7. 更新队列状态方法

8. Convert snake_case to camelCase

8. 将蛇形命名转换为驼峰命名

9. Update representation calls

9. 更新表示层调用

10. Move updateMessage to session

10. 将updateMessage方法迁移至session对象

Quick Reference Table

快速参考对照表

Detailed Reference

详细参考

New Error Types

新增错误类型

New Configuration Types

新增配置类型

2. Replace
`.core`
with
`.http`

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