# LLMWiki 知识基建完善计划

## 一、现状盘点

### 1.1 已有的东西

| 组件 | 状态 | 说明 |
|------|------|------|
| 目录结构 | ✅ 已有 | concepts/ entities/ sources/ reports/ syntheses/ |
| Front Matter | ⚠️ 部分规范 | 概念页有，实体页有，但 top-level 混乱 |
| auto-digest | ✅ 已有 | .openclaw-wiki/cache/agent-digest.json |
| Reports | ✅ 已启用 | claim-health/contradictions/stale-pages 等6个报告 |
| index.md | ⚠️ 残缺 | 有人工写的索引，但与 digest 不同步 |
| WIKI.md | ✅ 已有 | vault 元数据（isolated/native） |
| AGENTS.md | ✅ 已有 | Agent 交互规则 |

### 1.2 缺失的核心文件

| 文件 | 用途 | 状态 |
|------|------|------|
| `SCHEMA.md` | 领域规范：定义实体类型、关系、标签体系 | ❌ 不存在 |
| `log.md` | 操作日志：记录增删改、来源追踪 | ❌ 不存在 |
| `raw/` | 原始资料：PDF、HTML、剪藏的未处理原始内容 | ❌ 不存在（sources/ 混用了） |
| `claims.jsonl` | 机器可读的结构化事实库 | ❌ 不存在 |
| 标签体系 | 统一标签枚举 | ⚠️ 不一致 |

### 1.3 数据统计

```
Page counts:
  concepts:  7  ✅ 有实质内容
  entities:  2  ⚠️ 有内容但未在 agent-digest 中计入
  sources:   40 ✅ 散落在 sources/
  synthesis: 1  ⚠️ 哈尔滨工程大学报告（来源不明）
  reports:   6  ✅ 自动生成

Claim count: 5
  missing evidence: 5   ← 所有 claims 都缺来源
  contested: 0
  stale: 0
```

### 1.4 质量评估

**最大问题：所有 claims 都没有证据来源。**

这意味着知识库的"知识"部分其实还没有真正建立——页面虽然写了，但每个结论背后引用的原始资料没有被记录。

---

## 二、完善目标

### 2.1 目标状态

```
最小可用层（50页规模）：
  ✅ sources/ 有原始资料
  ✅ 实体页/概念页有完整 frontmatter
  ✅ SCHEMA.md 定义规范
  ✅ index.md 作为主入口
  ✅ log.md 记录变更历史

进阶层（100页）：
  ✅ raw/ 分离原始资料
  ✅ claims.jsonl 结构化事实库
  ✅ 标签体系规范化
  ✅ 置信度评分

知识图谱层（200页）：
  ⬜ 实体提取自动化
  ⬜ 类型化关系定义
  ⬜ 图遍历查询
```

---

## 三、分阶段实施方案

### 阶段 A：补全核心元文件（1-2天）

这是基础设施，补完才能谈其他所有功能。

#### A1. 创建 SCHEMA.md

```markdown
# SCHEMA.md — 知识库领域规范

## 领域定义
本知识库服务于：高等教育AI研究方向的知识积累与研究协作

## 实体类型（Entities）

| 类型 | 说明 | 示例 |
|------|------|------|
| person | 人物 | [[郭朝晖]] |
| organization | 组织机构 | [[宝钢]] |
| concept | 概念 | [[涌现]] |
| project | 项目/系统 | [[Hermes Agent]] |
| paper | 论文 | arXiv:2510.19247 |
| article | 文章 | 微信公众号文章 |
| tool | 工具/软件 | [[Obsidian]] |

## 概念类型（Concepts）

见 concepts/ 目录下的分类

## 关系类型

| 关系 | 说明 |
|------|------|
| uses | 使用某工具/方法 |
| depends-on | 依赖某系统 |
| caused-by | 由...导致 |
| contradicts | 与...矛盾 |
| supersedes | 替代旧内容 |
| related-to | 相关 |

## 标签体系（Canonical Tags）

必须从以下标签中选择，禁止自定义标签：

- 研究方向：[higher-ed, AI-education, curriculum-design, assessment]
- 技术类：[LLM, RAG, agent, knowledge-graph, embedding]
- 项目类：[project, tool, skill, workflow]
- 人物类：[researcher, practitioner, mentor]
- 元类：[meta, methodology, reflection]

## 页面创建规则

1. 每个页面必须有完整 frontmatter
2. 概念页必须包含：定义、关键特征、相关概念
3. 实体页必须包含：基本信息、主要贡献、关联概念
4. 来源页必须在 frontmatter 的 sources 字段中引用原始文件

## Claims 规范

每个 claim 格式：
```json
{"text": "...", "source": "来源ID", "confidence": 0.9, "date": "2026-05-20"}
```

## Lint 规则

- 所有 [[Wikilinks]] 必须指向已存在的页面
- sources 字段必须是已有来源的相对路径
- date 格式必须是 YYYY-MM-DD
```

#### A2. 创建 log.md

```markdown
# log.md — 知识库操作日志

## 格式规范
每条记录格式：[日期] [操作类型] [页面名] [操作人] [说明]

## 类型枚举
- CREATE: 新建页面
- UPDATE: 更新内容
- DELETE: 删除/归档
- INGEST: 批量摄入
- SYNC: Git 同步
- SCHEMA: 规范变更

## 记录

<!-- 起始记录 -->
[2026-05-20] [SCHEMA] [SCHEMA.md] [老何] 初始化领域规范
```

#### A3. 创建 raw/ 目录结构

```
raw/
├── papers/        # PDF + 提取的 markdown
├── articles/      # 网页剪藏 HTML/markdown
├── transcripts/   # 会议/课程转录
└── datasets/      # 数据集说明文档
```

**迁移任务**：将 sources/ 中的 PDF 和 HTML 分类移入 raw/，sources/ 专门放 AI 可读的 markdown 提炼版本。

---

### 阶段 B：规范化现有内容（1-2天）

#### B1. 统一 frontmatter 规范

现有页面 frontmatter 不一致，示例：

```yaml
# 现有（不统一）
---
title: 涌现
created: 2026-05-15
updated: 2026-05-15
type: concept
tags: [concept, complexity, physics, consciousness, systems-theory]
sources: [sources/涌现的本质是什么-万物本源说.html]
confidence: high
---

# 规范目标
---
type: concept
title: 涌现
created: 2026-05-15
updated: 2026-05-15
tags: [complexity, systems-theory, consciousness]
sources: [raw/articles/涌现的本质是什么-万物本源说.html]
confidence: high
claims:
  - text: "大量简单个体遵循简单规则聚集互动，会自发诞生全新宏观属性"
    source: "raw/articles/涌现的本质是什么-万物本源说.html"
    confidence: 0.9
    date: 2026-05-15
---
```

**任务**：遍历所有概念页和实体页，补全缺失的 frontmatter 字段。

#### B2. 修复 agent-digest 中的 entity 计数

当前 agent-digest 显示 `entity: 0`，但 entities/ 下有 2 个文件。
原因：frontmatter 中 entity 页面没有声明 `type: entity`。

---

### 阶段 C：建立 claims.jsonl（持续）

#### C1. 什么是 claims

Claims 是知识库中每个可校验的事实的结构化记录。

```jsonl
{"page": "concepts/涌现.md", "text": "涌现指大量简单个体遵循简单规则聚集互动，会自发诞生全新宏观属性", "source": "sources/涌现的本质是什么-万物本源说.html", "confidence": 0.9, "extracted": "2026-05-20"}
{"page": "entities/郭朝晖.md", "text": "郭朝晖曾任职于宝钢", "source": "sources/我的科研经历-反思与成长-郭朝晖.html", "confidence": 0.95, "extracted": "2026-05-20"}
```

#### C2. 提取策略

从现有页面提取：
1. 遍历所有概念页和实体页
2. 提取带有 `[引用]` 标记的句子
3. 关联到 sources/ 中的原始文件
4. 写入 `claims.jsonl`

新页面的 claims 在创建时同步生成。

---

### 阶段 D：Git 同步 + 冲突规避（阶段二同步做）

#### D1. Git 初始化

腾讯云 VM 端：
```bash
cd /home/obsidian/wiki
git init
git add -A
git commit -m "初始化 LLMWiki"
git remote add origin git@gitee.com:你的用户名/仓库名.git
git push -u origin main
```

#### D2. 分区写入规则（防冲突）

```markdown
## Git 同步的分区写入规则

| Agent | 可写目录 |
|-------|---------|
| main | 顶层 + concepts/ + entities/ + 03-工具/ |
| news | sources/ + raw/ |
| assistant | 04-Tools/ + reports/ |
| research | syntheses/ + 06-学术研究/ |
| PC OpenCode | 全部（用户操作层） |

原则：
- 每个 Agent 有主要负责的目录
- 跨越分区写入前先检查 git status
- 冲突时：最后提交者负责解决
```

#### D3. 同步触发机制

```bash
# cron 任务：每30分钟自动同步
*/30 * * * * cd /home/obsidian/wiki && git pull --rebase && git push
```

---

## 四、基础设施清单

| 任务 | 优先级 | 工作量 | 依赖 |
|------|--------|--------|------|
| 创建 SCHEMA.md | 🔴 高 | 1小时 | 无 |
| 创建 log.md | 🔴 高 | 30分钟 | 无 |
| 创建 raw/ 目录 | 🔴 高 | 30分钟 | 无 |
| 规范化现有 frontmatter | 🟡 中 | 2-3小时 | SCHEMA.md |
| 迁移 sources/ 到 raw/ | 🟡 中 | 1-2小时 | raw/ 建立 |
| 建立 claims.jsonl | 🟡 中 | 2-3小时 | frontmatter 规范 |
| Git 初始化 + Gitee | 🔴 高 | 1小时 | Gitee 仓库地址 |
| 配置 cron 同步 | 🟡 中 | 30分钟 | Git 初始化 |
| 补充 entity index | 🟡 中 | 30分钟 | 无 |

---

## 五、下一步行动

### 今天可以做

1. **创建 SCHEMA.md** — 定义领域、实体类型、标签体系
2. **创建 log.md** — 建立操作日志
3. **创建 raw/ 目录** — 分离原始资料

### 本周可以做

1. 规范化所有现有页面的 frontmatter（7个概念页 + 2个实体页）
2. Git 初始化 + Gitee 关联

### 需要确认

1. **Gitee 仓库地址** — 云端 Git 初始化需要
2. **同步频率** — 30分钟自动还是手动触发？
3. **PC 端 Obsidian 版本** — 是否 1.12+，决定能否用 Obsidian CLI