hehaiguang1123
a6f05ab2d5
- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
496 lines
14 KiB
Markdown
496 lines
14 KiB
Markdown
# 知识库同步可行性分析与实施计划
|
||
|
||
> **任务目标**：定期将 `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*
|