# Book 存储模型

> **状态：目标愿景（未完全实现）。**  
> **现行实现**以 `src/types/book.ts`、`src/book/store.ts`、`src/types/book-session.ts` 与 [`run-snapshot.md`](./run-snapshot.md) 为准（扁平 `books/{id}.json` + `session.json` + run/instance 快照）。  
> 下文 CardBook / PlayBook / designTrace 等为远期形态，**不要**按本文当当前磁盘契约写代码。

## 1. 定位

Book = **长期项目容器**。Session = 一次打开的运行进程。黑板 = Session 内运行时 tag。

存储须同时满足：

```text
1. 保存「创建过程」（designTrace / playTrace）
2. 保存「创建结果」（可复用资产，如角色卡）
3. 保存「游玩过程」（对话、轮次、变量、存档点）
```

第一版约束：不存 API key；历史与当前分离；accepted 才升为「当前事实」。

---

## 2. 三种 Book 形态

| 形态 | 用途 | 典型 kind |
|------|------|-----------|
| **CardBook** | 创作角色卡（design stage） | `character_card_design` |
| **CardAsset** | 从 CardBook 导出的可复用卡 | 资产条目，可挂卡库 |
| **PlayBook** | 用某张卡（+ 可选世界）游玩 | `character_card_play` / `roleplay` |
| **ProjectBook** | 小说等项目（沿用） | `novel` |

同一用户可：CardBook 创作 → 导出 CardAsset → 新建 PlayBook 引用该卡。

---

## 3. CardBook（创建角色卡）

### 3.1 存什么

```ts
type CardBook = {
  id: string;
  title: string;
  orchestratorId: string;
  lifecycleStage: "design" | "archived";

  /** 创作过程：可时间线展示、可续作设计 */
  designTrace: DesignTraceEntry[];

  /** 运行时黑板快照（设计.* tag） */
  designArtifacts: TaggedArtifact[];

  /** 用户可见对话；agent tool 对话可另存 agentTrace */
  messages: PersistedChatMessage[];

  runSkillManifest?: RunSkillManifest;  // 设计完成后：建议如何游玩
  readiness?: InstanceReadiness;

  createdAt: string;
  updatedAt: string;
};
```

```ts
type DesignTraceEntry = {
  at: string;
  type:
    | "user_input"
    | "agent_tool"
    | "skill_invoked"
    | "user_confirmed"
    | "user_rejected"
    | "declare_ready";
  skillId?: string;
  tool?: string;
  summary: string;
  outputTags?: string[];
};
```

**过程** = `designTrace` + `messages`（+ 可选 `agentTrace`）。  
**不是**预定实体槽填表；agent 调了哪些 instantiate skill，过程里就记哪些。

### 3.2 导出 CardAsset（创建结果）

```ts
type CardAsset = {
  id: string;
  cardBookId: string;
  title: string;
  tags: Record<string, string>;  // 角色卡.确认稿、角色.设定、口吻…
  runSkillManifest?: RunSkillManifest;
  confirmedAt: string;
};
```

游玩时 **加载 CardAsset**，不必重跑完整 design。

---

## 4. PlayBook（游玩角色卡 / 扮演）

```ts
type PlayBook = {
  id: string;
  title: string;
  orchestratorId: string;
  lifecycleStage: "play" | "archived";

  cardRef: { assetId: string; version?: string };
  worldRef?: { assetId?: string };

  contextProfile: ContextProfile;  // 实例化选的 variant
  runSkillManifest: RunSkillManifest;

  playTrace: PlayTraceEntry[];
  runState: {
    turn: number;
    variables: Record<string, unknown>;
    eventStream: string;
  };

  messages: PersistedChatMessage[];
  snapshotIds: string[];

  createdAt: string;
  updatedAt: string;
};
```

```ts
type PlayTraceEntry = {
  at: string;
  turn?: number;
  type: "user_input" | "skill_invoked" | "artifact" | "snapshot";
  skillId?: string;
  summary: string;
};
```

**游玩过程** = `playTrace` + `messages` + `runState`。  
**游玩存档** = `RunSnapshot`（kind=`run`），见 `run-snapshot.md`。

---

## 5. ProjectBook（小说等）

保留原 `BookProject` + `BookContentRecord` 思路：

```ts
type BookProject = {
  id: string;
  title: string;
  orchestratorId: string;
  kind: "novel" | "forum" | "weird_rules" | "custom";
  lifecycleStage: "design" | "play" | "done";
  currentContentId?: string;
  historyContentIds: string[];
  designTrace?: DesignTraceEntry[];
  sessionIds: string[];
  createdAt: string;
  updatedAt: string;
};
```

小说正文仍用 `BookContentRecord`（outline/chapter）；design 阶段 tag 可进 `designArtifacts`。

---

## 6. Session 与 Book

```text
Session（PersistedBookSession）
  当前打开的 working copy：RuntimeSession + 黑板 + messages
  关闭时可合并进 Book 的 trace / runState

Book
  稳定事实 + 过程记录 + 资产引用

沉淀规则
  design accepted tag  → CardBook.designArtifacts / 导出 CardAsset
  play accepted tag    → PlayBook.runState + 黑板归档
  draft / rejected     → trace 记一笔，默认不升 current
```

---

## 7. 与状态机

```text
worker_completed     → draft
user_accepted_artifact / no_confirmation / programmatic_pass
                     → 可写 Book（由 Runtime，非 agent 直接写）
```

---

## 8. 与黑板

| 阶段 | 黑板前缀示例 | 归档到 |
|------|--------------|--------|
| design | `设计.*`、`用户.需求` | CardBook / ProjectBook design |
| play | `运行.*`、`世界.*`、`输出.*` | PlayBook runState |

上下文拼接读黑板；Book 存 **确认稿与过程**，见 `context-assembly.md`。

---

## 9. 存储布局（建议）

```text
books/{bookId}/project.json
books/{bookId}/design-artifacts.json
books/{bookId}/traces.jsonl
books/{bookId}/contents/{contentId}.json   # 小说正文
assets/cards/{assetId}.json                # CardAsset 卡库
books/{bookId}/snapshots/{snapshotId}.json
sessions/{sessionId}.json                  # 可选 working copy
```

---

## 10. 实现优先级

```text
P0  文档对齐（本文）
P1  designTrace / playTrace 写入
P2  CardAsset 导出与 PlayBook.cardRef
P3  与现有 PersistedBookSession / RunSnapshot 字段合并
P4  卡库 UI、跨 Book 引用
```

代码现状：`src/types/book.ts`、`run-snapshot.ts` 仍为简化模型，实现时按本文扩展。

---

## 11. 角色卡流程示例

```text
1. 新建 CardBook → design stage
2. 用户与 agent 迭代 → designTrace 追加
3. invoke persona-* skills → 设计.* tag
4. 用户确认 → 导出 CardAsset
5. 新建 PlayBook，cardRef = assetId
6. play stage：每轮 playTrace + messages
7. 手动 PlaySnapshot 存档
8. 下次打开 PlayBook 或读 snapshot 续玩
```

创建过程、卡本身、游玩过程 **三者分开存**，互不覆盖。