standard-book-learning

协调管理书籍学习流程，按顺序调用章节提取、笔记生成、图谱构建及导入模块，跟踪进度并生成总结报告。

Security Scan

The skill's files and instructions match its stated purpose (coordinating extraction, note generation, Cypher generation and Neo4j import), but there are incoherences — notably hardcoded Neo4j credential usage in the importer examples and missing declared credentials/dependency declarations — that warrant caution before installing or running.

Purpose & Capability

The skill name/description (book learning coordinator) aligns with the provided modules (book-extractor, note-generator, neo4j-cypher-generator, neo4j-importer) and the code implements the expected pipeline. Minor mismatch: all file paths and examples are Windows-specific (F:\book, F:\Obsidian) which reduces portability but is consistent with the described workflow.

Instruction Scope

SKILL.md instructs the agent to read local book files and write notes/progress to F:\Obsidian, and to call the four submodules in sequence — this is within the skill's purpose. The instructions do write to and read from local filesystem paths and expect a local Neo4j endpoint; that is expected for this functionality but means the skill will access user files under those paths.

Install Mechanism

There is no install spec (instruction-only), which is lower risk. The Python scripts reference external libraries (python-docx, PyPDF2, optional OCR libs) but the package/dependency list isn't declared in the registry metadata; users must install these manually. No network download/install URLs were found.

Credentials

The registry declares no required environment variables or credentials, but the neo4j-importer documentation and PowerShell examples include a plaintext password example (ConvertTo-SecureString "12358lpok" -AsPlainText -Force) and use a neo4j username. That is inconsistent: a component that connects to a database normally requires configurable credentials (env vars or config). Hardcoded passwords in docs/scripts are a security risk and indicate missing, undeclared credential handling.

Persistence & Privilege

The skill does not request always:true and does not declare system-wide config modifications. It reads and writes files under F:\Obsidian and F:\book (expected for a note-taking/import skill). Autonomous invocation is enabled by default (normal), but not combined with high privilege settings in this package.

Scan Findings in Context

[hardcoded-credential-in-doc] unexpected: The neo4j-importer markdown includes a PowerShell credential example with a plaintext password ("12358lpok"). For a Neo4j importer, credentials should be configurable (env vars or secure store); an embedded password in examples or code is disproportionate and risky.

[undeclared-dependencies] expected: The Python scripts require python-docx, PyPDF2 and optional OCR libraries, but the skill metadata has no install spec or declared dependency list. This is expected for instruction-only skills but the lack of declared dependencies increases the chance a user will run code without required packages.

What to consider before installing

What to consider before installing or running this skill: - Inspect and edit scripts before running: the neo4j importer docs include a plaintext password; search all files (including .py and .md) for any hardcoded credentials and remove them. Replace with environment variables or a secure config file. - Provide credentials securely: the skill does not declare required env vars. If you use Neo4j, configure the connection (URI, username, password) via environment variables or a secure secret store, not by editing scripts with plaintext secrets. - Run in a safe environment first: test in an isolated VM or container and point the importer at a disposable/local Neo4j instance. That avoids accidental import into production databases or exposing real data. - Be aware of filesystem access: the workflow reads from F:\book and writes to F:\Obsidian. Ensure the paths are correct and that sensitive files are not unintentionally processed. Adjust paths in code if you use a different OS or directory layout. - Install dependencies explicitly: before running, pip-install required packages (python-docx, PyPDF2, etc.). The package does not declare an install step. - If you want this skill to run autonomously, consider limiting its permissions and confirm database and file access policies. If anything looks unexpected (other hardcoded endpoints, outbound network calls, or requests for unrelated credentials), do not run the skill and ask the author for clarification. If you want, I can: (1) scan the included Python scripts for any other hardcoded secrets or external endpoints, (2) suggest specific edits to move credentials to env vars, or (3) produce a checklist to safely run this skill in a VM.

🎯 书籍学习协调技能 (Book Learning Coordinator Skill)

创建日期: 2026-03-22 版本: 1.0 用途: 协调管理书籍学习的完整流程，控制各模块顺序执行 标签: #流程管理 #学习协调 #进度跟踪

---

🎯 核心职责

作为总控模块，协调book-extractor、note-generator、neo4j-cypher-generator、neo4j-importer四个子模块的执行顺序，管理学习进度，处理异常情况，生成学习总结报告。

---

📋 完整学习流程

flowchart TB
    A[开始学习] --> B[接收书籍路径]
    B --> C[初始化学习环境]
    C --> D[调用 book-extractor]
    D --> E{章节提取成功?}
    E -->|否 | X[终止并报告错误]
    E -->|是 | F[创建笔记目录]
    F --> G[初始化进度文件]
    G --> H[遍历章节列表]
    H --> I[调用 note-generator]
    I --> J[调用 neo4j-cypher-generator]
    J --> K[调用 neo4j-importer]
    K --> L[更新进度文件]
    L --> M{还有章节?}
    M -->|是 | H
    M -->|否 | N[生成全书总结报告]
    N --> O[学习完成]

    style A fill:#e1f5fe
    style D fill:#e8f5e9
    style I fill:#fff3e0
    style J fill:#f3e5f5
    style K fill:#fce4ec
    style O fill:#c8e6c9

---

🔧 执行步骤

Step 1: 初始化学习环境

输入验证:

def validate_input(book_path):
    """
    验证书籍路径
    """
    path_pattern = r"F:\\book\\(.+)\\\.docx"
    if not re.match(path_pattern, book_path):
        raise ValueError(f"Invalid path format. Expected: F:\\book\\<book>\\<book>.docx")

    if not os.path.exists(book_path):
        raise FileNotFoundError(f"Book file not found: {book_path}")

    return True

提取书名:

def extract_book_title(book_path):
    """
    从路径提取书名
    F:\book\Security Analysis\Security Analysis.docx -> Security Analysis
    """
    import os
    book_name = os.path.basename(os.path.dirname(book_path))
    return book_name

创建笔记目录:

$notePath = "F:\Obsidian\<书名>"
if (-not (Test-Path $notePath)) {
    New-Item -ItemType Directory -Path $notePath -Force
    Write-Output "Created: $notePath"
}

---

Step 2: 初始化进度跟踪文件

进度文件路径: F:\Obsidian\<书名>\学习进度跟踪.md

进度文件模板:

# 《书名》学习进度

- **开始日期**: YYYY-MM-DD
- **总章节数**: XX 章
- **已完成**: 0/XX
- **状态**: 📖 进行中

## 章节进度

| 章节 | 标题 | 笔记文件 | Neo4j概念数 | Neo4j关系数 | 状态 | 完成时间 |
|------|------|---------|------------|------------|------|---------|
| Ch 1 | 标题 | Ch01-*.md | 0 | 0 | ⏳ | - |
| Ch 2 | 标题 | Ch02-*.md | 0 | 0 | ⏳ | - |
| ... | ... | ... | ... | ... | ... | ... |

## 执行日志

| 时间 | 章节 | 操作 | 结果 |
|------|------|------|------|
| YYYY-MM-DD HH:MM | - | 初始化 | ✅ 成功 |

---

Step 3: 调用 book-extractor

执行指令:

请调用 book-extractor 模块，提取书籍的所有章节内容。

输入参数:
- 书籍路径: <book_path>

接收输出:

{
  "book_info": {
    "title": "Security Analysis",
    "path": "F:\\book\\Security Analysis\\Security Analysis.docx",
    "total_chapters": 40
  },
  "chapters": [
    {
      "chapter": 1,
      "title": "Security Analysis: Scope and Limitations",
      "paragraphs": [...]
    },
    ...
  ]
}

处理逻辑:

• 验证章节数量 > 0
• 更新进度文件的"总章节数"
• 初始化章节进度表格

---

Step 4: 逐章学习循环

循环执行流程:

def process_chapter(chapter_data, book_title, book_info):
    """
    处理单个章节的完整学习流程
    """
    chapter_num = chapter_data['chapter']
    chapter_title = chapter_data['title']

    # 4.1 调用 note-generator
    note_result = invoke_note_generator({
        "chapter": chapter_num,
        "title": chapter_title,
        "book_title": book_title,
        "book_version": book_info.get('version', ''),
        "author": book_info.get('author', ''),
        "paragraphs": chapter_data['paragraphs']
    })

    if not note_result['success']:
        return {
            "chapter": chapter_num,
            "success": False,
            "error": "Note generation failed",
            "details": note_result.get('error')
        }

    # 4.2 调用 neo4j-cypher-generator
    cypher_result = invoke_cypher_generator({
        "book_title": book_title,
        "chapter": chapter_num,
        "concepts": note_result['concepts'],
        "relationships": note_result['relationships']
    })

    if not cypher_result['success']:
        return {
            "chapter": chapter_num,
            "success": False,
            "error": "Cypher generation failed",
            "details": cypher_result.get('error')
        }

    # 4.3 调用 neo4j-importer
    import_result = invoke_neo4j_importer({
        "book_title": book_title,
        "chapter": chapter_num,
        "batches": cypher_result['batches'],
        "total_batches": cypher_result['total_batches'],
        "total_concepts": cypher_result['total_concepts'],
        "total_relationships": cypher_result['total_relationships']
    })

    # 4.4 更新进度文件
    update_progress_file(chapter_num, {
        "note_file": note_result['note_file'],
        "concepts_count": import_result.get('imported_concepts', 0),
        "relationships_count": import_result.get('imported_relationships', 0),
        "status": "✅" if import_result['overall_success'] else "❌",
        "completed_at": datetime.now().strftime("%Y-%m-%d %H:%M")
    })

    return {
        "chapter": chapter_num,
        "success": import_result['overall_success'],
        "note_file": note_result['note_file'],
        "concepts_count": import_result.get('imported_concepts', 0),
        "relationships_count": import_result.get('imported_relationships', 0)
    }

---

Step 5: 异常处理

异常分类处理:

异常类型	章节级别处理	全局处理
book-extractor失败	N/A	终止整个流程，报告错误
note-generator失败	记录错误，跳过当前章节	继续下一章节
cypher-generator失败	记录错误，跳过当前章节	继续下一章节
neo4j-importer失败	记录错误，跳过当前章节	继续下一章节

错误记录格式:

## 错误日志

| 时间 | 章节 | 模块 | 错误信息 |
|------|------|------|---------|
| YYYY-MM-DD HH:MM | Ch 5 | note-generator | 概念提取失败: 内容为空 |
| YYYY-MM-DD HH:MM | Ch 12 | neo4j-importer | 连接超时 |

---

Step 6: 全书总结

当所有章节处理完成后，调用note-generator的全书总结模式:

输入参数:

{
  "mode": "full_book_summary",
  "book_title": "Security Analysis",
  "book_version": "6th Edition",
  "author": "Benjamin Graham",
  "total_chapters": 40,
  "completed_chapters": 38,
  "failed_chapters": 2,
  "note_files": [
    "F:\\Obsidian\\Security Analysis\\Ch01-*.md",
    "F:\\Obsidian\\Security Analysis\\Ch02-*.md",
    ...
  ],
  "total_concepts": 150,
  "total_relationships": 80,
  "start_date": "2026-03-22",
  "end_date": "2026-03-25"
}

生成报告: F:\Obsidian\<书名>\全书学习完成报告.md

---

📊 学习统计报告

生成最终统计:

## 📊 学习完成统计

| 指标 | 数值 |
|------|------|
| **书籍名称** | Security Analysis |
| **作者** | Benjamin Graham |
| **学习日期** | 2026-03-22 ~ 2026-03-25 |
| **总章节数** | 40 |
| **成功完成** | 38 (95%) |
| **失败跳过** | 2 (5%) |
| **笔记文件** | 38 个 |
| **Neo4j概念** | 150 个 |
| **Neo4j关系** | 80 个 |
| **总耗时** | ~8 小时 |

---

🔄 子模块调用接口

1. book-extractor 调用

def invoke_book_extractor(book_path):
    """
    调用书籍章节提取模块
    """
    # 指令：调用 book-extractor 模块
    # 输入：book_path
    # 输出：章节列表
    pass

2. note-generator 调用

def invoke_note_generator(chapter_data):
    """
    调用笔记生成模块
    """
    # 指令：调用 note-generator 模块
    # 输入：章节内容 + 书籍信息
    # 输出：Markdown笔记 + 概念列表
    pass

3. neo4j-cypher-generator 调用

def invoke_cypher_generator(concepts_data):
    """
    调用Cypher生成模块
    """
    # 指令：调用 neo4j-cypher-generator 模块
    # 输入：概念列表 + 关系列表
    # 输出：批次化Cypher语句
    pass

4. neo4j-importer 调用

def invoke_neo4j_importer(batches_data):
    """
    调用Neo4j导入模块
    """
    # 指令：调用 neo4j-importer 模块
    # 输入：批次列表
    # 输出：执行报告
    pass

---

✅ 质量检查清单

初始化阶段

• 书籍路径格式正确
• 文件存在且可读
• 笔记目录创建成功
• 进度文件初始化完成

执行阶段

• book-extractor成功提取所有章节
• 每个章节的三个子模块按顺序调用
• 进度文件实时更新
• 错误正确记录

总结阶段

• 所有章节处理完成
• 全书总结报告生成
• 最终统计准确
• 错误章节已标注

---

🎓 使用示例

输入:

请开始学习书籍：F:\book\Security Analysis\Security Analysis.docx

执行流程:

1. 验证路径: ✅ F:\book\Security Analysis\Security Analysis.docx
2. 提取书名: Security Analysis
3. 创建笔记目录: F:\Obsidian\Security Analysis\
4. 初始化进度文件: ✅
5. 调用 book-extractor:
   - 提取到 40 个章节
6. 逐章处理:
   - Ch 1: note-generator → cypher-generator → neo4j-importer ✅
   - Ch 2: note-generator → cypher-generator → neo4j-importer ✅
   - ...
   - Ch 40: note-generator → cypher-generator → neo4j-importer ✅
7. 生成全书总结报告: ✅
8. 输出最终统计

输出:

{
  "success": true,
  "book_title": "Security Analysis",
  "total_chapters": 40,
  "completed_chapters": 40,
  "failed_chapters": 0,
  "note_files": 40,
  "total_concepts": 150,
  "total_relationships": 80,
  "duration": "8 hours",
  "summary_file": "F:\\Obsidian\\Security Analysis\\全书学习完成报告.md",
  "progress_file": "F:\\Obsidian\\Security Analysis\\学习进度跟踪.md"
}

---

🚀 高级功能

断点续学

从指定章节继续:

def resume_from_chapter(chapter_num):
    """
    从指定章节继续学习
    """
    # 读取进度文件
    progress = read_progress_file()

    # 跳过已完成章节
    for chapter in progress['completed']:
        continue

    # 从指定章节开始处理
    for chapter in chapters[chapter_num-1:]:
        process_chapter(chapter, book_title, book_info)

批量处理

一次处理多本书籍:

def process_multiple_books(book_paths):
    """
    批量处理多本书籍
    """
    results = []
    for path in book_paths:
        result = process_book(path)
        results.append(result)

    return results

---

🔄 模块依赖关系

book-learning-coordinator (总控)
    ├── book-extractor (章节提取)
    ├── note-generator (笔记生成)
    ├── neo4j-cypher-generator (Cypher生成)
    └── neo4j-importer (Neo4j导入)

---

⚠️ 注意事项

1. 执行顺序: 必须严格按照 book-extractor → note-generator → neo4j-cypher-generator → neo4j-importer 的顺序
2. 错误隔离: 单个章节失败不应影响其他章节
3. 进度持久化: 每完成一个章节必须更新进度文件
4. 资源管理: 确保文件句柄和连接正确关闭

---

📝 进度文件更新逻辑

def update_progress_file(chapter_num, data):
    """
    更新进度文件中的章节状态
    """
    # 读取现有进度文件
    progress_content = read_file("F:\\Obsidian\\<书名>\\学习进度跟踪.md")

    # 更新对应章节行
    # 替换: | Ch 1 | ... | ⏳ | - |
    # 为: | Ch 1 | ... | ✅ | 2026-03-22 18:30 |

    # 更新完成计数
    # 替换: - **已完成**: 0/XX
    # 为: - **已完成**: 1/XX

    # 添加执行日志
    # | YYYY-MM-DD HH:MM | Ch 1 | 章节学习 | ✅ 完成 (3概念, 2关系) |

    # 保存更新后的文件
    write_file("F:\\Obsidian\\<书名>\\学习进度跟踪.md", progress_content)

---

🛠️ OpenClaw 脚本配置

脚本文件: book-learning-coordinator-script.py 脚本类型: Python 调用方式: 外部工具 角色: 流程协调器，依赖其他4个子模块脚本

执行命令

python book-learning-coordinator-script.py --book_path "<书籍路径>" [--resume] [--start_chapter N]

输入参数

{
  "book_path": "F:\\book\\Security Analysis\\Security Analysis.docx",
  "resume": false,
  "start_chapter": null,
  "neo4j_config": {
    "uri": "http://localhost:7474",
    "user": "neo4j",
    "password": "your_password"
  }
}

输出格式

{
  "success": true,
  "book_title": "Security Analysis",
  "total_chapters": 40,
  "completed_chapters": 40,
  "failed_chapters": 0,
  "note_files": 40,
  "total_concepts": 150,
  "total_relationships": 80,
  "duration": "8 hours",
  "summary_file": "F:\\Obsidian\\Security Analysis\\全书学习完成报告.md",
  "progress_file": "F:\\Obsidian\\Security Analysis\\学习进度跟踪.md",
  "execution_log": [
    {
      "timestamp": "2026-03-22T18:30:00Z",
      "chapter": 1,
      "status": "completed",
      "concepts": 3,
      "relationships": 2
    }
  ]
}

OpenClaw 调用逻辑

完整流程

1. 初始化阶段

   • 验证书籍路径存在
   • 提取书名（从文件名）
   • 创建笔记目录
   • 初始化进度文件

2. 章节提取阶段

   • 调用 book-extractor-script.py
   • 获取章节列表
   • 验证提取结果

3. 逐章处理阶段

   • 循环处理每个章节
   • 按顺序调用3个子模块脚本
   • 每完成一章更新进度
   • 错误处理和日志记录

4. 总结阶段

   • 生成全书总结报告
   • 输出最终统计
   • 标注错误章节

子模块调用序列

book-learning-coordinator
  └─→ book-extractor-script.py
       └─→ for each chapter:
            ├─→ note-generator-script.py
            │    └─→ neo4j-cypher-generator-script.py
            │         └─→ neo4j-importer-script.py
            └─→ update progress file

特殊模式

断点续学模式

python book-learning-coordinator-script.py --resume --book_path "F:\book\...\book.docx"

• 读取进度文件，跳过已完成章节
• 从中断点继续处理

指定章节开始

python book-learning-coordinator-script.py --start_chapter 15 --book_path "F:\book\...\book.docx"

• 从指定章节开始处理
• 适用于重新处理特定章节

错误处理

• 提取失败 → 终止流程，报告错误
• 章节处理失败 → 记录错误，继续下一章
• Neo4j连接失败 → 提示检查服务，可重试
• 文件权限错误 → 检查目录权限

进度监控

协调器会实时更新进度文件，用户可通过以下方式查看进度：

1. 查看 学习进度跟踪.md 文件
2. 执行日志输出到控制台
3. 错误日志单独记录

---

Book Learning Coordinator v1.0 · 2026-03-22 🎯