deep-current

具有 CLI 的持久研究线程管理器，用于跟踪主题、注释、来源和发现。与每晚的 cron 作业配合，随着时间的推移构建个人研究摘要。附带的代码是用于线程管理的本地 Python CLI - 由代理使用其标准 web_search 和 web_fetch 工具执行研究。

# Deep Current

A research thread manager for agents. Track topics you care about, accumulate notes and sources over time, and pair with a scheduled cron job to produce regular research digests.

## Architecture

This skill ships **one component**: a Python CLI (`scripts/deep-current.py`) that manages research threads as local JSON data. It handles:
- Creating, listing, and updating research threads
- Storing notes, sources, and findings per thread
- Thread lifecycle (active/paused/resolved) and decay

**What this skill does NOT ship:** web search, link following, or report generation. Those capabilities come from the agent's built-in tools (`web_search`, `web_fetch`). The cron job prompt instructs the agent to use those tools to research threads, then write findings to a report file.

In short: the CLI manages *what* to research. The agent's existing tools do the *how*.

## How It Works

1. **Threads** — Long-running research topics stored in `deep-current/currents.json`
2. **Nightly job** — A cron job tells the agent which threads to research (agent uses its own `web_search`/`web_fetch` tools)
3. **Reports** — Each night's findings are written to `deep-current-reports/YYYY-MM-DD.md` (one file per run)
4. **Thread CLI** — Manage threads between sessions (add, note, source, finding, status)

## Setup

### 1. Create data directory

```bash
mkdir -p deep-current
```

### 2. Initialize currents.json

```json
{
  "threads": []
}
```

### 3. Schedule the cron job

Create an isolated cron job that runs nightly. The agent will use its own `web_search` and `web_fetch` tools to research each thread, then use the CLI to record findings. Example prompt:

```
You are running a Deep Current research session.

1. Run `python3 scripts/deep-current.py list` to see all active threads.
2. Run `python3 scripts/deep-current.py covered` to see topics and URLs already covered in recent reports. AVOID repeating these.
3. Pick TWO threads based on current relevance — check recent context to decide.
4. For each thread, use web_search and web_fetch to research the topic. Follow interesting links and cross-reference claims. Find NEW angles, developments, or sources not already covered.
5. Update each thread with notes/sources/findings using the deep-current.py CLI.

## Output Format
Create a new file in deep-current-reports/ named YYYY-MM-DD.md:

# Deep Current — [tonight's date]
## [catchy title for thread 1]
[findings with inline source links]
## [catchy title for thread 2]
[findings with inline source links]

Keep it dense and interesting. No fluff. Link to sources. Flag anything actionable.
```

Recommended: run at 1-3am, use a capable model, 30min timeout.

## Thread CLI

Manage research threads with `scripts/deep-current.py`:

| Command | Purpose |
|---------|---------|
| `list` | Show all threads with status |
| `show <id>` | Full thread details |
| `add <title>` | Create new thread |
| `note <id> <text>` | Add dated research note |
| `source <id> <url> [desc]` | Add source/reference |
| `finding <id> <text>` | Record key finding |
| `status <id> <active\|paused\|resolved>` | Change thread status |
| `digest` | Summary of all active threads |
| `decay` | Prune stale threads (>90 days inactive + no recent notes) |
| `covered [days]` | Show topics & URLs from recent reports (default 14 days) to avoid duplication |

Thread IDs are auto-generated slugs from the title. Prefix matching works for short IDs.

## Report Format

Each run creates a standalone file in `deep-current-reports/YYYY-MM-DD.md`. Each report contains:
- Date header
- 2+ research threads with catchy titles
- Dense findings with inline source links
- Actionable flags for anything the user should act on

One file per run — easy to browse, search, or archive.

## Research Quality Guidelines

When running a research session (nightly or manual), the agent should:
- Use `web_search` to find sources, `web_fetch` to read them
- Cross-reference claims across multiple sources
- Cite sources inline with markdown links
- Flag actionable items explicitly
- Write for a smart reader — dense, no filler
- Use catchy thread titles (this is morning reading, make it engaging)
- Distinguish speculation from sourced facts

---

## 中文说明

# Deep Current

面向代理的研究线程管理器。跟踪你关心的主题，随时间积累笔记与来源，并搭配定时 cron 作业生成定期的研究摘要。

## Architecture

本技能仅附带 **一个组件**：一个 Python CLI（`scripts/deep-current.py`），将研究线程作为本地 JSON 数据进行管理。它负责：
- 创建、列出和更新研究线程
- 按线程存储笔记、来源和发现
- 线程生命周期（active/paused/resolved）与衰减

**本技能不附带的内容：** 网络搜索、链接追踪或报告生成。这些能力来自代理的内置工具（`web_search`、`web_fetch`）。cron 作业的提示词会指示代理使用这些工具研究线程，然后将发现写入报告文件。

简而言之：CLI 管理 *研究什么*，代理已有的工具负责 *怎么研究*。

## How It Works

1. **Threads** —— 长期运行的研究主题，存储在 `deep-current/currents.json` 中
2. **Nightly job** —— 一个 cron 作业告诉代理要研究哪些线程（代理使用自己的 `web_search`/`web_fetch` 工具）
3. **Reports** —— 每晚的发现写入 `deep-current-reports/YYYY-MM-DD.md`（每次运行一个文件）
4. **Thread CLI** —— 在会话之间管理线程（add、note、source、finding、status）

## Setup

### 1. Create data directory

```bash
mkdir -p deep-current
```

### 2. Initialize currents.json

```json
{
  "threads": []
}
```

### 3. Schedule the cron job

创建一个每晚运行的隔离 cron 作业。代理将使用自己的 `web_search` 和 `web_fetch` 工具研究每个线程，然后使用 CLI 记录发现。示例提示词：

```
You are running a Deep Current research session.

1. Run `python3 scripts/deep-current.py list` to see all active threads.
2. Run `python3 scripts/deep-current.py covered` to see topics and URLs already covered in recent reports. AVOID repeating these.
3. Pick TWO threads based on current relevance — check recent context to decide.
4. For each thread, use web_search and web_fetch to research the topic. Follow interesting links and cross-reference claims. Find NEW angles, developments, or sources not already covered.
5. Update each thread with notes/sources/findings using the deep-current.py CLI.

## Output Format
Create a new file in deep-current-reports/ named YYYY-MM-DD.md:

# Deep Current — [tonight's date]
## [catchy title for thread 1]
[findings with inline source links]
## [catchy title for thread 2]
[findings with inline source links]

Keep it dense and interesting. No fluff. Link to sources. Flag anything actionable.
```

建议：在凌晨 1-3 点运行，使用能力较强的模型，30 分钟超时。

## Thread CLI

使用 `scripts/deep-current.py` 管理研究线程：

| Command | Purpose |
|---------|---------|
| `list` | 显示所有线程及其状态 |
| `show <id>` | 完整的线程详情 |
| `add <title>` | 创建新线程 |
| `note <id> <text>` | 添加带日期的研究笔记 |
| `source <id> <url> [desc]` | 添加来源/参考 |
| `finding <id> <text>` | 记录关键发现 |
| `status <id> <active\|paused\|resolved>` | 更改线程状态 |
| `digest` | 所有活跃线程的摘要 |
| `decay` | 清理过时线程（>90 天无活动且近期无笔记） |
| `covered [days]` | 显示近期报告中的主题与 URL（默认 14 天）以避免重复 |

线程 ID 是根据标题自动生成的 slug。短 ID 支持前缀匹配。

## Report Format

每次运行都会在 `deep-current-reports/YYYY-MM-DD.md` 中创建一个独立文件。每份报告包含：
- 日期标题
- 2 个以上带吸引力标题的研究线程
- 含内联来源链接的密集发现
- 对用户应采取行动的事项的可执行标记

每次运行一个文件 —— 便于浏览、搜索或归档。

## Research Quality Guidelines

在运行研究会话（每晚或手动）时，代理应：
- 使用 `web_search` 查找来源，用 `web_fetch` 阅读它们
- 跨多个来源交叉验证论断
- 用 markdown 链接内联标注来源
- 明确标记可执行事项
- 为聪明的读者而写 —— 内容密集、无废话
- 使用有吸引力的线程标题（这是早间读物，让它引人入胜）
- 区分推测与有来源支撑的事实