kimi-code-memory-mcp-server 0.1.1 → 0.1.2

package/README.md

@@ -1,54 +1,82 @@
 # Kimi Code Memory MCP Server
 
-[中文](./README.zh-CN.md)
+[English](./README.en.md)
 
 [![CI](https://github.com/Zehee/kimi-code-memory-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Zehee/kimi-code-memory-mcp-server/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/kimi-code-memory-mcp-server.svg?color=brightgreen)](https://www.npmjs.com/package/kimi-code-memory-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-A local stdio MCP server that gives [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) cross-session memory.
+一个为 [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) 提供跨会话记忆的本地 stdio MCP 服务器。
 
-> **Note:** This package is published to npm as `kimi-code-memory-mcp-server`. You can install it directly or run it from source.
+> **注意：** 本包已发布到 npm，包名为 `kimi-code-memory-mcp-server`。你可以直接安装，也可以从源码运行。
 
-User-facing memories are stored as plain Markdown files on disk. Refined turn summaries use a local SQLite cache, but no vector database, graph database, or external cloud service is required.
 
-## Features
+## 特性
 
-- **Markdown-first memories** — human-readable, git-friendly, LLM-compatible.
-- **Structured long-term memory** — `memory/decisions/`, `memory/knowledge/`, `memory/rules/`, `memory/reference/`.
-- **Workspace essence** — condensed digest (≤15 KB) generated from `memory/`.
-- **Cross-session context recovery** — parses Kimi Code CLI's `wire.jsonl` directly.
-- **Theme tracing** — associate conversation turns and memories with themes, then trace their evolution.
-- **Refined turn summaries** — reusable turn-level atomic summaries shared across themes.
-- **Rebuilding index** — `index.json` is a cache; `.md` files are the source of truth.
+- **Markdown 优先的记忆** —— 人类可读、适合 git、兼容 LLM。
+- **结构化长期记忆** —— `memory/decisions/`、`memory/knowledge/`、`memory/rules/`、`memory/reference/`。
+- **工作区精要** —— 从 `memory/` 提炼生成的浓缩摘要（≤15 KB）。
+- **跨会话上下文恢复** —— 直接解析 Kimi Code CLI 的 `wire.jsonl`。
+- **主题追溯** —— 将对话轮次和记忆关联到主题，并追踪其演化。
+- **精炼轮次摘要** —— 可在多个主题间共享的轮次级原子摘要。
+- **可重建索引** —— `index.json` 只是缓存，`.md` 文件才是真相来源。
 
-## Why Markdown?
+## 主题追溯
 
-Most agent memory systems default to vector databases. That works for fuzzy retrieval, but it also makes memories opaque, hard to audit, and hard to version-control.
+传统的上下文管理只关注**纵向**：时间越近越清晰，越久越远越衰减。但这忽略了真实工作的一个核心特征：
 
-This project starts from the opposite assumption:
+> **同一个 workspace 中的多次会话，往往不是单一叙事，而是多条主题线交织并行。**
 
-> Memories should be **judged, structured, and owned by the user** before they are stored.
+例如：
 
-Markdown + YAML frontmatter gives you:
+- Session A：开发 auth 鉴权
+- Session B：讨论orders数据表的迁移问题
+- Session C：加密RSA+解密BCrypt+验证码CAPTCHA+Cookie 
+- Session D：fix sql  error bug
+- Session E： 登录Login API设计
 
-- Full readability and editability
-- Native git diff support
-- No required external database or cloud service
-- Compatibility with any LLM that can read text
+如果只看纵向，这些 session 彼此独立。但如果横向扫描，会发现 A、C、E 都属于"注册登录"这一主题。
 
-See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the design rationale.
+**主题追溯**就是：把时间线上的每个 turn 看作一个圆柱，圆柱的高度代表该 turn 的计算/思考深度，颜色/标签代表主题。我们甚至可以从kimi code已经压缩归档的上下文中再次挖掘，进行深度横向扫描，把同色圆柱（对话轮turns）找出来，重新建立关联，组成theme并存入记忆。当我们三周以后准备升级的我们的“注册登录”模块，或者修复某个bug的时候，不是对着已经压缩过无数次上下文的agent，重新描述对其当时的设计思路和方案，而是你的agent说：“刚刚通过trace_theme("注册登录")这个主题，发现根据3周前的设计决策和中间经历的2次调整改进，现在的问题我们应该用方案B。”
 
-## Install
+>下图展示了 `kimi-memory` 如何看待对话历史：竖条是时间轴上的 turn，粗横线是簇，灰框是 session，彩色括号把跨 session 的相关 turns / clusters 串联成主题线。
 
-Node.js ≥ 18 is required.
+![时间轴上的 turns、簇、session 与主题追溯](./assets/contextFlow.svg)
 
-### From npm (recommended)
+下面是一段真实的 Kimi Code CLI 会话动图，使用 `kimi-memory`。用户先后要求总结 MCP 记忆服务器的演进历史、以及 E2E 测试工具的演进历史；Agent 跨会话召回相关记忆与对话 turns，并生成结构化总结。
+
+![Kimi Memory MCP Server 演示](https://github.com/user-attachments/assets/a8947676-1487-47ed-8e0c-8d15f8662618)
+
+相关工具：`tag_theme`、`trace_theme`、`list_themes`、`search_context`、`refine_session_turns`、`load_turn_context`。
+
+## 为什么用 Markdown？
+
+大多数 Agent 记忆系统默认使用向量数据库。这在模糊检索场景有效，但也让记忆变得不透明、难以审计、难以版本控制。
+
+本项目从相反的假设出发：
+
+> 记忆在存储之前应该经过**判断、结构化，并由用户拥有**。
+
+Markdown + YAML frontmatter 带来：
+
+- 完全可读、可编辑
+- 原生支持 git diff
+- 无需外部数据库或云服务
+- 兼容任何能读取文本的 LLM
+
+设计 rationale 见 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)。
+
+## 安装
+
+需要 Node.js ≥ 18。
+
+### 从 npm 安装（推荐）
 
 ```bash
 npm install -g kimi-code-memory-mcp-server
 ```
 
-### From source
+### 从源码安装
 
 ```bash
 git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
@@ -57,38 +85,38 @@ npm install
 npm run build
 ```
 
-## Quick Setup (recommended)
+## 快速配置（推荐）
 
-After installing from npm, run the setup command to configure Kimi Code CLI automatically:
+从 npm 安装后，运行 setup 命令自动配置 Kimi Code CLI：
 
 ```bash
 npx kimi-memory-setup
 ```
 
-This will:
+它会完成：
 
-1. Detect your `~/.kimi-code` directory.
-2. Inject memory protocol rules at the top of `~/.kimi-code/AGENTS.md`.
-3. Install the `memory-manage` skill to `~/.kimi-code/skills/memory-manage`.
-4. Add the `kimi-memory` MCP server entry to `~/.kimi-code/mcp.json`.
+1. 检测 `~/.kimi-code` 目录。
+2. 在 `~/.kimi-code/AGENTS.md` 顶部注入记忆协议规则。
+3. 将 `memory-manage` Skill 安装到 `~/.kimi-code/skills/memory-manage`。
+4. 在 `~/.kimi-code/mcp.json` 中添加 `kimi-memory` MCP 服务器配置。
 
-Preview changes without writing anything:
+预览变更而不写入文件：
 
 ```bash
 npx kimi-memory-setup --dry-run
 ```
 
-Remove the injected configuration later:
+后续如需移除注入的配置：
 
 ```bash
 npx kimi-memory-setup --undo
 ```
 
-## Configure Kimi Code CLI (manual)
+## 配置 Kimi Code CLI（手动）
 
-If you prefer to configure manually, edit `~/.kimi-code/mcp.json` and add the server.
+如果你希望手动配置，编辑 `~/.kimi-code/mcp.json` 并添加服务器。
 
-If you installed from npm with `-g`, use the absolute path to `dist/server.js` inside your global `node_modules`:
+如果你用 `npm install -g` 安装，使用全局 `node_modules` 中 `dist/server.js` 的绝对路径：
 
 ```json
 {
@@ -102,7 +130,7 @@ If you installed from npm with `-g`, use the absolute path to `dist/server.js` i
 }
 ```
 
-Or run it directly via `npx` (no install required):
+或者直接通过 `npx` 运行（无需安装）：
 
 ```json
 {
@@ -116,7 +144,7 @@ Or run it directly via `npx` (no install required):
 }
 ```
 
-If you built from source, point to your local `dist/server.js`:
+如果你从源码构建，指向本地 `dist/server.js`：
 
 ```json
 {
@@ -130,109 +158,157 @@ If you built from source, point to your local `dist/server.js`:
 }
 ```
 
-The server name **`kimi-memory`** is important because the bundled `AGENTS.md` rules call tools as `mcp__kimi-memory__*` (for example `mcp__kimi-memory__bootstrap_workspace`).
+服务器名称 **`kimi-memory`** 很重要，因为本仓库自带的 `AGENTS.md` 规则以 `mcp__kimi-memory__*` 形式调用工具（例如 `mcp__kimi-memory__bootstrap_workspace`）。
 
-Restart Kimi Code CLI to load the server.
+重启 Kimi Code CLI 以加载该服务器。
 
-## Optional: Install User-Level AGENTS.md Startup Hook
+## 可选：安装用户级 AGENTS.md 启动钩子
 
-For automatic memory recovery and behavioral rules on every session start, copy the bundled `AGENTS.md` to your Kimi Code user directory:
+如需每次会话启动时自动恢复记忆并应用行为规范，将本仓库自带的 `AGENTS.md` 复制到 Kimi Code 用户目录：
 
 ```bash
 cp AGENTS.md ~/.kimi-code/AGENTS.md
 ```
 
-This installs a startup hook that tells Kimi Code CLI to call `bootstrap_workspace` at the beginning of every session, and to follow the memory classification and decision-guard rules. Because `AGENTS.md` is injected into **every** session, it is the right place for memory-related behavior protocols.
+这会安装一个启动钩子，让 Kimi Code CLI 在每次会话开始时调用 `bootstrap_workspace`，并遵循记忆分类和决策守卫规则。由于 `AGENTS.md` 会注入到**每个**会话中，它是放置记忆相关行为协议的正确位置。
 
-> **Note:** Keep `AGENTS.md` focused on memory-related conventions only. Do not include tool preferences that belong to other MCP servers.
+> **注意：** `AGENTS.md` 规则会注入到每个会话中，请只保留与记忆相关的约定，不要包含属于其他 MCP server 的工具偏好。
 >
-> **Prerequisite:** The MCP server must be registered under the name `kimi-memory` in `~/.kimi-code/mcp.json`, otherwise the `mcp__kimi-memory__*` calls in `AGENTS.md` will fail.
+> **前提条件：** 必须在 `~/.kimi-code/mcp.json` 中将 MCP 服务器注册为 `kimi-memory`，否则 `AGENTS.md` 中的 `mcp__kimi-memory__*` 调用会失败。
 
-## Optional: Install the Memory Skill
+## 可选：安装记忆 Skill
 
-This repository also includes a lightweight Skill (`skills/memory-manage/SKILL.md`) that reminds Kimi Code CLI to call the memory tools when the user expresses a memory-related intent.
+本仓库还包含一个轻量 Skill（`skills/memory-manage/SKILL.md`），用于在用户表达记忆相关意图时提醒 Kimi Code CLI 调用记忆工具。
 
 ```bash
 cp -r skills/memory-manage ~/.kimi-code/skills/memory-manage
 ```
 
-The Skill does **not** enforce behavior on its own; it is a dispatcher. The actual protocols (when to remember, decision guard, etc.) live in `AGENTS.md`.
+该 Skill 本身**不强制**行为，它只是一个调度器。真正的协议（何时 remember、决策守卫等）应配置在 `AGENTS.md` 中。
 
-## Quick Start
+## 快速开始
 
-After the server is loaded, the agent can call memory tools naturally (tool names are prefixed with the MCP server name you configured, e.g. `mcp__kimi-memory__*`):
+服务器加载后，Agent 可以自然地调用记忆工具（工具名带有你在 MCP 配置中注册的 server 名称前缀，例如 `mcp__kimi-memory__*`）：
 
 ```text
-User: Let's use SQLite for the cache layer.
-Agent: [calls mcp__kimi-memory__remember] key=use-sqlite-cache, folder=memory/decisions
-
-User: Why did we choose SQLite?
-Agent: [calls mcp__kimi-memory__search] query=SQLite cache decision
-       [calls mcp__kimi-memory__recall] key=use-sqlite-cache, folder=memory/decisions
-       → "We chose SQLite over Redis because..."
-
-User: How has the cache design evolved?
-Agent: [calls mcp__kimi-memory__tag_theme] theme=cache-design
-       [calls mcp__kimi-memory__trace_theme] theme=cache-design
-       → shows related turns and decisions across sessions
+用户：我们用 SQLite 作为缓存层。
+Agent：[调用 mcp__kimi-memory__remember] key=use-sqlite-cache, folder=memory/decisions
+
+用户：为什么选 SQLite？
+Agent：[调用 mcp__kimi-memory__search] query=SQLite cache decision
+       [调用 mcp__kimi-memory__recall] key=use-sqlite-cache, folder=memory/decisions
+       → "我们选择 SQLite 而不是 Redis，因为……"
+
+用户：缓存设计是怎么演化的？
+Agent：[调用 mcp__kimi-memory__tag_theme] theme=cache-design
+       [调用 mcp__kimi-memory__trace_theme] theme=cache-design
+       → 展示跨会话的相关轮次和决策
 ```
 
-## Storage Layout
+## 存储布局
 
-The server stores data under `~/.kimi-code-memory/<workspace-id>/`:
+服务器将数据存储在 `~/.kimi-code-memory/<workspace-id>/` 下：
 
 ```text
 ~/.kimi-code-memory/workspace-a1b2c3d4/
-├── index.json              # v3-kv metadata cache (rebuildable)
+├── index.json              # v3-kv 元数据缓存（可重建）
 ├── memory/
-│   ├── decisions/          # architecture and product decisions
-│   ├── knowledge/          # project-specific knowledge
-│   ├── rules/              # conventions and guardrails
-│   └── reference/          # external references
+│   ├── decisions/          # 架构与产品决策
+│   ├── knowledge/          # 项目相关知识
+│   ├── rules/              # 约定与红线
+│   └── reference/          # 外部参考
 ├── essence/
-│   └── essence.md          # workspace digest (≤15 KB)
-├── notes/                  # scratch notes
+│   └── essence.md          # 工作区精要（≤15 KB）
+├── notes/                  # 临时速记
 ├── themes/
-│   └── my-theme.json       # theme -> turn/memory refs
+│   └── my-theme.json       # theme -> turn/memory 引用
 └── refined/
-    └── refined.sqlite      # turn-level summaries
+    └── refined.sqlite      # 轮次级摘要
 ```
 
-You can override the storage root with the `MEMORY_STORE_ROOT` environment variable.
-
-### Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `MEMORY_STORE_ROOT` | Override the default `~/.kimi-code-memory` storage root. |
-| `MEMORY_SESSIONS_ROOT` | Override the default `~/.kimi-code/sessions` path used to discover `wire.jsonl` files. |
-| `KIMI_CODE_HOME` | Alternative to `MEMORY_SESSIONS_ROOT`; sessions are read from `<KIMI_CODE_HOME>/sessions`. |
-
-## Tools
-
-| Tool | Purpose |
-|------|---------|
-| `remember` | Write a Markdown memory |
-| `recall` | Read a memory by key |
-| `recall_recent` | List recently updated memories |
-| `search` | Keyword search across memories |
-| `list` | List memories |
-| `list_tags` | List all tags |
-| `delete` | Delete a memory |
-| `move` | Move or rename a memory |
-| `organize_memories` | Distill `memory/` into `essence/essence.md` |
-| `sync_workspace_index` | Rebuild `index.json` from disk |
-| `bootstrap_workspace` | Load context, essence, and memory tree |
-| `load_workspace_context` | Load recent conversation context |
-| `load_more_context` | Load older conversation rounds |
-| `search_context` | Search across all session wires |
-| `load_turn_context` | Load specific turn details |
-| `tag_theme` | Associate a turn or memory with a theme |
-| `trace_theme` | Trace a theme's evolution |
-| `list_themes` | List themes |
-| `refine_session_turns` | Generate refined turn summaries |
-
-## Development
+可通过 `MEMORY_STORE_ROOT` 环境变量覆盖存储根目录。
+
+### 环境变量
+
+| 变量 | 用途 |
+|------|------|
+| `MEMORY_STORE_ROOT` | 覆盖默认存储根目录 `~/.kimi-code-memory`。 |
+| `MEMORY_SESSIONS_ROOT` | 覆盖默认的 `~/.kimi-code/sessions` 路径，用于发现 `wire.jsonl` 文件。 |
+| `KIMI_CODE_HOME` | `MEMORY_SESSIONS_ROOT` 的替代方案；会话从 `<KIMI_CODE_HOME>/sessions` 读取。 |
+
+## 工具列表
+
+| 工具 | 用途 |
+|------|------|
+| `remember` | 写入一条 Markdown 记忆 |
+| `recall` | 按 key 读取记忆 |
+| `search` | 在记忆中关键词搜索 |
+| `list` | 列出记忆，支持按 folder / tag 过滤和 limit 限制 |
+| `list_tags` | 列出所有标签 |
+| `delete` | 删除记忆 |
+| `move` | 移动或重命名记忆 |
+| `organize_memories` | 将 `memory/` 提炼为 `essence/essence.md` |
+| `sync_workspace_index` | 从磁盘重建 `index.json` |
+| `bootstrap_workspace` | 加载上下文、精要和记忆树 |
+| `load_workspace_context` | 加载最近对话上下文 |
+| `load_more_context` | 加载更早的对话轮次 |
+| `search_context` | 跨所有会话 wire 搜索 |
+| `load_turn_context` | 加载指定轮次详情 |
+| `tag_theme` | 将轮次或记忆关联到主题 |
+| `trace_theme` | 追溯主题演化 |
+| `list_themes` | 列出主题 |
+| `refine_session_turns` | 生成精炼轮次摘要 |
+
+## Prompts
+
+本服务器同时提供可复用的 MCP Prompt，供客户端在调用工具前拉取：
+
+| Prompt | 用途 |
+|--------|------|
+| `memory-decision-check` | 修改文件前，先检查与其相关的历史决策 |
+| `memory-theme-trace` | 追溯某个主题在多次会话中的演化 |
+| `memory-session-summary` | 总结当前会话，并建议值得挂载的主题 |
+
+## Resources
+
+本服务器暴露以下 MCP Resource URI，客户端可按需读取：
+
+| URI 模式 | 说明 |
+|----------|------|
+| `memory://<folder>/<key>` | 读取 `memory/` 下的某条 Markdown 记忆 |
+| `theme://<theme>` | 读取某个主题的关联摘要（Markdown 格式） |
+| `essence://essence` | 读取工作区精要 `essence/essence.md` |
+
+## 可视化仪表盘
+
+提供独立的 Web 仪表盘，用于查看工作区记忆、主题时间线和近期决策：
+
+```bash
+npx kimi-memory-vis
+```
+
+启动后会自动打开浏览器，默认地址 `http://127.0.0.1:58628`。
+
+也可以在 MCP 服务器启动时自动启动仪表盘：
+
+```bash
+export KIMI_MEMORY_AUTO_VIS=1
+```
+
+或者在会话中让 Agent 打开：
+
+```json
+{ "name": "open_memory_dashboard" }
+```
+
+仪表盘支持：
+
+- 工作区概览与 `essence.md` 行内编辑
+- 主题时间线浏览
+- 近期决策列表
+- 显式记忆目录浏览
+
+## 开发
 
 ```bash
 git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
@@ -243,50 +319,51 @@ npm test
 npm run lint
 ```
 
-See [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) for contribution guidelines.
+贡献指南见 [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.zh-CN.md)。
 
-## Project Structure
+## 项目结构
 
 ```text
 src/
-├── server.ts              # MCP server entry
-├── config.ts              # defaults and paths
-├── theme-manager.ts       # theme storage
-├── refined-manager.ts     # refined turn storage
+├── server.ts              # MCP 服务器入口
+├── config.ts              # 默认值与路径
+├── theme-manager.ts       # 主题存储
+├── refined-manager.ts     # 精炼轮次存储
 ├── dao/
-│   ├── index.ts           # index.json DAO (v3-kv)
-│   └── memory-store.ts    # Markdown file operations
+│   ├── index.ts           # index.json DAO（v3-kv）
+│   └── memory-store.ts    # Markdown 文件操作
 ├── context/
-│   └── wire-context.ts    # wire.jsonl parsing
+│   └── wire-context.ts    # wire.jsonl 解析
 ├── tools/
-│   ├── index.ts           # tool schemas & dispatch
-│   ├── memory-tools.ts    # memory CRUD
-│   ├── context-tools.ts   # context recovery
-│   ├── theme-tools.ts     # theme tracing
-│   └── system-tools.ts    # organize/sync/bootstrap
+│   ├── index.ts           # 工具 schema 与分发
+│   ├── memory-tools.ts    # 记忆增删改查
+│   ├── context-tools.ts   # 上下文恢复
+│   ├── theme-tools.ts     # 主题追溯
+│   └── system-tools.ts    # 整理/同步/引导
 └── utils/
     ├── frontmatter.ts
     ├── paths.ts
     └── validation.ts
 ```
 
-## Roadmap
+## 路线图
 
-- [x] Modular source structure
+- [x] 模块化源码结构
 - [x] ESLint + Prettier
-- [x] Basic integration tests
-- [x] Core test coverage for context/theme tools
-- [ ] Optional local embedding search
-- [ ] Optional LLM-based turn refinement
-- [ ] Pluggable wire format adapters
-- [ ] Memory usage benchmarks
+- [x] 基础集成测试
+- [x] 上下文/主题工具核心测试覆盖
+- [ ] 可选本地 embedding 搜索
+- [ ] 可选 LLM 精炼轮次
+- [ ] 可插拔 wire 格式适配器
+- [ ] 内存使用 benchmark
 
-## Related Documents
+## 相关文档
 
-- [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — system design and data flow
-- [`docs/search-logic.md`](./docs/search-logic.md) — how `search` and `search_context` work
-- [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) — how to contribute
+- [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) —— 系统设计与数据流
+- [`docs/three-layer-memory-model.zh-CN.md`](./docs/three-layer-memory-model.zh-CN.md) —— 本服务器背后的记忆模型理论
+- [`docs/search-logic.zh-CN.md`](./docs/search-logic.zh-CN.md) —— `search` 与 `search_context` 的实现逻辑
+- [`docs/CONTRIBUTING.zh-CN.md`](./docs/CONTRIBUTING.zh-CN.md) —— 如何贡献
 
-## License
+## 许可证
 
 MIT

package/assets/contextFlow.svg

@@ -0,0 +1,144 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 520" width="900" height="520">
+  <defs>
+    <style>
+      .session-box { fill: #f5f5f5; stroke: #bdbdbd; stroke-width: 2; }
+      .timeline { stroke: #212121; stroke-width: 4; stroke-linecap: round; }
+      .turn { stroke: none; rx: 2; }
+      .cluster { stroke-width: 6; stroke-linecap: round; fill: none; opacity: 0.85; }
+      .theme-line { fill: none; stroke-width: 2; }
+      .theme-bracket { fill: none; stroke-width: 1.5; }
+      .label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; font-size: 13px; fill: #424242; }
+      .label-small { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; font-size: 11px; fill: #757575; }
+      .theme-label { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; font-size: 13px; font-weight: 600; }
+      .legend-box { rx: 3; }
+    </style>
+    <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#212121"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="520" fill="#ffffff"/>
+
+  <!-- Sessions -->
+  <rect class="session-box" x="70" y="220" width="180" height="110" rx="6"/>
+  <rect class="session-box" x="265" y="220" width="180" height="110" rx="6"/>
+  <rect class="session-box" x="460" y="220" width="180" height="110" rx="6"/>
+  <rect class="session-box" x="655" y="220" width="180" height="110" rx="6"/>
+
+  <!-- Session labels -->
+  <text class="label" x="160" y="355" text-anchor="middle">sessionA</text>
+  <text class="label" x="355" y="355" text-anchor="middle">sessionB</text>
+  <text class="label" x="550" y="355" text-anchor="middle">sessionC</text>
+  <text class="label" x="745" y="355" text-anchor="middle">sessionD</text>
+
+  <!-- Timeline -->
+  <line class="timeline" x1="40" y1="300" x2="860" y2="300" marker-end="url(#arrowhead)"/>
+  <text class="label" x="870" y="305" text-anchor="start">timeline</text>
+
+  <!-- ========== Session A turns ========== -->
+  <!-- Red turns (themeC) -->
+  <rect class="turn" fill="#e53935" x="105" y="265" width="8" height="35"/>
+  <rect class="turn" fill="#e53935" x="120" y="255" width="8" height="45"/>
+  <rect class="turn" fill="#e53935" x="135" y="270" width="8" height="30"/>
+  <!-- Orange turn -->
+  <rect class="turn" fill="#fb8c00" x="165" y="275" width="8" height="25"/>
+  <!-- Blue turns (themeB) -->
+  <rect class="turn" fill="#1e88e5" x="195" y="260" width="8" height="40"/>
+  <rect class="turn" fill="#1e88e5" x="210" y="275" width="8" height="25"/>
+  <rect class="turn" fill="#1e88e5" x="225" y="280" width="8" height="20"/>
+
+  <!-- Clusters A -->
+  <line class="cluster" stroke="#e53935" x1="100" y1="315" x2="145" y2="315"/>
+  <line class="cluster" stroke="#1e88e5" x1="190" y1="315" x2="235" y2="315"/>
+
+  <!-- ========== Session B turns ========== -->
+  <!-- Red turns (themeC) -->
+  <rect class="turn" fill="#e53935" x="300" y="270" width="8" height="30"/>
+  <rect class="turn" fill="#e53935" x="315" y="255" width="8" height="45"/>
+  <rect class="turn" fill="#e53935" x="330" y="265" width="8" height="35"/>
+  <!-- Green turn (themeA) -->
+  <rect class="turn" fill="#43a047" x="365" y="275" width="8" height="25"/>
+  <!-- Blue turns (themeB) -->
+  <rect class="turn" fill="#1e88e5" x="395" y="260" width="8" height="40"/>
+  <rect class="turn" fill="#1e88e5" x="410" y="250" width="8" height="50"/>
+  <rect class="turn" fill="#1e88e5" x="425" y="275" width="8" height="25"/>
+
+  <!-- Clusters B -->
+  <line class="cluster" stroke="#e53935" x1="295" y1="315" x2="340" y2="315"/>
+  <line class="cluster" stroke="#1e88e5" x1="390" y1="315" x2="435" y2="315"/>
+
+  <!-- ========== Session C turns ========== -->
+  <!-- Orange turn -->
+  <rect class="turn" fill="#fb8c00" x="485" y="280" width="8" height="20"/>
+  <!-- Green turns (themeA) -->
+  <rect class="turn" fill="#43a047" x="510" y="255" width="8" height="45"/>
+  <rect class="turn" fill="#43a047" x="525" y="245" width="8" height="55"/>
+  <rect class="turn" fill="#43a047" x="540" y="270" width="8" height="30"/>
+  <!-- Red turn (themeC) -->
+  <rect class="turn" fill="#e53935" x="575" y="270" width="8" height="30"/>
+  <!-- Blue turns (themeB) -->
+  <rect class="turn" fill="#1e88e5" x="605" y="265" width="8" height="35"/>
+  <rect class="turn" fill="#1e88e5" x="620" y="275" width="8" height="25"/>
+
+  <!-- Clusters C -->
+  <line class="cluster" stroke="#43a047" x1="505" y1="315" x2="550" y2="315"/>
+  <line class="cluster" stroke="#1e88e5" x1="600" y1="315" x2="630" y2="315"/>
+
+  <!-- ========== Session D turns ========== -->
+  <!-- Blue turns (themeB) -->
+  <rect class="turn" fill="#1e88e5" x="675" y="275" width="8" height="25"/>
+  <rect class="turn" fill="#1e88e5" x="690" y="260" width="8" height="40"/>
+  <!-- Green turns (themeA) -->
+  <rect class="turn" fill="#43a047" x="720" y="265" width="8" height="35"/>
+  <rect class="turn" fill="#43a047" x="735" y="250" width="8" height="50"/>
+  <rect class="turn" fill="#43a047" x="750" y="270" width="8" height="30"/>
+
+  <!-- Clusters D -->
+  <line class="cluster" stroke="#1e88e5" x1="670" y1="315" x2="700" y2="315"/>
+  <line class="cluster" stroke="#43a047" x1="715" y1="315" x2="760" y2="315"/>
+
+  <!-- ========== Theme brackets (endpoints align with vertical connectors) ========== -->
+  <!-- themeC (red): sessionA red cluster → sessionB red cluster → sessionC red turn -->
+  <path class="theme-bracket" stroke="#e53935" d="M 122 190 L 122 175 L 579 175 L 579 190"/>
+  <text class="theme-label" fill="#e53935" x="350" y="168" text-anchor="middle">themeC</text>
+
+  <!-- themeB (blue): sessionA → sessionB → sessionC → sessionD blue clusters -->
+  <path class="theme-bracket" stroke="#1e88e5" d="M 212 135 L 212 120 L 685 120 L 685 135"/>
+  <text class="theme-label" fill="#1e88e5" x="448" y="113" text-anchor="middle">themeB</text>
+
+  <!-- themeA (green): sessionB green turn → sessionC green cluster → sessionD green cluster -->
+  <path class="theme-bracket" stroke="#43a047" d="M 369 95 L 369 80 L 737 80 L 737 95"/>
+  <text class="theme-label" fill="#43a047" x="553" y="73" text-anchor="middle">themeA</text>
+
+  <!-- Vertical connectors from themes to representative turns/clusters -->
+  <line class="theme-line" stroke="#e53935" x1="122" y1="175" x2="122" y2="220"/>
+  <line class="theme-line" stroke="#e53935" x1="317" y1="175" x2="317" y2="220"/>
+  <line class="theme-line" stroke="#e53935" x1="579" y1="175" x2="579" y2="220"/>
+
+  <line class="theme-line" stroke="#1e88e5" x1="212" y1="120" x2="212" y2="220"/>
+  <line class="theme-line" stroke="#1e88e5" x1="412" y1="120" x2="412" y2="220"/>
+  <line class="theme-line" stroke="#1e88e5" x1="615" y1="120" x2="615" y2="220"/>
+  <line class="theme-line" stroke="#1e88e5" x1="685" y1="120" x2="685" y2="220"/>
+
+  <line class="theme-line" stroke="#43a047" x1="369" y1="80" x2="369" y2="220"/>
+  <line class="theme-line" stroke="#43a047" x1="527" y1="80" x2="527" y2="220"/>
+  <line class="theme-line" stroke="#43a047" x1="737" y1="80" x2="737" y2="220"/>
+
+  <!-- Callouts -->
+  <line stroke="#9e9e9e" stroke-width="1" x1="122" y1="250" x2="122" y2="235"/>
+  <text class="label-small" x="122" y="248" text-anchor="middle" fill="#e53935">turn</text>
+
+  <line stroke="#9e9e9e" stroke-width="1" x1="122" y1="332" x2="122" y2="350"/>
+  <text class="label-small" x="122" y="365" text-anchor="middle" fill="#e53935">cluster</text>
+
+  <!-- Legend (top-left to avoid blocking theme lines) -->
+  <rect class="legend-box" x="30" y="30" width="190" height="95" fill="#fafafa" stroke="#e0e0e0"/>
+  <text class="label" x="40" y="52" font-weight="600">图例</text>
+  <rect class="turn" fill="#e53935" x="40" y="62" width="6" height="20"/>
+  <text class="label-small" x="55" y="76">= turn（对话轮）</text>
+  <line class="cluster" stroke="#1e88e5" x1="40" y1="92" x2="70" y2="92"/>
+  <text class="label-small" x="75" y="96">= cluster（簇）</text>
+  <rect class="session-box" x="40" y="105" width="30" height="12"/>
+  <text class="label-small" x="75" y="115">= session</text>
+</svg>