> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 会话 (Sessions)

> 使用 LLMSession 与 hb llm session CLI 的有状态 LLM 会话。

<Note>
  *LLM 什么都不记得。这是特性——直到你想要它记得。*
</Note>

`hb.LLM` 有意保持无状态。对话历史只是你传给 `chat` 或 `stream` 的消息列表。需要多轮 chat 又不想每次重建该列表时，`LLMSession` 替你持有历史与可选工具。

<br />

## 1. 无会话的手动历史 (Manual History Without a Session)

只需一两轮时，你可以自行管理历史：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

messages = [
    {"role": "user", "content": "Remember the code word is hb-ok."},
    {"role": "assistant", "content": "Remembered."},
    {"role": "user", "content": "What is the code word?"},
]

answer = hb.LLM(preset="chat").chat(messages)
```

对已在别处携带状态的流水线，这一模式已足够。

<br />

## 2. 会话工具 (Session Tools)

`LLMSession` 可持有会话工具并在每轮使用。工具遵循与 `LLM.chat` 相同的 `tools=[...]` 契约：接受 Python 可调用对象、`Tool`、工具集 (Toolkit) 与 schema 字典。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb
from heavenbase.utils import LLMSession


def add(left: int, right: int) -> int:
    """Add two numbers."""
    return left + right


session = LLMSession(hb.LLM(preset="chat"))
session.add_tool(add)

answer = session.send("Use the add tool for 2 + 3.")
print(answer["content"])
```

外部 MCP 服务器作为会话工具集 (Toolkit) 导入：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
session = LLMSession(hb.LLM(preset="chat"))
session.add_mcp("http://127.0.0.1:7001/mcp")
session.send("What tools are available?")
```

会话将 assistant tool call、`role="tool"` 结果与最终 assistant 响应存入 `messages`。完整可执行工具契约见 [Tool Use](/features/llm/tool-use)。

<br />

## 3. 会话生命周期 (Session Lifecycle)

`LLMSession` 为交互式工作流提供小型辅助方法：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
session.append_assistant("Draft saved.")   # append without a provider call
session.back()                             # drop the latest user turn and everything after it
session.clear()                            # reset message history
session.list_tools()                       # active runtime tool names
```

仅持久化消息——执行中的 MCP 工具集 (Toolkit) 不宜序列化：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
session.save("./session.json")
restored = LLMSession.load("./session.json", llm=hb.LLM(preset="chat"))
```

`to_dict()` 与 `from_dict()` 返回 JSON 安全载荷，遵循相同的消息专用契约。

<br />

## 4. CLI 交互式会话 (CLI Interactive Sessions)

以 `chat` preset 启动多轮 CLI 会话：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm session
```

在 `>>>` 提示符下输入消息。斜杠命令：

| Command         | Action                   |
| --------------- | ------------------------ |
| `/help`         | 显示可用命令                   |
| `/save <path>`  | 将消息历史保存为 JSON            |
| `/load <path>`  | 从 JSON 加载消息历史            |
| `/clear`        | 清空会话                     |
| `/regen <seed>` | 用可选 seed 重新生成最后一条响应      |
| `/back`         | 移除最近一轮 user 输入           |
| `/tools`        | 列出已附加工具                  |
| `/mcp SOURCE`   | 会话中途附加 MCP 工具集 (Toolkit) |
| `/bye`, `/exit` | 退出                       |

启动时用重复的 `--mcp` 值附加 MCP 工具：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm session --mcp http://127.0.0.1:7001/mcp
hb llm session --mcp quickstart.math-tools:-1
hb llm session --mcp math-tools
```

运行中的会话内用 `/mcp` 添加更多工具：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
>>> /mcp quickstart.math-tools:-1
>>> What's 42 * 73?
```

规范工具集 (Toolkit) 引用形式为 `namespace.toolkit:version`。负版本从最新往回数：`-1` 为最新，`-2` 为次新。

当 provider 单独输出思考内容时，CLI 会话在可见 assistant 文本前将其打印在 `<think>` 与 `</think>` 内。工具迭代逐步打印 `STEPS: 001 / 020`，随后是 tool call 与 tool 结果。

<br />

## 5. 检查解析状态 (Inspect Resolved State)

需要查看 client 如何解析时使用 `spec`：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

llm = hb.LLM(model="ds-flash", provider="deepseek")

print(llm.spec.to_dict())
print(llm.spec.materialize())
```

`spec.to_dict()` 省略密钥。`spec.to_dict(secrets=True)` 包含物化后的解析字典，仅应在可信调试场景使用。

解析后的 spec 还会产生用于去重与缓存查找的稳定哈希键：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
spec_key = llm.spec.hash_key()
litellm_key = llm.spec.hash_key("litellm")
client_key = llm.spec.client_key()
```

`client_key()` 仅包含入口 (Gateway) client 构造字段，因此重复的 `LLM` 实例可复用同一内存中的 OpenAI 兼容 SDK client。

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Tool Use](/features/llm/tool-use) — 仅 schema 与可执行工具、MCP 工具集 (Toolkit) 与结构化输出。
  * [LLM Chat](/features/llm/chat) — 消息输入、流式输出与 include 投影。
  * [First LLM](/quickstart/first-llm) — CLI 会话导览与快速入门中的 MCP 附加。
</Tip>

<br />