# dsh-gap-feed

[English](README.md) | [中文](README.zh.md)

[![npm](https://img.shields.io/npm/v/dsh-gap-feed)](https://www.npmjs.com/package/dsh-gap-feed)
[![GitHub stars](https://img.shields.io/github/stars/faukwaa/dsh-gap-feed)](https://github.com/faukwaa/dsh-gap-feed)

[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件：agent 思考超过阈值时，**直接在对话流中打出一条**热点新闻或提醒卡片。频率极低、绝不打扰正常对话。

![demo](assets/demo.png)

## 功能特性

- **对话流注入**：agent 思考超时时，插件以 `assistant/message` 消息直接追加进会话日志（`session.append` + `surfaceOp:'append'`），UI 自动渲染成对话流卡片（带可点击链接）；内容源挂了静默降级，不阻塞对话。
- **多内容源**：今日头条热榜（公开接口，免登录）+ **GitHub 本周热门仓库**（按星数排序）+ **B站全站热榜**；多源并发抓取，单源失败不影响其他。
- **对话建提醒**：对话里直接说"提醒我 18:00 开会"，模型调用 `gap_feed_reminder_add` 工具写入提醒，到点后在间隙内容里**优先于新闻**展示。
- **设置页管理**：dsh 设置页按 schema 自动渲染 `gap-feed` 表单，可改配置、管理提醒（增删改查 / 启停 / 完成），改动即时生效。
- **限频参数**：思考时长阈值 + 冷却间隔 + 每小时上限可配，保证低频、不刷屏。
- **内容优先级**：到点提醒 > 未到点提醒 > 新闻；同一内容不重复插入。
- **持久化安全**：追加的消息从会话现有消息继承合法 `model source`（kind/provider/model），重启后会话可正常加载（伪造 source 会被 SessionPersistence 校验拒绝）。

## 安装

```bash
dsh plugin --profile web add dsh-gap-feed
```

重启 `dsh web`（或刷新页面即可）。

> 已发布到 npm（[`dsh-gap-feed`](https://www.npmjs.com/package/dsh-gap-feed)）——市场优先展示预构建 npm 包（免 `allowBuilds` 构建授权）。

## 使用

### 触发条件

一次注入需**同时**满足：

1. `enabled` 为 true（总开关）；
2. agent 持续思考超过 `minThinkSeconds`（默认 20 秒）——通过轮询 agents 注册表检测，对事件时序鲁棒；
3. 距上次注入超过 `cooldownMinutes`（默认 15 分钟）；
4. 最近 1 小时注入次数未超 `maxPerHour`（默认 4）。

不满足则静默，什么都不做。

### 对话建提醒

对话里说一句带时间 + 事项的话即可，例如：

- "提醒我 18:00 开会"
- "半小时后提醒我回邮件"

模型解析为 `text`（事项）+ `dueAt`（unix 毫秒，缺省 = 当前 + 1 小时）写入提醒。解析失败返回友好错误，不阻塞对话。到点后该提醒在下次注入时**优先于新闻**展示。

### 设置页

dsh 设置页自动渲染 `gap-feed` 命名空间表单，可改配置、管理提醒，改动即时生效、重启后保留。

## 配置项

| 配置项 | 类型 | 默认 | 说明 |
|--------|------|------|------|
| `enabled` | boolean | `true` | 总开关 |
| `minThinkSeconds` | number | `20` | 思考超过该秒数才考虑注入 |
| `cooldownMinutes` | number | `15` | 两次注入最小间隔（分钟），限频核心 |
| `maxPerHour` | number | `4` | 每小时注入上限（兜底） |
| `blacklist` | string[] | `[]` | 标题黑名单词，命中任一即过滤 |

默认值定义在 `src/types.ts` 的 `DEFAULT_CONFIG`。

## 提醒数据存储

```
$DSH_HOME/profiles/<profile>/data/gap-feed/reminders.json
```

- `DSH_HOME` 缺省为 `~/.dsh`；
- JSON 数组，字段 `id / text / dueAt / done / enabled / createdAt`；目录不存在自动建，读写失败或 JSON 损坏时静默降级为内存态，绝不抛错。

## 开发

```bash
npm install        # 装 devDeps
npm test           # vitest：67 条单测 + 契约测试
npm run typecheck  # tsc --noEmit
npm run build      # tsc -> dist/（prepack 自动执行）
```

分层纪律：纯函数层（`decision.ts` / `picker.ts`）零 dsh 依赖、全分支覆盖；副作用层（`news.ts` 网络 / `reminders.ts` 文件 I/O）经 `Source` 接口可 mock；接线层（`index.ts`）只做运行时接线。

## 已知限制

- **B站源**在数据中心 IP 可能被风控（`-352`），自动静默降级，不影响其他源；
- 提醒卡片与新闻卡片走同一对话流通道；提醒管理 UI 在设置页；
- 会话内去重为插件生命周期级（不跨重启）。

## License

MIT