portability.md

# Portability and credentials

The distribution contains the application and generic deployment Skill, with no developer account, private home path, registry, local book, vector database, API key or embedded model weights. The optional weight bundle is a separate asset. Application paths are discovered from the running program, the current user's data/home directories, package metadata, or explicit command options. The audited original-format SiliconFlow endpoint is a query compatibility contract; importing a package does not enable it or make its credential mandatory.

The portable baseline is import → lexical retrieval → original PDF/EPUB reads → optional image generation, with `vector-search=none`, `reranker=none` and remote query/rerank disabled. It works without a SiliconFlow key. Vector retrieval is an optional capability: `none` keeps text/source access available, `offline` uses compatible existing local query files, and `online` uses the package's approved original query service. A missing query runtime or credential does not make the book unusable. Text retrieval reports `lexical_fallback`, leaves dense scores null and does not claim semantic retrieval. A caller-supplied compatible-space query vector can reuse the stored vectors as an explicit vector operation, with unverified provenance; it does not make an arbitrary model interchangeable with the index.

A natural-language dense query still needs the original index's compatible query runtime. For a supported original format, provide its existing compatible local query-model files to use an offline adapter when available. A local path is operational configuration for that installation; it is not stored in the input manifests or baked into the program. Model files are optional external assets, subject to their own license and format checks. Never replace an unverified original query encoder with another model merely because dimensions match. When no compatible local files/runtime exist, keep lexical fallback or explicitly enable the audited original remote endpoint. An environment-variable name such as `SILICONFLOW_API_KEY` is a credential reference, not a bundled key or required account binding.

On another machine, copy the read-only knowledge package and the distribution for that operating system. Keep runtime storage outside the package and initialize using the package's new location:

```powershell
book-agent --data-dir 'D:\BookAgentData' init 'D:\Books\My Book' --reranker none
book-agent --data-dir 'D:\BookAgentData' doctor 'D:\Books\My Book'
book-agent --data-dir 'D:\BookAgentData' install-host 'D:\Books\My Book' --host codex --dry-run
book-agent --data-dir 'D:\BookAgentData' install-host 'D:\Books\My Book' --host codex
```

These are illustrative receiving-machine paths, not required directories. Content identity binds original/Markdown/database hashes, so relocating identical content preserves `book_id`. Reinitialization rebinds local paths without generating document vectors; unchanged runtime sidecars can be reused when retaining that machine's data directory. A fresh data directory creates a fresh registry/config for the same ID. Windows, macOS and Linux require their own executable build or source/runtime installation; a Windows binary is not cross-platform.

For offline vector queries, put the supported original query-model files in a chosen local directory and install/verify them separately, then select offline query execution:

```powershell
book-agent --data-dir 'D:\BookAgentData' install-query-model BOOK_ID --model-dir 'D:\Models\Original-Query-Model'
book-agent --data-dir 'D:\BookAgentData' configure BOOK_ID --vector-search offline --query-model-path 'D:\Models\Original-Query-Model'
```

`--download` is an explicit optional request when the model installer supports that original package format. A separately delivered weight package can instead be unpacked into the chosen model directory; check its hash/receipt and license before installation. No SiliconFlow credential is needed for the offline route. Copying a weight directory does not authorize arbitrary model code or establish equivalence to an unspecified hosted model revision. If weights, dependencies or model-space validation are unavailable, use `--vector-search none` and retain text/source functionality. `--vector-search online` remains optional and requires explicit endpoint consent plus its own protected credential reference.

Generate Host configuration on the receiving machine using its runtime executable and data directory. The generated MCP entry contains local argv and a registered book ID. Absolute operational paths are normal there; copying an old machine's config does not automatically relocate them. With the command installed on PATH, a generic `book-agent` executable name can be used. Credentials belong in the receiving server process environment or protected local credential store, and never in the copied Skill or Host entry. Host configuration generation does not establish a successful MCP handshake or an Agent/model visual test.

Do not distribute runtime registry/config/cache/log/deployment state as a generic release. It may contain local book paths and source excerpts. Build rules exclude `.work`, `.venv` and release staging; original copyrighted examples and model weights are excluded. Rebuild wheel, source archive and executable after code changes rather than assuming a prior artifact includes them.

`tests/test_portability.py` audits application/deployment source for private user paths and recognizable credential literals, checks available wheel/source payloads for runtime/book/model files, and inspects application code constants/filenames in the available trusted Windows executable. It also removes provider credentials and blocks networking while exercising default lexical/source access, relocation/reinit with stable identity, and separate freshly generated Codex configs in isolated machine fixtures. The frozen application code currently uses relative module filenames rather than developer home paths. Native third-party debug/build metadata is outside the application constant audit and does not select runtime accounts or locations.

This is a binding/credential hygiene audit, not a proof that every possible secret format is detectable or that a real model is offline-compatible. Local query/rerank and actual Host operations must retain their distinct validation status. No personal Host settings are changed by the portability tests.

原文 SHA-256：5e52678a1d4593a14a39c309112f911993e5fccfaf6c121624023e0771a67ecf