# 统一会话核心

DotCraft 不为每个客户端维护一套独立的 Agent 流程。**Unified Session Core** 是把执行、状态、审批、可观测性收敛到一个引擎上的设计——CLI、Desktop、TUI、ACP、QQ 机器人、自动化任务都连同一个核心。

> 一个核心，多个入口，会话与状态从一处生长。

## 模型：Thread → Turn → Item

```mermaid
flowchart TB
  Thread["Thread<br/>(一段持续的会话)"] --> Turn1["Turn #1"]
  Thread --> Turn2["Turn #2"]
  Thread --> Turn3["Turn #N"]

  Turn1 --> UserMsg1["Item: User Message"]
  Turn1 --> ToolCall1["Item: Tool Call"]
  Turn1 --> ToolResult1["Item: Tool Result"]
  Turn1 --> AgentMsg1["Item: Agent Message"]
```

| 实体 | 含义 |
|---|---|
| **Thread** | 一段长期会话。跨入口共享，可恢复、可订阅、可审计。 |
| **Turn** | 一轮"用户输入 → Agent 工作 → 用户可见结果"的逻辑单元。 |
| **Item** | Turn 内的最小事件：用户消息、Agent 消息、工具调用、工具结果、思考、审批等。 |

`ISessionService` 是核心 API：负责 Thread 生命周期、输入提交、流式事件订阅、审批流。所有入口（CLI、ACP、Automations、外部渠道适配器）都通过这一个接口跟引擎对话。

## 跨入口共享是怎么发生的

```mermaid
flowchart LR
  Workspace[".craft/<br/>(threads · sessions)"] --> Hub["Hub<br/>(本机协调器)"]
  Hub --> AppServer["AppServer<br/>(JSON-RPC over stdio/WebSocket)"]
  AppServer --> SessionCore["Session Core<br/>(ISessionService)"]
  SessionCore --> Engine["Agent Engine"]
  Engine -->|读写| Workspace

  Desktop --> Hub
  TUI --> Hub
  ACP["IDE / Editor (ACP)"] --> AppServer
  CLI["dotcraft exec / Channels"] --> AppServer
```

要点：

- **Hub** 在本机为每个工作区"凑"出一个 AppServer。Desktop 和 TUI 默认走这条路，所以同一个项目目录无论从哪个入口打开，都连到同一个进程。
- **AppServer** 把 ISessionService 投影成 JSON-RPC（[完整协议](../developing/appserver-protocol.md)），任何语言都可以做客户端。
- **Workspace `.craft/`** 是持久化层：Thread 写到 `threads/`，Session 元信息写到 `sessions/`，Dreams 写到 `dreams/`，重启后任何入口都能恢复。

## 审批与人在环路

Session Core 把"工具调用是否允许执行"独立成审批事件，让前端可以把它转译成自己的 UI：

| 入口 | 审批呈现方式 |
|---|---|
| Desktop | 模态框 / Approvals 面板 |
| TUI | 内联快捷键 |
| ACP（IDE） | `requestPermission` 转给编辑器 UI |
| QQ / WeCom 等渠道 | 平台原生消息回复 |

> 同一个 Thread 在不同入口接管时，审批 UI 会用对应平台原生形式呈现——Desktop 不会把 QQ 群消息硬塞进自己的弹窗。

## 跨渠道恢复

| 维度 | 不带统一会话核心 | DotCraft Unified Session Core |
|---|---|---|
| 客户端定制 | 消息总线丢失语义，难以定制 | 各客户端按需要展示 thinking、diff、approval、tool call |
| 审批 / HITL | 无法表达平台原生交互 | 每个平台用自己的 UI |
| 跨渠道恢复 | 不支持 | 同一 Thread 可被任意已连入口接管 |
| 工作区持久化 | 不支持 | `.craft/` 内自然存档 |

典型场景：

- 早上在 Desktop 让 Agent 起草 PR，下班在地铁里用 ACP 移动客户端继续 review；同一 Thread。
- 自动化任务在 Cron 里跑出一半遇到审批，Desktop 收到通知接力批准或修改。
- 微信收到用户提问，机器人回复后，研发人员可在 Desktop 的同一 Thread 看历史并接手。

## Hub vs AppServer 的分工

DotCraft 在本机有两层协调：

- **Hub** —— 用户级协调器，按需启动/复用每个工作区的 AppServer，避免一个工作区被多个 AppServer 同时占用。日常 Desktop / TUI 不用关心。
- **AppServer** —— 工作区级运行时，所有 Thread / 工具 / 审批 / 事件流的真实承担者。

需要直接控制 AppServer（远程部署、CI、机器人、调试）时，参考：

- [AppServer 模式](../developing/appserver.md) — 手动启动、`--listen`、`--token`、远程连接
- [Hub 协议](../developing/hub-protocol.md) — 实现 Hub 客户端
- [AppServer 协议](../developing/appserver-protocol.md) — 实现 AppServer 客户端

## 何时关心 Session Core

| 角色 | 需要关心吗 |
|---|---|
| 普通 Desktop 用户 | 不需要 |
| 想多客户端共享同一工作区 | 阅读 [AppServer 模式](../developing/appserver.md) |
| 想构建机器人或外部渠道 | 阅读 [Python SDK](../developing/sdk-python.md) 或 [TypeScript SDK](../developing/sdk-typescript.md) |
| 想接入新 IDE / 编辑器 | 阅读 [ACP 模式](./entry-points/editors.md) |
| 想自定义协议层客户端 | 阅读 [AppServer 协议](../developing/appserver-protocol.md) |

## 相关入口

- [入口总览](./entry-points/index.md) — 现成入口对比与决策表
- [可观测性](./observability.md) — 在 Dashboard 看 Trace、审批、调用
- [AppServer 模式](../developing/appserver.md) — 远程 / 多客户端 / 自定义集成
