package-format.md

# Prebuilt package format and import

Book Agent receives an existing book package containing a PDF or EPUB, full Markdown, the original distilled Book Skill, `vector_db/vectors.sqlite3`, `vector_db/manifest.json`, `vector_db/README.md`, `vector_db/search.py`, and `archive_manifest.json`. Supporting Skill files vary by book. There is no external `chunks/` requirement and no automatic splitting, distillation or document-vector generation.

The implemented archive manifest adapter recognizes the actual pipeline v3 structure. Required fields are `archive_version: 3`, `original`, `markdown`, `skill`, `vector_db`, and a `files` path-to-metadata mapping. The real producer uses archive-root-relative paths including the outer folder. Package-root-relative paths are also accepted. An explicit v1 interchange variant uses package-root-relative paths; unknown versions receive an adapter diagnostic. The original manifest remains untouched.

Each `files` entry may declare `sha256` and `size_bytes`; when present they must match. Missing declared files, invalid JSON, required-role files or empty Book Skill content fail inspection. Nonempty legacy Skill content without valid name/description frontmatter receives an explicit warning; the host adapter can generate a compliant wrapper while preserving original bytes. Archive/vector model IDs, declared book identity and Markdown hashes are checked for conflicts. Optional locator or encoder metadata is never silently replaced with default page numbers or models. Matching file hashes establish consistency; they are not a publisher signature.

Internal book IDs hash the original file, Markdown and existing SQLite database identities. They are not derived solely from filenames or historical slugs, so two distinct book versions cannot silently share a runtime record. Path rebinding can preserve the identity when content is unchanged. More than one candidate `archive_manifest.json` requires explicit root selection; the program never chooses the first book arbitrarily.

`PackageInspector` performs static script review and returns normalized `PackageInfo`; `PackageValidator` validates the documented SQLite adapter and existing records. No module imports or automatically executes `search.py`. Source/Skill/README/manifest contents are untrusted evidence, not instructions to execute commands or reveal credentials.

Archives use content-addressed managed directories separated from the original input. ZIP extraction streams chunks; 7z uses py7zr and a bounded writer factory. Before extraction, paths, entry count, declared sizes, compression ratio, links and special files are checked. Absolute paths, `..`, Windows drives/ADS/device names, symlinks/junctions and duplicate or case-colliding paths are rejected. Extraction also enforces actual bytes against per-entry declarations and total limits. Failure removes only the checked temporary managed directory. Package scripts are retained as data and listed in the external import receipt.

Default archive limits are 10000 entries, 2 GiB total expanded data, 1 GiB per file and a 200:1 compression ratio. They can be tightened or explicitly adjusted through the library `ArchiveLimits`; oversized books receive actionable import errors. Encrypted archives are not supported. This library boundary does not make arbitrary external script execution safe; it never attempts such execution.

Original archive size, modification time and SHA-256 are checked during import. Receipts live alongside the managed tree, not inside it, and record extracted file hashes. Repeated imports of an unchanged archive reuse its verified managed directory. Concurrent imports use an exclusive per-content lock; callers retry an `import_busy` response. Input packages, SQLite files and scripts receive no caches, logs, `__pycache__` or sidecars. All normalized metadata, indexes, caches and host output belong in a separate runtime directory.

Read-only is an application behavior rather than a filesystem permission mutation: the original archive's permissions and content are never changed. SQLite WAL/SHM/journal dependencies are rejected, and the program does not repair input snapshots. Malformed or unsupported schemas remain explicit diagnostics.

Windows input paths use consistent `\\?\` extended syntax so nested archive and Skill files can exceed the legacy 260-character limit. SQLite receives a percent-encoded filename URI preserving that native syntax. Containment comparisons normalize both operands with `filesystem_path`; mixing native extended and ordinary representations would weaken overlap checks. Other platforms use ordinary absolute paths.

原文 SHA-256：5aa7150f59ab11cdee595be1e9bc08f05156e32b60017e75f696cf08c2b6382f