kb

name	kb
description	Knowledge base manager — compile raw content into the Obsidian wiki, manage ideas, and generate daily digests. Use when the user asks to compile, digest, search, or maintain the knowledge base. Also use proactively to append ideas during conversations.

/kb — Knowledge Base Manager

You manage the AutoWiki knowledge base — a pure-markdown Obsidian wiki at kb/.

Core principle: kb/ is just markdown files. You use Read/Write/Edit/Grep/Glob to manage it directly. No Python code writes to kb/.

kb/ Structure

kb/
├── _index.md              # Landing page (you maintain)
├── wiki/                  # Your domain — auto-compiled knowledge
│   ├── _index.md          # Grep-friendly lookup table (one row per item)
│   ├── items/
│   │   ├── papers/<topic>/<slug>.md
│   │   ├── articles/<topic>/<slug>.md
│   │   └── news/<topic>/<slug>.md
│   ├── topics/<topic>.md  # Cross-kind aggregation pages
│   └── sources/<source>.md
├── notes/                 # Human's domain
│   ├── ideas/
│   │   ├── _index.md      # Idea index (Open / Archived)
│   │   └── <slug>.md      # Expanded ideas
│   └── journal/           # Personal notes (optional)
└── daily/                 # Daily digests
    └── YYYY-MM-DD.md

Item Frontmatter Contract

Every file under wiki/items/ must have:

---
title: "Paper or article title"
date: YYYY-MM-DD
kind: paper | article | news
source: arxiv | hackernews | follow-builders | clipped
url: "https://..."
primary_topic: topic-slug        # determines physical directory
topics: ["[[topic1]]", "[[topic2]]"]
tags: [keyword1, keyword2]       # flat, for grep
raw: "[[raw/YYYY-MM-DD/filename]]"       # or raw/topic-dir/filename
---

File naming: Use short title slugs (3-5 keywords, lowercase, hyphenated). Example: self-preservation-bias-llm.md not arxiv-2604.02174.md.

One raw file → multiple kb items: When a raw file is a curated list (e.g., a survey with 50 papers), you may create multiple kb items from it. Each item links back to the same raw file.

raw/ Directory Types

raw/ supports three types of subdirectories:

raw/
├── 2026-04-04/         # Date-based: auto-fetched by /fetch
├── 2026-04-03/         # Date-based: auto-fetched by /fetch
├── safety_agent/       # Topic-based: manual research collections
├── Clippings/          # Web Clipper inbox
└── clipped/            # Web Clipper inbox (alternative)

Raw files may be messy — not all have frontmatter, some are partial, some are just link lists. You need to handle this gracefully: skip files that aren't useful, extract what you can from well-structured ones.

Compile State Tracking

After compiling a raw file into kb/, mark it in the raw file's frontmatter:

# Compiled successfully — item created in kb:
compiled: true
compiled_to: "[[self-preservation-bias-llm]]"

# Reviewed but deliberately skipped (not interesting enough, duplicate, etc.):
compiled: skipped

• Files with compiled: true → skip on next compile
• Files with compiled: skipped → skip on next compile
• Files without compiled field → candidate for compilation
• Files without frontmatter at all → read content, decide if it's worth creating frontmatter + compiling, or skip

Available Commands

/kb compile [path] — Compile raw content into the knowledge base

Usage:

• /kb compile — compile all uncompiled files across all raw/ subdirectories
• /kb compile raw/safety_agent — compile only from a specific directory
• /kb compile raw/2026-04-04 — compile only from a specific date

Steps:

1. Scan target directory: List all .md files in the target path. Skip files that already have compiled: true or compiled: skipped in frontmatter.

2. Read uncompiled files: Read each candidate file. For files without frontmatter, read the content and assess whether it contains useful knowledge.

3. Read context: Read user profile from profiles/ and interests from feeds.yaml.

4. Filter: Decide which items are worth saving based on user interests and content quality. For messy files (e.g., link lists, partial notes), extract the valuable parts rather than skipping entirely.

5. Create item files: For each selected item, directly write the markdown file:

   • Determine kind (paper/article/news), primary_topic, and slug
   • Write to kb/wiki/items/<kind>/<primary_topic>/<slug>.md
   • Use the frontmatter contract above
   • Body: concise summary in Chinese, key findings, ## Related section with [[wikilinks]]
   • For topic-based raw dirs (e.g., raw/safety_agent/), one raw file may produce MULTIPLE kb items if it contains a list of papers/resources

6. Mark raw files: After compilation, add to each processed raw file's frontmatter:

   • compiled: true + compiled_to: "[[slug]]" for files that produced kb items
   • compiled: skipped for files deliberately skipped
   • If a raw file has no frontmatter, add a minimal frontmatter block:

     ---
     compiled: true
     compiled_to: "[[slug1]], [[slug2]]"
     ---
     

7. Update topic files: For each topic with new items, read kb/wiki/topics/<topic>.md and append new item links. Create the topic file if it doesn't exist.

8. Update source files: Same pattern — read, append, create if needed.

9. Update indexes (all three levels):

   • Append rows to kb/wiki/_index.md table
   • Append items to kb/wiki/items/<kind>/_index.md under the right topic heading
   • Update stats in kb/_index.md

10. Report: Print a summary of what was compiled, what was skipped, and what's new in kb/.

/kb digest — Generate today's daily digest

Write kb/daily/YYYY-MM-DD.md with:

• 🔴 重点关注 (2-5 high-priority items)
• 📰 今日摘要 (all items grouped by category)
• 🔗 值得跟进的外链
• 💡 深度洞察
• 📎 引用源

Link to kb items using [[slug]] or [[slug|display text]].

Commit:

git add kb/
git commit -m "digest: YYYY-MM-DD daily feed"

/kb idea <content> — Quick-append an idea

1. Read kb/notes/ideas/_index.md
2. Append under ## Open:

   - YYYY-MM-DD — <content>
   

3. If the idea references a wiki item, add: 灵感: [[slug]]
4. Save the file (don't commit on every idea).

/kb comment <slug> <content> — Add commentary to an item

1. Find the item file: grep "<slug>" kb/wiki/_index.md to confirm it exists
2. Read the item file
3. If ## User Commentary section exists, append to it. If not, add the section before ## Related:

   ## User Commentary
   > YYYY-MM-DD: <content>
   

4. Save the file.

/kb report <topic> — Generate a deep research report

Traverse the knowledge base via wikilinks to build a comprehensive, insightful report on a topic. The report is written to kb/wiki/items/articles/<topic>/report-<topic>.md and also printed to terminal.

Steps:

1. Gather material: Read the topic page at kb/wiki/topics/<topic>.md. Follow every [[wikilink]] to read all related items. For each item, also follow its ## Related links to discover second-degree connections. Read raw files too (via raw: links) if more detail is needed.

2. Cross-topic discovery: Check other topic pages for items that also tag this topic. Search grep "<topic>" kb/wiki/_index.md to find anything the topic page might have missed.

3. Analyze and synthesize into this structure:

---
title: "Research Report: <Topic Display Name>"
date: YYYY-MM-DD
kind: article
primary_topic: <topic>
topics: ["[[<topic>]]"]
tags: [report, <topic>]
---

# <Topic Display Name> — 深度研究报告

## 1. 问题定义
这个领域在解决什么根本问题？为什么重要？

## 2. 领域地图
子方向有哪些？如何关联？（可以用列表或简图）

## 3. 主流做法
当前的技术路线、代表方法、关键工具

## 4. 里程碑工作
哪些论文/项目定义了这个领域？（带 [[wikilinks]]）

## 5. 最新进展
近期突破、趋势转向（带日期）

## 6. 开放问题与 Gap
什么没被解决？什么被忽略了？哪些假设可能有问题？
（这是报告最有价值的部分——需要真正的分析，不只是列清单）

## 7. 跨领域连接
与 kb 中其他 topic 的关联洞察（通过 wikilinks 发现）

## Sources
- [[item1]] — 贡献了什么
- [[item2]] — 贡献了什么

4. Write the report to kb/wiki/items/articles/<topic>/report-<topic>.md

5. Update indexes: Add the report to wiki/_index.md table and articles/_index.md

6. Ask the user: "报告已生成。要不要我把发现的 idea 记录到 notes/ideas/？"

/kb summary — Archive conversation and refine knowledge

After a discussion about kb/ content, this command does three things with user confirmation:

1. Ask: 归档 idea？ — Review the conversation for ideas, insights, and questions. Present them as a list and ask: "以下 idea 是否归档到 notes/ideas/？"

   • If yes → append each to kb/notes/ideas/_index.md
   • If an idea deserves expansion → create notes/ideas/<slug>.md

2. Ask: 归档到 raw？ — "是否将本次讨论完整归档到 raw/？"

   • If yes → write raw/YYYY-MM-DD/discussion-<topic>.md with full discussion notes
   • Use the /summary skill format (frontmatter + structured body)

3. Ask: 提炼到 kb？ — "是否将核心内容提炼到 kb/wiki/？"

   • If yes → for each substantive insight:
     • If it's commentary on an existing item → append ## User Commentary
     • If it's new knowledge → create or update a wiki item
     • If it updates understanding of a topic → edit the topic page
   • Update indexes after any changes

Always ask before each step — the user controls what gets saved where. Print a preview of what would be written before confirming.

/kb search <query> — Search the knowledge base

1. First try: grep "<query>" kb/wiki/_index.md (fast, searches the lookup table)
2. If needed: grep -r "<query>" kb/wiki/items/ (deep search in body text)
3. Present results with wikilinks to matching items and topics

/kb lint — Health check and auto-fix

Check phase — scan for issues:

1. Orphaned items: items not listed in any topic page
2. Stale topics: topics with no items in last 30 days
3. Index drift: wiki/_index.md table vs actual files on disk
4. Broken wikilinks: [[slug]] pointing to nonexistent files
5. Stale ideas: open ideas older than 30 days in notes/ideas/_index.md
6. Topic count mismatch: item_count in frontmatter doesn't match actual links

Report — print a summary table:

✅ Passed: index table matches disk (19/19)
✅ Passed: wikilinks valid (18/18)
⚠️  Orphan: report-agentic-safety not in any topic page
⚠️  Missing cross-link: ai-safety ↔ agentic-safety

Fix phase — after reporting, ask user "是否自动修复？" then:

Issue	Auto-fix
Orphaned item	Add to its primary_topic topic page
Index drift — item on disk but not in table	Append row to wiki/_index.md
Index drift — row in table but file missing	Remove the row
Broken wikilink	Report which file contains it; suggest removal or correction
Topic count mismatch	Update item_count in frontmatter
Missing cross-topic link	Add [[topic]] to Related Topics section

Commit fixes:

git add kb/
git commit -m "kb lint: auto-fix N issues"

Real-Time Write-Back During Conversations

When chatting with the user, watch for these signals and act immediately:

Signal	Action
User expresses a new idea	Append to kb/notes/ideas/_index.md
User comments on a wiki item	Append ## User Commentary to the item
User discovers cross-item connections	Update ## Related sections
User says "记一下" / "这个很重要"	Append to ideas immediately

Important Notes

• YOU manage wiki/ directly with Write/Edit. No Python intermediary.
• notes/ is the human's domain. Only append to notes/ideas/_index.md.
• All _index.md files are your responsibility to keep current.
• Use Chinese for summaries. Keep technical terms and titles in English.
• Use [[slug]] for wikilinks, [[slug|Display Text]] for human-readable labels.
• Replace YYYY-MM-DD with today's actual date.