# 知识库同步可行性分析与实施计划

> **任务目标**：定期将 `D:\TC_UP\home-wiki` 的笔记内容更新到 `D:\Applications\app\kepano-obsidian-main` 仓库

---

## 一、双仓库结构对比

### 1.1 目录结构映射

| 源仓库 (D:\TC_UP\home-wiki) | 目标仓库 (kepano-obsidian-main) | 兼容性 |
|---------------------------|-------------------------------|-------|
| `concepts/` (12 文件) | `wiki/` (464 文件，概念页) | ✅ 高度兼容 |
| `entities/` | `References/` + `wiki/` (实体页) | ✅ 可兼容 |
| `raw/` (48 文件) | `raw/` (480 文件) | ✅ 完全兼容 |
| `sources/` | `raw/` (已有，需合并) | ✅ 需映射 |
| `Daily/` | `Daily/` | ✅ 完全兼容 |
| `Templates/` | `Templates/` | ✅ 需检查冲突 |
| `MyNotes/` | `Notes/` | ✅ 可映射 |
| `scripts/` | `tools/scripts/` | ✅ 可兼容 |
| `04-Tools/` | 无对应（可作为知识卡片） | ⚠️ 需映射 |
| `syntheses/` | `wiki/` (概念/研究报告) | ✅ 可兼容 |
| `reports/` | `wiki/archive/` (归档报告) | ⚠️ 需过滤 |

### 1.2 核心规范对比

| 维度 | home-wiki | kepano-obsidian-main | 兼容性 |
|------|-----------|---------------------|-------|
| **Frontmatter** | `type`, `title`, `created`, `updated` | `categories`, `tags`, `created`, `source`, `type` | ⚠️ 格式不同 |
| **标签体系** | Canonical Tags ( predefined list) | 自由 tags (no whitelist) | ⚠️ 需转换 |
| **关系类型** | Wikilinks + `→`, `⊍` 符号 | 标准 Wikilinks | ⚠️ 需清理 |
| **Claims 规范** | 严格 source 追溯 | `[raw:文件名:行号]` 格式 | ⚠️ 需转换 |
| **文件命名** | 中文优先 | 中英文混合 | ✅ 兼容 |
| **日期格式** | `YYYY-MM-DD` | `YYYY-MM-DD` | ✅ 兼容 |

---

## 二、可行性分析

### 2.1 技术可行性 ✅ **可行**

1. **底层技术栈一致**：两个仓库都使用 Obsidian + Markdown + Git
2. **核心概念相似**：
   - 都使用 `raw/` 存储原始来源
   - 都使用 `Daily/` 存储日记
   - 都使用概念/实体分离的组织方式
3. **内容高度互补**：
   - home-wiki: 专注"高等教育 AI"，12 个概念页，48 个 raw 文件
   - kepano-obsidian-main: 综合性知识库，464 个 wiki 页面，480 个 raw 文件

### 2.2 内容冲突风险 ⚠️ **中等**

1. **Frontmatter 格式差异**：
   ```yaml
   # home-wiki 格式
   ---
   type: concept
   title: 涌现
   created: 2026-05-20
   updated: 2026-05-20
   tags: [phenomenon, systems-theory]
   sources: [raw/articles/原始资料.html]
   ---

   # kepano-obsidian-main 格式
   ---
   categories:
     - "[[LLM Wiki]]"
   tags:
     - wiki
     - concept
   created: 2026-06-30
   source: "[[{source-file}]]"
   type: concept
   ---
   ```

2. **关系符号**：home-wiki 使用 `→`, `⊍` 等符号，目标仓库不使用
3. **Claims 规范**：
   ```yaml
   # home-wiki
   claims:
     - text: "事实陈述"
       source: "raw/articles/原始资料.html"
       confidence: 0.9

   # kepano-obsidian-main
   事实陈述[raw:文件名:行号]
   ```

### 2.3 数据规模 ⚠️ **需筛选**

| 类型 | home-wiki | kepano-obsidian-main | 策略 |
|------|-----------|---------------------|------|
| 概念页 | 12 | 177+ | ✅ 全部同步 |
| 实体页 | ~5 | 120+ | ✅ 全部同步 |
| 原始来源 | 48 | 480 | ⚠️ 需去重 |
| Daily | 未知 | 未知 | ✅ 合并 |
| 模板 | 未知 | 多个 | ⚠️ 需冲突检查 |
| 工具文档 | 7 | 26+ | ✅ 全部同步 |

---

## 三、实施计划

### 3.1 第一阶段：准备工作（Week 1）

#### 3.1.1 冲突检查与映射表创建

**任务**：创建 `tools/sync-mapping.json` 映射表

```json
{
  "directoryMapping": {
    "concepts/": "wiki/",
    "entities/": ["wiki/", "References/"],
    "raw/": "raw/",
    "sources/": "raw/",
    "Daily/": "Daily/",
    "Templates/": "Templates/",
    "MyNotes/": "Notes/",
    "scripts/": "tools/scripts/",
    "04-Tools/": "wiki/", // 作为工具知识卡片
    "syntheses/": "wiki/",
    "reports/": "wiki/archive/"
  },
  "tagMapping": {
    "phenomenon": "concept/phenomenon",
    "theory": "concept/theory",
    "technology": "concept/technology",
    "person": "people",
    "organization": "entity/organization",
    "AI-education": "ai/education",
    "higher-ed": "education/higher-ed"
  },
  "conflictFiles": ["AGENTS.md", "SCHEMA.md", "Templates/*.md"]
}
```

**输出**：
- `tools/sync-mapping.json` — 目录和标签映射表
- `tools/sync-conflicts.md` — 冲突文件清单

#### 3.1.2 Frontmatter 转换器

**任务**：创建 `tools/sync/convert-frontmatter.py`

```python
# 转换规则
# 1. type: concept → categories: "[[LLM Wiki]]", type: concept
# 2. tags: [a, b] → tags: [wiki, a, b] (添加 wiki 标签)
# 3. sources: [...] → source: "[[{primary-source}]]"
# 4. updated: 删除（目标仓库不使用）
# 5. claims → 转换为 [raw:文件名:行号] 格式
# 6. 移除 →, ⊍ 等关系符号，替换为标准 Wikilinks
```

**输出**：
- `tools/sync/convert-frontmatter.py` — Frontmatter 转换脚本
- `tools/sync/convert-frontmatter-test.md` — 转换测试样例

### 3.2 第二阶段：核心内容同步（Week 2）

#### 3.2.1 概念页同步

**任务**：同步 `concepts/` → `wiki/`

**步骤**：
1. 读取 `D:\TC_UP\home-wiki\concepts\*.md`
2. 转换 frontmatter（使用转换器）
3. 转换关系符号（`→`, `⊍` → 标准 Wikilinks）
4. 转换 claims（`claims[].text[raw:source]` → `[raw:文件名:行号]`）
5. 写入 `wiki/`，避免冲突（添加后缀 `_from_homewiki`）
6. 更新 `wiki/index.md`（添加到核心概念章节）

**检查点**：
- [ ] 12 个概念页全部转换
- [ ] Frontmatter 格式符合目标仓库规范
- [ ] Wikilinks 无断链
- [ ] 索引更新完成

#### 3.2.2 实体页同步

**任务**：同步 `entities/` → `wiki/` + `References/`

**步骤**：
1. 读取 `D:\TC_UP\home-wiki\entities\*.md`
2. 根据实体类型分流：
   - `subtype: person` → `wiki/` + `References/People.md` 添加条目
   - `subtype: organization` → `References/` + `wiki/`
   - `subtype: tool` → `wiki/`（工具页）
3. 转换 frontmatter（使用转换器）
4. 检查与现有实体页冲突（如郭朝晖是否已存在）
5. 写入目标位置，更新索引

**检查点**：
- [ ] ~5 个实体页全部转换
- [ ] 实体类型分类正确
- [ ] 无重复实体
- [ ] 索引更新完成

### 3.3 第三阶段：原始来源同步（Week 3）

#### 3.3.1 raw/ 去重与合并

**任务**：合并 `raw/` + `sources/` → `raw/`

**步骤**：
1. 扫描 `D:\TC_UP\home-wiki\raw/` + `sources/`
2. 计算文件哈希值，去重（避免重复文件）
3. 对比目标仓库 `raw/`，识别新文件
4. 创建新文件到 `raw/`（按类型分类：papers/, articles/, transcripts/）
5. 更新 Wiki 页面的 source 字段

**检查点**：
- [ ] 去重完成
- [ ] 新文件识别正确
- [ ] Source 字段更新完成

#### 3.3.2 claims 追溯转换

**任务**：转换 claims 为 `[raw:文件名:行号]` 格式

**步骤**：
1. 扫描所有 Wiki 页面中的 `claims` 字段
2. 提取 `claims[].source` 路径
3. 查找对应的 raw 文件行号
4. 转换格式：`text[raw:文件名:行号]`
5. 删除原 `claims` 字段

**检查点**：
- [ ] 所有 claims 转换完成
- [ ] 行号正确
- [ ] 溯源格式符合目标仓库规范

### 3.4 第四阶段：其他内容同步（Week 4）

#### 3.4.1 Daily/ 合并

**任务**：合并 `Daily/` → `Daily/`

**步骤**：
1. 扫描 `D:\TC_UP\home-wiki\Daily\*.md`
2. 按日期去重（同名文件需要合并内容）
3. 写入目标 `Daily/`

**检查点**：
- [ ] 日记合并完成
- [ ] 无内容丢失

#### 3.4.2 Templates/ 冲突处理

**任务**：检查模板文件冲突

**步骤**：
1. 对比两个仓库的模板文件列表
2. 识别同名文件（如 `Concept Template.md`）
3. 决策：保留目标仓库模板，或融合两个模板

**检查点**：
- [ ] 冲突识别完成
- [ ] 融合方案确定

#### 3.4.3 工具文档同步

**任务**：同步 `04-Tools/` + `scripts/` → `tools/`

**步骤**：
1. 读取 `D:\TC_UP\home-wiki\04-Tools\*.md` + `scripts/`
2. 写入 `tools/scripts/`
3. 更新 `wiki/index.md` 工具章节

**检查点**：
- [ ] 工具文档全部同步
- [ ] 索引更新完成

### 3.5 第五阶段：验证与优化（Week 5）

#### 3.5.1 Lint 检查

**任务**：运行 Wiki Lint 检查

**检查项**：
- [ ] Frontmatter 一致性
- [ ] Wikilink 连通性
- [ ] 标签格式
- [ ] 日期格式
- [ ] 溯源格式

**修复**：
- 运行 `tools/scripts/wiki-lint-orphan.ps1`
- 运行 `tools/scripts/wiki-lint-broken-v2.ps1`
- 运行 `tools/scripts/wiki-lint-fix-type.ps1`

#### 3.5.2 交叉引用检查

**任务**：检查新 Wiki 页面与现有页面的交叉引用

**步骤**：
1. 扫描新 Wiki 页面的所有 Wikilinks
2. 检查目标页面是否存在
3. 如不存在，创建占位页面或删除链接
4. 更新相关页面的反向链接

**检查点**：
- [ ] 断链修复完成
- [ ] 反向链接添加完成

#### 3.5.3 日志更新

**任务**：更新 `wiki/log.md`

**步骤**：
1. 记录同步操作（日期、操作类型、涉及页面）
2. 记录转换规则（frontmatter、claims、标签）
3. 记录冲突处理（文件、解决方案）

**输出**：
- `wiki/log.md` 追加同步日志条目

---

## 四、定期同步机制

### 4.1 同步频率

| 频率 | 内容 | 负担 |
|------|------|------|
| **每日** | Daily/ 日记 | 低 |
| **每周** | concepts/, entities/, raw/ 新增内容 | 中 |
| **每月** | 全量检查、去重、Lint | 高 |

### 4.2 自动化脚本

**方案 1：PowerShell 脚本**

```powershell
# tools/sync/daily-sync.ps1
# 用途：每日同步 Daily/ 日记

$sourcePath = "D:\TC_UP\home-wiki\Daily"
$targetPath = "D:\Applications\app\kepano-obsidian-main\Daily"

Get-ChildItem $sourcePath -Filter "*.md" | ForEach-Object {
    $targetFile = Join-Path $targetPath $_.Name
    if (-not (Test-Path $targetFile)) {
        Copy-Item $_.FullName $targetFile
        Write-Host "Copied $($_.Name)"
    } else {
        Write-Host "Skipped $($_.Name) (exists)"
    }
}
```

**方案 2：Python 脚本**

```python
# tools/sync/weekly-sync.py
# 用途：每周同步 concepts/, entities/, raw/

import os
import shutil
from pathlib import Path

MAPPINGS = {
    "concepts": "wiki",
    "entities": ["wiki", "References"],
    "raw": "raw",
}

def sync_directory(source, target, converter=None):
    """同步目录，可选转换器"""
    for file in Path(source).glob("*.md"):
        target_file = Path(target) / file.name
        if not target_file.exists():
            if converter:
                content = converter(file.read_text())
                target_file.write_text(content)
            else:
                shutil.copy(file, target_file)
            print(f"Synced {file.name}")
```

### 4.3 冲突解决策略

| 冲突类型 | 策略 | 优先级 |
|---------|------|--------|
| 文件同名 | 添加后缀 `_from_homewiki` | 目标仓库 |
| Frontmatter 格式 | 转换为目标仓库格式 | 目标仓库 |
| 标签冲突 | 保留目标仓库标签，融合源仓库标签 | 目标仓库 |
| Wikilink 断链 | 创建占位页面或删除链接 | 目标仓库 |
| claims 格式 | 转换为 `[raw:文件名:行号]` | 目标仓库 |

---

## 五、风险与对策

### 5.1 风险识别

| 风险 | 概率 | 影响 | 对策 |
|------|------|------|------|
| **格式冲突** | 高 | 中 | 提前创建转换器，自动化处理 |
| **内容重复** | 中 | 低 | 去重脚本，哈希值比对 |
| **断链风险** | 中 | 高 | Lint 检查，反向链接补充 |
| **数据丢失** | 低 | 高 | Git 备份，增量同步 |
| **同步失败** | 中 | 中 | 错误日志，回滚机制 |

### 5.2 回滚机制

```powershell
# Git 回滚命令
git log --oneline -10  # 查看最近 10 次提交
git reset --hard HEAD~1  # 回滚到上一次提交
git reflog  # 查看所有提交历史
```

---

## 六、成功标准

### 6.1 定量指标

| 指标 | 目标值 | 测量方法 |
|------|--------|---------|
| 概念页同步率 | 100% (12/12) | `Get-ChildItem wiki\*_from_homewiki.md | Measure-Object` |
| 实体页同步率 | 100% (~5/~5) | 人工检查 + grep |
| raw/ 去重率 | 100% | 哈希值比对 |
| Lint 错误率 | 0% | 运行 lint 脚本 |
| Wikilink 断链数 | 0 | 运行断链检测 |

### 6.2 定性标准

- [ ] 所有同步内容符合目标仓库 Frontmatter 规范
- [ ] 所有 claims 正确转换为 `[raw:文件名:行号]` 格式
- [ ] 所有 Wikilink 可正常跳转
- [ ] 索引页面更新完成，包含新内容
- [ ] 日志记录完整，可追溯操作历史

---

## 七、时间表

| 阶段 | 任务 | 时间 | 产出 |
|------|------|------|------|
| Week 1 | 准备工作（映射表、转换器） | 5 天 | `sync-mapping.json`, `convert-frontmatter.py` |
| Week 2 | 核心内容同步（概念、实体） | 5 天 | 12 概念页 + ~5 实体页 |
| Week 3 | 原始来源同步（raw/ 去重、claims 转换） | 5 天 | 48 raw 文件，claims 转换 |
| Week 4 | 其他内容同步（Daily, Templates, Tools） | 5 天 | Daily, Templates, Tools 同步完成 |
| Week 5 | 验证与优化（Lint, 交叉引用, 日志） | 5 天 | Lint 通过，索引更新，日志追加 |

**总计**：5 周（35 个工作日）

---

## 八、后续维护

### 8.1 日常维护任务

- **每日**：运行 `tools/sync/daily-sync.ps1`（同步 Daily/）
- **每周**：运行 `tools/sync/weekly-sync.py`（同步新增内容）
- **每月**：运行 Lint 检查 + 去重 + 索引更新

### 8.2 定期审查

- **每季度**：审查同步脚本的有效性，更新映射表
- **每半年**：评估同步策略，优化自动化程度
- **每年**：评估仓库结构，调整同步方向（单向→双向）

---

## 九、总结

### 9.1 可行性结论 ✅ **高度可行**

1. **技术兼容**：两个仓库底层技术栈一致（Obsidian + Markdown + Git）
2. **内容互补**：home-wiki 专注"高等教育 AI"，与目标仓库高度互补
3. **风险可控**：通过转换器、Lint 检查、回滚机制，风险可控
4. **收益明确**：统一知识库，减少维护负担，提高知识积累效率

### 9.2 关键成功因素

1. **提前规划**：映射表、转换器、冲突处理策略
2. **自动化脚本**：减少人工操作，降低错误率
3. **增量同步**：避免一次性大规模迁移，降低风险
4. **验证机制**：Lint 检查、交叉引用、日志记录

### 9.3 下一步行动

1. **立即行动**：创建 `tools/sync-mapping.json` 映射表
2. **本周任务**：开发 `convert-frontmatter.py` 转换器
3. **下周任务**：开始核心内容同步（概念页）

---

*本方案由 opencode 生成，日期：2026-06-30*