# book2skill
**Repository Path**: li_nanqi/book2skill
## Basic Information
- **Project Name**: book2skill
- **Description**: Book2Skill 是一个本地优先的文档知识编译器。它把一次性阅读材料转换成结构化知识、来源台账和可部署 Skill,而不是简单复制全文或生成一份不可核验的摘要。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-09-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Evidence-first Book2Skill
将书籍和文档编译为可追溯、可复核、可部署的 AI Skill,而不是无法验证的摘要。
> English documentation: [README.md](README.md) · Package/CLI name: `book2skill`
[](https://github.com/lajark/evidence-first-book-to-skill-compiler/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
## 为什么需要它
把文档压缩成摘要很容易;证明每条可用结论来自哪里、能否复核,以及来源更新后如何变化,则需要明确的证据边界。Book2Skill 是一个本地优先的文档知识编译器,专门维护这条边界。
```mermaid
flowchart LR
A[源文档] --> B[证据台账
哈希 + 定位]
B --> C[结构化知识]
C --> D[质量与安全闸门]
D --> E[可部署 Agent Skill]
E --> F[审核、更新、回放]
F --> B
```
## 核心差异
| 普通文档转 Skill | Evidence-first Book2Skill |
|---|---|
| 摘要优先 | Evidence 优先 |
| 结论难以追溯 | 稳定 source ID、block locator 和 provenance |
| 黑箱输出 | AnalysisBundle、IR 和报告可审核 |
| 重建时丢失上下文 | 确定性回放与增量更新 |
| 只宣称准确 | 质量、安全和内容完整性闸门 |
四个长期承诺是 **Traceable · Reviewable · Reproducible · Updateable**。
这些能力的证据与边界见[来源追踪矩阵](TRACEABILITY_MATRIX.md)、[质量闸门](docs/QUALITY_GATES.md)
和[公开 Benchmark](docs/BENCHMARK.md)。
## 3 分钟案例
公开案例使用仓库原创短文和离线 Mock LLM,不上传源文档:
```bash
python scripts/build_public_demo.py --output-dir .workspace/tmp/public-demo --json
```
打开生成目录中的 `skill/SKILL.md`、`skill/provenance.yml`、`skill/quality-report.md` 和 `skill/content-integrity.json`,即可查看从 source/block locator 到最终 Skill 的证据链。详见[案例说明](examples/evidence-first-demo/README.md)和[Benchmark 合同](docs/BENCHMARK.md)。
## 输出内容
生成的 Skill 通常包含可执行的 `SKILL.md`、带来源的 references、provenance 清单、[质量与兼容性报告](docs/QUALITY_GATES.md)、可回放规范化边界和内容完整性证据。项目不绕过 DRM,也不会默认发布用户的版权原文;发布边界见[分发政策](DISTRIBUTION_POLICY.md)。
## 上游与架构背景
本项目参考并选择性移植了 [virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill) 的部分格式适配器;上游许可证、移植文件和 commit 记录见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 与 [docs/PROVENANCE.yml](docs/PROVENANCE.yml)。上游项目的核心体验是将书籍或文档提炼成可按需加载的 Agent Skill,并提供确定性抽取器、章节文件和多宿主使用方式。
在此基础上,Book2Skill 的工程化差异如下:
| 维度 | 上游 `book-to-skill` | Book2Skill |
|---|---|---|
| 目标 | 快速生成可使用的书籍/文档 Skill | 面向长期维护、审核和发布的知识编译管线 |
| 来源链 | 抽取内容并生成章节/Skill | 不可变 Raw、SHA-256、`source_id + block_id`、locator、provenance 回放 |
| 中间产物 | 以 Skill 文件为主 | 版本化 `AnalysisBundle`、Schema、IR、Wiki 和差异记录 |
| 更新能力 | 支持更新/fold-in 工作流 | add-only 默认策略、显式替换来源、冲突检测、事务日志、回滚和 active pointer |
| 发布质量 | Skill 规则校验 | 来源覆盖、断链、注入、路径、版权引文、Token 预算、强断言和运行时脚手架质量门 |
| 模型接入 | 由 Agent/抽取工作流使用模型 | OpenAI-compatible Adapter、profile 契约、数据发送策略、并发路由、缓存、流式指标和 fail-closed 运行清单 |
| 扩展能力 | 以 Skill/脚本扩展为主 | 公开 Extension SDK、Manifest、依赖解析、安装/升级/回滚和 typed registrar |
| 宿主部署 | 重点覆盖 Copilot CLI、Amp、Claude Code | Claude Code、TRAE、Codex/OpenAI、ChatGPT 项目目录和通用项目目录 |
| 交付方式 | 仓库中的 Agent Skill/CLI | Python 包、wheel、Schema、SDK、CLI 和可审计发布目录 |
这不是对上游项目质量的否定,而是不同的产品边界:上游擅长“提炼并使用”,Book2Skill 进一步解决“可追溯、可审核、可更新、可发布和可扩展”。
## 安装
### 系统要求
- Python 3.11 或更高版本(推荐 3.13)
- Windows、macOS 或 Linux(本次新增的桌面安装包仅面向 Windows)
- `pip` 或 `uv`
- MOBI/AZW 需要可选的 Calibre `ebook-convert`;扫描 PDF 的 OCR 需要 Tesseract
Windows 日常使用也可安装本地 WebGUI:
```powershell
python -m pip install -e ".[desktop-safe]"
book2skill-desktop
```
安装、配置、日常使用和宿主边界见
[docs/DESKTOP_GUIDE.md](docs/DESKTOP_GUIDE.md);安装器、目录、安全边界和构建方式见
[docs/DESKTOP_WINDOWS.md](docs/DESKTOP_WINDOWS.md)。本次不提供 macOS 桌面安装包。
### 从源码安装(推荐开发和本地使用)
PowerShell:
```powershell
cd D:\AI\01_Book2Skill
py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[pdf,epub,docx,html,ocr,llm,dev]"
book2skill hello
book2skill version
```
macOS/Linux/Git Bash:
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[pdf,epub,docx,html,ocr,llm,dev]"
book2skill hello
```
如果已安装 `uv`,也可以执行:
```bash
uv sync --all-extras
uv run book2skill hello
```
### 安装已构建 wheel
```powershell
python -m pip install dist\book2skill--py3-none-any.whl
book2skill version
```
只安装核心运行时时不需要可选格式依赖;按实际输入格式安装对应 extras。MOBI/AZW 不通过 pip 安装 Calibre。
## 快速使用
以下示例默认使用本地 Mock LLM,不发送文档内容到网络。
### 1. 分析文档
```bash
book2skill analyze input/my-book.pdf --json
```
输出 AnalysisBundle,并保存到默认 `output/bundles/`。分析阶段也会在 `output/workspace/` 固化 Raw、哈希和定位映射。
### 2. 一步构建 Skill
```bash
book2skill build input/my-book.pdf \
--name my-book \
--description "将文档知识转为可执行、可追溯的 Skill" \
--use-when "需要依据该文档进行判断或执行时"
```
### 3. 从审核后的 Bundle 构建
```bash
book2skill build --from-analysis output/bundles/bundle_my-book.json \
--name my-book \
--description "将文档知识转为可执行、可追溯的 Skill" \
--use-when "需要依据该文档进行判断或执行时"
```
### 4. 校验 Skill
```bash
book2skill validate output/skills/my-book
book2skill validate output/skills/my-book --write
book2skill validate output/skills/my-book --json
book2skill compatibility output/skills/my-book --write
```
校验包括 frontmatter、来源覆盖、版权引文、Prompt Injection/危险链接、Token 预算、高风险断言、运行时脚手架和证据边界。兼容报告会分别记录内部检查、可选外部工具与宿主证据。
可重放规范化边界或比较新旧 Skill 正文:
```bash
book2skill normalize output/bundles/bundle_my-book.json -o normalized-bundle.json
book2skill compare-skill-artifacts path/to/v1.0 path/to/v1.0.1 --json
```
### 5. 部署到 Agent 宿主
```bash
book2skill install output/skills/my-book --host claude
book2skill install output/skills/my-book --host codex --project-level
book2skill install output/skills/my-book --host project --project-root ./my-project
book2skill install output/skills/my-book --host claude --dry-run --json
book2skill uninstall my-book --host claude
```
### 6. 增量更新和回滚
```bash
book2skill update --data-home ./output/workspace \
--collection-id col-xxx --name my-book --use-when "..."
book2skill update --data-home ./output/workspace \
--collection-id col-xxx --confirm
book2skill update --data-home ./output/workspace --rollback
```
## 接入 OpenAI-compatible 模型(可选)
真实模型默认 fail-closed;API Key 只从环境变量、系统凭据或 `.env` 读取,不接受命令行 API Key。推荐先复制模板:
```bash
cp .env.example .env
```
Profile 方式适合多通道、路由和审计:
```bash
book2skill build input/my-book.epub \
--name my-book \
--description "..." \
--use-when "..." \
--llm-profiles llm-profiles.example.yaml \
--llm-strategy balanced \
--output-dir output/skills/my-book \
--bundle-dir output/bundles \
--data-home output/workspace \
--rights-note "user-licensed"
```
真实发送前确认:输入文档的使用权、provider 数据策略、profile 角色和 API 预算。完整配置见 [docs/LLM_CONFIG.md](docs/LLM_CONFIG.md)。
## 输入和交付物
默认目录:
```text
input/ # 用户提供的输入文档(不提交版权原文)
output/bundles/ # AnalysisBundle
output/skills// # 最终 Skill 目录
output/workspace/ # Raw / Schema / 缓存 / 发布状态
dist/book2skill--*.{whl,tar.gz} # Python 交付包
```
一个 Skill 通常包含:
```text
SKILL.md # 主 Skill 和 Workflow
references/ # 知识单元、Wiki、来源引用
provenance.yml # 来源清单和哈希
quality-report.{md,json} # 校验结果
normalized-bundle.json # 可回放、内容寻址的确定性边界
skill-design-review.json # 任务与执行边界建议
skill-fixtures.json # 触发与执行回归夹具
compatibility-report.{md,json} # 规范、工具和宿主分层证据
```
## 格式支持
| 格式 | 扩展名 | 依赖 |
|---|---|---|
| PDF | `.pdf` | `pymupdf` / `pypdf` / `pdfminer.six` |
| EPUB | `.epub` | `ebooklib` / `beautifulsoup4` |
| DOCX | `.docx` | `python-docx`(可回退到 ZIP/XML) |
| TXT / Markdown | `.txt` / `.md` | 标准库 |
| HTML | `.html` / `.htm` | `beautifulsoup4` 或标准库回退 |
| RTF | `.rtf` | 内置解析器 |
| MOBI / AZW | `.mobi` / `.azw` / `.azw3` | Calibre CLI |
不绕过 DRM,不下载盗版,不默认联网,不把特定模型或转换器设为不可替代依赖。
## 测试与质量
```bash
.venv/Scripts/pytest tests -q
.venv/Scripts/ruff check src/ tests/ scripts/
.venv/Scripts/mypy src/
.venv/Scripts/python scripts/check_provenance.py
.venv/Scripts/python -m hatchling build
```
CI 会执行受支持的 Python/OS 矩阵、测试、Lint、类型检查、来源一致性、策略扫描和交付检查;可选外部工具或平台场景会单独标注,不会伪装成核心门禁。
## 文档
- [README.md](README.md) — English guide
- [docs/LLM_CONFIG.md](docs/LLM_CONFIG.md) — LLM、profile、数据策略和路由
- [ARCHITECTURE.md](ARCHITECTURE.md) — 架构
- [SECURITY.md](SECURITY.md) — 安全策略
- [SKILL_DEPLOYMENT.md](SKILL_DEPLOYMENT.md) — 宿主部署
- [EXTENSION_SDK.md](EXTENSION_SDK.md) — Extension SDK
- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) — 第三方通知
- [docs/PROVENANCE.yml](docs/PROVENANCE.yml) — 上游来源与移植记录
## 许可证与版权边界
代码采用 MIT,见 [LICENSE](LICENSE)。项目只处理用户合法持有或有权处理的资料;第三方版权书籍生成的 Skill 不应公开发布。生成文件的版权和再分发责任由使用者承担。