Asset-aware-mcp

專案遵循 [語義化版本](https://semver.org/lang/zh-TW/)。

[Unreleased]

Added

- Added automatic mixed-format batch ingestion: `document(op="auto"/"ingest"/"import", file_paths=[...])`
now detects a batch mixing PDF with DOCX/DOC/ODT/ODS and routes it through a
single background job (`mixed_ingest_support.py` + `create_conversion_job`)
that ingests each file with its correct existing engine, isolates per-file
failures without aborting the batch, and reports `[i/N filename]` progress
via the existing `get_job_status` tool. No new public MCP tool was added
(still 30 tools / 43 endpoints).
- Added `source_engine` visibility to `inspect_document_manifest` so agents
can tell which backend (`pymupdf`/`pymupdf4llm`/`docling`/`mineru[:pipeline]`)
parsed an already-ingested document without re-reading the ingest response.

Fixed

- Fixed multi-engine output provenance so `DocumentManifest.source_engine`
and `IngestResult.backend` always carry the real engine identity instead of
being hardcoded to `marker` for every structured-engine path (Docling,
MinerU) or silently defaulting to `pymupdf` with no per-extractor
distinction. Figure/table `.source`, `segmentation.json`'s
`source_backend`, and citation-index attribution now derive from the same
authoritative field.
- Fixed Docling bbox coordinates to normalise to top-left origin (matching
PyMuPDF/Marker/MinerU) instead of passing through Docling's native
coordinate system, which can use bottom-left origin depending on the
source PDF.
- Fixed mixed-batch job result shape so `documents`/`failed_files`/`warnings`
reach the top level of `job.result` where `get_job_status` reads them,
instead of being nested under an inner `conversion` key.
- Fixed mixed-batch job failure semantics so a job is marked `FAILED` (with a
clear per-file error summary) whenever any file in the batch fails,
matching the existing PDF-only batch convention, while still preserving
every successfully ingested document.
- Fixed `get_job_status` next-step suggestions to be format-aware: DOCX
documents now suggest `docx(op="get"/"blocks"/"validate")` instead of the
PDF-only `document(op=...)` facade, which would 404 against a DOCX
`doc_id`.

Added

- Added a pluggable multi-engine PDF -> asset extraction architecture selected
via `ETL_ENGINE`: `pymupdf` (default, fast, no models), `pymupdf4llm`
(`[pdf-plus]`, drop-in layout-aware upgrade), `docling` (`[docling]`,
MIT-licensed layout+table+formula+chart engine), and `mineru` (`[mineru]`,
highest-accuracy formula-to-LaTeX/table-to-HTML engine). All three resolve
`Pillow>=12.2.0` cleanly, unlike the still-disabled `marker` backend.
- Added a cross-platform Docling installer (`scripts/setup_docling.py` plus
`.sh`/`.ps1` wrappers) that provisions an isolated `.venv-docling`
interpreter and a subprocess bridge so the main environment never needs a
direct, version-sensitive Docling install. See `docs/docling-setup.md` for
the zero-configuration install path for CLI, VS Code, and MCP agents.
- Added `StructuredPDFExtractor`, a shared protocol implemented by
Marker/Docling/MinerU so structured engines are interchangeable behind
`src/infrastructure/extractor_factory.py` and emit a Marker-compatible
result, reusing the existing ingestion pipeline without touching its logic.

Changed

- `DocumentService`'s structured-parser slot is now engine-agnostic
(`StructuredPDFExtractor` protocol) while keeping its existing parameter
name and behavior for backward compatibility with existing callers/tests.

Added

- Added structural document pointer artifacts through `document(op="pointer_index")`,
`document(op="structural_retrieve")`, and `document(op="compare")`, with
section breadcrumbs, line/char/byte locators, source hashes, asset IDs, and
evidence-span provenance.
- Added `accessibility_report.json` readiness diagnostics inside the existing
`document` facade, keeping PDF safety, native structure, coverage, and
accessibility audits artifact-only without increasing the public tool count.
- Added A2T row search/filter/coverage support through `table_data(op="query_rows")`
and citation coverage through `table_cite(op="coverage")`.

Changed

- A2T tables now persist stable row IDs, row provenance, and manifest sidecars,
and cell history now follows stable row IDs instead of drifting after row
deletion.
- Large A2T Markdown/HTML renders now use artifact-only streaming writers with
file hashes and bounded previews, preventing Cline/stdio OOM from inline
full-table strings.
- Document readiness now exposes a single v2 contract with
`status`, `blockers`, `warnings`, `capabilities`, `artifacts`,
`missing_audits`, `invalid_audits`, `audit_artifacts`, and `next_actions`,
and read-only discovery avoids creating document directories.

Fixed

- Fixed manifest path trust in readiness and structural retrieval so escaped
artifact paths cannot leak outside the canonical document directory.
- Fixed structural pointer evidence matching so stale or fabricated
`citation_index.jsonl` spans are not promoted unless doc/revision/locator
identity matches the current segmentation.
- Fixed cached audit readiness so `skipped` / `unavailable` or stale
source-revision/locator artifacts are blockers and are rebuilt by
`document(op="audit")` instead of being treated as ready.
- Fixed skipped-large-table startup UX so skipped tables remain visible with
actionable metadata and can be deleted safely.
- Fixed `row_id` citation lookups so unknown row IDs fail closed instead of
falling back to table-level citations.

Added

- Added a runtime MCP tool-surface policy with `balanced` as the default
30-tool public surface, `compact` as the 17-facade surface, and
`legacy`/`ASSET_AWARE_MCP_ENABLE_LEGACY_TOOLS=true` for full direct-tool
compatibility.
- Added the `section(...)` facade and expanded `document(...)` facade routing
for OCR, segmentation export, and layout visualization.
- Added runtime diagnostics for preferred Python, platform tags, and native
dependency import status to help debug older Windows/macOS installation
failures.

Changed

- VS Code runtime preparation now uses version-pinned `uv tool run`, handles
Windows paths with spaces safely, and tries Python 3.11 before Python 3.10 so
older machines have a fallback path.
- README, VSIX README, wiki source, GitHub Pages payload, count scripts, and
assistant harness assets now report the balanced public surface instead of
conflating public tools with the legacy decorator inventory.
- A2T table operations now validate updated cells directly, prevent duplicate
column renames, preserve persisted draft timestamps, clean up empty citation
refs, and make `table_history` friendlier for shortcut usage.

Fixed

- Fixed stale smoke/doc references to retired direct KG and section tools by
routing examples through `knowledge(...)`, `section(...)`, and the balanced
shortcuts.
- Fixed LLM wiki harness drift so bundled Cline/Codex assets stay scoped to
Asset-Aware document evidence, citation bundles, and optional KG/Foam flows.

Added

- Added shared response-size guards for MCP text, JSON, and image payloads so
large document/DFM/table/KG requests return bounded previews or artifact
references instead of flooding Cline/stdio clients.
- Added regression coverage for large MCP responses, Cline installer safety env,
VSIX-managed Copilot/Codex/Cline env preservation, subprocess worker startup,
table startup caps, and release harness drift.
- Added an optional OpenRouter fast/free preset for low-cost summaries and draft
RAG answers using `liquid/lfm-2.5-1.2b-instruct:free` via the
OpenAI-compatible OpenRouter API.

Changed

- VSIX and Cline launch specs now inject conservative safety defaults:
`ASSET_AWARE_MCP_TEXT_RESPONSE_CHARS=12000`,
`ASSET_AWARE_MCP_IMAGE_RESPONSE_CHARS=750000`, and
`ASSET_AWARE_TABLE_STARTUP_LOAD_MAX_BYTES=20971520`.
- Startup paths now avoid eager optional-heavy imports and large persisted table
loads unless explicitly needed, keeping default source/uvx launches slim.
- VSIX install smoke runtime diagnostics now run with isolated uv cache/data
directories and `--isolated`, so release checks are not polluted by a user's
global uv tool/cache state.
- VS Code settings now expose OpenRouter API key/base URL/model fields, an
OpenRouter preset button, and Ollama CPU/GPU model preset selection while
preserving custom model input.

Fixed

- Fixed Cline OOM-prone responses from simple document extraction, DFM/DOCX
reads, table resources, section tools, KG queries, job results, and citation
helpers by returning bounded content and stable artifact paths.
- Fixed VSIX-managed Copilot and Codex config updates so custom user env such as
`HTTP_PROXY` and `SSL_CERT_FILE` are preserved while stale unsafe OOM guard
values are replaced.
- Fixed release blockers from retired LLM wiki harness text and stale docs-site
version metadata.