dcc-mcp-excel 0.1.1__tar.gz

dcc_mcp_excel-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    # Headless by design: the xlsx compile + read-back gate must prove it does
+    # NOT depend on a desktop Excel installation, so it runs on Linux.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check src tests
+      - name: Pytest
+        run: pytest -q
+
+  packaging:
+    # Windows-only: dcc-mcp-cli ships as a Windows binary through the
+    # dcc-mcp-core release train (not pip), and there is no Linux build to
+    # fall back on. The headless gate above already covers the Office-free
+    # path, so Windows here adds coverage rather than gating on it.
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: CLI smoke (version + preflight must work on a clean install)
+        shell: pwsh
+        run: |
+          python -m dcc_mcp_excel._standalone_entry --version
+          python -m dcc_mcp_excel._standalone_entry preflight
+      - name: Skill lint (official dcc-mcp-cli validator)
+        shell: pwsh
+        run: |
+          # dcc-mcp-cli ships through the dcc-mcp-core release train, not pip.
+          Invoke-WebRequest -Uri "https://github.com/dcc-mcp/dcc-mcp-core/releases/download/v0.20.6/dcc-mcp-cli-windows-x86_64.exe" -OutFile "$env:RUNNER_TEMP\dcc-mcp-cli.exe"
+          & "$env:RUNNER_TEMP\dcc-mcp-cli.exe" lint src/dcc_mcp_excel/skills --warnings-as-errors --non-interactive

dcc_mcp_excel-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,97 @@
+name: Release
+
+# Automated releases via release-please (conventional commits), mirroring
+# dcc-mcp-office's release flow.
+#
+# Every push to main runs release-please, which keeps a release PR up to date.
+# When that PR is merged, release-please creates the GitHub release and tag;
+# this workflow publishes the wheel to PyPI from that exact tag after
+# verifying the tag, the manifest and pyproject.toml agree on one version.
+#
+# No standalone binary job on purpose: dcc-mcp-excel is a headless,
+# Office-free adapter (ADR 004) and ships the same wheel to every platform.
+# The PyOxidizer bundle in dcc-mcp-powerpoint exists to carry the Windows-only
+# C# COM host; nothing here needs it.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          # A PAT (user-owned) is required: PRs opened with the default
+          # GITHUB_TOKEN do not trigger pull_request workflows, so CI would
+          # never run on release PRs.
+          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [release-please]
+    if: needs.release-please.outputs.release_created == 'true'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dcc-mcp-excel
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Verify release identity and version
+        env:
+          EXPECTED_VERSION: ${{ needs.release-please.outputs.tag_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
+            echo "Release target must be a canonical vMAJOR.MINOR.PATCH tag." >&2
+            exit 1
+          }
+          export EXPECTED_VERSION="${RELEASE_TAG#v}"
+          python - <<'PY'
+          import json
+          import os
+          import re
+          from pathlib import Path
+
+          expected = os.environ["EXPECTED_VERSION"]
+          manifest = json.loads(Path(".release-please-manifest.json").read_text(encoding="utf-8"))["."]
+          source = Path("pyproject.toml").read_text(encoding="utf-8")
+          match = re.search(r'^version = "([0-9]+\.[0-9]+\.[0-9]+)"', source, re.MULTILINE)
+          if match is None or manifest != expected or match.group(1) != expected:
+              raise SystemExit("Checked-out package version does not match the release target.")
+          PY
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Publish to PyPI with trusted publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          verbose: true
+          print-hash: true

dcc_mcp_excel-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+*.egg-info/
+.idea/
+.vscode/

dcc_mcp_excel-0.1.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.1"
+}

dcc_mcp_excel-0.1.1/AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md — dcc-mcp-excel
+
+> Progressive disclosure: this file is a **map**, not an encyclopedia.
+
+## 30-Second Summary
+
+`dcc-mcp-excel` is the **thin Excel adapter** over `dcc-mcp-office`. It owns
+Excel application semantics only: workbook generation from structured data,
+the headless XLSX compile + read-back path, capability grading and the
+office-host launcher. Shared machinery (protocol, IR envelope, C# COM
+runtime, jobs, security policy) comes from `dcc-mcp-office` + `dcc-mcp-core`.
+
+**Current status:** v0.1.0 — headless path live. Workbook IR → Open XML
+compile → read-back verification runs end to end with **no Excel
+installation**, and the gate runs on a Linux runner in CI. Native
+recalculation, chart/pivot rendering and PDF export are `host_limited`:
+declared, graded, and never claimed as verified.
+
+## Repo Map
+
+| Path | What it is |
+|---|---|
+| `src/dcc_mcp_excel/workbook_ir.py` | Workbook IR contract (mirrors dcc-mcp-office-ir) |
+| `src/dcc_mcp_excel/workbook_io.py` | shared write/read helpers (titles, value comparison) |
+| `src/dcc_mcp_excel/compiler.py` | headless Open XML compiler: Workbook IR → XLSX (openpyxl) |
+| `src/dcc_mcp_excel/readback.py` | write-then-read-back verification (the 1.0 gate) |
+| `src/dcc_mcp_excel/capabilities.py` | verified / host_limited / unimplemented grading |
+| `src/dcc_mcp_excel/host_matrix.py` | host matrix + preflight self-check |
+| `src/dcc_mcp_excel/com_export.py` | desktop COM PDF export (pywin32, Windows only) |
+| `src/dcc_mcp_excel/host_client.py` | stdlib-only JSON-RPC client for the shared office host |
+| `src/dcc_mcp_excel/server_launcher.py` | registers the bundled skills with `dcc-mcp-server` |
+| `src/dcc_mcp_excel/skills/excel-workbook/` | SKILL.md + tools.yaml + scripts (generate/validate/inspect) |
+| `src/dcc_mcp_excel/skills/excel-capabilities/` | capability report + preflight scripts |
+| `examples/` | shot-list Workbook IR + generated XLSX |
+| `tests/` | pytest (headless; COM only via subprocess boundary) |
+| `docs/adr/` | adapter-level decisions |
+
+## Upstream Dependencies
+
+- `dcc-mcp-core` (pip) — gateway, skills runtime, sidecar lifecycle.
+- `dcc-mcp-office` — Rust crates (`dcc-mcp-office-protocol`,
+  `dcc-mcp-office-ir`, `dcc-mcp-office-tools`) + the `office-host` runtime.
+
+## Capabilities owned here
+
+- `workbook.compile` — Workbook IR → XLSX (headless) → read-back verification.
+- `workbook.read_back` — reopen the artifact and compare every cell.
+- `excel.workbook.calculate` / `excel.chart.generate` / `excel.pivot.refresh`
+  — `host_limited` in v0.1.0 (COM backend not wired).
+- Graph Workbook sessions (proposal §6.3) — out of scope; needs Azure app
+  registration and tenant consent.
+
+## Dependency policy
+
+- **Package import is stdlib-only.** openpyxl and pywin32 are **opt-in**:
+  `compiler` / `readback` import openpyxl inside the module, `com_export`
+  imports pywin32 inside the function body. A test pins this
+  (`tests/test_runtime_purity.py`).
+- One xlsx implementation only (ADR 004): no second writer inside the
+  adapter, even as a fallback. A missing shared host is reported, not worked
+  around.
+
+## Test
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+The headless gate must stay green on **Linux** — that is the proof the
+adapter does not depend on a desktop Excel installation.

dcc_mcp_excel-0.1.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.1](https://github.com/dcc-mcp/dcc-mcp-excel/compare/v0.1.0...v0.1.1) (2026-10-09)
+
+
+### Features
+
+* headless Workbook IR to XLSX adapter with read-back verification ([e83fe29](https://github.com/dcc-mcp/dcc-mcp-excel/commit/e83fe29f5baa70ba09b549b2b751ea4657d2d09d))

dcc_mcp_excel-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dcc_mcp_excel-0.1.1/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: dcc-mcp-excel
+Version: 0.1.1
+Summary: Excel adapter for the DCC-MCP ecosystem — headless Workbook IR to XLSX compile with read-back verification over the dcc-mcp-office runtime
+Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-excel
+Author-email: Long Hao <hal.long@outlook.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,dcc,excel,llm,mcp,model-context-protocol,office,xlsx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: dcc-mcp-core<1.0.0,>=0.18.2
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: pywin32>=306; (sys_platform == 'win32') and extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: headless
+Requires-Dist: openpyxl>=3.1; extra == 'headless'
+Provides-Extra: sidecar
+Requires-Dist: dcc-mcp-server>=0.17.43; extra == 'sidecar'
+Description-Content-Type: text/markdown
+
+# dcc-mcp-excel
+
+Excel adapter for the DCC-MCP ecosystem — the **thin application layer** over
+[dcc-mcp-office](https://github.com/dcc-mcp/dcc-mcp-office): structured
+workbook generation from production data, headless XLSX compilation and
+read-back verification.
+
+**Status: v0.1.0 — headless path live.** The compile pipeline runs end to end
+without Excel installed: Workbook IR (`office-ir/1.0`) → headless Open XML
+compile (openpyxl) → write-then-read-back verification → structural report.
+Skill scripts execute through the dcc-mcp gateway.
+
+Two grades of capability, and the difference is evidence:
+
+| Grade | What it means | Examples |
+|---|---|---|
+| `verified` | CI-green on a Linux runner, no Office installed | workbook compile, read-back, grid/formula/named-range/validation/conditional-format writes |
+| `host_limited` | Requires desktop Excel (COM); the artifact is valid but the value only materializes when Excel opens it | native recalculation, chart and pivot rendering, PDF export |
+
+Run `dcc-mcp-excel capabilities` (or the `excel-capabilities` skill) for the
+full graded list.
+
+<!-- dcc-mcp-coverage-pointer:start -->
+<!-- Generated from dcc-mcp-catalog.yml by scripts/generate_adapter_pointer.py in dcc-mcp/dcc-mcp-core. Do not edit by hand. -->
+## Part of the DCC-MCP host matrix
+
+**dcc-mcp-excel** — Excel adapter for DCC-MCP — headless Workbook IR to XLSX compile
+with read-back verification over the dcc-mcp-office runtime.
+
+It is one of **39 host adapters** in the DCC-MCP catalog. Every adapter speaks the same
+MCP protocol and builds on the same core runtime contract; each one exposes the tools
+its own host needs on top of that.
+
+- [All host adapters and install metadata](https://dcc-mcp.github.io/ecosystem)
+- [Host matrix on the core README](https://github.com/dcc-mcp/dcc-mcp-core#readme)
+- [Showcase](https://dcc-mcp.github.io/showcase)
+
+This block is generated from the catalog entry in
+[`dcc-mcp-catalog.yml`](https://github.com/dcc-mcp/dcc-mcp-core/blob/main/dcc-mcp-catalog.yml).
+Re-run the generator after changing the catalog.
+<!-- dcc-mcp-coverage-pointer:end -->
+
+## Why headless first
+
+The `dcc-mcp-office` shared core already ships a CI-green headless xlsx
+writer (`skills/office-generate-production-dashboard`). Building the adapter
+on that path means the 1.0 gate — host matrix, preflight self-check,
+write-then-read-back — is verifiable in CI on a plain Linux runner instead of
+depending on a licensed desktop Office install.
+
+Desktop Excel stays the path for the things only Excel can do: evaluate a
+formula, render a chart, refresh a pivot, paginate a PDF. Those are declared
+and graded `host_limited`, never claimed as verified.
+
+## Install
+
+```bash
+pip install "dcc-mcp-excel"
+# headless compilation needs the openpyxl extra:
+pip install "dcc-mcp-excel[headless]"
+```
+
+See [install.md](./install.md) for the verified live route.
+
+## Skill packs
+
+- `excel-workbook` — compile a Workbook IR into an editable XLSX, then reopen
+  it and verify every cell against the source IR; validate an IR; inventory an
+  existing workbook.
+- `excel-capabilities` — the graded capability report plus the host matrix and
+  the start-up preflight self-check.
+
+## Agent usage (via dcc-mcp-cli / gateway)
+
+1. Start the registered adapter (the launcher binds the bundled skill packs
+   and script runtime to the official `dcc-mcp-server`):
+   `dcc-mcp-excel serve`
+2. Run a skill script directly (gateway `execute_script` contract —
+   stdin JSON or CLI flags):
+   ```bash
+   python src/dcc_mcp_excel/skills/excel-workbook/scripts/generate_workbook.py \
+     --input examples/shot_list.json --out out
+   ```
+3. Validate the packs with the official linter:
+   ```bash
+   dcc-mcp-cli lint src/dcc_mcp_excel/skills --warnings-as-errors --non-interactive
+   ```
+
+## From production tracking to a spreadsheet
+
+`dcc-mcp-fpt` reads Flow Production Tracking; this adapter turns what it
+returns into something you can send. `tests/test_e2e.py` pins that chain with
+a real `find_entities` payload: entities → Workbook IR → XLSX → read-back.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+## License
+
+MIT

dcc_mcp_excel-0.1.1/README.md

@@ -0,0 +1,105 @@
+# dcc-mcp-excel
+
+Excel adapter for the DCC-MCP ecosystem — the **thin application layer** over
+[dcc-mcp-office](https://github.com/dcc-mcp/dcc-mcp-office): structured
+workbook generation from production data, headless XLSX compilation and
+read-back verification.
+
+**Status: v0.1.0 — headless path live.** The compile pipeline runs end to end
+without Excel installed: Workbook IR (`office-ir/1.0`) → headless Open XML
+compile (openpyxl) → write-then-read-back verification → structural report.
+Skill scripts execute through the dcc-mcp gateway.
+
+Two grades of capability, and the difference is evidence:
+
+| Grade | What it means | Examples |
+|---|---|---|
+| `verified` | CI-green on a Linux runner, no Office installed | workbook compile, read-back, grid/formula/named-range/validation/conditional-format writes |
+| `host_limited` | Requires desktop Excel (COM); the artifact is valid but the value only materializes when Excel opens it | native recalculation, chart and pivot rendering, PDF export |
+
+Run `dcc-mcp-excel capabilities` (or the `excel-capabilities` skill) for the
+full graded list.
+
+<!-- dcc-mcp-coverage-pointer:start -->
+<!-- Generated from dcc-mcp-catalog.yml by scripts/generate_adapter_pointer.py in dcc-mcp/dcc-mcp-core. Do not edit by hand. -->
+## Part of the DCC-MCP host matrix
+
+**dcc-mcp-excel** — Excel adapter for DCC-MCP — headless Workbook IR to XLSX compile
+with read-back verification over the dcc-mcp-office runtime.
+
+It is one of **39 host adapters** in the DCC-MCP catalog. Every adapter speaks the same
+MCP protocol and builds on the same core runtime contract; each one exposes the tools
+its own host needs on top of that.
+
+- [All host adapters and install metadata](https://dcc-mcp.github.io/ecosystem)
+- [Host matrix on the core README](https://github.com/dcc-mcp/dcc-mcp-core#readme)
+- [Showcase](https://dcc-mcp.github.io/showcase)
+
+This block is generated from the catalog entry in
+[`dcc-mcp-catalog.yml`](https://github.com/dcc-mcp/dcc-mcp-core/blob/main/dcc-mcp-catalog.yml).
+Re-run the generator after changing the catalog.
+<!-- dcc-mcp-coverage-pointer:end -->
+
+## Why headless first
+
+The `dcc-mcp-office` shared core already ships a CI-green headless xlsx
+writer (`skills/office-generate-production-dashboard`). Building the adapter
+on that path means the 1.0 gate — host matrix, preflight self-check,
+write-then-read-back — is verifiable in CI on a plain Linux runner instead of
+depending on a licensed desktop Office install.
+
+Desktop Excel stays the path for the things only Excel can do: evaluate a
+formula, render a chart, refresh a pivot, paginate a PDF. Those are declared
+and graded `host_limited`, never claimed as verified.
+
+## Install
+
+```bash
+pip install "dcc-mcp-excel"
+# headless compilation needs the openpyxl extra:
+pip install "dcc-mcp-excel[headless]"
+```
+
+See [install.md](./install.md) for the verified live route.
+
+## Skill packs
+
+- `excel-workbook` — compile a Workbook IR into an editable XLSX, then reopen
+  it and verify every cell against the source IR; validate an IR; inventory an
+  existing workbook.
+- `excel-capabilities` — the graded capability report plus the host matrix and
+  the start-up preflight self-check.
+
+## Agent usage (via dcc-mcp-cli / gateway)
+
+1. Start the registered adapter (the launcher binds the bundled skill packs
+   and script runtime to the official `dcc-mcp-server`):
+   `dcc-mcp-excel serve`
+2. Run a skill script directly (gateway `execute_script` contract —
+   stdin JSON or CLI flags):
+   ```bash
+   python src/dcc_mcp_excel/skills/excel-workbook/scripts/generate_workbook.py \
+     --input examples/shot_list.json --out out
+   ```
+3. Validate the packs with the official linter:
+   ```bash
+   dcc-mcp-cli lint src/dcc_mcp_excel/skills --warnings-as-errors --non-interactive
+   ```
+
+## From production tracking to a spreadsheet
+
+`dcc-mcp-fpt` reads Flow Production Tracking; this adapter turns what it
+returns into something you can send. `tests/test_e2e.py` pins that chain with
+a real `find_entities` payload: entities → Workbook IR → XLSX → read-back.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+## License
+
+MIT

dcc_mcp_excel-0.1.1/docs/README.md

@@ -0,0 +1,6 @@
+# docs
+
+- `adr/` — adapter-level architecture decisions (single headless
+  implementation, capability grading)
+- the platform proposal itself lives in
+  `dcc-mcp-office/docs/proposals/office-automation-platform-v1.0.md`

dcc_mcp_excel-0.1.1/docs/adr/004-headless-xlsx-single-implementation.md

@@ -0,0 +1,38 @@
+# ADR 004 — 无头 xlsx 只保留一份实现，落在共享核心
+
+- **Status**: Accepted
+- **Date**: 2026-10-06
+- **Related**: dcc-mcp-office ADR-006, PIP-4281, PIP-4276
+
+## Context
+
+`dcc-mcp-office` v0.2.3 已经有一条 CI 绿的无头 xlsx 路径
+（`skills/office-generate-production-dashboard/scripts/generate_dashboard.py`，
+Python + openpyxl，在 ubuntu-latest 上跑通）。adapter 侧需要同样的能力。
+
+薄适配层是生态约定：adapter 只带应用语义，重型实现留在共享核心。如果在
+adapter 内再起一套 openpyxl writer，短期更快，长期必然语义漂移 —— 两套
+实现对同一个 Workbook IR 的边界处理（ragged rows、sheet 名长度、公式
+求值语义）迟早分叉，而 ADR 006 已明确「keeping exactly one COM
+implementation」。
+
+## Decision
+
+1. **无头 xlsx writer 只有一个**：位于 `dcc-mcp-office`（共享核心或其
+   `skills/`）。adapter 通过一个薄的 `host_client` 调它，不在仓内另起一套。
+2. **adapter 内不实现 fallback**。共享 host 缺失时 `rpc()` 返回
+   `OFFICE_HOST_NOT_FOUND` 并带上修复提示，绝不静默回退到本地 writer。
+3. **本次过渡期**：`compiler.py` 直接调 openpyxl，结构与共享核心的
+   dashboard 脚本对齐（同样的 `office-ir/1.0` envelope、同样的 A1 寻址）。
+   共享核心 `workbook.compile` capability 落地后，`compiler.py` 换成一次
+   `office.command.execute` RPC —— 调用面不变，实现位置变。
+4. **能力分级写进契约**：无头可验证的标 `verified`，只有 Excel 能做
+   （recalc / chart / pivot / PDF）标 `host_limited`，永不冒充 verified。
+
+## Consequences
+
+- 只有一份实现，语义漂移面消失。
+- CI 可以在 Linux runner 上验证 1.0 门禁（写后回读），不依赖 Office 授权。
+- 共享 host 未就绪时 adapter 的降级是显式的、可诊断的，不是静默的。
+- 过渡期 `compiler.py` 与共享脚本存在一段代码相似期；切换点被
+  `host_client.compile_workbook()` 签名固定，切换只需替换函数体。

dcc_mcp_excel-0.1.1/docs/adr/005-capability-grading.md

@@ -0,0 +1,39 @@
+# ADR 005 — 能力分级写进代码，不是写进文档
+
+- **Status**: Accepted
+- **Date**: 2026-10-06
+- **Related**: PIP-4276, PIP-4281
+
+## Context
+
+Excel 有一批能力只有装了 Excel 才成立：原生公式重算、图表渲染、数据透视
+刷新、分页 PDF 导出。无头 Open XML 路径写得出结构，但写不出这些值。
+
+如果在文档里「说明」而代码里不区分，会出现两类失败：
+
+1. agent 读 README 后向用户承诺「表里已经有算好的数」，实际是公式文本；
+2. 后续维护者把 `host_limited` 能力当成已验证能力继续往上搭。
+
+`dcc-mcp-powerpoint` 的 `render_deck` 已有先例：Office 不可用时返回显式
+reason，绝不产出假产物。
+
+## Decision
+
+1. **`capabilities.py` 是唯一分级来源**：每条能力带
+   `grade` / `summary` / `evidence` / `requires_office`，`verified` 与
+   `host_limited` 两集合不重叠（有测试钉住）。
+2. **分级可被机器读取**：`dcc-mcp-excel capabilities` 与
+   `excel-capabilities` skill 输出同一份 `dcc-mcp-capability-grade/1` JSON。
+3. **`host_limited` 能力在校验里报 warning，不报 passing check**。
+   `validate_envelope` 遇到 IR 里的 chart / pivot 只声明「已声明、未验证」，
+   不生成一条名为 chart 的绿色检查 —— 测试钉住这一点。
+4. **缺失的 desktop Excel 是报告不是失败**：`preflight()` 的 `ok` 只反映
+   无头后端，Linux runner 上不算挂。
+5. **`unimplemented` 单独一档**，用于 Graph Workbook 会话这类「评估过、
+   明确不做」的能力，避免与「还没做」混淆。
+
+## Consequences
+
+- agent 在承诺 Excel 能力前可以先查分级，而不是猜。
+- 把 `host_limited` 冒充 `verified` 会直接测试失败。
+- 新增能力必须带 evidence 字段（有测试钉住），分级无法退化成装饰。

dcc_mcp_excel-0.1.1/docs/adr/README.md

@@ -0,0 +1,6 @@
+# Architecture Decision Records
+
+| ADR | Title | Status |
+|---|---|---|
+| [004](004-headless-xlsx-single-implementation.md) | 无头 xlsx 只保留一份实现，落在共享核心 | Accepted |
+| [005](005-capability-grading.md) | 能力分级写进代码，不是写进文档 | Accepted |