beaver

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

/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 · 检查已有页面（三层查重）

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 分支

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

enrich 分支

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

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 模板

---
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 行