knowledge-base

Files (9)

• SKILL.md
• build_manifest.ts · scripts/
• build_notes_index.py · scripts/
• extract_symbols.py · scripts/
• make_sidecar.ts · scripts/
• pdf_to_md.py · scripts/
• sphinx_html_to_md.py · scripts/
• tools.test.ts
• tools.ts

SKILL.md (first lines)

# Knowledge Base Skill

构建**可探索的结构化知识库**，让 agent 在 `grep + 文件阅读 + 原 PDF 回查`的朴素组合下，快速在陌生技术领域干活。

## 何时使用

1. **查 API / 手册内容**：用户问 "X 是什么 / 怎么用 / 什么时候改" 这类事实性问题，涉及已建立的 kb 领域（如某 C/C++ SDK、API 手册、编程指南等）
2. **接触陌生领域**：用户给了一批 PDF/HTML/docx 文档文件夹说"先整理一下"——用本 skill 的构建流程跑一遍
3. **回答技术问题不确定时**：先 `ls ~/.maxclaw/kb/` 看有无现成领域库；有就从 manifest 入手

## 目录约定

每个领域一个 kb 根目录：

```
~/.maxclaw/kb/<领域名>/
├── manifest.md                ← agent 主入口（按类别 + 组件 + notes 三视角）
├── md/                        ← 正文 Markdown（原始文档转换）
│   ├── <子领域>/*.md
│   └── web-mirror/*.md        （可选：Sphinx HTML 来源的单文件视图）
├── notes/                     ← agent 沉淀的智慧结晶（新增）
│   ├── INDEX.md               ← 自动生成：按 tag + 时间倒排
│   └── <slug>.md              ← 单篇笔记（front matter + 正文）
├── index/
│   ├── sidecars/*.json        ← L1 LLM 摘要 per-file
│   ├── symbols.jsonl          ← L3 符号引用（含 md/ 与 notes/ 代码块）
│   ├── symbols_inverted.json  ← symbol → [file:line] 倒排
│   ├── topics.json            ← topic → [files]
│   ├── categories.json        ← category → [files]
│   ├── notes_tags.json        ← tag → [notes] 倒排（新增）
│   ├── _sidecar_report.json
│   └── _pdf_conversion_report.json
└── raw-pdf/                   ← 原始 PDF 保留，供回查图表/公式
    └── by-component/          （软链或拷贝到原始目录）
```

## 查询流程（agent 视角）

**进入一个领域查一个具体项时，按顺序走**：

### Step 0 — 先查 notes（前人智慧）

notes/ 里是之前的 Claw session 沉淀的跨文档结论 / gotcha / 实测经验。**如果别人已经答过这个问题，直接站在他肩膀上**。

```bash
# 扫所有 notes 标题
ls ~/.maxclaw/kb/<domain>/notes/ 2>/dev/null | grep -v INDEX

# 按 tag 找（从 notes_tags.json 倒排）
jq -r '.["<tag>"] // []' ~/.maxclaw/kb/<domain>/index/notes_tags.json

# 关键词 grep notes
grep -l "KEYWORD" ~/.maxclaw/kb/<domain>/notes/*.md 2>/dev/null
```

如果 note 命中且**够新**（看 `updated` front matter，或 sources 引用的 md 没大变动），直接读它，跳到 Step 5/6 按需补充原文。如果 note 不够/过时/没命中，继续 Step 1。

### Step 1 — 先看 manifest

```bash
cat ~/.maxclaw/kb/<domain>/manifest.md | head -100
```

manifest 里按类别列出所有文档 + `when_to_read` 提示。如果问题明确，可直接定位到 1-2 份候选文档。

### Step 2 — L3 符号倒排（代码类符号）

```bash
jq -r '.["SYMBOL_NAME"] // "not indexed"' \
  ~/.maxclaw/kb/<domain>/index/symbols_inverted.json
```

命中即得 `[{file, line, kind}]`，直接跳到第 4 步。

**L3 覆盖的符号类型**（`extract_symbols.py` 的 PATTERNS）：
- `builtin`：双下划线标识符 `__xxx` / `__xxx__`（intrinsic / 属性修饰符 / 类型限定符，如 `__nram__`、`__mlu_entry__`、`__bang_move`、`__BANG_ARCH__`）
- `call`：函数调用 `name(...)`（非双下划线前缀）
- `function_def`：函数定义 `type name(...) {`
- `macro`：`#define MACRO`
- `type` / `typedef`：`struct/class/union/enum Name`
- `constant`：全大写至少 4 字符的标识符 `SOME_CONST`
- `py_function` / `py_class`

**L3 的边界（设计上不抓）**：
- **只扫 fenced code block 内**——正文描述段落里的符号不抓（例如文档正文里 "声明 `__sram__` 地址空间" 这种描述性出现会漏）
- **环境变量、配置项、概念词**（如 `MLUOP_SET_JOB_LIMIT_CAPABILITY` 这种通常只在使用方法段落描述的变量）→ 走 Step 3 grep
- **L3 0 命中时的两种情况**：
  - (a) 仅在正文描述，不在代码块 → grep 能找到 → 正常走 Step 3
  - (b) grep 也 0 hit → 本 kb 版本里真没这个符号（可能叫别的名字/在更新版 SDK 里）

### Step 3 — 全文 grep（非代码符号）

```bash
grep -rn "SYMBOL_OR_KEYWORD" ~/.maxclaw/kb/<domain>/md/ | head -20
```

### Step 4 — 读目标文件附近上下文

```bash
sed -n '<line-10>,<line+30>p' ~/.maxclaw/kb/<domain>/md/<path>.md
```

每份 MD 内有 `<!-- page: N -->` 锚点，能精确对应到原 PDF 页码。

### Step 5 — 概念回溯

如果 Step 4 命中的是 API/常量但概念没讲清（比如 `CN_KERNEL_CLASS_UNION` 背后的 Union 任务模型），**回到 L3/grep 查核心概念词**，跳到另一份相关文档（通常是开发者指南/编程指南）补上下文。

### Step 6（可选）— 回查原 PDF 图表

当 MD 里有 "见图 X.Y" 或文字描述不清楚（公式/硬件架构图/流程图）：

```
raw-pdf/by-component/<...>.pdf  页码 N（从 <!-- page: N --> 锚点来）
```

用户需要看图时告诉他 PDF 路径 + 页码即可（如果是 web channel 可以直接路径链接）。

### Step 7 — 沉淀笔记（适用时）

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss