---
name: initializing-kb
description: "创建新知识库或初始化 KB 工作空间（默认在 ~/kb，可通过 KB_HOME 环境变量自定义）。当用户说'建个知识库'、'我想整理XX的知识'时使用。"
---

# Initializing KB

创建一个基于 Markdown 的知识库。主要产物是 `<KB>/<slug>/` 目录和其中的 `AGENTS.md`。

## 工作区路径

KB workspace 路径由环境变量 `KB_HOME` 决定，未设置时默认 `~/kb`。

- Bash 命令里直接用 `${KB_HOME:-$HOME/kb}`，shell 会展开。例：`cd "${KB_HOME:-$HOME/kb}"`、`ls "${KB_HOME:-$HOME/kb}/REGISTRY.md"`
- 非 Bash 工具（Read / Glob / Edit）需要绝对路径时，先在 Bash 里 `echo "${KB_HOME:-$HOME/kb}"` 拿到值，再用

后文中所有 `<KB>` 占位符均指此 workspace 根路径——调用 Read / Glob / Edit 这类需要绝对路径的工具时，请把 `<KB>` 替换为 `echo "${KB_HOME:-$HOME/kb}"` 的实际输出。

## 核心：工作目录

所有知识库都在 `<KB>` 下，每个知识库一个子目录。

```text
<KB>/
├── REGISTRY.md
├── PROGRESS.md
├── <slug>/
│   ├── AGENTS.md
│   ├── index.md
│   ├── log.md
│   ├── raw/
│   └── wiki/
│       ├── overview/
│       ├── entities/
│       ├── sources/
│       └── analyses/
└── .git/
```

## 启动 SOP

1. `ls "${KB_HOME:-$HOME/kb}/REGISTRY.md"`
   - 不存在 → 初始化根目录（见下方"首次初始化"）
   - 存在 → 读 `REGISTRY.md`，了解已有的知识库
2. 询问用户要创建什么主题的知识库

## 首次初始化

如果 `<KB>` 不存在：

1. `mkdir -p "${KB_HOME:-$HOME/kb}"`
2. 创建 `<KB>/REGISTRY.md`：

   ```markdown
   # 知识库注册表

   | slug | 主题 | 状态 | 创建日期 | 说明 |
   |------|------|------|----------|------|
   ```

3. 创建 `<KB>/PROGRESS.md`：

   ```markdown
   # 知识库工作日志
   ```

4. `cd "${KB_HOME:-$HOME/kb}" && git init && git add -A && git commit -m "init kb workspace"`

## 创建知识库

1. 询问用户知识库主题
2. 从主题生成 kebab-case slug 建议（不带 `-kb` 后缀）
3. 校验 slug：
   - 匹配 `^[a-z0-9][a-z0-9-]{0,29}$`
   - 不与 `REGISTRY.md` 已有 slug 重复
   - 让用户确认或修改
4. `mkdir -p "${KB_HOME:-$HOME/kb}/<slug>"`
5. 检查当前素材（如果用户指定了已有目录或文件）
6. 确定所需的最小页面类型集合
7. 创建 `AGENTS.md`（见下方"AGENTS.md 内容"）
8. 创建 `index.md`、`log.md`、`raw/`、`wiki/overview/`、`wiki/entities/`、`wiki/sources/`、`wiki/analyses/`
9. 追加 `<KB>/REGISTRY.md` 新行
10. `cd "${KB_HOME:-$HOME/kb}" && git add -A && git commit -m "[<slug>] init: <主题>"`

## AGENTS.md 内容

至少应包含：

- 仓库目标
- `raw/` 的 source-of-truth 规则
- 页面类型及其职责
- ingest 工作流
- query 工作流
- lint 工作流
- 编辑规则
- 命名约定
- 何时应新建页面，而不是继续扩写旧页
- agent 修改后的输出要求

## 页面模型

默认页面职责：

- `wiki/sources/`：每个来源一页
- `wiki/entities/`：每个跨多个来源反复出现的稳定实体或概念一页
- `wiki/overview/`：每个主题或认知领域一页
- `wiki/analyses/`：长期有效的答案、比较、综合或决策记录

避免混淆这些角色。

## 命名规则

- 来源页：`YYYY-MM-DD-short-source-name.md`
- 分析页：`YYYY-MM-DD-short-analysis-name.md`
- 实体页：`kebab-case-entity-name.md`
- 综述页：`kebab-case-topic-name.md`

## 好的结果

一个好的 schema 应该让这些决策变得容易：

- 新来源应该落到哪里
- 一个概念什么时候值得拥有独立实体页
- 一个高价值答案应该写回哪里
- 冲突信息应如何呈现
- 之后如何再次找到这些页面