架构文档：跨工具会话迁移插件 session-import

August 14, 2026 · View on GitHub

版本：v0.1（Draft）日期：2026-08-14 对应需求：plugin-req-session-import.md 插件代号：session-import

1. 架构总览

插件以 Cordis 插件 形态接入 dsh，整体遵循 dsh 的「事件溯源会话日志（event-sourced session-log）」模型。核心思想是：解析与映射解耦、源适配可插拔、导入与知识沉淀分管道。

flowchart LR
    subgraph 外部源[外部 Agent 工具导出]
        S1[Claude Code] S2[ChatGPT] S3[Cursor] S4[...12+源] S5[通用 JSON/MD]
    end
    subgraph 插件[session-import 插件]
        A[Source Ingest 源接入] --> B[Parser Adapters 可插拔解析]
        B --> C[Fidelity Mapping 保真映射]
        C --> D[(dsh session-log 事件溯源)]
        C --> E[Knowledge Extractor 知识抽取]
        E --> F[(dsh memory seam)]
        A --> G[Privacy Scanner 脱敏]
        D --> H[Import & Continue 续聊]
        H --> I[Client UI 导入向导/历史面板]
        D --> J[Exporter 双向导出]
    end
    subgraph dsh核心[dsh 核心]
        D
        F
        P[persistence] K[client-modules]
    end
    S1 & S2 & S3 & S4 & S5 --> A
    I --> K

2. 模块划分与职责

模块	职责	关键接口/产物
Source Ingest	接收文件/目录、嗅探来源类型、按类型路由到对应 parser	`ingest(input): SourceType`
Parser Adapters	每种源一个解析器，产出统一的 `NormalizedConversation`	`ParserAdapter.parse(raw): NormalizedConversation`
Fidelity Mapping	把 `NormalizedConversation` 转为 dsh session-log 事件序列	`mapToEvents(nc): SessionEvent[]`
Import & Continue	写入目标会话、冲突处理、支持续聊上下文拼接	`importSession(events, opts)`
Knowledge Extractor	抽取决策/代码/约定，去重聚类，写入 memory seam	`extract(nc): KnowledgeItem[]`
Privacy Scanner	敏感字段检测、脱敏提醒、加密归档	`scan(text): SensitiveHit[]`
Exporter	把 dsh 会话导出为标准格式（JSON/MD）	`export(sessionId, fmt)`
Client UI	导入向导、历史面板、冲突解决弹窗	dsh client-modules

3. 关键流程

3.1 导入主流程

sequenceDiagram
    participant U as 用户
    participant UI as 导入向导
    participant IN as Source Ingest
    participant PA as Parser
    participant MP as Fidelity Mapping
    participant PR as Privacy Scanner
    participant IM as Import & Continue
    participant SL as dsh session-log

    U->>UI: 选择文件/目录
    UI->>IN: ingest(input)
    IN->>PA: 路由到对应 parser
    PA->>MP: NormalizedConversation
    MP->>PR: 各消息文本
    PR-->>UI: SensitiveHit[]（如有则提醒）
    MP->>IM: SessionEvent[]
    IM->>SL: 写入（重命名/合并/跳过 冲突策略）
    IM-->>UI: 导入完成，可续聊

3.2 续聊流程

导入完成后，目标 dsh 会话末条 assistant 消息作为上下文保留。用户在新一轮输入时，dsh 正常进入 LLM 调用，历史事件作为前缀上下文注入。无需插件额外介入——插件只负责「把过去还原成 dsh 原生会话」。

3.3 知识 / 记忆抽取流程

flowchart TB
    NC[NormalizedConversation] --> EX[LLM 抽取决策/代码/约定]
    EX --> DD[去重聚类 against 已有 memory]
    DD --> CK{是否人工确认?}
    CK -->|是| W[写入 memory seam]
    CK -->|否| W2[直接写入]
    W & W2 --> M[(dsh memory)]

3.4 双向导出流程

Exporter 读取 dsh session-log，逆向映射为通用 NormalizedConversation，再序列化为目标格式（dsh 原生 JSON / 通用 Markdown / transcript），供迁回其它工具。

4. dsh 架构对接点

dsh 接入点	用途	对接方式
`session` 投影 / 写入	把映射后的事件写入事件溯源日志	调用 session 投影 API，按 event-sourced 方式追加
`persistence`	会话存储、原文归档	复用 dsh 持久化层；原文加密归档落到本地存储
`memory` seam	知识/记忆抽取结果沉淀	调用 memory 写入接口，带去重键
`client-modules`	导入向导、历史面板、冲突弹窗	注册插件 UI 模块到 dsh 客户端

5. 数据模型与 Schema

5.1 统一中间表示 `NormalizedConversation`

interface NormalizedConversation {
  source: SourceType;            // claude_code | chatgpt | cursor | generic_json ...
  schemaVersion: string;         // 适配器版本门
  messages: NormalizedMessage[];
  attachments?: AttachmentRef[];
  extensions?: Record<string, unknown>; // 源专有字段（citation/diff...）
}

interface NormalizedMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
  thinking?: string;             // reasoning 块
  toolCalls?: ToolCall[];        // name/args/result
  codeBlocks?: CodeBlock[];
  extensions?: Record<string, unknown>;
}

5.2 dsh session-log 事件（写入形态）

映射层产出 SessionEvent[]，每条事件承载一个原子动作（user_msg / assistant_msg / tool_call / tool_result / thinking / attachment），保持原始顺序与角色。源专有字段落 meta.extensions，dsh 无对应工具时 tool_call.result 存原始 JSON。

6. 扩展机制（适配器注册）

新增一个源 = 实现一个 ParserAdapter 并注册到 Cordis 上下文，无需改动核心：

interface ParserAdapter {
  readonly source: SourceType;
  readonly schemaVersion: string;
  detect(raw: RawInput): boolean;          // 嗅探是否本源
  parse(raw: RawInput): NormalizedConversation;
}
// 注册：container.set(ParserAdapter, new ClaudeCodeAdapter())

Source Ingest 通过依赖注入收集所有 ParserAdapter，按 detect() 结果选择；都不匹配时回落到 GenericJsonAdapter。

7. 安全与隐私架构

本地优先：解析、映射、抽取全部在本地进程内完成，无网络上传（NFR-01）。
敏感检测：Privacy Scanner 用正则 + 轻量分类器识别 API Key / 手机号 / 邮箱 / 身份证等，命中即弹提醒，用户可一键脱敏后再写入。
加密归档：原文归档可选 AES 加密，密钥由用户本地管理，不进日志。
密钥不落明文：解析过程中遇到的密钥仅在内存中临时处理，写入前必须脱敏或加密。

8. 部署与集成形态

作为 Cordis 插件发布，依赖 dsh dev-preview 提供 session / persistence / memory / client-modules 接入点。
适配 Node 22.19+ / 24+；对 dsh breaking change 做版本门与告警（NFR-03）。
大文件采用流式分片：解析器按消息块增量产出 NormalizedMessage，映射层增量写入，避免整文件载入导致内存峰值（NFR-02 / FR-10）。