前言¶

用 DSH Agent 刷视频、读帖子时，标题、链接、是否看完、一句感受往往只留在对话里。下次想回看，只能翻聊天记录。社区里也有各自记笔记、导出链接的做法，但和 Agent 的「看完即写一条」流程往往对不上。

下面介绍的是维护者 H-Y-1-1 在 DSH 社区目录「记忆」分类下的插件 dsh-watch-history（当前 README 标注 v0.1.1）。它不负责发现新内容，只把「看过的别丢」收成一份本地 JSONL，并在 DSH 设置页用卡片墙展示。

这是什么¶

dsh-watch-history 是跨平台观看历史 DSH 插件：记录由 Agent 或 HTTP 调用写入；插件负责存储、补全元数据、在设置页展示卡片。platform 只是字符串，不要求插件提前内置某一家平台。

数据流可以概括为：

Agent 看完 / 学完
→ 调 watch_history_add（或 POST /api/watch-history）
→ 写 history.jsonl
→ 设置页出现卡片

运行要求（来自 README）：DSH ≥ 0.2.0、Node ≥ 22；安装后需重启一次 DSH。

核心功能¶

• 统一记录：不同平台的「看过什么」写入同一份 append-only JSONL（同一条调用两次会写两条，不去重）。
• 卡片墙：封面、标题、UP/作者、标签、平台、看了/没看、观看方式等；支持按平台、看了/没看筛选，按标题/UP/标签搜索。
• 元数据补全：B 站 / GitHub 用公开接口；抖音、快手、小红书、贴吧、小黑盒读公开页面 OG；补不上留空。优先级为：记录自带字段 > 内置适配器 > Provider > 声明式配置 > 占位图。
• 三种写入：AI 工具 watch_history_add、带 token 的 HTTP API、CLI 脚本 node tools/add.mjs。
• 本地鉴权：同源校验 + 随机 token，仅用于本机请求；不保存 B 站 cookie、SESSDATA，不做评论、点赞等账号操作。

插件以当前 DSH 进程权限运行；安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证。

安装与启用¶

桌面版¶

DSH → Settings → Plugins → Add plugin，填写：

https://github.com/H-Y-1-1/dsh-watch-history

装完重启 DSH，打开 设置 → 观看历史。README 说明：桌面版 profile 由 Electron App 独占管理，不要用 dsh plugin --profile desktop add，否则会报 profile "desktop" is managed exclusively by the Electron application。

Web / headless profile¶

dsh plugin --profile web add github:H-Y-1-1/dsh-watch-history

然后重启对应 profile。

典型用法¶

快速开始¶

1. 安装 → 重启 → 打开「观看历史」；
2. 默认历史为空（新数据文件）；
3. 用 watch_history_add 写第一条；
4. 刷新设置页，卡片出现。

若已有 JSONL，可在插件目录下的 config.json 里把 dataFile 指过去（空则默认 ~/.dsh/watch-history/history.jsonl）。

AI 工具写入¶

watch_history_add
  platform: bilibili
  content_id: BV1xx...
  title: 标题
  started_at: 2026-10-25T12:00:00+08:00
  status: watched        # watched / metadata_only / reference_only
  seen: true
  view_mode: subtitle    # full_playback / frames / subtitle / ai_review / metadata / reference
  one_liner: 一句话感受
  tags: ["游戏", "整活"]

B 站记录缺 url / cover_url 时，插件会用公开 view API 补；其他平台可直接传 cover_url。

HTTP API¶

GET  /api/watch-history/bootstrap        → token + HttpOnly cookie
GET  /api/watch-history?limit=&offset=   → 需要 token/cookie
POST /api/watch-history                  → 需要 token/cookie + application/json
GET  /api/watch-history/fallback         → 通用占位图

示例：

curl http://127.0.0.1:<port>/api/watch-history/bootstrap

curl -X POST http://127.0.0.1:<port>/api/watch-history \
  -H "Content-Type: application/json" \
  -H "X-Watch-History-Token: <token>" \
  -d '{"platform":"bilibili","content_id":"BV1xx","title":"标题"}'

API 只接受 Host 为本机回环地址的请求，并校验 Origin/Referer、Sec-Fetch-Site 与 token。请勿把 DSH 端口直接暴露公网；若走反向代理，需把 Host 重写为 127.0.0.1 并自行加认证层。

脚本写入¶

node tools/add.mjs out/record.json

配置概要¶

复制 config.example.json 为 config.json（可用环境变量 WATCH_HISTORY_CONFIG 指向别处）：

{
  "dataFile": "",
  "fallbackImage": "",
  "provider": {
    "url": "",
    "timeout_ms": 3000,
    "headers": {}
  },
  "adapters": []
}

完整字段说明与 schema 见仓库内 schema/history.schema.json 与 README。

适用场景与注意¶

适合谁：用 DSH Agent 跨平台消费内容，希望留下「看过什么、看没看完、一句话感受」，并在设置页统一回看的人。

边界（README 明确列出）：不主动发现新视频、不监控浏览器；append-only 不去重；元数据补全失败不影响写入，封面可能显示占位图 assets/fallback.svg。

DSH 生态理念是「一切皆插件」；SkillHub 目录页 是社区独立站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

经过上面的步骤，你可以把 Agent 会话里散落的「看过」信息收成一条本地记录，在 设置 → 观看历史 用卡片墙筛选和搜索。源码、Changelog 与问题反馈见 GitHub：H-Y-1-1/dsh-watch-history。