# Beaver

> 将任意文本源（书籍、文档、笔记、语料）转化为结构化 wiki 百科页面。识别并提取三种知识：fact（列表/表格型）、narrative（叙述型实体页）、skill（程序型 how-to 页）。通过 add_page.py 写入 wiki。支持永续迭代模式，自动追踪进度、捕获跨域洞察。

- Skill: `orangeviolin/beaver` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add orangeviolin/beaver`
- Raw SKILL.md: https://api.skillmd.com/api/skills/orangeviolin/beaver/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OrangeViolin (https://skillmd.com/u/orangeviolin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/orangeviolin/beaver

---


# /beaver — Anything to Wiki

将任意文本源转化为结构化 wiki 百科页面。支持单次运行和**永续迭代**两种模式。

工作目录：见 `local/config/beaver.config.md`

---

## 核心概念：三种知识类型

| 类型 | 回答的问题 | 典型内容 | Wiki 呈现 |
|------|-----------|---------|----------|
| **narrative** | 这是什么？它是谁？发生了什么？ | 人物传记、事件经过、概念解释、机构介绍 | 实体百科页（person/concept/event/organization/system/theory/…） |
| **fact** | 有哪些？数据是什么？清单如何？ | 数据表格、属性列表、关系清单、统计数字 | 列表页（list）或任意页内的结构化数据节 |
| **skill** | 怎么做？流程是什么？如何判断？ | 操作步骤、分析框架、决策流程、最佳实践 | 程序型页（concept 类型，结构化步骤正文） |

**判断优先级**：
- 若内容描述"某个实体的完整面貌" → narrative
- 若内容是"若干项目的并列清单/数据" → fact
- 若内容是"完成某件事的步骤" → skill

**MECE 原则**：勘察表应**完全覆盖**来源文本中的所有实体——不仅选"有趣的"，而是穷举。

---

## 两种运行模式

| 模式 | 触发方式 | 特点 |
|------|---------|------|
| **单次模式** | `/beaver <文件路径或粘贴文本>` | 处理完整输入，适合短文本（< 10 万字符） |
| **永续迭代模式** | `/beaver --loop <文件路径>` | 分批处理长文本，维护进度文件，每批后暂停或继续 |

---

## 执行流程

### 步骤 0 · 初始化进度文件（永续模式专用）

永续模式首次启动时，创建进度追踪文件：

```
wiki/logs/beaver/<source-slug>/
├── progress.md      # 进度：已处理批次、剩余批次
├── coverage.md      # 勘察表（累积，每批追加）
└── insights.md      # 跨域洞察（累积）
```

---

### 步骤 1 · 读取源文本

接受以下任何形式的输入：
- 文件路径（`.txt`、`.md`、`.pdf`）
- URL（网页正文）
- 直接粘贴的文本

读完后，**在回复中用一段话概括内容**，确认理解正确再继续。

超过 10 万字符时按段落边界切分为若干批次，每批不少于 2 万字符，依次处理。

---

### 步骤 2 · 勘察：列出知识单元

**每批必做三遍扫描**：

**① Narrative 扫描** — 批次中出现了哪些实体？（人物/事件/概念/理论/系统/机构/时代）

**② Fact 扫描** — 批次中是否有多项并列的清单、表格、属性对比？

**③ Skill 扫描**（常被遗漏，必须独立完成）— 批次中是否描述了：
- 推理/演绎过程（从前提出发得出结论）
- 决策框架（在什么条件下选择A vs B）
- 操作/技术方法（执行某件事的步骤）

产出一张**知识单元勘察表**：

```
| 序号 | 候选标题（wiki slug） | 类型 | 理由摘要（≤30字） |
|------|---------------------|------|-----------------|
```

---

### 步骤 3 · 检查已有页面（三层查重）

```python
import json
d = json.load(open('docs/wiki/pages.json', encoding='utf-8'))
pages, ai = d['pages'], d.get('alias_index', {})

def check_page(candidate):
    def _q(slug):
        return pages.get(slug, {}).get('quality', '?')
    if candidate in pages:
        return 'exact', candidate, _q(candidate)
    if candidate in ai:
        return 'alias', ai[candidate], _q(ai[candidate])
    hits = [(k,v) for k,v in ai.items()
            if (candidate in k or k in candidate) and len(k)>=3]
    if hits:
        slug = max(hits, key=lambda x: len(x[0]))[1]
        return 'fuzzy', slug, _q(slug)
    return 'missing', None, None

candidates = ['候选1', '候选2', ...]
for c in candidates:
    match, slug, quality = check_page(c)
    if match == 'missing':
        print(f'[CREATE ] {c}')
    elif quality in ('stub', 'basic'):
        print(f'[ENRICH ] {c} → {slug} [{quality}]')
    else:
        print(f'[SKIP   ] {c} → {slug} [{quality}]')
```

---

### 步骤 4 · 逐页生成内容

#### create 分支

```bash
python3 wiki/scripts/add_page.py <SLUG> - --summary "<一句话说明>" --author beaver << 'EOF'
<frontmatter+正文>
EOF
```

#### enrich 分支

先 Read 已有页面，合并内容后：

```bash
python3 wiki/scripts/edit_page.py <SLUG> - --summary "<一句话说明>" --author beaver << 'EOF'
<合并后完整页面>
EOF
```

每页写入后：`git add $(find docs/wiki/pages -name "<SLUG>.md" | head -1)`

---

### 步骤 5 · 捕获跨域洞察

每批处理完毕，判断是否有值得记录的跨域洞察（跨领域的交叉模式、意外联系、结构性原则）。大多数批次不产生洞察——不更新就是正确行为。

---

### 步骤 6 · 更新进度（永续模式）

更新 `progress.md`，标记已完成批次。若还有未完成批次，询问是否继续。

---

### 步骤 7 · 自改（每轮必做）

每轮结束后反思一个具体可改进的地方，追加到 `CHANGELOG.md`（详见 PRJ3-changelog-maintain）。

---

## 页面类型映射

| 实体 | Wiki type |
|------|-----------|
| 人物（研究者、工程师） | `person` |
| AI系统、程序、模型 | `system` |
| 概念、技术方法 | `concept` |
| 理论、框架 | `theory` |
| 事件（会议、发布、竞赛） | `event` |
| 机构、实验室、公司 | `organization` |
| 时代、历史阶段 | `era` |
| 列表 | `list` |

## Frontmatter 模板

```yaml
---
id: <slug>
type: <类型>
label: <中文显示名>
aliases: [<别名>]
tags: [<标签>]
description: <一句话描述，≤50字>
era: <年代，如 1950s>
field: <领域，如 机器学习>
affiliation: <机构（人物用）>
nationality: <国籍（人物用）>
born: <出生年>
died: <逝世年>
quality: stub
---
```

## Wikilink 规范

所有页面中出现其他已知实体时使用 `[[词条名]]` 格式内链。

## 质量标准

- `stub`：只有定义段，< 5 行正文
- `basic`：有 2+ 节，≥ 15 行
- `standard`：有 3+ 节，有引文，≥ 30 行
- `featured`：有 5+ 节，引文充实，≥ 60 行