---
name: initializing-kb
description: "创建新知识库或初始化 KB 工作空间（默认在 ~/kb）。当用户说'建个知识库'、'我想整理XX的知识'时使用。"
version: 0.3.0
owner_repo: Optima-Chat/kb-skills
---

# Initializing KB

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

## 核心：工作目录

所有知识库都在 `~/kb` 下，每个知识库一个子目录。

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

## 启动 SOP

0. 自动迁移与同步（静默执行，无需告知用户）：
   ```bash
   [ -d ~/kb/.git ] && kb migrate
   [ -n "$KB_BACKEND_URL" ] && kb sync
   ```
1. `ls ~/kb/REGISTRY.md`
   - 不存在 → 初始化根目录（见下方"首次初始化"）
   - 存在 → 读 `REGISTRY.md`，了解已有的知识库
3. 询问用户要创建什么主题的知识库

## 首次初始化

如果 `~/kb` 不存在：

1. `mkdir -p ~/kb`
2. 创建 `~/kb/PROGRESS.md`：

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

3. 如果 `KB_BACKEND_URL` 已设置，运行 `kb sync`（会自动生成 REGISTRY.md）。否则手动创建空 REGISTRY.md：

   ```markdown
   # Knowledge Base Registry

   | local_dir | slug | name | scope | owner | status | created_at | notes |
   |-----------|------|------|-------|-------|--------|------------|-------|
   ```

## 创建知识库

1. 询问用户知识库主题
2. 从主题生成 kebab-case slug 建议（不带 `-kb` 后缀）
3. 校验 slug：
   - 匹配 `^[a-z0-9][a-z0-9-]{0,29}$`
   - 不与 `REGISTRY.md` 已有 slug 重复
   - 让用户确认或修改
4. `kb create --slug <slug> --name "<主题>"`
   - 自动创建目录结构（AGENTS.md、index.md、log.md、raw/、wiki/）
   - 自动 git init + commit
   - 如果 KB_BACKEND_URL 已设置，自动注册到 kb-backend
5. 根据用户的素材和需求，编辑 `AGENTS.md`（见下方"AGENTS.md 内容"）

## 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 应该让这些决策变得容易：

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