bindery-cli 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af953a6d3a3f8b05cff050e4a9e7a6ced73a8bfc59a6c9269793b5f53e60cbde
-  data.tar.gz: 877069de98701d6a504b010f3268cb1f2a1ce471fc4e5b56d3ea058ec769e35d
+  metadata.gz: aa243cc79c9ba7f641f57451435e100cbad86106f3a6d9fa497dedb777c23470
+  data.tar.gz: e4719f6f1b737b87a0370ce80a3d49724c29c2a4537ed70cdfd83e6ce6f31f1a
 SHA512:
-  metadata.gz: 95295349a768fd7abb2c8c2a557391ae789b581265a07d299b9dfb617bcad57f6a902956fb53dc87dd7a8bc1bf480a390d4f28a08f0f07f4598cfb28d0f06cfc
-  data.tar.gz: c05bfa81b2fa39164c2d0d21497b1cbebb1ae090fb95f6b87590796cd58a6542b9e69531849c62a2ac7989486082c3aaf201b0b17d93f63caf4c18d328079441
+  metadata.gz: a862c3a812471a5a85d183d7fe67a8dfc43c93861a58f52402eeb2e45bb530e11b07486ba2cc8dbb8d5847d3526d4ccc4d8a697c476f0bc1c7ba2bd174ed9f00
+  data.tar.gz: 319cd5177f67fb49fe759e2cbb077af355fc61c95307efd75e076b098866fb04782812c940354f9a2b643d56234cb05397b0be570c02369927c941d632b7f0c1

data/README.md

@@ -2,9 +2,10 @@
 
 把 Markdown 公版书批量构建为 EPUB 的项目脚手架工具。
 
-- `bindery new <项目名>` 创建整套项目结构
-- `bindery generate book <id> <书名>` 为单本书生成骨架
+- `bindery init` 在当前目录初始化项目
+- `bindery new book <书名>` 新建一本书（ID 自动生成）
 - `bindery build` 调用 [Pandoc](https://pandoc.org) 批量构建 EPUB
+- `bindery validate` / `clean` / `watch` / `serve` / `status` 管理书籍与产物
 
 仅依赖 Ruby 标准库，不引入任何第三方 gem。
 
@@ -27,23 +28,47 @@ brew install pandoc
 ## 快速开始
 
 ```bash
-# 1. 创建项目
-bindery new my-books
+# 1. 创建并进入项目目录
+mkdir my-books
 cd my-books
 
-# 2. 新建一本书
-bindery generate book lunyu "论语" --author "孔子及弟子" --dynasty "先秦"
+# 2. 就地初始化项目
+bindery init
 
-# 3. 编辑 books/lunyu/chapters/ 下的章节文件
+# 3. 新建一本书（ID 自动生成，可 --id 指定；--cover 自动生成封面）
+#    也可以一步到位建好章节：bindery new book "论语" chapter 20 --author "孔子及弟子"
+#    （N = 正文章节数，封面/目录由构建自动生成）
+bindery new book "论语" --author "孔子及弟子" --dynasty "先秦" --translator "译者甲" --isbn "9781234567890" --cover
 
-# 4. 构建 EPUB
-bindery build lunyu
+# 4. （可选）卷式结构：每个卷在 EPUB 中独立成页（h2=卷名，h3=章名）
+bindery new volume <id> "学而" --chapters 5
+bindery new volume <id> "为政" --chapters 5
 
-# 批量构建所有书
+# 5. 编辑 books/<id>/chapters/ 下的章节文件
+#    （可选）单独批量创建章节：bindery new chapter <id> 10
+#    （可选）单独生成封面：bindery cover <id>
+
+# 6. 构建 EPUB
 bindery build --all
 
+# 构建前校验（不实际构建）
+bindery validate --all
+bindery build --all --check
+
+# 构建后用 epubcheck 校验
+bindery build --all --epubcheck
+
 # 查看书籍状态
 bindery status
+
+# 监听书籍目录，改动自动重建
+bindery watch
+
+# 本地启动书库站点
+bindery serve
+
+# 清理构建产物
+bindery clean --all
 ```
 
 ## 项目结构
@@ -51,11 +76,17 @@ bindery status
 ```
 my-books/
 ├── config/bindery.yml     # 项目标记文件，不要删除
-├── books/                 # 每本书一个子目录
+├── books/                 # 每本书一个子目录（ID 即目录名）
 │   └── <id>/
 │       ├── metadata.yaml  # 书籍元信息
-│       ├── cover.jpg      # 封面（可选）
-│       └── chapters/      # Markdown 章节，按文件名排序合并
+│       ├── cover.png      # 封面（可选，bindery cover 自动生成）
+│       └── chapters/      # 平铺章节，或卷目录（每卷独立成页）
+│           ├── 01-chapter.md
+│           ├── 01-学而/
+│           │   ├── 01.md
+│           │   └── 02.md
+│           └── 02-为政/
+│               └── 01.md
 ├── templates/style.css    # 全项目共用的 EPUB 样式
 ├── output/epub/           # 构建产物
 └── books.json             # 自动生成的书目索引

data/lib/bindery/book.rb

@@ -57,14 +57,38 @@ module Bindery
       dir + "chapters"
     end
 
+    # 平铺的章节文件（直接在 chapters/ 下，卷式书里通常为空）
     def chapters
       return [] unless chapters_dir.directory?
 
       chapters_dir.children.select { |f| f.file? && f.extname == ".md" }.sort
     end
 
+    # 卷目录（chapters/ 下的子目录，按文件名排序）
+    def volumes
+      return [] unless chapters_dir.directory?
+
+      chapters_dir.children.select(&:directory?).sort
+    end
+
+    def has_volumes?
+      !volumes.empty?
+    end
+
+    # 某个卷目录下的章节文件
+    def volume_chapters(vol_dir)
+      return [] unless vol_dir.directory?
+
+      vol_dir.children.select { |f| f.file? && f.extname == ".md" }.sort
+    end
+
+    # 所有章节（平铺 + 各卷内），供统计 / 校验使用
+    def all_chapters
+      (chapters + volumes.flat_map { |v| volume_chapters(v) }).sort_by(&:to_s)
+    end
+
     def valid?
-      metadata_file.file? && chapters.any?
+      metadata_file.file? && all_chapters.any?
     end
 
     def epub_output(project_root = Project.root!)
@@ -74,5 +98,14 @@ module Bindery
     def built?(project_root = Project.root!)
       epub_output(project_root).file?
     end
+
+    def cover?
+      !cover_path.nil?
+    end
+
+    def built_at(project_root = Project.root!)
+      path = epub_output(project_root)
+      path.file? ? path.mtime : nil
+    end
   end
 end

data/lib/bindery/builder.rb

@@ -9,15 +9,20 @@ module Bindery
   class Builder
     class BuildError < Bindery::Error; end
 
-    def initialize(book, project_root: Project.root!)
+    def initialize(book, project_root: Project.root!, verbose: false)
       @book = book
       @project_root = project_root
+      @verbose = verbose
     end
 
     # 返回 true/false 表示是否成功；详细错误信息可通过 #last_error 获取
     def build_epub
-      chapters = @book.chapters
-      if chapters.empty?
+      if @book.has_volumes?
+        if @book.all_chapters.empty?
+          @last_error = "#{@book.id} 的卷目录下没有任何 .md 文件"
+          return false
+        end
+      elsif @book.chapters.empty?
         @last_error = "#{@book.id} 的 chapters/ 目录下没有任何 .md 文件"
         return false
       end
@@ -26,7 +31,14 @@ module Bindery
       ensure_pandoc!
 
       Dir.mktmpdir("bindery-#{@book.id}-") do |tmp|
-        merged = merge_chapters(chapters, tmp)
+        if @book.has_volumes?
+          merged = merge_volumes(tmp)
+          split_level = 2
+        else
+          merged = merge_chapters(@book.chapters, tmp)
+          split_level = nil
+        end
+
         meta_file = write_pandoc_metadata(tmp, meta)
 
         out_dir = Project.output_dir(@project_root) + "epub"
@@ -35,6 +47,7 @@ module Bindery
 
         cmd = ["pandoc", merged.to_s, "-o", out_path.to_s,
                "--metadata-file", meta_file.to_s, "--toc"]
+        cmd += ["--split-level", split_level.to_s] if split_level
 
         css = Project.templates_dir(@project_root) + "style.css"
         cmd += ["--css", css.to_s] if css.file?
@@ -42,6 +55,7 @@ module Bindery
         cover = @book.cover_path
         cmd += ["--epub-cover-image", cover.to_s] if cover
 
+        puts "  $ #{cmd.join(' ')}" if @verbose
         run(cmd)
       end
     rescue Bindery::Error => e
@@ -53,6 +67,16 @@ module Bindery
       @last_error
     end
 
+    # 运行 epubcheck 校验单个 epub，返回 [成功?, 输出]
+    def epubcheck(path)
+      unless system("epubcheck", "--version", out: File::NULL, err: File::NULL)
+        return [false, "未安装 epubcheck（参考 https://github.com/w3c/epubcheck/releases）"]
+      end
+
+      stdout, stderr, status = Open3.capture3("epubcheck", path.to_s)
+      [status.success?, stderr.empty? ? stdout : stderr]
+    end
+
     private
 
     def ensure_pandoc!
@@ -72,15 +96,55 @@ module Bindery
       path
     end
 
+    # 卷式书：每卷生成一个 ## 卷名（h2）页，卷内章节标题降级为 h3
+    def merge_volumes(tmp_dir)
+      path = Pathname.new(tmp_dir) + "merged.md"
+      path.open("w") do |out|
+        @book.volumes.each_with_index do |vol_dir, i|
+          out.puts if i.positive?
+          name = vol_dir.basename.to_s.sub(/\A\d+-/, "")
+          out.puts "## #{name}"
+          out.puts
+          @book.volume_chapters(vol_dir).each do |chapter|
+            out.puts demote_headings(chapter.read, 2)
+            out.puts
+          end
+        end
+      end
+      path
+    end
+
+    # 把 ATX 标题降级指定级数（跳过代码围栏内部）
+    def demote_headings(text, levels)
+      in_fence = false
+      text.lines.map do |line|
+        if line =~ /^\s*(`{3,}|~{3,})/
+          in_fence = !in_fence
+          line
+        elsif in_fence
+          line
+        elsif line =~ /^(\#{1,6})(\s|$)/
+          ("#" * levels) + line
+        else
+          line
+        end
+      end.join
+    end
+
     def write_pandoc_metadata(tmp_dir, meta)
+      config = Project.config(@project_root)
       pandoc_meta = {
         "title"     => meta["title"] || @book.id,
         "author"    => meta["author"] || "佚名",
-        "lang"      => meta["lang"] || "zh-CN",
-        "rights"    => meta["rights"] || "公共领域",
-        "publisher" => meta["publisher"] || "再读经典",
+        "lang"      => meta["lang"] || config["lang"] || "zh-CN",
+        "rights"    => meta["rights"] || config["rights"] || "公共领域",
+        "publisher" => meta["publisher"] || config["publisher"] || "再读经典",
       }
       pandoc_meta["date"] = meta["dynasty"] if meta["dynasty"] && !meta["dynasty"].to_s.empty?
+      # 可选元数据：ISBN / 译者 / 分类，映射到 Pandoc 识别的字段
+      pandoc_meta["identifier"] = meta["isbn"] if meta["isbn"] && !meta["isbn"].to_s.empty?
+      pandoc_meta["contributor"] = meta["translator"] if meta["translator"] && !meta["translator"].to_s.empty?
+      pandoc_meta["subject"] = meta["category"] if meta["category"] && !meta["category"].to_s.empty?
 
       path = Pathname.new(tmp_dir) + "metadata.yaml"
       path.write(pandoc_meta.to_yaml)

data/lib/bindery/cli.rb

@@ -1,8 +1,9 @@
 require "optparse"
+require "fileutils"
 
 module Bindery
   # 命令行入口：解析子命令并分发
-  # 支持: new / generate(g) / build / status / version / help
+  # 支持: init / new book / build / clean / validate / watch / serve / status / version / help
   class CLI
     def self.start(argv)
       new.run(argv)
@@ -11,12 +12,22 @@ module Bindery
     def run(argv)
       command, *rest = argv
       case command
+      when "init"
+        cmd_init(rest)
       when "new"
         cmd_new(rest)
-      when "generate", "g"
-        cmd_generate(rest)
       when "build"
         cmd_build(rest)
+      when "clean"
+        cmd_clean(rest)
+      when "validate"
+        cmd_validate(rest)
+      when "cover"
+        cmd_cover(rest)
+      when "watch"
+        cmd_watch(rest)
+      when "serve"
+        cmd_serve(rest)
       when "status"
         cmd_status(rest)
       when "version", "-v", "--version"
@@ -38,74 +49,170 @@ module Bindery
 
     private
 
-    # ---------- bindery new <项目名> ----------
-    def cmd_new(args)
-      name = args.first
-      if name.nil? || name.empty?
-        warn "用法: bindery new <项目名>"
+    # ---------- bindery init ----------
+    def cmd_init(args)
+      unless args.empty?
+        warn "用法: bindery init（不接受参数）"
         exit 1
       end
-      Generators::ProjectGenerator.call(name)
+      Generators::ProjectGenerator.call
     end
 
-    # ---------- bindery generate book <id> <title> [选项] ----------
-    def cmd_generate(args)
+    # ---------- bindery new book|chapter|volume ... ----------
+    def cmd_new(args)
       type, *rest = args
       case type
       when "book"
-        cmd_generate_book(rest)
+        cmd_new_book(rest)
+      when "chapter"
+        cmd_new_chapter(rest)
+      when "volume"
+        cmd_new_volume(rest)
       when nil
-        warn "用法: bindery generate book <id> <书名> [--author NAME] [--dynasty 朝代] [--category 分类]"
+        warn "用法: bindery new book <书名> [chapter <章数>] [选项]"
+        warn "      bindery new chapter <book-id> <数量>"
+        warn "      bindery new volume <book-id> <卷名> [--chapters N]"
         exit 1
       else
-        warn "未知的生成器类型: #{type}（目前只支持 book）"
+        warn "未知的生成器类型: #{type}（支持 book / chapter / volume）"
+        exit 1
+      end
+    end
+
+    # ---------- bindery new chapter <book-id> <数量> ----------
+    def cmd_new_chapter(args)
+      book_id, count = args
+      if book_id.nil? || count.nil?
+        warn "用法: bindery new chapter <book-id> <数量>"
+        exit 1
+      end
+      Generators::ChapterGenerator.call(book_id, count)
+    end
+
+    # ---------- bindery new volume <book-id> <卷名> [--chapters N] ----------
+    def cmd_new_volume(args)
+      options = { chapters: 0 }
+      parser = OptionParser.new do |o|
+        o.on("--chapters N", Integer) { |v| options[:chapters] = v }
+      end
+      positional = parser.parse(args)
+      book_id, volume_name = positional
+      if book_id.nil? || volume_name.nil?
+        warn "用法: bindery new volume <book-id> <卷名> [--chapters N]"
+        exit 1
+      end
+      Generators::VolumeGenerator.call(book_id, volume_name, chapters: options[:chapters])
+    end
+
+    # ---------- bindery cover <book-id> ----------
+    def cmd_cover(args)
+      id = args.first
+      if id.nil?
+        warn "用法: bindery cover <book-id>"
         exit 1
       end
+      project_root = Project.root!
+      book = Bindery::Book.find(id, project_root)
+      path = Bindery::Cover.generate(book)
+      puts "已生成封面: #{path}"
     end
 
-    def cmd_generate_book(args)
-      options = { author: "佚名", dynasty: "", category: "" }
+    def cmd_new_book(args)
+      options = { author: "佚名", dynasty: "", category: "", translator: "", isbn: "", id: nil, cover: false }
       parser = OptionParser.new do |o|
         o.on("--author NAME") { |v| options[:author] = v }
         o.on("--dynasty NAME") { |v| options[:dynasty] = v }
         o.on("--category NAME") { |v| options[:category] = v }
+        o.on("--translator NAME") { |v| options[:translator] = v }
+        o.on("--isbn ISBN") { |v| options[:isbn] = v }
+        o.on("--id ID") { |v| options[:id] = v }
+        o.on("--cover") { options[:cover] = true }
       end
       positional = parser.parse(args)
-      id, title = positional
-      if id.nil? || title.nil?
-        warn "用法: bindery generate book <id> <书名> [--author NAME] [--dynasty 朝代] [--category 分类]"
+      title = positional.first
+      if title.nil? || title.empty?
+        warn "用法: bindery new book <书名> [chapter <章数>] [--cover] [--author NAME] [--dynasty 朝代] [--category 分类] [--translator 译者] [--isbn ISBN] [--id ID]"
         exit 1
       end
 
+      # 可选组合参数：bindery new book <书名> chapter <章数>
+      # 语义：总共 N 章（默认已含第一章，所以再补 N-1 章）
+      chapters = nil
+      unless positional[1].nil?
+        if positional[1] == "chapter"
+          chapters = positional[2].to_i
+          unless chapters.positive?
+            warn "章节数必须是正整数"
+            exit 1
+          end
+        else
+          warn "未知参数: #{positional[1]}"
+          exit 1
+        end
+      end
+
+      id = options[:id] || Generators::BookGenerator.auto_id(title)
       Generators::BookGenerator.call(
         id, title,
-        author: options[:author], dynasty: options[:dynasty], category: options[:category]
+        author: options[:author], dynasty: options[:dynasty], category: options[:category],
+        translator: options[:translator], isbn: options[:isbn]
       )
+      Generators::ChapterGenerator.call(id, chapters - 1) if chapters && chapters > 1
+      Bindery::Cover.generate(Bindery::Book.find(id)) if options[:cover]
     end
 
-    # ---------- bindery build [<id>] [--all] ----------
+    # ---------- bindery build [<id>] [--all] [--check] [--dry-run] [--verbose] ----------
     def cmd_build(args)
-      options = { all: false }
+      options = { all: false, check: false, dry_run: false, verbose: false, epubcheck: false }
       parser = OptionParser.new do |o|
         o.on("--all") { options[:all] = true }
+        o.on("--check") { options[:check] = true }
+        o.on("--dry-run") { options[:dry_run] = true }
+        o.on("--verbose") { options[:verbose] = true }
+        o.on("--epubcheck") { options[:epubcheck] = true }
       end
       positional = parser.parse(args)
 
       project_root = Project.root!
       books = options[:all] ? Bindery::Book.all(project_root) : [book_from_arg(positional.first, project_root)]
 
+      if options[:check]
+        # 仅做构建前校验，不实际调用 Pandoc
+        exit 1 unless check_books(books, project_root)
+        return
+      end
+
       if books.empty?
         warn "books/ 目录下没有任何书籍"
+        # 即使没有书也重建索引，保证 books.json 存在（供 CI / 静态站读取）
+        Index.rebuild(project_root)
+        puts "" if options[:all]
+        puts "完成：成功 0 本，失败 0 本" if options[:all]
+        return
+      end
+
+      if options[:dry_run]
+        books.each do |book|
+          puts "[#{book.id}] 将构建 → #{book.epub_output(project_root)}（#{book.all_chapters.size} 个章节）"
+        end
         return
       end
 
       success = 0
       failure = 0
       books.each do |book|
-        builder = Builder.new(book, project_root: project_root)
+        builder = Builder.new(book, project_root: project_root, verbose: options[:verbose])
         if builder.build_epub
           puts "✅ [#{book.id}] epub 构建成功"
           success += 1
+          if options[:epubcheck]
+            ok, msg = builder.epubcheck(book.epub_output(project_root))
+            if ok
+              puts "   ✅ epubcheck 通过"
+            else
+              puts "   ⚠️ epubcheck 未通过：#{msg.lines.first&.strip}"
+            end
+          end
         else
           puts "❌ [#{book.id}] epub 构建失败"
           puts "   #{builder.last_error}"
@@ -126,6 +233,118 @@ module Bindery
       Bindery::Book.find(id, project_root)
     end
 
+    # ---------- bindery clean [--all] ----------
+    def cmd_clean(args)
+      options = { all: false }
+      parser = OptionParser.new do |o|
+        o.on("--all") { options[:all] = true }
+      end
+      parser.parse(args)
+
+      project_root = Project.root!
+      epub_dir = Project.output_dir(project_root) + "epub"
+      count = 0
+      if epub_dir.directory?
+        epub_dir.children.each do |f|
+          FileUtils.rm_rf(f)
+          count += 1
+        end
+      end
+
+      if options[:all]
+        index = Project.index_file(project_root)
+        if index.file?
+          index.delete
+          count += 1
+        end
+      end
+
+      puts "清理完成：移除 #{count} 项"
+    end
+
+    # ---------- bindery validate [<id>] [--all] ----------
+    def cmd_validate(args)
+      options = { all: false }
+      parser = OptionParser.new do |o|
+        o.on("--all") { options[:all] = true }
+      end
+      positional = parser.parse(args)
+
+      project_root = Project.root!
+      books = options[:all] ? Bindery::Book.all(project_root) : [book_from_arg(positional.first, project_root)]
+      exit 1 unless check_books(books, project_root)
+    end
+
+    # 校验并打印结果，返回是否全部通过（供 validate 与 build --check 共用）
+    def check_books(books, project_root)
+      return true if books.empty?
+
+      ok = true
+      books.each do |book|
+        issues = Bindery::Validator.check(book, project_root: project_root)
+        warns  = Bindery::Validator.warnings(book, project_root: project_root)
+        if issues.empty?
+          puts "✅ [#{book.id}] 校验通过"
+          warns.each { |w| puts "   ⚠️ #{w}" }
+        else
+          ok = false
+          puts "❌ [#{book.id}] 发现问题："
+          issues.each { |i| puts "   - #{i}" }
+          warns.each { |w| puts "   ⚠️ #{w}" }
+        end
+      end
+      ok
+    end
+
+    # ---------- bindery watch [--interval SECONDS] ----------
+    def cmd_watch(args)
+      options = { interval: 2.0 }
+      parser = OptionParser.new do |o|
+        o.on("--interval SECONDS", Float) { |v| options[:interval] = v }
+      end
+      parser.parse(args)
+
+      project_root = Project.root!
+      puts "监听 books/ 变化，检测到改动会自动重建全部书籍（Ctrl-C 退出）..."
+      previous = books_fingerprint(project_root)
+      loop do
+        sleep options[:interval]
+        current = books_fingerprint(project_root)
+        next if current == previous
+
+        previous = current
+        puts "\n[#{Time.now.strftime('%H:%M:%S')}] 检测到变化，重新构建..."
+        cmd_build(["--all"])
+      end
+    rescue Interrupt
+      puts "\n已停止监听"
+    end
+
+    def books_fingerprint(project_root)
+      books_dir = Project.books_dir(project_root)
+      return nil unless books_dir.directory?
+
+      sig = []
+      Pathname.glob(books_dir + "**" + "*").each do |f|
+        sig << [f.to_s, f.mtime.to_f, f.size] if f.file?
+      end
+      sig.hash
+    end
+
+    # ---------- bindery serve [--port N] [--host H] ----------
+    def cmd_serve(args)
+      options = { port: 8000, host: "127.0.0.1" }
+      parser = OptionParser.new do |o|
+        o.on("--port N", Integer) { |v| options[:port] = v }
+        o.on("--host H") { |v| options[:host] = v }
+      end
+      parser.parse(args)
+
+      project_root = Project.root!
+      Index.rebuild(project_root) # 确保书库索引是最新的
+      Bindery::Server.new(project_root, host: options[:host], port: options[:port]).start
+    end
+
     # ---------- bindery status ----------
     def cmd_status(_args)
       project_root = Project.root!
@@ -135,16 +354,18 @@ module Bindery
         return
       end
 
-      printf("%-16s %-16s %-8s %-6s\n", "书籍ID", "标题", "章节数", "EPUB")
-      puts "-" * 50
+      printf("%-16s %-16s %-6s %-4s %-6s %-16s\n", "书籍ID", "标题", "章节数", "封面", "EPUB", "构建时间")
+      puts "-" * 66
       books.each do |book|
         printf(
-          "%-16s %-16s %-8d %-6s\n",
-          book.id, book.title, book.chapters.size,
-          book.built?(project_root) ? "✅" : "—"
+          "%-16s %-16s %-6d %-4s %-6s %-16s\n",
+          book.id, book.title, book.all_chapters.size,
+          book.cover? ? "✅" : "—",
+          book.built?(project_root) ? "✅" : "—",
+          book.built_at(project_root)&.strftime("%m-%d %H:%M") || "—"
         )
       end
-      puts "-" * 50
+      puts "-" * 66
       puts "共 #{books.size} 本书"
     end
 
@@ -153,12 +374,25 @@ module Bindery
         bindery #{Bindery::VERSION} — 再读经典项目脚手架工具
 
         用法:
-          bindery new <项目名>                              创建新项目
-          bindery generate book <id> <书名> [选项]           为项目生成一本新书
-            简写: bindery g book <id> <书名>
-            选项: --author NAME  --dynasty 朝代  --category 分类
+          bindery init                                      在当前目录初始化项目
+          bindery new book <书名> [chapter <章数>] [选项]    新建一本书（ID 自动生成）
+            可组合: chapter <章数> 一并批量创建章节（N = 正文章节数，封面/目录不计入）
+            选项: --id ID（可选） --author NAME  --dynasty 朝代  --category 分类
+                  --translator 译者  --isbn ISBN  --cover 自动生成封面
+          bindery new chapter <book-id> <数量>               批量创建章节（编号自动接续）
+          bindery new volume <book-id> <卷名> [--chapters N] 新建卷（每卷在 EPUB 中独立成页）
+          bindery cover <book-id>                           自动生成装饰性封面
           bindery build <id>                                构建单本书的 epub
           bindery build --all                               批量构建所有书
+          bindery build <id> --check                        构建前校验（不实际构建）
+          bindery build <id> --dry-run                      仅打印将构建的目标
+          bindery build <id> --verbose                      打印 pandoc 命令
+          bindery build <id> --epubcheck                    构建后用 epubcheck 校验
+          bindery validate <id>                             校验单本书
+          bindery validate --all                            校验所有书
+          bindery clean [--all]                             清理构建产物（--all 连 books.json 一起删）
+          bindery watch [--interval 秒]                      监听 books/ 自动重建
+          bindery serve [--port N] [--host H]                启动本地书库站点
           bindery status                                     查看所有书籍状态
           bindery version                                    查看版本号
       HELP