ljskill-knowledge

name	ljskill-knowledge
description	将散落的 Markdown 笔记转化为结构化、可检索的知识 Wiki。支持六层模型（M1-M5 + P-index）提取、知识图谱构建、领域自动发现、Obsidian 兼容输出。适用场景：搭建个人知识库、整理笔记成体系、构建第二大脑、将碎片文章结构化。触发方式：/ljskill-knowledge、/构建wiki知识库

知识库构建器

将散落的 Markdown 笔记转化为结构化、可检索的知识 Wiki。系统从文章中提取六层模型（M1-M5 + P-index），自动发现领域分类，构建知识图谱，输出 Obsidian 可直接使用的 Wiki。

核心原则

AI 全托管，用户只回答问题。

你是执行者。所有命令由你运行，所有质量由你判断，所有决策由你做。用户只需要提供素材位置和项目名称，其余全部交给你。

交互流程

第一步：收集信息

向用户询问（只需这两个）：

1. 你的 Markdown 文件在哪里？（文件夹路径）
2. 知识库叫什么名字？（项目名称）

如果用户给的路径是相对路径，直接使用；如果是绝对路径，也直接使用。脚本支持任意路径。

第二步：环境检查

自动检查依赖，缺什么就帮用户装：

python3 --version          # 需要 3.8+
python3 -c "import yaml"   # 需要 PyYAML
claude --version           # 需要 Claude CLI

• PyYAML 缺失 → 运行 pip3 install pyyaml
• Claude CLI 缺失 → 提示用户安装：npm install -g @anthropic-ai/claude-cli
• Python 版本过低 → 提示用户升级

第三步：生成配置

运行初始化脚本生成 config.yaml：

python3 <skill路径>/scripts/init_config.py --name "用户给的名字" --source "用户给的路径"

第四步：全托管构建

依次执行以下步骤。每步执行后，你自动判断质量，决定是否继续。

4.1 审计

python3 <skill路径>/scripts/audit.py --config config.yaml

自动判断：

• 文件 < 10 篇或字数 < 2 万 → 告诉用户"素材太少，建议补充到至少 10 篇"，暂停等待
• 平均文件 < 200 字 → 告诉用户"短文提取效果差，建议合并短文"，暂停等待
• 空文件 > 30% → 告诉用户"空文件太多，建议清理"，暂停等待
• 其他情况 → 继续

4.2 扫描

python3 <skill路径>/scripts/scan_corpus.py --config config.yaml

4.3 试跑 + 自动质量审查

python3 <skill路径>/scripts/extract_m1m4.py --round 1 --limit 10 --config config.yaml

自动审查（打开 wiki/_meta/m1m4-round1-raw.yaml）：

• 定义是否 < 30 字、一句话本质？
• 规则是否可证伪？（"要努力"是鸡汤，"投入产出比 >1"是规则）
• 场景是否具体？（"永远适用"不算，"创业初期、资金有限"才算）
• 各层级是否都有产出？

自动决策：

• 质量达标（大部分定义精准、规则可证伪、场景具体）→ 继续全量提取
• 质量不佳（定义模糊、规则是鸡汤、场景太泛）→ 直接修改 <skill路径>/scripts/extract_m1m4.py 中的 ROUND1_SYSTEM Prompt，增加约束（如"定义不超过 30 字""规则必须可证伪""场景必须具体"），然后重新试跑 10 篇，最多重试 2 次
• 重试 2 次仍不佳 → 告诉用户"素材质量较低，提取效果有限"，询问是否继续

4.4 全量提取

python3 <skill路径>/scripts/extract_m1m4.py --round 1 --config config.yaml
python3 <skill路径>/scripts/extract_m1m4.py --direct --config config.yaml

逐篇处理，100 篇约 30-60 分钟。中途断了重新运行即可，已处理的自动跳过。

4.5 生成知识卡片

python3 <skill路径>/scripts/generate_cards.py --config config.yaml
python3 <skill路径>/scripts/add_related_articles.py --config config.yaml

自动判断：领域数是否合理（5-15 个），质量评分分布。如果领域碎片化（20+ 个），在 config.yaml 中设置 domain_hints（如 domain_hints: ["AI技术", "职场成长", "创业商业"]），然后重新运行卡片生成，让 Claude 按提示归类。

4.6 提取问题索引

python3 <skill路径>/scripts/generate_p_index.py --config config.yaml

4.7 构建知识图谱

python3 <skill路径>/scripts/generate_knowledge_graph.py --config config.yaml

4.8 结构化处理（编号 + wiki-link）

python3 <skill路径>/scripts/rename_with_id.py --config config.yaml
python3 <skill路径>/scripts/add_wiki_links.py --config config.yaml

4.9 生成领域页面和 MOC

python3 <skill路径>/scripts/generate_domains.py --config config.yaml
python3 <skill路径>/scripts/generate_moc.py --config config.yaml

4.10 配置 Obsidian 图谱

自动写入 .obsidian/graph.json：

{
  "search": "-path:P-索引 -path:_meta -path:QA-日志 -path:知识卡片 -path:knowledge-graph",
  "showOrphans": false,
  "hideUnresolved": true,
  "colorGroups": [
    {"query": "path:M1-概念", "color": {"a": 1, "rgb": 3066993}},
    {"query": "path:M2-方法", "color": {"a": 1, "rgb": 15105570}},
    {"query": "path:M3-规则",     
          
          
  

4.11 质量验证

python3 <skill路径>/scripts/validate_quality.py --config config.yaml

自动判断：

• M1 概念数 → 20 篇文章产出 15 个概念是好结果，200 篇产出 15 个是问题
• 领域覆盖 → 内容集中在 1-2 个领域是正常的
• 图谱连通率 → 低于 50% 需要检查匹配逻辑
• 卡片质量 → 大量 1-2 分说明内容本身质量不高

第五步：交付

向用户报告：

• 构建完成了多少个知识节点（M1 概念数、M2 方法数、M3 规则数、M4 场景数）
• 生成了多少张知识卡片
• 覆盖了哪些领域
• 图谱连通率
• 用 Obsidian 打开 wiki/ 目录即可使用

第六步：增量更新（用户触发）

当用户说"我有新文章了"或"我有新文章了，帮我更新"或类似表达时，自动执行：

SKILL=<skill所在路径>

python3 $SKILL/scripts/scan_corpus.py --incremental --config config.yaml
python3 $SKILL/scripts/extract_m1m4.py --round 1 --incremental --config config.yaml
python3 $SKILL/scripts/extract_m1m4.py --direct --config config.yaml
python3 $SKILL/scripts/generate_cards.py --incremental --config config.yaml
python3 $SKILL/scripts/generate_p_index.py --incremental --config config.yaml
python3 $SKILL/scripts/generate_knowledge_graph.py --incremental --config config.yaml
python3 $SKILL/scripts/rename_with_id.py --config config.yaml
python3 $SKILL/scripts/add_wiki_links.py --config config.yaml
python3 $SKILL/scripts/generate_domains.py --config config.yaml
python3 $SKILL/scripts/generate_moc.py --config config.yaml

只处理新增文件，中途失败不影响已有数据。

增量模式说明：

• 首次运行会自动保存 wiki/_meta/graph-state.yaml 状态文件
• 增量模式基于文件哈希对比，只处理新增或修改的节点
• 新节点会自动与现有节点匹配生成关联边
• 如需强制全量重建，使用 --full 参数：--incremental --full

增量 vs 全量适用场景：

场景	推荐方式
个人知识管理、日常维护	增量更新，快速可用
学术研究、严谨图谱	全量重建（--full）

一键流水线（备用）

如果需要手动运行全流程，可使用：

python3 <skill路径>/scripts/run_pipeline.py --config config.yaml

常用选项：

--resume    # 断点续跑（跳过已完成的步骤）
--step 3    # 从第 3 步开始
--dry-run   # 预览不执行
--no-audit  # 跳过审计

输出结构

wiki/
├── index.md                    # MOC 主入口
├── analysis.md                 # 健康报告
├── knowledge-graph.md          # Mermaid 图谱
├── knowledge-graph.yaml        # 图谱数据
├── M1-概念/                     # 核心概念（m1-001-名称.md）
├── M2-方法/                     # 方法流程（m2-001-名称.md）
├── M3-规则/                     # 原则规律（m3-001-名称.md）
├── M4-场景/                     # 适用场景（m4-001-名称.md）
├── M5-卡片/                     # 知识卡片（m5-001-标题.md）
├── P-索引/                      # 问题索引
│   ├── _index.md
│   └── problem-*.yaml
├── 知识卡片/                    # YAML 卡片（数据源）
├── 领域/                        # 领域索引页
├── QA-日志/                     # 问答日志
└── _meta/                      # 构建元数据

问题排查

参见 references/troubleshooting.md。

依赖要求

• Python 3.8+
• PyYAML（pip3 install pyyaml）
• Claude CLI（claude 命令可用）