duduexcel 0.2.0__tar.gz

duduexcel-0.2.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to duduExcel. This project uses [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-09-05
+
+### Added
+
+#### M7 — Format semantics, hidden content, embedded images (inspired by VOYAGER-Inc/excel-vision-mcp)
+- **Format semantics markers** in `read_range`: `[B]` bold, `[I]` italic, `[S]` strikethrough (cancelled),
+  `[HL:color]` highlight (needs review), `[C:color]` font color, `[M]` merged cell
+  - Markers are attached **only when formatting is actually used** — plain sheets cost zero extra tokens
+  - Includes `marker_legend` and a `formatted_view` for quick reading
+- **Hidden content handling**: hidden rows/columns skipped by default; cells referenced by visible
+  formulas are kept and tagged `[HIDDEN-REF]`; skip counts always reported (never silent)
+- **`list_images`**: lists embedded images via zero-dependency `xl/media/` scan (count, filename, size, dimensions)
+- `workbook_info` now reports merged-cell count, hidden row/col counts, and embedded image count
+- **Atomic save**: write to temp → swap, so a failed write can never corrupt the original
+- **Multi-directory sandbox**: `DUDU_EXCEL_ROOT` accepts several paths (`;` on Windows, `:` elsewhere)
+
+#### M6 — Advanced operations
+- `create_pivot` (static summary table; honestly labelled as non-interactive)
+- `add_conditional_format` (data bar, color scale, greater/less/equal, between, duplicate)
+- `compare_sheets` (keyed diff: only-in-left / only-in-right / value differences)
+- `join_sheets` (left/right/inner/outer, returns first N rows only)
+
+#### Packaging & docs
+- `LICENSE` (MIT), `MANIFEST.in`, English `README_EN.md`
+- GitHub Actions CI (Python 3.10–3.12 × Ubuntu/Windows) + build job
+- `scripts/install_libreoffice.py`, `scripts/check_libreoffice.py`, `scripts/health_check.py`
+- `docs/SUBMISSION.md` — ready-to-paste copy for MCP directories
+
+### Fixed
+- **Recalculation failed on Chinese paths** — LibreOffice cannot overwrite a file in place when the path
+  contains non-ASCII characters (`SfxBaseModel::impl_store failed: 0x4c0c`).
+  Now converts into an ASCII temp directory and moves the result back. Verified on `E:\工作类\研发\`.
+- Non-zero soffice exit now surfaces stderr instead of only reporting "file not rewritten"
+- **`_as_bool` internal helper was mistakenly decorated with `@mcp.tool()`**, registering it as a bogus
+  19th tool and polluting `tools/list`. Removed the decorator (back to 18 tools) with a guard comment.
+- `test_m34.py` adapts to environment: asserts real recalculation when LibreOffice exists,
+  degradation path when it does not
+
+## [0.1.0] — 2026-09-03
+
+### Added
+
+#### M1 — Core + safe read/write
+- `workbook_info`, `read_range` (pagination + honest truncation), `write_cells` (bulk), `revert_last_write`
+- Path sandbox (`DUDU_EXCEL_ROOT`), backup-before-write, auto rollback on failure
+
+#### M2 — Server-side analysis
+- `sheet_profile` (one call replaces a dozen probes), `filter_count`, `aggregate` (incl. `group_by`), `top_n`
+- `_meta.tokens_saved` self-reporting, equivalent Excel formulas and TSV output on results
+
+#### M3 — Formula verification
+- `recalculate` with external-link circuit breaker and file-fingerprint silent-failure guard
+- `scan_formula_errors` (7 Excel error types, honest truncation reporting)
+
+#### M4 — Chinese scenarios & charts
+- `apply_chinese_style` (YaHei headings, CJK-aware autofit, freeze panes), `set_number_format` (`¥#,##0`, `0.0%`, `0.0x`)
+- `add_chart` (bar/line/pie/scatter)
+
+#### M5 — Skill layer
+- `SKILL.md` + `references/{style,formulas,charts}.md`
+
+### Fixed
+- Type-handling crashes found by boundary probing:
+  1. `TypeError` when comparing text columns with `>`/`<` — now a readable error suggesting text operators
+  2. `TypeError: bad operand type for unary -: 'str'` when aggregating text columns with `group_by` —
+     replaced with a type-safe sort key
+
+---
+
+## Design lineage
+
+Ideas borrowed (never code) from the ecosystem:
+
+| Idea | Source |
+|---|---|
+| Server-side atomic operations ("results, not rows") | jwadow/mcp-excel |
+| `_meta.tokens_saved`, destructive-action preflight | jgravelle/jdatamunch-mcp |
+| Bulk tools, explicit "don't loop the single version" | knorq-ai/xlsx-mcp-server |
+| Path sandbox (`EXCEL_FILES_PATH`) | haris-musa/excel-mcp-server |
+| External-link breaker, honest truncation, validate-before-deliver | Anthropic official xlsx skill (Proprietary — engineering ideas only) |
+| Format semantics, hidden-content handling, embedded images, atomic save | VOYAGER-Inc/excel-vision-mcp |

duduexcel-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shine8592
+
+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.

duduexcel-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include README_EN.md
+include LICENSE
+include CHANGELOG.md
+recursive-include skill *
+recursive-exclude tests *
+recursive-exclude scripts *
+global-exclude __pycache__
+global-exclude *.py[cod]

duduexcel-0.2.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: duduexcel
+Version: 0.2.0
+Summary: Excel MCP server for AI agents: context-efficient (server-side aggregation), safe writes (atomic save + backup + rollback), format semantics (strikethrough/highlight), formula recalculation, and first-class Chinese support.
+Author: Shine8592
+License: MIT License
+        
+        Copyright (c) 2026 Shine8592
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Shine8592/duduExcel
+Project-URL: Repository, https://github.com/Shine8592/duduExcel
+Project-URL: Issues, https://github.com/Shine8592/duduExcel/issues
+Project-URL: Changelog, https://github.com/Shine8592/duduExcel/blob/main/CHANGELOG.md
+Keywords: excel,xlsx,spreadsheet,mcp,model-context-protocol,ai-agent,llm,openpyxl,pandas,automation,chinese
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: analysis
+Requires-Dist: pandas>=2.0.0; extra == "analysis"
+Provides-Extra: dev
+Requires-Dist: pandas>=2.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# 📊 duduExcel
+
+**Excel MCP server built for AI agents** — context-efficient, safe to write, and it understands what the author *meant*, not just cell values.
+
+```
+Agent ──MCP (stdio)──► duduExcel ──► openpyxl / pandas ──► .xlsx
+```
+
+*Read this in [中文](README.md)*
+
+---
+
+## Why another Excel MCP?
+
+Most Excel MCP servers make you choose between two things:
+
+| Approach | Examples | Can write? | Context-friendly? |
+|---|---|---|---|
+| Full read/write | haris-musa, knorq | ✅ | ❌ dumps whole sheets |
+| Atomic analysis | jwadow, jdatamunch | ❌ read-only | ✅ |
+| Methodology only | Anthropic's xlsx skill | ✅ (via generated code) | ✅ but relies on the model writing Python |
+
+**duduExcel does all three**: server-side aggregation (cheap), full read/write (capable), and a bundled Skill (reliable).
+
+### And it sees what others silently drop
+
+> A strikethrough row means *cancelled*. A yellow-highlighted cell means *needs review*. A pasted flowchart in `B12` holds half the spec.
+> **Every other Excel MCP flattens all of that into plain strings** — so a cancelled row looks identical to an active one.
+
+```
+# Other MCP servers
+[["Legacy export", "Cancelled"], ["Driver roll call", "Needs review"]]
+
+# duduExcel
+A3: Legacy export [S] | B3: Cancelled [S]        ← [S] = strikethrough
+A4: Driver roll call  | B4: Needs review [HL:yellow]  ← [HL:] = highlight
+```
+
+---
+
+## ✨ 18 Tools
+
+| Layer | Tools |
+|---|---|
+| **Inspect** | `workbook_info` · `sheet_profile` |
+| **Analyze** (server-side) | `filter_count` · `aggregate` · `top_n` |
+| **Read / Write** | `read_range` · `write_cells` · `revert_last_write` |
+| **Verify** ⭐ | `recalculate` · `scan_formula_errors` |
+| **Chinese** ⭐ | `apply_chinese_style` · `set_number_format` |
+| **Charts** ⭐ | `add_chart` |
+| **Advanced** | `create_pivot` · `add_conditional_format` · `compare_sheets` · `join_sheets` · `list_images` |
+
+⭐ = capabilities competitors commonly lack
+
+### Highlights
+
+- **Context-efficient by design** — `read_range` paginates (default `limit=200`) and reports `truncated` honestly. Analysis runs server-side: you get `{"sum": 575}`, not 5,000 rows. Every response carries `_meta.tokens_saved`.
+- **Format semantics** — `[B]` bold · `[I]` italic · `[S]` strikethrough (cancelled) · `[HL:color]` highlight (needs review) · `[C:color]` font color · `[M]` merged · `[HIDDEN-REF]` hidden-but-referenced. **Markers are only attached when formatting is actually used**, so plain sheets cost zero extra tokens.
+- **Hidden content, handled** — hidden rows/cols are skipped by default (an author hiding them signals they're not for review), **except** cells referenced by visible formulas, which are kept and tagged `[HIDDEN-REF]`. Skipped counts are always reported — nothing disappears silently.
+- **Embedded images** — `list_images` scans `xl/media/` with zero extra dependencies, so flowcharts pasted into cells no longer vanish.
+- **Formula recalculation** — via LibreOffice, with **external-link circuit breaker**: if a workbook has external links whose cached values were stripped by openpyxl, recalculation would turn them into `#NAME?` **and delete the links permanently**. duduExcel refuses by default and tells you why; pass `force=true` only if you accept the loss.
+- **Safe writes** — atomic save (temp file → swap), `.bak` backup before every write, auto-rollback on failure, `revert_last_write` to undo.
+- **Chinese-first** — Microsoft YaHei headings, CJK-aware column autofit (2 units per CJK char), `¥#,##0` currency, `0.0%`, `0.0x` multiples.
+
+---
+
+## 🚀 Install
+
+```bash
+pip install "duduexcel[analysis]"     # analysis extra enables pandas-backed tools
+# or run without installing:
+uvx duduexcel
+```
+
+**Requirements:** Python 3.10+. Formula recalculation (`recalculate`) additionally needs [LibreOffice](https://www.libreoffice.org/) installed; without it the tool degrades explicitly with install instructions — it never silently pretends to succeed.
+
+---
+
+## 🔌 MCP Configuration
+
+### opencode (`~/.config/opencode/opencode.jsonc`)
+
+```jsonc
+"duduexcel": {
+  "type": "local",
+  "command": ["python", "-u", "-m", "duduexcel"],
+  "enabled": true
+}
+```
+
+### Claude Desktop / Cursor / Cline
+
+```json
+{
+  "mcpServers": {
+    "duduexcel": {
+      "command": "uvx",
+      "args": ["duduexcel"]
+    }
+  }
+}
+```
+
+Restart your client after editing the config.
+
+---
+
+## 🔒 Security
+
+- **Path sandbox** — set `DUDU_EXCEL_ROOT` to one or more directories (`;` on Windows, `:` elsewhere); absolute paths and `..` traversal outside them are rejected.
+- **Atomic save** — a failed write can never corrupt your original file.
+- **Auto backup / rollback** — `.bak` before every write, auto-restore on exception, `revert_last_write` to undo.
+- **External-link circuit breaker** — refuses irreversible recalculation unless you force it.
+- **Local-first** — stdio transport; your files never leave the machine.
+
+---
+
+## ⚠️ Known Limitations (honest list)
+
+- **Interactive PivotTables are not supported.** `create_pivot` produces a **static summary table** (group-and-aggregate written back) — numerically equivalent and verified correct (e.g. East 365 / South 210), but not clickable. openpyxl cannot create real PivotTable objects (`ws._pivots` is empty).
+- ~~Conditional formatting can be written, not read~~ — **corrected**: it *can* be read. `list_conditional_formats` returns range, type, operator, thresholds, fill color, and priority (verified: 4/4 rules read back). This limitation was mistakenly copied from a competitor's README without verification.
+- **`.xlsm` macros** are preserved on read; not guaranteed on write.
+- Max **100,000 cells** per write.
+- `recalculate` needs LibreOffice (verified working on 26.8, ~4s for a typical sheet).
+
+---
+
+## 🧪 Tests
+
+```bash
+python tests/test_smoke.py       # read/write, pagination, safety
+python tests/test_m2.py          # server-side analysis
+python tests/test_m34.py         # recalc degradation + Chinese styling + charts
+python tests/test_m6.py          # pivot / conditional format / multi-sheet
+python tests/test_edge_cases.py  # regression guards for past bugs
+python tests/test_m7.py          # format semantics / hidden / images / atomic save
+python tests/test_m8_recalc.py   # real recalculation (skips if no LibreOffice)
+```
+
+---
+
+## 📚 Bundled Agent Skill
+
+`skill/duduexcel/` ships methodology the agent can auto-load:
+
+```
+SKILL.md                  # tool routing + 5 hard rules + formula constraints
+references/style.md       # financial-model color semantics, number formats
+references/formulas.md    # function allowlist, _xlfn. prefixes, 7 error types
+references/charts.md      # chart recipes and fidelity caveats
+```
+
+> Anthropic's official xlsx skill is **Proprietary** (derivative works prohibited). duduExcel borrows only its *engineering ideas* (validate-before-deliver, honest truncation, external-link breaker); all text and code are written independently.
+
+---
+
+## 🗺️ Roadmap
+
+- [x] M1 core + safe read/write
+- [x] M2 server-side analysis + token self-reporting
+- [x] M3 formula recalculation + external-link breaker
+- [x] M4 Chinese styling + charts
+- [x] M5 Skill layer
+- [x] M6 pivot / conditional format / multi-sheet joins
+- [x] M7 format semantics / hidden content / embedded images / atomic save
+- [x] Conditional-formatting reading (`list_conditional_formats`)
+- [ ] Interactive PivotTables (blocked by openpyxl)
+
+---
+
+## License
+
+MIT © Shine8592

duduexcel-0.2.0/README.md

@@ -0,0 +1,178 @@
+# 📊 duduExcel
+
+面向 AI Agent 的 Excel MCP 服务 —— **上下文高效 + 安全读写 + 中文场景 + 公式验证**。
+
+```
+Agent ──MCP(stdio)──► duduExcel ──► openpyxl/pandas ──► .xlsx
+```
+
+## 为什么又一个 Excel MCP？
+
+调研了 GitHub 上 10+ 个同类项目后，发现它们分裂成两个对立阵营，没人同时做到"能写"和"不炸上下文"：
+
+| 阵营 | 代表 | 能写 | 上下文友好 | 问题 |
+|---|---|---|---|---|
+| 读写全能型 | haris-musa、knorq | ✅ | ❌ | 整表读进上下文就爆了 |
+| 原子分析型 | jwadow、jdatamunch | ❌ 只读 | ✅ | 改不了文件 |
+| 方法论型 | Anthropic 官方 xlsx Skill | ✅（靠写代码） | ✅ | 靠 Agent 自己写 Python，不稳定 |
+
+**duduExcel：把三者优点合到一个项目** —— 服务端原子分析（省 token）+ 完整读写 + 内置方法论 Skill。
+
+## ✨ 能力（17 个工具）
+
+| 层 | 工具 | 说明 |
+|---|---|---|
+| **探查** | `workbook_info` | 表清单、行列数、文件大小 |
+| | `sheet_profile` | 列画像：类型/空值率/唯一数/Top值/统计（一次替代十几次调用） |
+| **分析** | `filter_count` | 条件计数（14 种运算符），只回传数字 |
+| | `aggregate` | sum/mean/count/… 支持分组与过滤 |
+| | `top_n` | 排行榜，只回传前 N 行 |
+| **读写** | `read_range` | 分页读取，默认 limit=200 防上下文溢出 |
+| | `write_cells` | **批量**写入，一次调用完成；`=` 开头即公式 |
+| **验证** ⭐ | `recalculate` | 公式重算 + 外链熔断（差异化，竞品多不支持） |
+| | `scan_formula_errors` | 扫描 7 类公式错误 |
+| **中文** ⭐ | `apply_chinese_style` | 微软雅黑表头、中文列宽自适应、冻结首行 |
+| | `set_number_format` | `¥#,##0` / `0.0%` / `0.0x` 等内置格式 |
+| **图表** ⭐ | `add_chart` | bar/line/pie/scatter（官方 skill 无图表指导，knorq 明确不支持） |
+| **高级** | `create_pivot` | 透视汇总表（静态，诚实标注不可交互） |
+| | `add_conditional_format` | 数据条/色阶/阈值高亮/重复值（openpyxl 原生规则） |
+| | `compare_sheets` | 两表按关键列比对，只回差异摘要 |
+| | `join_sheets` | 两表关联（left/right/inner/outer），只回前 N 行 |
+| **安全** | `revert_last_write` | 回滚最近一次写入 |
+
+⭐ = 差异化能力
+
+## 🔑 汲取的设计（附来源）
+
+| 设计点 | 来源 | 落地 |
+|---|---|---|
+| 一次调用替代 N 次试探 | jwadow `get_data_profile` | `sheet_profile` |
+| 服务端原子操作（results, not rows） | jwadow | `filter_count`/`aggregate`/`top_n` |
+| 分页 + 截断诚实报告 | jwadow、官方 `recalc.py` | `read_range` 返回 `truncated`+`hint` |
+| `_meta.tokens_saved` 自报节省 | jdatamunch | 每个分析工具的 `_meta` |
+| 结果附 Excel 公式（可复现） | jwadow | `filter_count`/`aggregate`/`top_n` |
+| TSV 输出（便于粘回 Excel） | jwadow | `aggregate`/`top_n` |
+| 批量接口，禁止循环调用 | knorq | `write_cells` |
+| 路径白名单 + 拒目录穿越 | haris-musa | `DUDU_EXCEL_ROOT` |
+| 外链熔断（不可逆保护） | 官方 `recalc.py` | `recalculate` 的 force 机制 |
+| 文件指纹防静默失败 | 官方 `recalc.py` | `recalculate` |
+| 诚实的 Limitations | knorq | 见下 |
+
+## 🚀 安装与挂载
+
+```bash
+cd duduExcel
+pip install -e ".[analysis]"     # analysis 可选（提供 pandas）
+```
+
+opencode（`~/.config/opencode/opencode.jsonc`）：
+
+```jsonc
+"duduexcel": {
+  "type": "local",
+  "command": ["<你的python路径>", "-u", "-m", "duduexcel"],
+  "enabled": true,
+  "cwd": "E:\\工作类\\研发\\duduExcel"
+}
+```
+
+其他 MCP 客户端（Claude Code / Cursor / Cline）同理，指向 `python -m duduexcel`。
+**配置改完需重启客户端生效。**
+
+## 🔒 安全
+
+- **路径白名单**：设 `DUDU_EXCEL_ROOT` 后，所有路径必须在根目录内，拒绝绝对路径与 `..` 穿越
+- **写前自动备份**：任何写入前生成 `.xlsx.bak`，备份失败则中止写入
+- **失败自动回滚**：写入异常时自动还原，不留半成品
+- **外链熔断**：检测到外链缓存丢失时拒绝重算（否则会永久破坏外链），需显式 `force=true`
+- **本地优先**：stdio 传输，文件不出本机
+
+## 🔄 汲取的新设计（第二轮调研）
+
+调研 `VOYAGER-Inc/excel-vision-mcp` 后发现一个 openpyxl 生态的普遍盲区，
+而 duduExcel 原本也有：**内嵌图片、格式语义、隐藏行列全部丢失**。
+作者用删除线表示"已取消"、黄底表示"待审阅"，而纯文本读取会把它们抹平——
+模型看到的是"字符串表格"，不是"作者想表达的意思"。
+
+已补齐：
+
+| 汲取点 | 来源 | 落地 |
+|---|---|---|
+| **格式语义标记** | excel-vision-mcp | `read_range` 返回 `[B]/[I]/[S]/[HL:色]/[C:色]/[M]`；**只在真用了格式时才附加**，朴素表零额外 token |
+| **隐藏内容智能处理** | excel-vision-mcp | 默认跳过隐藏行列（作者隐藏=不想让你看），但**被可见公式引用的隐藏单元格仍保留**并标 `[HIDDEN-REF]`；始终报告跳过数量，绝不静默丢弃 |
+| **内嵌图片不丢失** | excel-vision-mcp | 新增 `list_images`（零依赖扫描 `xl/media/`），`workbook_info` 也报告图片数 |
+| **原子保存** | excel-vision-mcp | 写临时文件成功后再替换目标，失败的写入永不损坏原文件 |
+| **多目录沙箱** | excel-vision-mcp | `DUDU_EXCEL_ROOT` 支持 `;` 分隔多个目录 |
+
+## ⚠️ 已知限制（诚实清单）
+
+- **公式重算需要 LibreOffice**：未安装时 `recalculate` 明确降级并给出安装指引（不静默假装成功）。
+  此时写入的公式无缓存值，`read_range` 读回 `None` —— 这是预期行为，非数据丢失。
+
+  ✅ **已在本机打通验证**（LibreOffice 26.8）：`recalculate` 实测 **4 秒**完成重算，
+  `=SUM(销售!C2:C7)` 正确算出 **575** 并落盘（回归测试见 `tests/test_m8_recalc.py`）。
+
+  ⚠️ **中文路径坑（已修复）**：LibreOffice 在中文路径下**原地覆盖**文件会失败
+  （`SfxBaseModel::impl_store failed: 0x4c0c`）。本实现改为先输出到纯 ASCII 临时目录再移回，
+  因此在 `E:\工作类\研发\` 这类中文路径下也能正常重算。
+- **不支持可交互透视表**：`create_pivot` 生成的是静态汇总表（数值正确且已验证，如华东 365 / 华南 210），
+  但 openpyxl 无法创建真正的 PivotTable 对象（实测 `ws._pivots` 为空），因此不可点击交互。
+- ~~条件格式只能写入不能读取~~ —— **已更正**：实测条件格式**可以完整读回**。
+  `list_conditional_formats` 能返回作用区域/类型/运算符/阈值/填充色/优先级（实测 4 条规则全部读回）。
+  此前我照抄了竞品 knorq 的 Known Limitations 而未亲自验证，这是错误的。
+- **`.xlsm` 宏**：读取保留 VBA，写入不保证
+- 单次写入上限 **10 万单元格**
+- 小表上 `_meta.tokens_saved` 节省不明显属正常（省 token 的收益随表增大而放大）
+
+## 🧪 测试
+
+```bash
+python tests/test_smoke.py       # M1 读写与分页
+python tests/test_m2.py          # M2 服务端分析
+python tests/test_m34.py         # M3 重算降级 + M4 中文样式与图表
+python tests/test_m6.py          # M6 透视表/条件格式/多表关联
+python tests/test_edge_cases.py  # 边界回归（防 BUG 复发）
+python tests/test_m7.py          # M7 格式语义/隐藏处理/图片/原子保存
+```
+
+6 个测试文件 **全部通过**，另有 **20 项 MCP stdio 端到端验证**（覆盖全部 19 个工具）。
+
+## 🧠 踩过的坑（值得记住）
+
+1. **openpyxl `read_only=True` 模式不加载行列维度** —— `ws.row_dimensions` 为空，
+   隐藏检测会**静默失效**。改为直接解析 sheet XML（零内存且准确）。
+2. **mcp 2.x 的 schema 生成器会丢弃 `str | None`（PEP 604）标注的参数** ——
+   表现为"工具传了参数却不生效"。统一改用 `Optional[str]` 才正常。
+3. **图表 `Reference(range_string="B2:B5")` 要求 `表名!A1:B2` 形式** ——
+   中文表名还需引号包裹。改用 `range_boundaries()` 解析成行列参数。
+4. **重复 `@mcp.tool()` 注册同名函数**会触发 `Tool already exists` 警告且行为异常。
+
+## 📚 Skill 层
+
+`skill/duduexcel/` 提供 Agent 方法论（非 MCP 工具）：
+
+```
+SKILL.md                    # 工具路由表 + 5 条铁律 + 公式约束
+references/style.md         # 配色语义、数字格式码、结构规范
+references/formulas.md      # 函数白名单、_xlfn. 前缀、7 类错误速查
+references/charts.md        # 图表做法与保真度
+```
+
+> 合规说明：Anthropic 官方 xlsx skill 为 Proprietary（禁止衍生作品）。
+> 本 Skill 仅借鉴其**工程思想**（验证优先、截断诚实性、外链熔断），
+> 文字与代码均为独立撰写。
+
+## 🗺️ 路线图
+
+| 阶段 | 状态 |
+|---|---|
+| M1 骨架 + 安全读写 | ✅ |
+| M2 服务端分析 + token 自报 | ✅ |
+| M3 公式重算 + 外链熔断 | ✅ |
+| M4 中文样式 + 图表 | ✅ |
+| M5 Skill 层 | ✅ |
+| 透视表 / 条件格式 / 多表关联 | 待做 |
+
+## License
+
+MIT