kb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

kb CLI and Knowledge Base Pattern

Build and maintain a self-compiling Obsidian markdown knowledge base using the

kb

CLI. The LLM reads raw sources, writes cross-linked wiki articles, files Q&A results back into the corpus, and runs lint-and-heal passes. The CLI also supports codebase ingestion with deep inspection commands for code quality, architecture health, and symbol relationships.

Each topic lives in its own top-level folder (e.g.

ai-harness/

) with

raw/

wiki/

outputs/

bases/

subtrees plus a topic-level

log.md

and

CLAUDE.md

. All topics share a single Obsidian vault at the repo root. Read

references/architecture.md

for the full rationale and the four-phase pipeline (ingest → compile → query → lint).

The topic's CLAUDE.md
(symlinked to

AGENTS.md

) is the schema document — it tells the LLM the scope, conventions, current articles, and research gaps for that topic. Co-evolve it as the topic matures.

使用

kb

CLI构建并维护一个可自动编译的Obsidian Markdown知识库。LLM读取原始来源，编写带交叉链接的维基文章，将问答结果存入语料库，并运行检查与修复流程。该CLI还支持代码库导入，通过深度检查命令分析代码质量、架构健康状况和符号关系。

每个主题都位于独立的顶级文件夹中（例如

ai-harness/

），包含

raw/

、

wiki/

、

outputs/

、

bases/

子目录，以及主题级别的

log.md

和

CLAUDE.md

。所有主题共享仓库根目录下的一个Obsidian库。阅读

references/architecture.md

了解完整设计思路以及四阶段流水线（导入 → 编译 → 查询 → 检查）。

主题的**

CLAUDE.md

（符号链接至
AGENTS.md
）是模式文档**——它告知LLM该主题的范围、约定、现有文章以及研究空白。随着主题发展，需同步更新该文档。

Prerequisites

前置条件

Verify the
```
kb
```
binary is available:
bash
```
kb version
```
For search and index commands, verify QMD is installed:
bash
```
qmd --version
# If missing: npm install -g @tobilu/qmd
```
Supported source languages for codebase analysis: TypeScript (
```
.ts
```
), TSX (
```
.tsx
```
), JavaScript (
```
.js
```
), JSX (
```
.jsx
```
), Go (
```
.go
```
).

验证
```
kb
```
二进制文件可用：
bash
```
kb version
```

对于搜索和索引命令，验证QMD已安装：

bash

qmd --version
# 若未安装：npm install -g @tobilu/qmd

代码库分析支持的源语言：TypeScript（
```
.ts
```
）、TSX（
```
.tsx
```
）、JavaScript（
```
.js
```
）、JSX（
```
.jsx
```
）、Go（
```
.go
```
）。

Pattern Overview

模式概述

Based on Andrej Karpathy's LLM Wiki pattern, the KB treats the LLM as a compiler that reads raw source documents and produces a structured, cross-linked markdown wiki. The four-phase loop:

Ingest — Scrape/curate sources via
```
kb
```
CLI →
```
raw/
```
(immutable staging)
Compile — LLM reads
```
raw/
```
, writes
```
wiki/concepts/
```
articles (3000-4000 words, dense wikilinks)
Query — Q&A against wiki → file answers to
```
outputs/queries/
```
, promote strong answers to wiki
Lint — Automated structural checks + LLM-driven semantic healing

Read

references/architecture.md

for the full rationale, context-window vs RAG tradeoffs, and multi-topic vault design.

基于Andrej Karpathy的LLM维基模式，该知识库将LLM视为编译器，读取原始源文档并生成结构化、带交叉链接的Markdown维基。四阶段循环：

导入 — 通过
```
kb
```
CLI抓取/整理来源 → 存入
```
raw/
```
（不可变暂存区）
编译 — LLM读取
```
raw/
```
内容，编写
```
wiki/concepts/
```
下的文章（3000-4000字，包含密集的维基链接）
查询 — 针对维基进行问答 → 将答案存入
```
outputs/queries/
```
，将优质答案升级为维基文章
检查 — 自动化结构检查 + LLM驱动的语义修复

阅读

references/architecture.md

了解完整设计思路、上下文窗口与RAG的权衡，以及多主题库设计。

Related Skills

kb CLI Quick Reference

kb CLI快速参考

Topic management

主题管理

bash

kb topic new <slug> <title> <domain>     # scaffold a new topic
kb topic list                             # list all topics in the vault
kb topic info <slug>                      # topic metadata (counts, last log entry)

bash

kb topic new <slug> <title> <domain>     # 搭建新主题
kb topic list                             # 列出库中所有主题
kb topic info <slug>                      # 主题元数据（统计数、最新日志条目）

Ingestion (auto-generates frontmatter, auto-appends to log.md)

导入（自动生成前置元数据，自动追加至log.md）

bash

kb ingest url <url> --topic <slug>        # scrape a web URL via Firecrawl
kb ingest file <path> --topic <slug>      # convert local file (PDF, DOCX, EPUB, HTML, images w/OCR, etc.)
kb ingest youtube <url> --topic <slug>    # extract YouTube transcript
kb ingest bookmarks <path> --topic <slug> # ingest a bookmark-cluster markdown file
kb ingest codebase <path> --topic <slug>  # analyze a codebase into raw/codebase/

bash

kb ingest url <url> --topic <slug>        # 通过Firecrawl抓取网页URL
kb ingest file <path> --topic <slug>      # 转换本地文件（PDF、DOCX、EPUB、HTML、带OCR的图片等）
kb ingest youtube <url> --topic <slug>    # 提取YouTube字幕
kb ingest bookmarks <path> --topic <slug> # 导入书签集群Markdown文件
kb ingest codebase <path> --topic <slug>  # 分析代码库并存入raw/codebase/

Codebase inspection

代码库检查

bash

kb inspect smells [--type <smell-type>] --format json
kb inspect dead-code --format json
kb inspect complexity [--top N] --format json
kb inspect blast-radius [--min N] [--top N] --format json
kb inspect coupling [--unstable] --format json
kb inspect circular-deps --format json
kb inspect symbol <name> --format json
kb inspect file <path> --format json
kb inspect backlinks <name-or-path> --format json
kb inspect deps <name-or-path> --format json

bash

kb inspect smells [--type <smell-type>] --format json
kb inspect dead-code --format json
kb inspect complexity [--top N] --format json
kb inspect blast-radius [--min N] [--top N] --format json
kb inspect coupling [--unstable] --format json
kb inspect circular-deps --format json
kb inspect symbol <name> --format json
kb inspect file <path> --format json
kb inspect backlinks <name-or-path> --format json
kb inspect deps <name-or-path> --format json

Structural linting

结构检查

bash

kb lint [<slug>] [--save]                 # dead links, orphans, missing sources, format violations, stale content

bash

kb lint [<slug>] [--save]                 # 检查无效链接、孤立文章、缺失来源、格式违规、过时内容

Indexing and search (requires QMD)

索引与搜索（需QMD）

bash

kb index --topic <slug>                   # create or update QMD collection
kb search "<query>" --topic <slug>        # hybrid BM25 + vector search
kb search "<query>" --lex --topic <slug>  # keyword-only search
kb search "<query>" --vec --topic <slug>  # vector-only search

After running

kb ingest

kb lint --save

, the CLI auto-appends entries to

<topic>/log.md

. Manual log entries are still needed for compile, query, promote, and split operations (Procedure 5).

bash

kb index --topic <slug>                   # 创建或更新QMD集合
kb search "<query>" --topic <slug>        # 混合BM25 + 向量搜索
kb search "<query>" --lex --topic <slug>  # 仅关键词搜索
kb search "<query>" --vec --topic <slug>  # 仅向量搜索

运行

kb ingest

或

kb lint --save

后，CLI会自动将条目追加至

<topic>/log.md

。编译、查询、升级和拆分操作仍需手动添加日志条目（见流程5）。

Command Dispatch

命令匹配

Map the user's intent to the correct command:

Intent	Command
Scaffold a new topic	`kb topic new <slug> <title> <domain>`
List all topics	`kb topic list`
Scrape a web URL	`kb ingest url <url> --topic <slug>`
Ingest a local file (PDF, DOCX, etc.)	`kb ingest file <path> --topic <slug>`
Extract a YouTube transcript	`kb ingest youtube <url> --topic <slug>`
Ingest bookmark clusters	`kb ingest bookmarks <path> --topic <slug>`
Analyze a codebase	`kb ingest codebase <path> --topic <slug> --progress never`
Find code smells	`kb inspect smells --format json`
Find dead exports and orphan files	`kb inspect dead-code --format json`
Rank functions by complexity	`kb inspect complexity --format json`
Find high-impact symbols (blast radius)	`kb inspect blast-radius --min 5 --format json`
Find unstable files (coupling)	`kb inspect coupling --unstable --format json`
Find circular imports	`kb inspect circular-deps --format json`
Look up a specific symbol	`kb inspect symbol <name> --format json`
Look up a specific file	`kb inspect file <path> --format json`
Find what depends on X (incoming refs)	`kb inspect backlinks <name-or-path> --format json`
Find what X depends on (outgoing deps)	`kb inspect deps <name-or-path> --format json`
Run structural lint	`kb lint <slug> --save`
Index vault for search	`kb index --topic <slug>`
Search the knowledge base	`kb search "<query>" --topic <slug> --format json`

将用户意图映射到正确命令：

意图	命令
搭建新主题	`kb topic new <slug> <title> <domain>`
列出所有主题	`kb topic list`
抓取网页URL	`kb ingest url <url> --topic <slug>`
导入本地文件（PDF、DOCX等）	`kb ingest file <path> --topic <slug>`
提取YouTube字幕	`kb ingest youtube <url> --topic <slug>`
导入书签集群	`kb ingest bookmarks <path> --topic <slug>`
分析代码库	`kb ingest codebase <path> --topic <slug> --progress never`
查找代码异味	`kb inspect smells --format json`
查找死导出和孤立文件	`kb inspect dead-code --format json`
按复杂度排序函数	`kb inspect complexity --format json`
查找高影响符号（影响范围）	`kb inspect blast-radius --min 5 --format json`
查找不稳定文件（耦合度）	`kb inspect coupling --unstable --format json`
查找循环导入	`kb inspect circular-deps --format json`
查找特定符号	`kb inspect symbol <name> --format json`
查找特定文件	`kb inspect file <path> --format json`
查找依赖X的内容（传入引用）	`kb inspect backlinks <name-or-path> --format json`
查找X依赖的内容（传出依赖）	`kb inspect deps <name-or-path> --format json`
运行结构检查	`kb lint <slug> --save`
为搜索创建库索引	`kb index --topic <slug>`
搜索知识库	`kb search "<query>" --topic <slug> --format json`

Codebase Analysis Workflow

代码库分析工作流

For codebase-specific analysis, the

kb ingest codebase

command must run before any inspect command.

Workflow A -- Code Analysis (no QMD required):

kb ingest codebase <path> --topic <slug> --> kb inspect <subcommand>

Workflow B -- Full Pipeline (requires QMD):

kb ingest codebase <path> --topic <slug> --> kb index --> kb search <query>

On first run,

kb ingest codebase

bootstraps the topic under

<path>/.kb/vault/<topic-slug>/

by default. Later commands auto-discover this vault only when they run from inside that repository tree; otherwise pass

--vault <path>

针对代码库的特定分析，必须先运行

kb ingest codebase

命令，才能执行任何inspect命令。

工作流A -- 代码分析（无需QMD）：

kb ingest codebase <path> --topic <slug> --> kb inspect <subcommand>

工作流B -- 完整流水线（需QMD）：

kb ingest codebase <path> --topic <slug> --> kb index --> kb search <query>

首次运行时，

kb ingest codebase

默认在

<path>/.kb/vault/<topic-slug>/

下初始化主题。后续命令仅在该仓库目录内运行时自动识别此库；否则需传递

--vault <path>

参数。

Ingest a Codebase

导入代码库

bash

kb ingest codebase <path> --topic <slug> --progress never

Always use

--progress never

in agent contexts to prevent TTY progress bars from corrupting stdout. Use

--title

and

--domain

only when bootstrapping a missing topic.

Parse the JSON output from stdout to extract key values:

```
topicSlug
```
-- the topic identifier for later commands
```
vaultPath
```
-- absolute path to the vault root
```
topicPath
```
-- absolute path to the topic directory
```
filesScanned
```
,
```
filesParsed
```
,
```
symbolsExtracted
```
-- summary statistics
```
diagnostics
```
-- check for warnings or errors

Stderr carries structured stage logs. Do not treat stderr content as failure evidence.

Key flags:

```
--vault <dir>
```
-- override vault root location
```
--output <dir>
```
-- deprecated alias for
```
--vault
```
```
--topic <slug>
```
-- target topic slug inside the vault
```
--title <value>
```
-- bootstrap-only topic title override
```
--domain <value>
```
-- bootstrap-only topic domain override
```
--include <pattern>
```
-- re-include paths that would otherwise be ignored (repeatable)
```
--exclude <pattern>
```
-- exclude additional paths from scanning (repeatable)
```
--semantic
```
-- enable semantic analysis when adapters support it

Read

references/cli-ingest-codebase.md

for the full flag table and output schema.

bash

kb ingest codebase <path> --topic <slug> --progress never

在Agent环境中始终使用

--progress never

，防止TTY进度条破坏标准输出。仅在初始化缺失主题时使用

--title

和

--domain

参数。

解析标准输出中的JSON以提取关键值：

```
topicSlug
```
-- 后续命令使用的主题标识符
```
vaultPath
```
-- 库根目录的绝对路径
```
topicPath
```
-- 主题目录的绝对路径
```
filesScanned
```
,
```
filesParsed
```
,
```
symbolsExtracted
```
-- 统计摘要
```
diagnostics
```
-- 检查警告或错误

标准错误输出包含结构化阶段日志，请勿将标准错误内容视为失败证据。

关键参数：

```
--vault <dir>
```
-- 覆盖库根目录位置
```
--output <dir>
```
--
```
--vault
```
的已弃用别名
```
--topic <slug>
```
-- 库内的目标主题标识
```
--title <value>
```
-- 仅初始化时覆盖主题标题
```
--domain <value>
```
-- 仅初始化时覆盖主题领域
```
--include <pattern>
```
-- 重新包含原本会被忽略的路径（可重复使用）
```
--exclude <pattern>
```
-- 额外排除扫描路径（可重复使用）
```
--semantic
```
-- 当适配器支持时启用语义分析

阅读

references/cli-ingest-codebase.md

获取完整参数表和输出模式。

Inspect the Vault

检查库内容

Run inspect subcommands to analyze code quality and architecture.

Shared flags for all inspect subcommands:

```
--format json
```
-- always use JSON for programmatic parsing
```
--vault <path>
```
-- explicit vault root (omit to auto-discover from cwd)
```
--topic <slug>
```
-- explicit topic slug (omit if only one topic exists)

运行inspect子命令分析代码质量和架构。

所有inspect子命令的共享参数：

```
--format json
```
-- 用于程序解析时始终使用JSON格式
```
--vault <path>
```
-- 显式指定库根目录（省略则从当前工作目录自动识别）
```
--topic <slug>
```
-- 显式指定主题标识（若仅存在一个主题可省略）

Tabular Subcommands

表格类子命令

These return a list of rows sorted by the primary metric:

smells -- List symbols and files with detected code smells.

kb inspect smells --format json
kb inspect smells --type high-complexity --format json

dead-code -- List dead exports and orphan files.
```
kb inspect dead-code --format json
```

complexity -- Rank functions/methods by cyclomatic complexity. Default top 20.

kb inspect complexity --format json
kb inspect complexity --top 50 --format json

blast-radius -- Rank symbols by transitive dependent count.

kb inspect blast-radius --format json
kb inspect blast-radius --min 10 --top 20 --format json

coupling -- Rank files by instability (Ce / (Ca + Ce)).

kb inspect coupling --format json
kb inspect coupling --unstable --format json

circular-deps -- List files participating in circular import chains.
```
kb inspect circular-deps --format json
```

这些命令返回按主指标排序的行列表：

smells -- 列出检测到代码异味的符号和文件。

kb inspect smells --format json
kb inspect smells --type high-complexity --format json

dead-code -- 列出死导出和孤立文件。
```
kb inspect dead-code --format json
```

complexity -- 按圈复杂度对函数/方法排序。默认显示前20个。

kb inspect complexity --format json
kb inspect complexity --top 50 --format json

blast-radius -- 按传递依赖数量对符号排序。

kb inspect blast-radius --format json
kb inspect blast-radius --min 10 --top 20 --format json

coupling -- 按不稳定性（Ce / (Ca + Ce)）对文件排序。

kb inspect coupling --format json
kb inspect coupling --unstable --format json

circular-deps -- 列出参与循环导入链的文件。
```
kb inspect circular-deps --format json
```

Detail Lookup Subcommands

详情查询子命令

These return field-value pairs for a single matched entity:

symbol <name> -- Case-insensitive substring match. Returns detail fields for a single match, or a summary table for multiple matches.
```
kb inspect symbol parseConfig --format json
```
file <path> -- Exact source path lookup. Use the source-relative path as stored in vault frontmatter.
```
kb inspect file src/config.ts --format json
```

这些命令返回单个匹配实体的键值对：

symbol <name> -- 不区分大小写的子字符串匹配。返回单个匹配的详细字段，或多个匹配的摘要表。
```
kb inspect symbol parseConfig --format json
```
file <path> -- 精确源路径查询。使用库前置元数据中存储的源相对路径。
```
kb inspect file src/config.ts --format json
```

Relation Subcommands

关系类子命令

These return relation edges (

target_path

type

confidence

backlinks <name-or-path> -- Incoming references. Accepts a symbol name or file path.
```
kb inspect backlinks parseConfig --format json
```
deps <name-or-path> -- Outgoing dependencies. Accepts a symbol name or file path.
```
kb inspect deps src/config.ts --format json
```

Read

references/cli-inspect.md

for all column schemas and flag details.

这些命令返回关系边（

target_path

type

confidence

）：

backlinks <name-or-path> -- 传入引用。接受符号名称或文件路径。
```
kb inspect backlinks parseConfig --format json
```
deps <name-or-path> -- 传出依赖。接受符号名称或文件路径。
```
kb inspect deps src/config.ts --format json
```

阅读

references/cli-inspect.md

获取所有列模式和参数详情。

Index the Vault

为库创建索引

Index the vault content into QMD for search. This step requires QMD on PATH.

bash

kb index --topic <slug>

The command is idempotent: it checks whether the collection already exists and chooses

add

(create) or

update

(refresh) automatically.

Key flags:

```
--embed
```
(default true) -- run embedding after syncing files
```
--force-embed
```
-- force re-embedding all documents
```
--context <text>
```
-- attach human context to improve search relevance
```
--name <name>
```
-- override the derived collection name

Read

references/cli-search-index.md

for the full output schema.

将库内容索引到QMD以支持搜索。此步骤要求QMD在PATH中。

bash

kb index --topic <slug>

该命令具有幂等性：它会检查集合是否已存在，自动选择创建（add）或更新（refresh）。

关键参数：

```
--embed
```
（默认true）-- 同步文件后运行嵌入
```
--force-embed
```
-- 强制重新嵌入所有文档
```
--context <text>
```
-- 添加人工上下文以提高搜索相关性
```
--name <name>
```
-- 覆盖自动生成的集合名称

阅读

references/cli-search-index.md

获取完整输出模式。

Search the Vault

搜索库内容

Search indexed vault content with QMD. Requires a prior

kb index

run.

bash

kb search "<query>" --topic <slug> --format json

Search modes:

Hybrid (default) -- combines lexical and vector search
Lexical (
```
--lex
```
) -- BM25 keyword search only
Vector (
```
--vec
```
) -- embedding-based semantic search

The

--lex

and

--vec

flags are mutually exclusive. Omit both for hybrid mode.

Key flags:

```
--limit N
```
(default 10) -- maximum results
```
--min-score N
```
-- minimum relevance threshold
```
--full
```
-- return full document content instead of snippets
```
--all
```
-- return all matches above the minimum score

Read

references/cli-search-index.md

for full details.

使用QMD搜索已索引的库内容。需先运行

kb index

命令。

bash

kb search "<query>" --topic <slug> --format json

搜索模式：

混合模式（默认）-- 结合词法和向量搜索
词法模式（
```
--lex
```
）-- 仅BM25关键词搜索
向量模式（
```
--vec
```
）-- 基于嵌入的语义搜索

--lex

和

--vec

参数互斥。同时省略则使用混合模式。

关键参数：

```
--limit N
```
（默认10）-- 最大结果数
```
--min-score N
```
-- 最低相关性阈值
```
--full
```
-- 返回完整文档内容而非片段
```
--all
```
-- 返回所有高于最低分数的匹配结果

阅读

references/cli-search-index.md

获取完整详情。

KB Maintenance Procedures

知识库维护流程

Procedure 1: Compile a wiki article

流程1：编译维基文章

Read
```
references/compilation-guide.md
```
to anchor on length, style, wikilink density, and sourcing rules.

Identify candidate sources via

kb search "<topic phrase>" --topic <slug>

or read

<topic>/wiki/index/Source Index.md

Load the candidate raw sources fully into context.
Load
```
<topic>/wiki/index/Concept Index.md
```
for orientation on existing articles and wikilink targets (including in other topics).
Surface takeaways BEFORE drafting. Present to the user: 3-5 key takeaways from the sources, the entities/concepts this article will introduce or update, and anything that contradicts existing wiki articles. Ask: "Anything specific to emphasize or de-emphasize?" Wait for the response. Skip this step only if the user has explicitly asked for autonomous compilation.
Write the article to
```
<topic>/wiki/concepts/<Article Title>.md
```
following the obsidian-markdown skill for wikilink, callout, and frontmatter syntax. Use the frontmatter schema from
```
references/frontmatter-schemas.md
```
. Target 3000-4000 words with a Sources section, wikilinks to related articles, and code or diagram blocks where applicable.
Backlink audit -- do not skip. Grep every existing article in
```
<topic>/wiki/concepts/
```
for mentions of the new article's title, aliases, or core entities. For each match, add a
```
[[New Article]]
```
wikilink at the first mention (and one later occurrence). This is the step most commonly skipped -- a compounding wiki depends on bidirectional links.
bash
```
grep -rln "<new article title or key term>" <topic>/wiki/concepts/
```
Update the topic's indexes (Procedure 2).
Update
```
<topic>/CLAUDE.md
```
current-articles list.
Re-index the topic's collection:
```
kb index --topic <slug>
```
.

Append an entry to

<topic>/log.md

(Procedure 5) -- e.g.,

## [YYYY-MM-DD] compile | <Article Title> (<word_count> words, <N> sources)

When updating an existing article (rather than writing new), use the

Current / Proposed / Reason / Source

diff format and contradiction-sweep workflow described in

references/compilation-guide.md

阅读
```
references/compilation-guide.md
```
，明确文章长度、风格、维基链接密度和来源规则。

通过

kb search "<主题短语>" --topic <slug>

或阅读

<topic>/wiki/index/Source Index.md

确定候选来源。

将候选原始来源完全加载到上下文中。
加载
```
<topic>/wiki/index/Concept Index.md
```
，了解现有文章和维基链接目标（包括其他主题中的内容）。
在起草前先提炼要点。向用户展示：从来源中提取的3-5个关键要点、本文将介绍或更新的实体/概念，以及与现有维基文章矛盾的内容。询问：*“有什么需要特别强调或弱化的内容吗？”*等待用户回复。仅当用户明确要求自主编译时才可跳过此步骤。
按照obsidian-markdown技能的维基链接、提示框和前置元数据语法，将文章写入
```
<topic>/wiki/concepts/<Article Title>.md
```
。使用
```
references/frontmatter-schemas.md
```
中的前置元数据模式。目标字数为3000-4000字，包含来源部分、相关文章的维基链接，以及适用的代码或图表块。
反向链接审核——不可跳过。在
```
<topic>/wiki/concepts/
```
下的所有现有文章中搜索新文章的标题、别名或核心实体。对于每个匹配项，在首次提及（以及后续一次提及）处添加
```
[[New Article]]
```
维基链接。这是最常被跳过的步骤——一个相互关联的维基依赖于双向链接。
bash
```
grep -rln "<新文章标题或关键词>" <topic>/wiki/concepts/
```
更新主题索引（见流程2）。
更新
```
<topic>/CLAUDE.md
```
中的现有文章列表。
重新索引主题集合：
```
kb index --topic <slug>
```
。

向

<topic>/log.md

追加条目（见流程5）——例如

## [YYYY-MM-DD] compile | <文章标题>（<字数>字，<N>个来源）

。

当更新现有文章（而非撰写新文章）时，使用

references/compilation-guide.md

中描述的

当前内容 / 拟修改内容 / 修改原因 / 来源

差异格式和矛盾排查工作流。

Procedure 2: Maintain topic indexes

流程2：维护主题索引

After adding, renaming, or removing any wiki article:

```
<topic>/wiki/index/Dashboard.md
```
-- update article count, total word count, featured sections, and any Obsidian Base embeds (use the obsidian-bases skill to author
```
.base
```
files and embed them).
```
<topic>/wiki/index/Concept Index.md
```
-- insert/update the article row alphabetically with its one-line summary.
```
<topic>/wiki/index/Source Index.md
```
-- for each new article, append rows for every source it cites, with a wikilink back to the article.
Optionally refresh the live view in Obsidian with the obsidian-cli skill (
```
obsidian open <path>
```
,
```
obsidian search <query>
```
).

添加、重命名或删除任何维基文章后：

```
<topic>/wiki/index/Dashboard.md
```
-- 更新文章数量、总字数、特色版块，以及所有Obsidian Base嵌入内容（使用obsidian-bases技能编写
```
.base
```
文件并嵌入）。
```
<topic>/wiki/index/Concept Index.md
```
-- 按字母顺序插入/更新文章行，包含一行摘要。
```
<topic>/wiki/index/Source Index.md
```
-- 对于每篇新文章，追加其引用的每个来源的行，并添加指向该文章的维基链接。
（可选）使用obsidian-cli技能刷新Obsidian中的实时视图（
```
obsidian open <path>
```
、
```
obsidian search <query>
```
）。

Procedure 3: Query the wiki and file back the answer

流程3：查询维基并保存答案

A query has two phases: Phase A produces the answer by reading the wiki (never from general knowledge); Phase B files the answer back so the exploration compounds.

Precondition: Identify which topic(s) the question belongs to. If the question spans topics, load each topic's Concept Index.

查询分为两个阶段：阶段A通过读取维基生成答案（绝不使用通用知识）；阶段B保存答案，使探索成果不断积累。

**前置条件：**确定问题所属的主题。若问题跨多个主题，加载每个主题的概念索引。

Phase A -- Answer from the wiki

阶段A -- 从维基获取答案

Read the topic's Concept Index first (
```
<topic>/wiki/index/Concept Index.md
```
). Scan the full index to identify candidate articles. Do NOT answer from general knowledge -- the wiki is the source of truth, even when the answer seems obvious. A contradiction between the wiki and general knowledge is itself valuable signal.
Locate relevant articles. At small scale (<30 articles), the index is enough. At larger scale, supplement with
```
kb search "<phrase>" --topic <slug>
```
. Also grep the topic for keywords:
```
grep -rl "<keyword>" <topic>/wiki/concepts/
```
.
Read the identified articles in full. Follow one level of
```
[[wikilinks]]
```
when targets look relevant to the question. Stop at one hop -- deeper traversal wastes context.
(Optional) Pull in raw sources if an article's claim is ambiguous and its
```
sources:
```
frontmatter points at a specific raw file worth verifying.
Synthesize the answer with these properties:
- Grounded in the wiki articles you just read -- every factual claim traces back to a
```
[[Wiki Article]]
```
  citation.
- Notes agreements and disagreements between articles when they exist.
- Flags gaps explicitly: "The wiki has no article on X" or "[[Article Y]] does not yet cover Z".
- Suggests follow-up ingest targets or open questions.
Match format to question type:
- Factual → prose with inline
```
[[wikilink]]
```
  citations.
- Comparison → table with rows per alternative, citations in cells.
- How-it-works → numbered steps with citations.
- What-do-we-know-about-X → structured summary with "Known", "Open questions", "Gaps".
- Visual → ASCII/Mermaid diagram, Marp deck (see
```
references/tooling-tips.md
```
  ), or matplotlib chart.

先阅读主题的概念索引（
```
<topic>/wiki/index/Concept Index.md
```
）。扫描完整索引以确定候选文章。绝不从通用知识中获取答案——维基是唯一的事实来源，即使答案看似显而易见。维基与通用知识之间的矛盾本身就是有价值的信号。
定位相关文章。规模较小时（<30篇文章），索引已足够。规模较大时，可补充使用
```
kb search "<短语>" --topic <slug>
```
。也可在主题中搜索关键词：
```
grep -rl "<关键词>" <topic>/wiki/concepts/
```
。
完整阅读找到的文章。当维基链接目标看起来与问题相关时，跟随一级
```
[[维基链接]]
```
。仅停留一级——更深层次的遍历会浪费上下文。
（可选）提取原始来源——如果文章的某个声明模糊，且其
```
sources:
```
前置元数据指向某个值得验证的特定原始文件。
合成答案，需具备以下特性：
- 基于刚阅读的维基文章——每个事实声明都可追溯到
```
[[维基文章]]
```
  引用。
- 记录文章之间的一致与分歧（若存在）。
- 明确指出空白：“维基中没有关于X的文章”或“[[文章Y]]尚未涵盖Z”。
- 建议后续导入目标或待解决问题。
根据问题类型匹配格式：
- 事实类 → 带内嵌
```
[[维基链接]]
```
  引用的散文。
- 对比类 → 每行对应一个选项的表格，单元格中包含引用。
- 工作原理类 → 带引用的编号步骤。
- 关于X我们知道什么 → 包含“已知内容”、“待解决问题”、“空白”的结构化摘要。
- 可视化类 → ASCII/Mermaid图表、Marp幻灯片（见
```
references/tooling-tips.md
```
  ）或matplotlib图表。

Phase B -- File back the answer

阶段B -- 保存答案

Save the answer to

<topic>/outputs/queries/<YYYY-MM-DD> <Question Slug>.md

with frontmatter:

type: output

stage: query

informed_by: ["[[Article 1]]", "[[Article 2]]"]

. See

references/frontmatter-schemas.md

for the full schema.

In the body, list which wiki articles informed the answer under
```
informed_by:
```
(as wikilinks) and call out new insights that should be absorbed back into those articles on the next compile pass.
When a filed-back insight contradicts or extends an article's claims, recompile the affected articles (Procedure 1).
Promote to wiki when the synthesis is durable. If the answer is a first-class reference (a comparison table, a trade-off analysis, a new concept synthesized from multiple articles), copy it to
```
<topic>/wiki/concepts/<Title>.md
```
following Procedure 1 standards and update the indexes (Procedure 2). Karpathy's pattern treats strong query answers as wiki citizens, not secondary artifacts.

Append to
<topic>/log.md
(Procedure 5) -- e.g.,

## [YYYY-MM-DD] query | <Question Slug>

plus a second line

## [YYYY-MM-DD] promote | <Title>

if promoted.

Anti-patterns to avoid:

Answering from memory -- always read the wiki pages. The wiki may contradict what you think you know.
No citations -- every factual claim must trace back to a
```
[[wikilink]]
```
.
Skipping the save -- good query answers compound the wiki's value. Always file to
```
outputs/queries/
```
; promote when durable.
Silent gaps -- surface missing coverage explicitly so the next ingest pass can fill it.

保存答案到

<topic>/outputs/queries/<YYYY-MM-DD> <问题标识>.md

，前置元数据为：

type: output

stage: query

informed_by: ["[[文章1]]", "[[文章2]]"]

。完整模式见

references/frontmatter-schemas.md

。

在正文中，列出为答案提供信息的维基文章（作为维基链接），并标注应在下次编译时吸收回这些文章的新见解。
当保存的见解与文章声明矛盾或扩展了文章内容时，重新编译受影响的文章（见流程1）。
当合成内容具有持久性时升级为维基文章。如果答案是一流参考内容（对比表格、权衡分析、从多篇文章合成的新概念），按照流程1的标准将其复制到
```
<topic>/wiki/concepts/<标题>.md
```
，并更新索引（见流程2）。Karpathy模式将优质查询答案视为维基的一部分，而非次要产物。
向
<topic>/log.md
追加条目（见流程5）——例如
```
## [YYYY-MM-DD] query | <问题标识>
```
，若升级为维基文章则添加第二行
```
## [YYYY-MM-DD] promote | <标题>
```
。

需避免的反模式：

凭记忆回答 — 始终阅读维基页面。维基可能与你认为已知的内容矛盾。
无引用 — 每个事实声明都必须可追溯到
```
[[维基链接]]
```
。
跳过保存步骤 — 优质查询答案会提升维基的价值。始终保存到
```
outputs/queries/
```
；具备持久性时升级为维基文章。
隐藏空白 — 明确指出缺失的内容，以便下次导入时补充。

Procedure 4: Lint and heal

流程4：检查与修复

Run structural lint via the

kb

CLI:

bash

kb lint <slug> --save

This checks dead wikilinks, orphan articles, missing source references, format violations, and stale content, saving a dated report to

<topic>/outputs/reports/

. For each issue, propose the fix with a diff before applying -- do not batch-apply changes:

Dead wikilink -- either create the missing article (Procedure 1) or rewrite the wikilink to point at an existing article.
Orphan article -- add incoming wikilinks from at least one related article, or remove the article if it is outside the topic's scope.
Missing source file -- an article's
```
sources:
```
frontmatter references a file absent from
```
raw/
```
. Either re-ingest (
```
kb ingest url/file
```
) or correct the reference.
Stale content -- article's
```
updated:
```
date is older than its source's
```
scraped:
```
date. Recompile with current sources.
Format violation -- fix missing frontmatter fields, H1 title, lead paragraph, or Sources section.

For deeper LLM-driven self-healing checks (inconsistencies across articles, missing coverage, wikilink audits, filed-back query absorption), read

references/lint-procedure.md

After the heal pass, append

## [YYYY-MM-DD] lint | <N> issues found, <M> fixed

<topic>/log.md

通过

kb

CLI运行结构检查：

bash

kb lint <slug> --save

此命令检查无效维基链接、孤立文章、缺失来源引用、格式违规和过时内容，并将带日期的报告保存到

<topic>/outputs/reports/

。对于每个问题，在应用修复前先提出差异方案——不要批量应用更改：

无效维基链接 — 要么创建缺失的文章（见流程1），要么重写维基链接指向现有文章。
孤立文章 — 从至少一篇相关文章添加传入维基链接，若文章超出主题范围则删除。
缺失源文件 — 文章的
```
sources:
```
前置元数据引用了
```
raw/
```
中不存在的文件。要么重新导入（
```
kb ingest url/file
```
），要么修正引用。
过时内容 — 文章的
```
updated:
```
日期早于其来源的
```
scraped:
```
日期。使用当前来源重新编译。
格式违规 — 修复缺失的前置元数据字段、H1标题、导语段落或来源部分。

如需更深入的LLM驱动自修复检查（文章间不一致、缺失内容、维基链接审核、查询答案吸收），请阅读

references/lint-procedure.md

。

修复完成后，向

<topic>/log.md

追加

## [YYYY-MM-DD] lint | 发现<N>个问题，修复<M>个

。

Procedure 5: Append to log.md

流程5：追加至log.md

The

kb

CLI auto-appends log entries for

ingest

and

lint --save

operations. Manual entries are needed for compile, query, promote, and split operations.

Format -- each entry is a single H2 heading with a consistent prefix so the log stays grep-able:

markdown

undefined

kb

CLI会自动为

ingest

和

lint --save

操作追加日志条目。编译、查询、升级和拆分操作仍需手动添加条目。

格式 — 每个条目都是一个H2标题，带有一致的前缀，以便日志可通过grep检索：

markdown

undefined

[YYYY-MM-DD] <op> | <short description>

[YYYY-MM-DD] <操作> | <简短描述>


Where `<op>` is one of `compile`, `query`, `promote`, or `split` (ingest and lint are handled by `kb`).

**Examples:**

```markdown


其中`<操作>`为`compile`、`query`、`promote`或`split`之一（ingest和lint由`kb`自动处理）。

**示例：**

```markdown

[2026-04-04] compile | Transformer Architecture (3847 words, 6 sources)

[2026-04-04] query | 2026-04-04 flash-attention-vs-paged-attention.md

[2026-04-04] promote | FlashAttention vs PagedAttention (from query)

[2026-04-05] split | "Inference Optimization" → KV Cache, Speculative Decoding


Optionally add a body paragraph under each entry with more context (key findings, source urls, decisions made). Keep entries terse -- the log is for skimming, not prose.

**Quick recent-activity check** -- the consistent prefix lets unix tools query the log:

```bash
grep "^## \[" <topic>/log.md | tail -10                  # last 10 events
grep "^## \[.*compile" <topic>/log.md | wc -l            # total compiles
grep "^## \[2026-04" <topic>/log.md                      # April 2026 events

Keep

log.md

at the topic root (not inside

wiki/

outputs/

) so it sits alongside

CLAUDE.md

as a first-class topic artifact.


可选择在每个条目下添加一段正文，提供更多上下文（关键发现、来源URL、做出的决策）。条目需简洁——日志用于快速浏览，而非长篇大论。

**快速查看近期活动** — 一致的前缀可通过Unix工具查询日志：

```bash
grep "^## \[" <topic>/log.md | tail -10                  # 最近10个事件
grep "^## \[.*compile" <topic>/log.md | wc -l            # 总编译次数
grep "^## \[2026-04" <topic>/log.md                      # 2026年4月的事件

将

log.md

放在主题根目录（而非

wiki/

或

outputs/

内），使其与

CLAUDE.md

一起作为主题的一级产物。

Output Format Selection

输出格式选择

All

inspect

and

search

commands support

--format

json -- always use for programmatic parsing
table -- human-readable aligned columns (default)
tsv -- tab-separated for piping to Unix tools

The

ingest codebase

and

index

commands always output JSON to stdout.

Read

references/output-formats.md

for format examples and empty result handling.

所有

inspect

和

search

命令支持

--format

参数：

json — 程序解析时始终使用此格式
table — 人类可读的对齐列（默认）
tsv — 制表符分隔格式，可传递给Unix工具

ingest codebase

和

index

命令始终向标准输出输出JSON。

阅读

references/output-formats.md

获取格式示例和空结果处理方式。

Error Handling

错误处理

CLI Errors

CLI错误

Error	Recovery
`unable to find a vault from <path>`	Run `kb ingest codebase <path> --topic <slug>` first, or re-run with `--vault <path>` if the vault lives elsewhere
`QMD is not available`	Run `npm install -g @tobilu/qmd`
`no topics were found`	Run `kb ingest codebase` or `kb topic new` to populate the vault
`multiple topics were found`	Re-run with `--topic <slug>`
`--title and --domain are bootstrap-only`	Remove those flags when re-ingesting an existing topic
`no symbols matched "<query>"`	Use `inspect smells` or `inspect complexity` to discover valid names
`no file matched "<path>"`	Use exact source-relative path from vault frontmatter (e.g. `src/config.ts` not `./src/config.ts` )

错误	恢复方法
`unable to find a vault from <path>`	先运行 `kb ingest codebase <path> --topic <slug>` ，若库位于其他位置则重新运行并添加 `--vault <path>` 参数
`QMD is not available`	运行 `npm install -g @tobilu/qmd`
`no topics were found`	运行 `kb ingest codebase` 或 `kb topic new` 填充库内容
`multiple topics were found`	重新运行并添加 `--topic <slug>` 参数
`--title and --domain are bootstrap-only`	重新导入现有主题时移除这些参数
`no symbols matched "<query>"`	使用 `inspect smells` 或 `inspect complexity` 查找有效名称
`no file matched "<path>"`	使用库前置元数据中的精确源相对路径（例如 `src/config.ts` 而非 `./src/config.ts` ）

KB Workflow Errors

知识库工作流错误

Error	Recovery
`kb` not found	Install the `kb` binary and ensure it is on PATH. Verify with `kb version`
Topic not found	Run `kb topic list` to see available topics, or scaffold with `kb topic new`
Article exceeds 4000 words	Extract a sub-topic into its own article and wikilink to it
Cross-topic wikilink ambiguity	Disambiguate with full path: `[[other-topic/wiki/concepts/Article Name\|Display Name]]`
`log.md` missing in existing topic	Create manually and backfill from git: `git log --format='## [%ad] <op> \| %s' --date=short <topic>/`

Read

references/error-handling.md

for the full error catalog with causes and recovery steps.

错误	恢复方法
`kb` not found	安装 `kb` 二进制文件并确保其在PATH中。通过 `kb version` 验证
Topic not found	运行 `kb topic list` 查看可用主题，或通过 `kb topic new` 搭建新主题
Article exceeds 4000 words	将子主题提取为独立文章并添加维基链接
Cross-topic wikilink ambiguity	使用完整路径消除歧义： `[[other-topic/wiki/concepts/Article Name\|Display Name]]`
`log.md` missing in existing topic	手动创建并从git回填： `git log --format='## [%ad] <op> \| %s' --date=short <topic>/`

阅读

references/error-handling.md

获取完整错误目录、原因和恢复步骤。

Constraints

约束

MUST DO

必须执行

Run
```
kb ingest codebase
```
before any inspect command on that topic
Use
```
--format json
```
when parsing output programmatically
Use
```
--progress never
```
when running
```
kb ingest codebase
```
in a non-interactive context
Parse stdout only for command output; treat stderr as diagnostics
Use the
```
topicSlug
```
from ingest output for subsequent
```
--topic
```
flags
Read
```
references/compilation-guide.md
```
before writing wiki articles
Run backlink audits after every article compile (Procedure 1, step 7)
File query answers to
```
outputs/queries/
```
(Procedure 3)
Append manual log entries for compile, query, promote, and split operations

在对某个主题执行任何inspect命令前，先运行
```
kb ingest codebase
```
程序解析输出时使用
```
--format json
```
在非交互式环境中运行
```
kb ingest codebase
```
时使用
```
--progress never
```
仅解析标准输出获取命令输出；将标准错误视为诊断信息
使用导入输出中的
```
topicSlug
```
作为后续
```
--topic
```
参数的值
编写维基文章前阅读
```
references/compilation-guide.md
```
每次编译文章后运行反向链接审核（流程1，步骤7）
将查询答案保存到
```
outputs/queries/
```
（流程3）
为编译、查询、升级和拆分操作追加手动日志条目

MUST NOT DO

禁止执行

Pass both
```
--lex
```
and
```
--vec
```
to
```
search
```
Pass
```
--force-embed
```
with
```
--embed=false
```
to
```
index
```
Treat stderr content as failure evidence for
```
kb ingest codebase
```
Assume vault location without running ingest or checking for
```
.kb/vault/
```

Use relative paths like

./src/config.ts

for

inspect file

-- use

src/config.ts

instead

Answer wiki queries from general knowledge -- the wiki is the source of truth
Skip the backlink audit when compiling articles
Batch-apply lint fixes without proposing diffs first

向
```
search
```
命令同时传递
```
--lex
```
和
```
--vec
```
参数
向
```
index
```
命令同时传递
```
--force-embed
```
和
```
--embed=false
```
参数
将
```
kb ingest codebase
```
的标准错误内容视为失败证据
未运行导入或检查
```
.kb/vault/
```
就假设库位置

对

inspect file

使用相对路径如

./src/config.ts

——改用

src/config.ts

从通用知识中回答维基查询——维基是唯一事实来源
编译文章时跳过反向链接审核
未提出差异方案就批量应用检查修复

kb

Original

Translation

kb CLI and Knowledge Base Pattern

kb CLI and Knowledge Base Pattern

Prerequisites

前置条件

Pattern Overview

模式概述

Related Skills

相关技能

kb CLI Quick Reference

kb CLI快速参考

Topic management

主题管理

Ingestion (auto-generates frontmatter, auto-appends to log.md)

导入（自动生成前置元数据，自动追加至log.md）

Codebase inspection

代码库检查

Structural linting

结构检查

Indexing and search (requires QMD)

索引与搜索（需QMD）

Command Dispatch

命令匹配

Codebase Analysis Workflow

代码库分析工作流

Ingest a Codebase

导入代码库

Inspect the Vault

检查库内容

Tabular Subcommands

表格类子命令

Detail Lookup Subcommands

详情查询子命令

Relation Subcommands

关系类子命令

Index the Vault

为库创建索引

Search the Vault

搜索库内容

KB Maintenance Procedures

知识库维护流程

Procedure 1: Compile a wiki article

流程1：编译维基文章

Procedure 2: Maintain topic indexes

流程2：维护主题索引

Procedure 3: Query the wiki and file back the answer

流程3：查询维基并保存答案

Phase A -- Answer from the wiki

阶段A -- 从维基获取答案

Phase B -- File back the answer

阶段B -- 保存答案

Procedure 4: Lint and heal

流程4：检查与修复

Procedure 5: Append to log.md

流程5：追加至log.md

[YYYY-MM-DD] <op> | <short description>

[YYYY-MM-DD] <操作> | <简短描述>

[2026-04-04] compile | Transformer Architecture (3847 words, 6 sources)

[2026-04-04] compile | Transformer Architecture (3847 words, 6 sources)

[2026-04-04] query | 2026-04-04 flash-attention-vs-paged-attention.md

[2026-04-04] query | 2026-04-04 flash-attention-vs-paged-attention.md

[2026-04-04] promote | FlashAttention vs PagedAttention (from query)

[2026-04-04] promote | FlashAttention vs PagedAttention (from query)

[2026-04-05] split | "Inference Optimization" → KV Cache, Speculative Decoding

[2026-04-05] split | "Inference Optimization" → KV Cache, Speculative Decoding

Output Format Selection

输出格式选择

Error Handling

错误处理

CLI Errors

CLI错误

KB Workflow Errors

知识库工作流错误

Constraints

约束

MUST DO

必须执行

MUST NOT DO