# DSH 知识卡片

[English](./README.md)

把 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web GUI 中的对话内容一键生成简洁质感的知识卡片——概念卡、流程图、对比表、要点列表、思维导图、引用卡、清单卡、时间线、问答卡——由 Agent 生成，Tab 画廊预览，多格式下载。

## 功能特性

- **🎴 一键生成** —— 每个会话头部都有「知识卡片」按钮，点击打开配置弹窗
- **🧠 九种卡片类型** —— 概念卡、流程图（Mermaid）、对比表、要点列表、思维导图（Mermaid）、引用卡、清单卡、时间线（Mermaid）、问答卡
- **🗂 Tab 画廊** —— 卡片按类型分 Tab，每个 Tab 独立滚动浏览
- **⬇ 多格式下载** —— 所有卡片支持 Markdown / HTML / JSON / TXT / SVG；每张卡片可单独选格式，也可批量全部下载
- **🔄 后台生成** —— 生成过程中可关闭弹窗，完成后按钮角标显示卡片数量并弹出浏览器通知
- **🌗 暗色模式** —— 跟随系统 `prefers-color-scheme`
- **🌍 中英双语** —— 简体中文与英文界面

## v0.1.3 更新内容

- **🆕 四种新卡片类型** —— `quote`（引用卡）、`checklist`（清单卡）、`timeline`（时间线）、`faq`（问答卡）
- **🧾 时间线 / 清单卡的事实层** —— Agent 会先输出 ```` ```facts ```` JSON 块；客户端将其合并去重到会话级存储，再基于全量历史确定性地生成这两类卡片
- **🎚 对话范围选择器** —— 可手动选择轮次，也可切换为全部历史；时间线和清单卡始终使用全部历史
- **♾ 全部历史模式自动加载更早页面** —— 会自动拉取更早的对话页，直到没有更多历史
- **🖼 九种卡片全部支持 SVG 下载** —— Mermaid 卡片导出渲染后的图形，Markdown 卡片导出自包含的样式化文本卡片
- **🎨 修复并优化问答卡 SVG 导出** —— 保留主题色、卡片边框、头部背景、标题/正文样式，以及标题 / 引用 / 代码格式
- **🎯 严格按所选类型生成** —— 只生成勾选的卡片类型，不再额外输出其他类型
- **📐 生成弹窗更紧凑** —— 弹窗高度改为自适应，大幅减少下方空白
- **🧹 界面精简** —— 移除了生成页顶部已废弃的「手动选择轮次 / 自动话题分割」按钮

## 版本与兼容性

当前版本：`v0.1.3`，已发布到 GitHub 和 npm，两者版本一致。

适配的 DSH 版本（与 `v0.1.2` 完全一致，本次更新未调整 DSH 兼容范围）：

| DSH 版本 | 日期 |
|---|---|
| `0.1.1-rc.2` | 2026-08-21 |
| `0.1.1-rc.1` | 2026-08-21 |
| `0.1.0-rc.8` | 2026-08-19 |
| `0.1.0-rc.7` | 2026-08-17 |
| `0.1.0-rc.6` | 2026-08-13 |

## 安装

从 npm 安装：

```bash
dsh plugin --profile web add @wangxueqi/dsh-client-ui-knowledge-cards
```

或从 GitHub 安装（`main` 分支）：

```bash
dsh plugin --profile web add github:wangxueqi00/dsh-client-ui-knowledge-cards
```

或固定到某个 tag：

```bash
dsh plugin --profile web add github:wangxueqi00/dsh-client-ui-knowledge-cards#v0.1.3
```

然后重启：

```bash
dsh --profile web
```

包已声明 `dsh.bundle`，`dsh plugin add` 会自动将其激活为 profile 配置层，无需手动修改任何配置。构建产物（`lib/`）已提交到仓库，因此 GitHub 安装无需构建步骤。

## 使用方法

1. 打开任意会话，点击会话头部的 **🎴 知识卡片** 按钮
2. 选择**对话范围**：手动选择轮次，或全部历史（自动加载更早的页面）。时间线/清单卡无论范围如何都会使用全部历史
3. 勾选**卡片类型**，点击「生成卡片」
3. Agent 分析所选轮次并输出结构化的卡片数据
4. 在按类型分组的 Tab 画廊中预览卡片，为每张卡片选择下载格式，单张下载或批量全部下载
5. 生成过程中可以关闭弹窗——完成后按钮右上角角标会显示卡片数量，并触发浏览器通知

## 卡片类型

| 类型 | 图标 | 内容形式 | 适用场景 |
|------|------|----------|----------|
| 概念卡 | 💡 | Markdown 标题 + 列表 | 定义与解释 |
| 流程图 | 🔀 | Mermaid `graph` | 流程与决策 |
| 对比表 | ⚖️ | Markdown 表格 | 多方案对比 |
| 要点列表 | 📋 | 列表 | 核心要点提炼 |
| 思维导图 | 🧠 | Mermaid `mindmap` | 层级概念梳理 |
| 引用卡 | ❝ | Markdown 引用块 | 关键结论与金句 |
| 清单卡 | ✅ | Markdown 任务列表 | 行动项与待办 |
| 时间线 | 🕒 | Mermaid `timeline` | 时间顺序事件与里程碑 |
| 问答卡 | ❓ | Markdown 问答 | 问题与答案 |

## 下载格式

| 格式 | 概念/对比/要点/引用/清单/问答 | 流程图/思维导图/时间线 |
|------|:---:|:---:|
| Markdown（`.md`） | ✅ | ✅ |
| HTML（独立 `.html`） | ✅ | ✅（CDN 加载 Mermaid） |
| JSON（`.json`） | ✅ | ✅ |
| 纯文本（`.txt`） | ✅ | ✅ |
| SVG（`.svg`） | ✅（文本卡片） | ✅（渲染图） |

## 工作原理

本插件由单文件浏览器 bundle 和少量主机层代码组成：

- **主机层**：注入 systemPrompt 指导，教会 Agent 输出 ```` ```card ```` JSON 代码块，并在末尾附加 `<!-- knowledge-cards-generated -->` 完成标记
- **客户端层**：向 `conversation.session.header.actions` 槽位注册按钮；按钮始终挂载并在后台监听会话，Agent 完成后把卡片解析进模块级存储——关闭弹窗不会丢失状态或中断生成
- **事实层**：时间线/清单请求会先输出 ```` ```facts ```` JSON 块；客户端把这些事实合并进会话级存储，并确定性地构建这两张卡片——全量历史卡片去重合并，重新生成时无需重读对话
- **渲染**：Mermaid 图（已内联进 bundle）+ Markdown，每种卡片类型使用独立的低饱和度主题色

## 开发

本仓库在 [DeepSeek Harness monorepo](https://github.com/deepseek-ai/deepseek-harness) 检出内开发--构建预设、tsconfig 引用和平台模块表都在那里。一份物理目录、两个视图：直接克隆进 monorepo，或把你的克隆用 junction 挂上去：

```powershell
# 在 DSH 检出内：本仓库的克隆就是物理目录
git clone https://github.com/wangxueqi00/dsh-client-ui-knowledge-cards.git `
  packages/client/ui-knowledge-cards

# 可选：在别处保留一个便捷视图
New-Item -ItemType Junction -Path <你的路径> -Target <DSH检出>\packages\client\ui-knowledge-cards

# 然后在 monorepo 根目录
pnpm install
```

构建（两个路径都行--脚本会自动解析 junction）：

```powershell
./scripts/build.ps1         # tsc -b + bundle
./scripts/build.ps1 -Watch   # tsc -b + watch
pnpm run bundle              # 仅打包：从仓库路径直接执行也可以
```

同一个 `package.json` 同时服务开发和发布：真实版本范围（`^0.1.1-rc.2`）在 monorepo 内链接 workspace 包（`linkWorkspacePackages`），从 npm/git 安装也直接可用--开发与发布形态之间无需任何转换。

### 目录结构

```
src/
├── index.ts               # 主机层：systemPrompt 指导
├── invariant.ts           # 不变量伴生插件
└── client/
    ├── index.ts           # 插件入口：apply()、槽位注册
    ├── card-store.ts      # 模块级卡片存储（跨弹窗开关持久化）
    ├── card-generator.ts  # 卡片类型、主题色、prompt 构建器
    ├── card-parser.ts     # 解析 Agent 输出的 ```card 代码块
    ├── card-data-collector.ts
    ├── download.ts        # MD / HTML / JSON / TXT / SVG 导出
    ├── mermaid-renderer.ts
    ├── locales.ts         # 中英词典
    └── components/        # CardButton、CardDialog、CardGallery、CardView、MermaidDiagram
```

## 发布

本仓库本身就是发布载体--源码、已提交的 `lib/` 产物、可直接发布的 `package.json` 全在一处：

```bash
./scripts/build.ps1                     # 1. 构建（lib/ 直接落在仓库里）
# 2. 在 package.json 中升版本号
git add .
git commit -m "release: v0.x.y"
git tag v0.x.y
git push origin main --tags             # 3. GitHub 发布
pnpm publish --no-git-checks            # 4. npm 发布
```

`lib/` 必须保持提交（检查 `.gitignore`）：这些产物让 `dsh plugin add github:...` 无需构建即可安装。

## 许可证

MIT