# https://github.com/plastic-labs/honcho 项目说明书

生成时间：2026-06-14 14:06:43 UTC

## 目录

- [Honcho 系统架构与核心数据模型](#page-1)
- [LLM、Embedding 与向量存储后端配置](#page-2)
- [Deriver 推理流水线、Conclusions 与 Dreamer](#page-3)
- [SDK、honcho-cli、MCP 与生态集成](#page-4)

<a id='page-1'></a>

## Honcho 系统架构与核心数据模型

### 相关页面

相关主题：[LLM、Embedding 与向量存储后端配置](#page-2), [Deriver 推理流水线、Conclusions 与 Dreamer](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [README.md](https://github.com/plastic-labs/honcho/blob/main/README.md)
- 资料来源： [src/main.py](https://github.com/plastic-labs/honcho/blob/main/src/main.py)
- 资料来源： [src/models.py](https://github.com/plastic-labs/honcho/blob/main/src/models.py)
- 资料来源： [src/config.py](https://github.com/plastic-labs/honcho/blob/main/src/config.py)
- 资料来源： [src/schemas/api.py](https://github.com/plastic-labs/honcho/blob/main/src/schemas/api.py)
- 资料来源： [src/routers/workspaces.py](https://github.com/plastic-labs/honcho/blob/main/src/routers/workspaces.py)
</details>

---

<a id='page-2'></a>

## LLM、Embedding 与向量存储后端配置

### 相关页面

相关主题：[Honcho 系统架构与核心数据模型](#page-1), [Deriver 推理流水线、Conclusions 与 Dreamer](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/plastic-labs/honcho/blob/main/README.md)
- [config.toml.example](https://github.com/plastic-labs/honcho/blob/main/config.toml.example)
- [src/embedding_client.py](https://github.com/plastic-labs/honcho/blob/main/src/embedding_client.py)
- [src/llm/api.py](https://github.com/plastic-labs/honcho/blob/main/src/llm/api.py)
- [src/llm/registry.py](https://github.com/plastic-labs/honcho/blob/main/src/llm/registry.py)
- [src/llm/backends/openai.py](https://github.com/plastic-labs/honcho/blob/main/src/llm/backends/openai.py)
- [src/llm/backends/anthropic.py](https://github.com/plastic-labs/honcho/blob/main/src/llm/backends/anthropic.py)
- [src/llm/backends/gemini.py](https://github.com/plastic-labs/honcho/blob/main/src/llm/backends/gemini.py)
- [sdks/python/src/honcho/api_types.py](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/api_types.py)
- [honcho-cli/src/honcho_cli/commands/conclusion.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/conclusion.py)
- [honcho-cli/src/honcho_cli/commands/peer.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/peer.py)
- [sdks/typescript/src/validation.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/validation.ts)
</details>

# LLM、Embedding 与向量存储后端配置

Honcho 在推理、嵌入生成与语义检索三个核心环节上都需要外部服务支撑。本页说明这三类后端的配置方式、参数语义，以及社区中常见的失败模式与对应的规避策略。

## 配置体系总览

Honcho 采用统一的配置加载机制，支持 TOML 文件与环境变量两种来源。优先级顺序为：**环境变量 > `.env` 文件 > `config.toml` > 默认值**。配置文件按功能划分为多个段，其中与本页相关的核心段包括 `[llm]`、`[deriver]`、`[peer_card]`、`[dialectic]`、`[summary]`、`[dream]` 与 `[vector_store]`。资料来源：[README.md:configuration]()。

启动时可直接复制示例配置：

```bash
cp config.toml.example config.toml
```

修改后通过环境变量或 TOML 段即可切换不同后端。每个段均可被同名环境变量覆盖，命名规则为 `<SECTION>_<KEY>`，例如 `LLM_OPENAI_API_KEY` 或 `DERIVER_MODEL_CONFIG__TRANSPORT`。

## LLM 后端配置

LLM 段负责为 deriver、dialectic、summary、dream 等后台推理任务提供模型访问能力。Honcho 通过 [src/llm/registry.py](https://github.com/plastic-labs/honcho/blob/main/src/llm/registry.py) 注册多种传输协议（transport），并由 `src/llm/backends/` 下的适配器实现具体调用，包括 OpenAI、Anthropic、Gemini 等。资料来源：[README.md:configuration]()。

社区中常见的失败模式集中在「OpenAI 兼容端点」场景：当 `LLM_OPENAI_API_KEY` 设置为 OpenRouter、vLLM、Together 等服务的密钥时，默认的 `AsyncOpenAI` 客户端缺少 `base_url`，会被路由到 `api.openai.com` 并返回 401。规避方法是显式设置 `OPENAI_BASE_URL` 与对应模型名，例如使用 Nvidia NIM 时：

```bash
LLM_OPENAI_API_KEY=api_key
OPENAI_BASE_URL=https://integrate.api.nvidia.com/v1
DERIVER_MODEL_CONFIG__TRANSPORT=openai
DERIVER_MODEL_CONFIG__MODEL=nvidia/nemotron-3-nano-omni-3
```

资料来源：[issue #641]() 与 [issue #789]()。另外，DeepSeek 等模型返回 `reasoning_content`（单数字符串）而非 OpenRouter 风格的 `reasoning_details`（列表），工具续接回合需在适配层做归一化处理——参见 [issue #723]()。

## Embedding 客户端配置

嵌入客户端由 [src/embedding_client.py](https://github.com/plastic-labs/honcho/blob/main/src/embedding_client.py) 驱动，负责将消息、文档与结论编码为向量。它支持多种 provider，但模型名称与部分 provider 的 base URL 在源码中被硬编码，导致用户无法直接接入自托管端点（Ollama、llama.cpp、TEI、Infinity 等）。资料来源：[issue #578]() 与 [issue #443]()。

主要已知问题：

- `provider == "openrouter"` 分支下若 `api_key` 为空，会回退到 `settings.LLM.OPENAI_COMPATIBLE_API_KEY`，未设置时直接抛错。
- 模型名硬编码为 jina 系（如 Jina1024），切换为本地 `bge-m3` 等需要修改源码。
- 两个 provider 的 base URL 同样硬编码，无法指向自托管实例。

社区已多次提出允许通过环境变量配置 `EMBEDDING_MODEL` 与 `EMBEDDING_BASE_URL` 的特性请求（[issue #578]()）。在官方支持之前，可行的临时方案是 fork 仓库并修改 `src/embedding_client.py` 中对应分支，或在反向代理层重写请求路径。

## 向量存储后端配置

`[vector_store]` 段用于选择 Honcho 内部 collections/documents 的物理存储，可选项包括 **pgvector**、**turbopuffer** 与 **lancedb**。资料来源：[README.md:configuration]()。

```mermaid
flowchart LR
  A[消息/文档] --> B[Embedding Client]
  B --> C{Vector Store}
  C -->|pgvector| D[(Postgres + pgvector)]
  C -->|turbopuffer| E[(turbopuffer Cloud)]
  C -->|lancedb| F[(本地 LanceDB)]
```

社区曾讨论将 TurboQuant / turbovec 作为可选后端以实现极致向量压缩，对 10M 级别语料可显著降低内存占用——参见 [issue #781]()。该方案目前仍处于提案阶段，未合入主分支。Cloud 与自托管实例之间迁移 workspace 时，需要同时迁移 embeddings 与 vector store 数据，相关迁移工具尚未官方提供，参见 [issue #721]()。

## 派生流程与后台 Worker

后台 deriver 是将原始消息转化为 conclusions（结论）的核心 worker。若部署中未自动启动 deriver，消息虽然入库但派生的 peer card / context / search 结果会一直为空——这是 [issue #494]() 报告的典型症状。结论的查询与删除接口由 CLI 与 SDK 暴露，例如 [honcho-cli/src/honcho_cli/commands/conclusion.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/conclusion.py) 与 [honcho-cli/src/honcho_cli/commands/peer.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/peer.py)。确保 deriver worker 与 API 服务在同一配置下启动，并检查 `DERIVER_*` 段参数是否正确传递。

## 已知限制与规避

- **派生态不自洽**：派生的 conclusion 可能与原始消息脱钩，并能在源文档删除与 Redis 缓存刷新后自我复现——参见 [issue #725]()。需要在删除时级联清理派生态。
- **embedding 切换困难**：如上节所述，模型名与 base URL 硬编码，临时方案是 fork 或反向代理。
- **CLI 依赖缺失**：`honcho-cli` 旧版本缺少 `click` 依赖（[issue #786]()），建议升级至包含修复的版本或等待 [issue #808]() 中的重新发布。
- **SDK 输入校验**：Python 与 TypeScript SDK 在入口处使用 Pydantic / Zod 对配置与消息进行校验，例如 [sdks/python/src/honcho/api_types.py](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/api_types.py) 与 [sdks/typescript/src/validation.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/validation.ts) 对 workspace ID 的字符集与长度进行约束。自托管部署若自定义 ID 规范，需同步调整校验逻辑。

---

## See Also

- [README.md](https://github.com/plastic-labs/honcho/blob/main/README.md) — 项目总览与配置章节
- [config.toml.example](https://github.com/plastic-labs/honcho/blob/main/config.toml.example) — 完整配置示例
- [src/embedding_client.py](https://github.com/plastic-labs/honcho/blob/main/src/embedding_client.py) — Embedding 客户端实现
- [src/llm/](https://github.com/plastic-labs/honcho/tree/main/src/llm) — LLM 传输与后端适配器
- [sdks/python/src/honcho/api_types.py](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/api_types.py) — Python SDK 配置类型
- [sdks/typescript/src/validation.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/validation.ts) — TypeScript SDK 校验逻辑

---

<a id='page-3'></a>

## Deriver 推理流水线、Conclusions 与 Dreamer

### 相关页面

相关主题：[Honcho 系统架构与核心数据模型](#page-1), [SDK、honcho-cli、MCP 与生态集成](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/plastic-labs/honcho/blob/main/README.md)
- [sdks/typescript/src/conclusions.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/conclusions.ts)
- [sdks/typescript/src/validation.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/validation.ts)
- [sdks/typescript/src/types/api.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/types/api.ts)
- [sdks/python/src/honcho/api_types.py](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/api_types.py)
- [sdks/python/src/honcho/__init__.py](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/__init__.py)
- [honcho-cli/src/honcho_cli/commands/conclusion.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/conclusion.py)
- [honcho-cli/README.md](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/README.md)
- [honcho-cli/src/honcho_cli/main.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/main.py)
</details>

# Deriver 推理流水线、Conclusions 与 Dreamer

## 1. 概览：记忆推理系统的核心作用

Honcho 在 README 中被定位为面向 AI agent 的"记忆层（memory layer）"，与传统 RAG 或纯向量数据库的关键差异在于其 **异步 deriver（推理器）后台流水线**：写入消息后，Honcho 不会立即返回检索结果，而是由 deriver 把消息提炼为结构化、可推理的"记忆原子"——也就是 **Conclusions**，并同步更新 **Peer Cards** 与 **Session summaries**。这三类产物共同构成 `Representation` API 暴露的对外视图。

```mermaid
flowchart LR
    Msg[新消息写入] --> Q[deriver 队列<br/>queue_manager]
    Q --> C[deriver consumer<br/>consumer.py]
    C --> LLM[LLM 抽取<br/>deriver.py]
    LLM --> Concl[写入 Conclusions]
    LLM --> PCard[更新 Peer Cards]
    LLM --> Summ[生成 Session Summaries]
    Concl --> VS[(向量库<br/>Collections/Documents)]
    PCard --> VS
    Summ --> VS
    VS --> Rep[Representation / Dialectic 响应]
    Dr[Dreamer 后台<br/>低频反思] -.周期性.-> VS
```

资料来源：[README.md]() · [sdks/typescript/src/conclusions.ts:12-34]()

## 2. Conclusions：记忆原子

### 2.1 数据模型与语义

`sdk/typescript/src/conclusions.ts` 中 `Conclusion` 类把后端 schema 镜像到前端 SDK，其字段反映了"视角方 vs 被观察方"的双 peer 模型：

| 字段 | 含义 |
|------|------|
| `id` | 后端生成的主键 |
| `content` | 提炼后的自然语言事实 |
| `observerId` | 视角方 peer（"谁在观察"） |
| `observedId` | 被观察方 peer |
| `sessionId` | 是否绑定到具体会话，可为 `null` |
| `createdAt` | ISO 8601 时间戳 |

`observer == observed` 表示"自表示"，`observer != observed` 表示"跨 peer 建模"，与 README 中 "Internal storage (Collections & Documents)" 小节对 `(observer, observed)` 双键 collection 的描述一致。

资料来源：[sdks/typescript/src/conclusions.ts:34-77]() · [README.md]()

### 2.2 创建参数与 CLI 入口

`ConclusionCreateParams` 只暴露两个字段：`content` 与可选的 `sessionId`（接受 ID 字符串或 `Session` 对象）。这意味着**手工写入 conclusion 时无法指定 observer/observed**——视角方由当前 peer context 隐式决定。

CLI 把 conclusion 暴露为一级命令：

```bash
honcho conclusion list          # 列出，支持 --observer/--observed
honcho conclusion search <q>    # 语义检索
honcho conclusion create        # 手工创建
honcho conclusion delete <id>   # 删除
```

`list` 与 `search` 都强制要求解析出 observer peer ID；缺失 scope 时 CLI 会发出结构化错误（`NO_PEER` / `NO_SCOPE`）并以非零状态退出，便于脚本层处理。

资料来源：[sdks/typescript/src/conclusions.ts:13-21]() · [honcho-cli/src/honcho_cli/commands/conclusion.py:18-46]() · [honcho-cli/README.md:30-36]()

## 3. 配置体系：deriver 与 dreamer 的开关

所有 deriver / dreamer 行为都通过 workspace 或 session 级 `configuration` 控制。Python 端在 `api_types.py` 用 Pydantic 模型定义，TypeScript 端在 `validation.ts` 用 Zod schema 镜像，两端通过 snake_case 协议通信：

| 配置类 | 关键字段 | 控制对象 |
|--------|----------|----------|
| `ReasoningConfiguration` | `enabled`, `custom_instructions` | 是否启用 deriver 推理 + 提示词覆盖 |
| `PeerCardConfiguration` | `use`, `create` | peer card 的读取/生成策略 |
| `SummaryConfiguration` | `enabled`, `messages_per_short_summary`, `messages_per_long_summary` | 会话摘要的窗口与开关 |
| `DreamConfiguration` | `enabled` | dreamer 后台进程是否启动 |

`WorkspaceConfiguration` 把上述四类聚合为一个对象；`SessionConfiguration` 与之同构，可覆盖 workspace 级设置。TypeScript 端的 `reasoningConfigToApi` / `reasoningConfigFromApi` 等函数负责 camelCase ↔ snake_case 转换，保证 SDK 一致性。

资料来源：[sdks/python/src/honcho/api_types.py:23-118]() · [sdks/typescript/src/validation.ts:23-110]() · [sdks/typescript/src/validation.ts:117-145]()

## 4. Dreamer：异步反思进程

Dreamer（"做梦"）是一种低频后台作业，周期性地对累积的 observations、conclusions 与历史消息进行再压缩、关联与遗忘，使 peer 表示在对话静默期间也持续演化。其开关由 `DreamConfiguration.enabled` 控制。README.md 的 `[dream]` 配置段进一步暴露了"specialist models"与"surprisal settings"等专属参数——这些参数与 deriver 共享 LLM 客户端，但通常使用不同模型与温度，以降低对实时路径的影响。

资料来源：[README.md]() · [sdks/python/src/honcho/api_types.py:71-79]()

## 5. 常见失败模式（社区反馈）

下列行为在 self-host 用户中反复出现，部署前应确认：

| 症状 | 根因 | 修复方向 |
|------|------|----------|
| 消息入队后 peer card / context 仍为空 | deriver 进程未启动或未消费队列（issue #494） | 在 `docker-compose` 中显式启动 deriver worker，或手动运行 |
| 删除某 conclusion 后立即重新出现 | deriver 重跑同窗口消息并再次派生（issue #725） | 增大源文档删除的传播窗口，或临时关闭对应 session 的 `ReasoningConfiguration.enabled` |
| OpenAI 兼容 provider 报 401 | `AsyncOpenAI` 缺少 `base_url`（issue #641） | 在 `.env` 设置 `OPENAI_BASE_URL` 等 provider 字段 |
| 本地嵌入模型无法直接使用 | `embedding_client.py` 硬编码 provider 模型与 URL（issue #578 / #443） | 通过 `EMBEDDING_*` 环境变量覆盖，或 fork 调整 |
| CLI 安装后 `ModuleNotFoundError: 'click'` | `honcho-cli` 0.1.0 缺少 `click` 依赖（issue #786） | 等修复版发布，或本地源码安装 |

资料来源：[README.md]() · [honcho-cli/README.md]() · [honcho-cli/src/honcho_cli/main.py:18-32]()

## See Also

- [Honcho 主仓库 README](https://github.com/plastic-labs/honcho/blob/main/README.md)
- [TypeScript SDK Conclusion 实现](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/conclusions.ts)
- [Python SDK API 类型](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/api_types.py)
- [honcho-cli Conclusion 命令](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/conclusion.py)
- [CrewAI 集成示例](https://github.com/plastic-labs/honcho/blob/main/examples/crewai/python/README.md)

---

<a id='page-4'></a>

## SDK、honcho-cli、MCP 与生态集成

### 相关页面

相关主题：[Honcho 系统架构与核心数据模型](#page-1), [Deriver 推理流水线、Conclusions 与 Dreamer](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/plastic-labs/honcho/blob/main/README.md)
- [sdks/python/src/honcho/api_types.py](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/api_types.py)
- [sdks/python/src/honcho/pagination.py](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/pagination.py)
- [sdks/typescript/src/index.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/index.ts)
- [sdks/typescript/src/validation.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/validation.ts)
- [sdks/typescript/src/types/api.ts](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/types/api.ts)
- [sdks/typescript/package.json](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/package.json)
- [honcho-cli/src/honcho_cli/main.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/main.py)
- [honcho-cli/src/honcho_cli/_help.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/_help.py)
- [honcho-cli/src/honcho_cli/commands/conclusion.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/conclusion.py)
- [honcho-cli/src/honcho_cli/commands/peer.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/peer.py)
- [honcho-cli/src/honcho_cli/commands/session.py](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/session.py)
- [mcp/src/config.ts](https://github.com/plastic-labs/honcho/blob/main/mcp/src/config.ts)
- [mcp/src/types.ts](https://github.com/plastic-labs/honcho/blob/main/mcp/src/types.ts)
- [examples/langgraph/typescript/package.json](https://github.com/plastic-labs/honcho/blob/main/examples/langgraph/typescript/package.json)
</details>

# SDK、honcho-cli、MCP 与生态集成

## 概览

Honcho 的核心是仓库内的 FastAPI 服务，围绕它构建了多层客户端与代理生态：Python SDK、TypeScript SDK、`honcho-cli` 终端工具、托管在 Cloudflare Worker 上的 MCP 服务器，以及面向 Claude Code、OpenCode、OpenClaw、Hermes、Cursor 等代理的插件。客户端层通过 REST/MCP 与核心服务交互，集成层把 Honcho 的“推理式记忆”能力嵌入到现有代理工作流中（资料来源：[README.md](https://github.com/plastic-labs/honcho/blob/main/README.md)）。

```mermaid
graph LR
    subgraph Core["核心服务"]
        API["FastAPI Server"]
    end
    subgraph Clients["客户端层"]
        Py["Python SDK"]
        Ts["TypeScript SDK"]
        CLI["honcho-cli"]
        MCP["MCP Server"]
    end
    subgraph Agents["代理 / 集成"]
        CC["Claude Code"]
        OC["OpenCode"]
        OCL["OpenClaw"]
        Cur["Cursor 等 MCP 客户端"]
    end
    API <--> Py
    API <--> Ts
    API <--> CLI
    API <--> MCP
    Py --> CC
    Py --> OC
    MCP --> CC
    MCP --> Cur
```

## Python 与 TypeScript SDK

### 共享数据模型

两个 SDK 都直接镜像后端 Pydantic schema。Python 端在 [`sdks/python/src/honcho/api_types.py`](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/api_types.py) 中以 `pydantic.BaseModel` 暴露 `WorkspaceConfiguration`、`PeerCardConfiguration`、`SummaryConfiguration`、`DreamConfiguration` 等，并把 `ConfigDict(extra="forbid")` 设为统一策略；TypeScript 端在 [`sdks/typescript/src/types/api.ts`](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/types/api.ts) 中导出 `WorkspaceResponse`、`PeerResponse`、`WorkspaceCreateParams` 等接口，二者字段一一对应，方便跨语言迁移。

### 运行时校验

TypeScript SDK 在 [`sdks/typescript/src/validation.ts`](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/validation.ts) 中使用 Zod 做强校验：`HonchoConfigSchema`（带 `.strict()`、约束 `baseURL` 必须为合法 URL、`maxRetries ∈ [0,3]`）、`WorkspaceIdSchema`（正则 `^[a-zA-Z0-9_-]+$`、最大 512 字符）等，可在请求发出前就拦截非法输入。Python SDK 则通过 Pydantic 的 `ConfigDict(extra="forbid")` 表达同样的“额外字段即报错”语义。

### 分页与流式

Python SDK 在 [`sdks/python/src/honcho/pagination.py`](https://github.com/plastic-labs/honcho/blob/main/sdks/python/src/honcho/pagination.py) 中提供 `SyncPage` / `AsyncPage` 泛型包装，对应后端 `items / page / size / total / pages` 结构，可选 `transform_func` 与 `fetch_next` 回调实现惰性翻页与对象转换。TypeScript SDK 在 [`sdks/typescript/src/index.ts`](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/src/index.ts) 中导出 `Page`、流式 `DialecticStreamChunk` 与 `DialecticStreamResponse`，把对话结果增量拼装到上下文。

### 示例与生态包

仓库自带 [`examples/langgraph/typescript/package.json`](https://github.com/plastic-labs/honcho/blob/main/examples/langgraph/typescript/package.json)，演示如何把 `@honcho-ai/sdk@^2.0.0` 与 LangGraph、OpenAI 组合，构建有状态对话代理。TypeScript SDK 自身仅依赖 `zod`（见 [`sdks/typescript/package.json`](https://github.com/plastic-labs/honcho/blob/main/sdks/typescript/package.json)），运行时开销极小。

## honcho-cli 终端

`honcho-cli` 是基于 Typer + Rich 的终端，统一暴露 `honcho` 命令（[`honcho-cli/src/honcho_cli/main.py`](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/main.py)），其关键设计：

- 顶层 Typer group 使用 `HonchoTyperGroup`（[`honcho-cli/src/honcho_cli/_help.py`](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/_help.py)），该模块集中定义 Rich 主题（边框、命令色、`--json` / `--version` 提前解析等），所有子命令复用同一外观，避免 `main.py` 出现循环导入。
- 资源子命令按域拆分：`conclusion.py` 暴露 list / search / create / delete；`peer.py` 提供 list / card / chat / search；`session.py` 处理 list / context / summaries 等（[`commands/conclusion.py`](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/conclusion.py)、[`commands/peer.py`](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/peer.py)、[`commands/session.py`](https://github.com/plastic-labs/honcho/blob/main/honcho-cli/src/honcho_cli/commands/session.py)）。它们统一通过 `add_common_options` + `handle_cmd_flags` 注入 `--json`、`--workspace/-w` 等参数，并在缺 scope 时输出结构化错误码（`NO_SCOPE`、`NO_PEER`、`NO_SESSION`），便于脚本和 CI 使用。
- CLI 内部调用 Python SDK 的 `Honcho` 客户端，因此它既是排查工具，也是面向脚本与 CI 的入口。

社区已知的安装问题：早期发布的 `honcho-cli 0.1.0` 缺少 `click` 依赖（[#786](https://github.com/plastic-labs/honcho/issues/786)），导致 `uv tool install honcho-cli` 后立即报 `ModuleNotFoundError`；官方在 [#808](https://github.com/plastic-labs/honcho/issues/808) 中跟进发布了带修复的新版本。

## MCP 服务器与代理集成

MCP 服务器位于 `mcp/`，运行在 Cloudflare Worker 上，向 Claude Code、Cursor、Cline、Windsurf 等任意 MCP 客户端暴露 Honcho 的工具集。

- [`mcp/src/config.ts`](https://github.com/plastic-labs/honcho/blob/main/mcp/src/config.ts) 中的 `parseConfig` 强制要求 `Authorization: Bearer <key>` 与 `X-Honcho-User-Name` 请求头；`HONCHO_API_URL` 仅从 Worker 环境变量读取，这样既允许把 MCP 指向自托管 Honcho 实例，又不会把内部地址泄露到公共请求。
- [`mcp/src/types.ts`](https://github.com/plastic-labs/honcho/blob/main/mcp/src/types.ts) 提供 `textResult` / `errorResult` / `formatMessage` / `formatSummary` / `formatSessionSummaries` 等序列化辅助，把 `Message`、`Summary`、`SessionSummaries` 标准化为 JSON-safe 对象返回给调用方。

README 列出的官方集成形态包括：Claude Code 插件市场（`/plugin marketplace add plastic-labs/claude-honcho`）、Claude Code 与通用 MCP 客户端（`claude mcp add honcho --transport http --url https://mcp.honcho.dev ...`）、OpenCode（`opencode plugin "@honcho-ai/opencode-honcho" --global`）、OpenClaw（`openclaw honcho setup` 会写入 key 并可选择把 `MEMORY.md` / `USER.md` / `IDENTITY.md` 迁移进 Honcho，原文件不会被删除）。

## 自托管与生态常见问题

自托管用户最容易踩到两类配置陷阱：

1. **OpenAI 兼容端点**：直接把 `LLM_OPENAI_API_KEY` 设为 OpenRouter / vLLM / Together / Anyscale 等 key 时，默认 `AsyncOpenAI` 客户端缺省 `base_url`，会回落到 `api.openai.com` 并触发 401（[#641](https://github.com/plastic-labs/honcho/issues/641)）；需显式配置 `LLM_OPENAI_BASE_URL` 并对应设置 `DERIVER_MODEL_CONFIG__TRANSPORT=openai` 等。[#789](https://github.com/plastic-labs/honcho/issues/789) 给出了 NVIDIA NIM 的完整示例。
2. **本地 / 自托管 Embedding**：[#443](https://github.com/plastic-labs/honcho/issues/443) 与 [#578](https://github.com/plastic-labs/honcho/issues/578) 指出原 `embedding_client.py` 同时硬编码了模型名与两个提供商的 `base_url`，目前必须通过环境变量与代码侧补丁才能对接 Ollama、TEI、Infinity 等自托管端点。

另一些看似是 SDK/MCP 表现的问题其实属于核心服务侧，例如自托管时 deriver 未启动导致派生记忆为空（[#494](https://github.com/plastic-labs/honcho/issues/494)）、结论在删除源文档并清缓存后仍会“自我重建”（[#725](https://github.com/plastic-labs/honcho/issues/725)）；`honcho-cli` 的 `conclusion list` 与 `peer card` 是排查它们最直接的可视化工具。

## See Also

- [README.md](https://github.com/plastic-labs/honcho/blob/main/README.md) — 总览、Quickstart、Integrations、Configuration
- Honcho 官方文档：https://honcho.dev/docs/v3/

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：plastic-labs/honcho

摘要：发现 20 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Conclusions re-derive after delete + cache flush (self-reinforcing)。

## 1. 安装坑 · 来源证据：Conclusions re-derive after delete + cache flush (self-reinforcing)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Conclusions re-derive after delete + cache flush (self-reinforcing)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/plastic-labs/honcho/issues/725 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 来源证据：Self-hosted/local Honcho ingests messages but derived memory does not appear automatically; peer card/context/search re…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Self-hosted/local Honcho ingests messages but derived memory does not appear automatically; peer card/context/search remain empty
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/plastic-labs/honcho/issues/494 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安全/权限坑 · 来源证据：I need help setting up honcho

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：I need help setting up honcho
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/plastic-labs/honcho/issues/789 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 失败模式：installation: [Bug] ModuleNotFoundError: No module named 'click'

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug] ModuleNotFoundError: No module named 'click'
- 对用户的影响：Developers may fail before the first successful local run: [Bug] ModuleNotFoundError: No module named 'click'
- 证据：failure_mode_cluster:github_issue | https://github.com/plastic-labs/honcho/issues/786 | [Bug] ModuleNotFoundError: No module named 'click'

## 5. 安装坑 · 失败模式：installation: [Feature] Support TurboQuant/turbovec as optional vector store backend for memory compression

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Feature] Support TurboQuant/turbovec as optional vector store backend for memory compression
- 对用户的影响：Developers may fail before the first successful local run: [Feature] Support TurboQuant/turbovec as optional vector store backend for memory compression
- 证据：failure_mode_cluster:github_issue | https://github.com/plastic-labs/honcho/issues/781 | [Feature] Support TurboQuant/turbovec as optional vector store backend for memory compression

## 6. 安装坑 · 失败模式：installation: honcho-cli 0.1.0 on PyPI still missing click — please publish release with #786 fix

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: honcho-cli 0.1.0 on PyPI still missing click — please publish release with #786 fix
- 对用户的影响：Developers may fail before the first successful local run: honcho-cli 0.1.0 on PyPI still missing click — please publish release with #786 fix
- 证据：failure_mode_cluster:github_issue | https://github.com/plastic-labs/honcho/issues/808 | honcho-cli 0.1.0 on PyPI still missing click — please publish release with #786 fix

## 7. 安装坑 · 来源证据：[Bug] ModuleNotFoundError: No module named 'click'

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] ModuleNotFoundError: No module named 'click'
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/plastic-labs/honcho/issues/786 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 安装坑 · 来源证据：[Feature] Support TurboQuant/turbovec as optional vector store backend for memory compression

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Support TurboQuant/turbovec as optional vector store backend for memory compression
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/plastic-labs/honcho/issues/781 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 安装坑 · 来源证据：honcho-cli 0.1.0 on PyPI still missing click — please publish release with #786 fix

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：honcho-cli 0.1.0 on PyPI still missing click — please publish release with #786 fix
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/plastic-labs/honcho/issues/808 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | github_repo:689777286 | https://github.com/plastic-labs/honcho | host_targets=openclaw, mcp_host, claude_code, claude, cursor

## 11. 配置坑 · 失败模式：configuration: I need help setting up honcho

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: I need help setting up honcho
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: I need help setting up honcho
- 证据：failure_mode_cluster:github_issue | https://github.com/plastic-labs/honcho/issues/789 | I need help setting up honcho

## 12. 配置坑 · 失败模式：configuration: Self-hosted/local Honcho ingests messages but derived memory does not appear automatically; p...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Self-hosted/local Honcho ingests messages but derived memory does not appear automatically; peer card/context/search remain empty
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Self-hosted/local Honcho ingests messages but derived memory does not appear automatically; peer card/context/search remain empty
- 证据：failure_mode_cluster:github_issue | https://github.com/plastic-labs/honcho/issues/494 | Self-hosted/local Honcho ingests messages but derived memory does not appear automatically; peer card/context/search remain empty

## 13. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | github_repo:689777286 | https://github.com/plastic-labs/honcho | README/documentation is current enough for a first validation pass.

## 14. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | github_repo:689777286 | https://github.com/plastic-labs/honcho | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:689777286 | https://github.com/plastic-labs/honcho | no_demo; severity=medium

## 16. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | github_repo:689777286 | https://github.com/plastic-labs/honcho | no_demo; severity=medium

## 17. 能力坑 · 失败模式：capability: Test issue for honcho_conclude parameters

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Test issue for honcho_conclude parameters
- 对用户的影响：Developers may hit a documented source-backed failure mode: Test issue for honcho_conclude parameters
- 证据：failure_mode_cluster:github_issue | https://github.com/plastic-labs/honcho/issues/777 | Test issue for honcho_conclude parameters

## 18. 运行坑 · 失败模式：performance: Conclusions re-derive after delete + cache flush (self-reinforcing)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: Conclusions re-derive after delete + cache flush (self-reinforcing)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Conclusions re-derive after delete + cache flush (self-reinforcing)
- 证据：failure_mode_cluster:github_issue | https://github.com/plastic-labs/honcho/issues/725 | Conclusions re-derive after delete + cache flush (self-reinforcing)

## 19. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | github_repo:689777286 | https://github.com/plastic-labs/honcho | issue_or_pr_quality=unknown

## 20. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | github_repo:689777286 | https://github.com/plastic-labs/honcho | release_recency=unknown

<!-- canonical_name: plastic-labs/honcho; human_manual_source: deepwiki_human_wiki -->