contracts.md

# Shared implementation contracts (v0.1.0)

PackageInfo dataclass: book_id, title, root, original_path, markdown_path, skill_path, database_path, archive_manifest, vector_manifest, diagnostics, file_hashes, read_only. Paths are pathlib.Path. to_dict serializable. PackageInspector().inspect(path, verify_hashes=True), PackageValidator().validate(info) -> list diagnostics; invalid required files/checksum/schema means BookAgentError. Diagnostics have code/message/severity/details. Import archive path via import_archive(path, managed_dir, limits=ArchiveLimits()) -> extracted parent; PackageInspector chooses unique root or reports ambiguity. Unknown schema explicitly unsupported; no script execution.

PrebuiltVectorStoreAdapter(database_path,manifest).inspect(),validate(),get_record(id),iter_records(),get_source_metadata(id),search(query_vector,top_k),close(). Record dataclass record_id (string), text (full), source dict, vector optional; VectorHit record/score. Core also keeps raw source and offsets.

resolve_query_runtime(package, sqlite_metadata=None) -> QueryRuntimeSpec.to_dict(); QueryRuntime(spec,config).encode_query(query) with operational compatibility status/diagnostics. Config allow_remote_requests=false by default, allowed_endpoints exactlist, auth_env string; model inherited, never user-selected or changed. Caller-supplied query_vector allowed without encoding, validate dimensions and mark query representation user-supplied compatibility unverified. No document embed APIs. Error type BookAgentError(code,message,details=None,remediation=None,available_capabilities=None), QueryRuntimeError extends.

SourceResolver(package,runtime_dir).inspect(), locate(hit_or_text,hints=None), read_source(locator,max_chars=12000), render_page(page_index,clip=None,...) returns JSON dict including actual path/image bytes optional; record locator and verification method. VisualFallbackPolicy().evaluate(query,hits,hints=None) -> dict recommended/reasons. PDF/EPUB outputs host_image_support=unknown absent realhostproof. No model interpretation.

create_reranker(config,runtime_dir), providers .rerank(query,candidates,top_n)-> dict hits/rerank_requested/rerank_applied/warnings/error; .healthcheck(), .provider_info(). candidates list hit dictionaries preserving evidence_id/record_id/text/source_locator/scores. Config provider none|siliconflow|local|custom, allow_remote_requests, allowed_endpoints, auth_env. Rerank success stores scores.rerank (not probability) + metadata; failures keep orstrict without fake applied. Never writes book package.

HostAdapter(host,home=None,data_dir=None).detect(),inspect(),plan_install(package,mcp_command,skill_dir=None),install_skill(package,...),configure_mcp(...),verify(...),uninstall(...),render_manual_instructions(...). Public high-level install(package,mcp_command,apply=False) -> plan/result; host named codex,trae,workbuddy,cherry-studio. Root CLI uses exact MCP argv [current executable or python,-m,book_agent,--data-dir,DATA,mcp,BOOK_ID]. Do not include credential literals in hostconfig; inherited processenv. Skill source shipped book_agent resources/skill path; wrappers original copied with original_hash manifest. No global host edits by agent; root actualchecks isolated orper-runhostoverride.

Core BookAgent(data_dir=None).inspect(path),init(path,reranker=none),resolve(book_ref)->registereddict containing book_id/package_root/runtime_dir/normalized packageinfo; .status(book_ref),prepare,configure,search(book_ref,query,top_k=6,strict=False,query_vector=None,hints=None),read_entry,read_markdown,get_skill,locate_source,read_source,render_page. CLI root implements argparse public subcommands and global --data-dir/--json anywhere. Runtime mutable config JSON (explicit format). Package dirs strictly unchanged. Registry atomic + crossprocess lock; sidecar/FTS ONLYruntime.

Testing uses pytest synthetic fixtures under tests/conftest.py ownedroot. Each worker may add own module fixtures inline or coordinate. New local .venv Python3.13 root installing deps. Root owns Core, lexical/fusion, CLI,MCP,metadata/build/evals/docs crossmodules. No livepipeline changes.

原文 SHA-256：a4296cd3baf586d0ec64a294fa45facb40613afcd8cfc7d62235ceff1c340133