zettel-brainstormer

它从您本地的 zettelkasten 笔记中读取，找到一个随机想法，并通过链接或标签查找参考，然后使用参考扩展该想法。

# Zettel Brainstormer 🧠

This skill formalizes the process of taking a rough idea or draft and enriching it with deep research, diverse perspectives, and structured brainstorming.

The configuration file is `config/models.json`, which can be edited manually or using the `setup.py` script.

## New 3-Stage Workflow

This skill now supports a 3-stage pipeline to balance cost and quality:

1) Find References (with `find_links.py`)

- Run `scripts/find_links.py` to identify relevant existing notes.
  - **Wikilinked documents** (follows [[wikilinks]] N levels deep, up to M total docs)
  - **Tag-similar documents** (finds notes with overlapping tags)
  - **Native Obsidian Integration**: Uses `obsidian-cli` for high-performance indexing and discovery if available.
  - **Semantic Discovery (Optional)**: Can leverage the `zettel-link` skill for finding "hidden" conceptual connections that don't share explicit tags or links.
- Output: A JSON list of absolute file paths to relevant notes.

2) Subagent: Preprocess contents (with `preprocess_model`)

- The agent iterates through the list of files found in Stage 1.
- For each file:
  - Read the file content.
  - Apply `templates/preprocess.md` using the `preprocess_model`, pass the seed note keypoints and file content as context.
  - Extract: Relevance score, Summary, Key Points, and Quotes.
  - Output: A structured markdown summary of the note.

3) Draft & Humanize (with `pro_model`)

- Gather all preprocessed markdown outputs from Stage 2.
- Apply `templates/draft.md` using the `pro_model`.
- Synthesize points, add proper Obsidian properties, tags, and links.
- Uses the `obsidian` skill if available to match style.

## Files & Scripts

This skill includes the following resources under the skill folder:

- `scripts/find_links.py`  -- finds relevant note paths (linked + tag similar)
- `scripts/draft_prompt.py` -- (Deprecated) generate prompt for agent
- `scripts/obsidian_utils.py` -- shared utilities for wikilink extraction
- `templates/preprocess.md` -- Instructions for subagent to extract info from single note
- `templates/draft.md` -- Instructions for final draft generation
- `config/models.example.json`  -- example configuration file

## Configuration & Setup

**First Run Setup**:
Before using this skill, you must run the setup script to configure models and directories.

```bash
python scripts/setup.py
```

This will create `config/models.json` with your preferences. You can press ENTER to accept defaults.

**Configuration Fields**:
- `pro_model`: The model used for drafting (defaults to agent's current model)
- `preprocess_model`: Cheap model for extraction (defaults to agent's current model)
- `zettel_dir`: Path to your Zettelkasten notes
- `output_dir`: Path where drafts should be saved
- `search_skill`: Which search skill to use for web/X research (web_search, brave_search, or none)
- `link_depth`: How many levels deep to follow [[wikilinks]] (N levels, default: 2)
- `max_links`: Maximum total linked notes to include (M links, default: 10)
- `discovery_mode`: Options are `standard` (default), `cli` (uses obsidian-cli), or `semantic` (uses zettel-link).

## Usage

- Trigger when user asks: "brainstorm X", "expand this draft", "research and add notes to <path>".
- Example workflow (pseudo):
  1. Pick a seed note.
  2. Find Links: `python scripts/find_links.py --input <seed_note> --output /tmp/paths.json`
  3. Preprocess Subagent Loop:
     - Load `/tmp/paths.json`.
     - For each path, read content.
     - Prompt `preprocess_model` with `templates/preprocess.md` + content.
     - Store result.
  4. Final Draft:
     - Concatenate seed note + all preprocess results.
     - Prompt `pro_model` with `templates/draft.md` + concatenated context.
  5. Save result to note.

## Notes for maintainers

- Keep preprocess outputs small (200-600 tokens) to save cost.
- Ensure all external links are included in the `References` section with full titles and URLs.
- When appending, always include a timestamp and short provenance line.

---

## 中文说明

# Zettel Brainstormer 🧠

本技能将“把一个粗略想法或草稿，通过深度研究、多元视角和结构化头脑风暴加以丰富”的过程规范化。

配置文件是 `config/models.json`，可手动编辑或使用 `setup.py` 脚本进行配置。

## 全新的 3 阶段工作流

本技能现在支持一条 3 阶段流水线，以平衡成本与质量：

1) 查找参考（使用 `find_links.py`）

- 运行 `scripts/find_links.py` 以识别相关的现有笔记。
  - **Wiki 链接文档**（沿 [[wikilinks]] 深入 N 层，最多 M 个文档）
  - **标签相似文档**（查找标签重叠的笔记）
  - **原生 Obsidian 集成**：如果可用，使用 `obsidian-cli` 进行高性能索引和发现。
  - **语义发现（可选）**：可借助 `zettel-link` 技能查找不共享显式标签或链接的“隐藏”概念关联。
- 输出：相关笔记的绝对文件路径的 JSON 列表。

2) 子智能体：预处理内容（使用 `preprocess_model`）

- 智能体遍历第 1 阶段找到的文件列表。
- 对每个文件：
  - 读取文件内容。
  - 使用 `preprocess_model` 应用 `templates/preprocess.md`，将种子笔记要点和文件内容作为上下文传入。
  - 提取：相关性评分、摘要、要点和引文。
  - 输出：该笔记的结构化 markdown 摘要。

3) 起草与人性化（使用 `pro_model`）

- 汇总第 2 阶段所有预处理过的 markdown 输出。
- 使用 `pro_model` 应用 `templates/draft.md`。
- 综合各要点，添加恰当的 Obsidian 属性、标签和链接。
- 如果可用，使用 `obsidian` 技能以匹配风格。

## 文件与脚本

本技能在技能文件夹下包含以下资源：

- `scripts/find_links.py`  -- 查找相关笔记路径（链接 + 标签相似）
- `scripts/draft_prompt.py` -- （已弃用）为智能体生成提示
- `scripts/obsidian_utils.py` -- 用于 wikilink 提取的共享工具
- `templates/preprocess.md` -- 供子智能体从单条笔记提取信息的指令
- `templates/draft.md` -- 最终草稿生成的指令
- `config/models.example.json`  -- 示例配置文件

## 配置与设置

**首次运行设置**：
在使用本技能前，你必须运行设置脚本以配置模型和目录。

```bash
python scripts/setup.py
```

这将创建带有你偏好设置的 `config/models.json`。你可以按 ENTER 接受默认值。

**配置字段**：
- `pro_model`：用于起草的模型（默认为智能体当前模型）
- `preprocess_model`：用于提取的廉价模型（默认为智能体当前模型）
- `zettel_dir`：你的 Zettelkasten 笔记路径
- `output_dir`：草稿应保存的路径
- `search_skill`：用于网络/X 研究的搜索技能（web_search、brave_search 或 none）
- `link_depth`：沿 [[wikilinks]] 深入跟踪的层数（N 层，默认：2）
- `max_links`：包含的链接笔记总数上限（M 条链接，默认：10）
- `discovery_mode`：可选项为 `standard`（默认）、`cli`（使用 obsidian-cli）或 `semantic`（使用 zettel-link）。

## 用法

- 当用户提出以下请求时触发：“brainstorm X”、“expand this draft”、“research and add notes to <path>”。
- 示例工作流（伪代码）：
  1. 选取一条种子笔记。
  2. 查找链接：`python scripts/find_links.py --input <seed_note> --output /tmp/paths.json`
  3. 预处理子智能体循环：
     - 加载 `/tmp/paths.json`。
     - 对每个路径，读取内容。
     - 用 `templates/preprocess.md` + 内容提示 `preprocess_model`。
     - 存储结果。
  4. 最终草稿：
     - 拼接种子笔记 + 所有预处理结果。
     - 用 `templates/draft.md` + 拼接后的上下文提示 `pro_model`。
  5. 将结果保存到笔记。

## 给维护者的说明

- 保持预处理输出小巧（200-600 tokens）以节省成本。
- 确保所有外部链接都包含在 `References` 部分，并附有完整标题和 URL。
- 追加内容时，始终包含时间戳和简短的出处行。