# 消息级溯源设计

> 创建:2026-06-19 | 编号:F-260619-04(消息级溯源) | 状态:✅ **已落地**(2026-06-28 核验:ChatMessage.id + source_ref/audit/idea 四场景全部完成 + P2 切读全部完成)
> 关联任务:`消息级溯源:知识库/审计/灵感全链路从对话级升级到消息级`(DevFlow 项目)
> 关联灵感:b2e61a21 消息拆分存储 + 消息级溯源 + 知识脉络网络
> 关联设计:[消息拆分存储设计-2026-06-19.md](./消息拆分存储设计-2026-06-19.md)(本设计的持久化基础)
> 上级索引:[../INDEX.md](../INDEX.md)

---

## 一、目标

将 DevFlow 所有溯源场景从「对话级」升级为「消息级」,实现四个场景的精确定位:

| 场景 | 升级后溯源字段 | 粒度 |
|---|---|---|
| 知识库提炼 | `source_ref = "conv_msg:{message_id}"` | 消息级 |
| 知识生命线·提炼/引用 | `source_ref = "conv_msg:{message_id}"` | 消息级 |
| 工具执行审计 | `message_id: Option<String>` 独立列 | 消息级 |
| 灵感来源 | `source = "conv_msg:{message_id}"` | 消息级 |

> **依赖关系**:本设计依赖[消息拆分存储](./消息拆分存储设计-2026-06-19.md)提供持久化消息 ID,但**中间态可不依赖拆表先上线**(见 §五)。

---

## 二、现状(4 个溯源场景全部只到对话级)

| 场景 | 当前溯源字段 | 粒度 | 位置 |
|---|---|---|---|
| 知识库提炼 | `source_ref = "conv:{conversation_id}"` | 对话级 | `knowledge_inject.rs:434` |
| 知识生命线·提炼/引用 | `source_ref = "conv:{conversation_id}"` | 对话级 | `knowledge_timeline.rs:87,99` |
| 工具执行审计 | `conversation_id`(无 message_id 列) | 对话级 | `audit/mod.rs`(14 处写入) |
| 灵感来源 | `source`(自由文本,无结构) | 无结构 | `idea.rs:27` |

### 痛点

- **知识溯源**:打开整个对话,不知道是哪一轮产出的
- **工具审计(最痛)**:`tool_call_id` 埋在整个对话 JSON 里,排查"AI 为什么删这个文件"需反序列化全量 JSON 逐条搜
- **知识引用追踪**:不知道知识在对话哪一轮被使用

---

## 三、前置:ChatMessage 加 id 字段

### 3.1 字段定义

`crates/df-ai-core/src/types.rs:72` 的 `ChatMessage` 加:

```rust
/// 消息全局唯一 ID(ULID)。用于消息级溯源(source_ref / audit message_id / idea source)。
/// 构造时生成;老 JSON 反序列化为 None(向前兼容)。
/// 消息拆分存储(F-260619-03)后,此 ID 即 ai_messages.id 列主键。
#[serde(default, skip_serializing_if = "Option::is_none")]
pub id: Option<String>,
```

### 3.2 ID 生成时机

| 构造路径 | ID 生成 |
|---|---|
| `ChatMessage::new_user()` | 构造时 `Some(new_id())` |
| `ChatMessage::new_assistant()` | 构造时 `Some(new_id())` |
| `ChatMessage::new_tool()` | 构造时 `Some(new_id())` |
| `ChatMessage::new_system()` | 构造时 `Some(new_id())` |
| 老消息反序列化 | `None`(serde default) |

> `new_id()` 来自 `df-types::types::new_id()`(ULID)。df-ai-core 已依赖 df-types。

### 3.3 向前兼容

- `#[serde(default)]`:老 JSON 无 id 字段 → 反序列化为 `None`
- `skip_serializing_if = "Option::is_none"`:id = None 时不序列化(不污染老格式)
- **round-trip 测试**:序列化 → 反序列化 → 字段一致

---

## 四、溯源字段升级

### 4.1 知识库提炼

**文件**:`src-tauri/src/commands/ai/knowledge_inject.rs:434`

```rust
// 旧
source_ref: Some(format!("conv:{}", conv_id)),

// 新
source_ref: Some(format!("conv_msg:{}", message_id)),
```

`message_id` 来源:提炼触发时,取当前 assistant 消息的 `id`。

### 4.2 知识生命线

**文件**:`src-tauri/src/commands/knowledge_timeline.rs:87,99`

```rust
// 旧(timeline 提炼事件 + 引用事件)
source_ref: Some(format!("conv:{}", conv_id)),

// 新
source_ref: Some(format!("conv_msg:{}", message_id)),
```

### 4.3 工具执行审计

**文件**:`crates/df-storage/src/models.rs` + `crud/conversation_repo.rs` + `src-tauri/src/commands/ai/audit/mod.rs`

#### 4.3.1 Model + 迁移

`AiToolExecutionRecord` 加 `message_id: Option<String>`。

V21 迁移(与消息拆分同一版本,或拆为 V21a/V21b):

```rust
// migrations.rs migrate_v21
if !column_exists(conn, "ai_tool_executions", "message_id") {
    conn.execute(
        "ALTER TABLE ai_tool_executions ADD COLUMN message_id TEXT",
        [],
    )?;
    tracing::info!("v21: 补建 ai_tool_executions.message_id 列(消息级溯源)");
}
```

V9 建表 SQL 同步补 `message_id TEXT` 列(新库直接有)。

#### 4.3.2 CRUD 层

- `ai_tool_execution_from_row`:加 `message_id: row.get("message_id")?`
- insert/update SQL:加 message_id 列 + params 占位

#### 4.3.3 审计写入(14 处)

`audit/mod.rs` 中 14 处写入 `AiToolExecutionRecord` 的位置,在 `conversation_id` 旁加 `message_id`:

```rust
// audit 记录构造
let record = AiToolExecutionRecord {
    // ... 既有字段 ...
    conversation_id: Some(conv_id.clone()),
    message_id: current_message_id.clone(),  // 新增
    // ...
};
```

`current_message_id` 来源:audit 写入时,从 ContextManager 取当前 assistant 消息的 `id`。

### 4.4 灵感来源

**文件**:`src-tauri/src/commands/idea.rs:27`

```rust
// 旧(AI 路径,自由文本)
source: Some(format!("AI 对话 {}", conv_id)),

// 新(AI 路径,结构化)
source: Some(format!("conv_msg:{}", message_id)),
```

人工创建的灵感 source 保持自由文本不变。

---

## 五、中间态(不依赖消息拆表)

本设计可**先于消息拆分存储上线**:

### 5.1 内存 ID 已足够写入溯源

- ChatMessage 加 id 字段后,所有新消息有 ULID
- 溯源写入时带上 message_id —— **信息已存下**

### 5.2 查询体验(中间态)

| 操作 | 中间态(消息未拆表) | 最终态(消息拆表后) |
|---|---|---|
| 知识溯源点击 | 反序列化对话 JSON 搜 id | `SELECT * FROM ai_messages WHERE id = ?`(O(1)) |
| 工具审计查消息 | 反序列化对话 JSON 搜 id | `SELECT * FROM ai_messages WHERE id = ?`(O(1)) |

中间态查询不快,但**溯源信息已完整存下**,消息拆表后自然升级为 O(1)。

### 5.3 source_ref 格式约定

| 格式 | 含义 | 示例 |
|---|---|---|
| `conv:{conversation_id}` | 对话级(旧格式,向前兼容) | `conv:abc123` |
| `conv_msg:{message_id}` | 消息级(新格式) | `conv_msg:01J...` |

解析逻辑:前缀匹配 `conv_msg:` → 消息级;`conv:` → 对话级(兼容)。

---

## 六、涉及文件

| 文件 | 改动 |
|---|---|
| `crates/df-ai-core/src/types.rs` | ChatMessage 加 `id: Option<String>` + 构造器生成 |
| `crates/df-storage/src/migrations.rs` | V21 迁移 ai_tool_executions 加 message_id 列 + V9 建表 SQL 同步 |
| `crates/df-storage/src/models.rs` | AiToolExecutionRecord 加 `message_id: Option<String>` |
| `crates/df-storage/src/crud/conversation_repo.rs` | ai_tool_execution_from_row + insert/update SQL 补 message_id |
| `src-tauri/src/commands/ai/knowledge_inject.rs` | source_ref 升级为 `conv_msg:{id}` |
| `src-tauri/src/commands/knowledge_timeline.rs` | source_ref 升级(2 处) |
| `src-tauri/src/commands/ai/audit/mod.rs` | 14 处 conversation_id 写入旁加 message_id |
| `src-tauri/src/commands/idea.rs` | source 字段结构化(AI 路径) |

---

## 七、验收标准

1. **ChatMessage 有稳定 id**:构造时生成 ULID,序列化/反序列化 round-trip 正确
2. **知识库提炼的 source_ref 为 `conv_msg:{id}` 格式**
3. **工具审计记录携带 message_id**(14 处全覆盖)
4. **老数据(无 id)无回归**:source_ref 解析兼容 `conv:` 旧格式;ChatMessage id = None 不报错
5. `cargo check --workspace EXIT 0`

---

## 八、与消息拆分存储的协作

```
消息级溯源(F-260619-04)              消息拆分存储(F-260619-03)
┌─────────────────────────┐         ┌─────────────────────────┐
│ ChatMessage.id 字段     │◄────────│ ai_messages 表          │
│ (内存 ULID,中间态)     │  提供   │ (持久化 id,最终态)    │
│                         │         │                         │
│ source_ref = conv_msg:X │ 查询时  │ SELECT WHERE id = X     │
│ audit.message_id = X    │───────►│ (O(1) 查询)            │
└─────────────────────────┘         └─────────────────────────┘
```

**实施顺序建议**:

1. **先上消息级溯源**(本设计):ChatMessage 加 id + 溯源字段升级 —— 中间态可上线
2. **再上消息拆分存储**:ai_messages 表 + 全量迁移 + 切读 —— 溯源查询升级为 O(1)