excel-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Excel Automation with excelcli

使用excelcli实现Excel自动化

CRITICAL RULES (MUST FOLLOW)

重要规则（必须遵守）

Rule 1: NEVER Ask Clarifying Questions

规则1：绝不询问澄清问题

Execute commands to discover the answer instead:

DON'T ASK	DO THIS INSTEAD
"Which file should I use?"	`excelcli -q session list`
"What table should I use?"	`excelcli -q table list --session <id>`
"Which sheet has the data?"	`excelcli -q sheet list --session <id>`

You have commands to answer your own questions. USE THEM.

请执行命令自行获取答案：

不要问	应执行的操作
“我应该使用哪个文件？”	`excelcli -q session list`
“我应该使用哪个表格？”	`excelcli -q table list --session <id>`
“哪个工作表包含数据？”	`excelcli -q sheet list --session <id>`

你有可以自行获取答案的命令，请使用它们。

Rule 2: Use File-Based Input for Complex Data

规则2：针对复杂数据使用基于文件的输入

PowerShell cannot reliably parse inline JSON or M code:

powershell

undefined

PowerShell无法可靠解析内联JSON或M代码：

powershell

undefined

CORRECT - Use --values-file

正确方式 - 使用--values-file

$data = '[["Name","Price"],["Widget",100]]' $data | Out-File -Encoding UTF8 C:\temp\data.json excelcli -q range set-values --session 1 --sheet Sheet1 --range A1 --values-file C:\temp\data.json

CORRECT - Use --mcode-file for Power Query

正确方式 - 针对Power Query使用--mcode-file

$mcode | Out-File -Encoding UTF8 C:\temp\query.m excelcli -q powerquery create --session 1 --query Products --mcode-file C:\temp\query.m

undefined

$mcode | Out-File -Encoding UTF8 C:\temp\query.m excelcli -q powerquery create --session 1 --query Products --mcode-file C:\temp\query.m

undefined

Rule 3: Session Lifecycle

规则3：会话生命周期

powershell

excelcli -q session open C:\path\file.xlsx     # Returns session ID
excelcli -q range set-values --session 1 ...   # Use session ID
excelcli -q session close --session 1 --save   # Save and release

Unclosed sessions leave Excel processes running, locking files.

powershell

excelcli -q session open C:\\path\\file.xlsx     # 返回会话ID
excelcli -q range set-values --session 1 ...   # 使用会话ID
excelcli -q session close --session 1 --save   # 保存并释放会话

未关闭的会话会导致Excel进程持续运行，锁定文件。

Rule 4: Data Model Prerequisites

规则4：数据模型前置条件

DAX operations require tables in the Data Model:

powershell

excelcli -q table add-to-datamodel --session 1 --table Sales  # Step 1
excelcli -q datamodel create-measure --session 1 ...          # Step 2 - NOW works

DAX操作要求表格已加入数据模型：

powershell

excelcli -q table add-to-datamodel --session 1 --table Sales  # 步骤1
excelcli -q datamodel create-measure --session 1 ...          # 步骤2 - 现在可以正常执行

Rule 5: Power Query Development Lifecycle

规则5：Power Query开发生命周期

BEST PRACTICE: Test M code before creating permanent queries

powershell

undefined

最佳实践：在创建永久查询前测试M代码

powershell

undefined

Step 1: Test M code without persisting (catches errors early)

步骤1：测试M代码但不持久化（提前捕获错误）

excelcli -q powerquery evaluate --session 1 --mcode-file query.m

Step 2: Create permanent query with validated code

步骤2：使用验证后的代码创建永久查询

excelcli -q powerquery create --session 1 --query Q1 --mcode-file query.m

Step 3: Load data to destination

步骤3：将数据加载到目标位置

excelcli -q powerquery refresh --session 1 --query Q1


**Why evaluate first:** Better error messages than COM exceptions, see actual data preview, avoids broken queries in workbook.

excelcli -q powerquery refresh --session 1 --query Q1


**为什么要先评估？** 相比COM异常能提供更清晰的错误信息，可查看实际数据预览，避免工作簿中出现损坏的查询。

Rule 6: Report File Errors Immediately

规则6：立即报告文件错误

If you see "File not found" or "Path not found" - STOP and report to user. Don't retry.

如果出现“文件未找到”或“路径未找到”错误，请停止操作并告知用户，不要重试。

Rule 7: Use Calculation Mode for Bulk Writes

规则7：批量写入时使用计算模式

When writing many values/formulas (10+ cells), disable auto-recalc for performance:

powershell

undefined

当写入大量值或公式（10个以上单元格）时，禁用自动计算以提升性能：

powershell

undefined

1. Set manual mode

1. 设置手动计算模式

excelcli -q calculationmode set-mode --session 1 --mode manual

2. Perform bulk writes

2. 执行批量写入操作

excelcli -q range set-values --session 1 --sheet Sheet1 --range A1 --values-file data.json

3. Recalculate once at end

3. 最后执行一次计算

excelcli -q calculationmode calculate --session 1 --scope workbook

4. Restore automatic mode

4. 恢复自动计算模式

excelcli -q calculationmode set-mode --session 1 --mode automatic


**When NOT needed:** Reading formulas, small edits (1-10 cells), or when you need immediate calculation results.

excelcli -q calculationmode set-mode --session 1 --mode automatic


**无需使用的场景：** 读取公式、少量编辑（1-10个单元格）或需要立即获取计算结果时。

Quick Reference

快速参考

Task	Command
Open workbook	`excelcli -q session open <path>`
List sheets	`excelcli -q sheet list --session <id>`
Read data	`excelcli -q range get-values --session <id> --sheet Sheet1 --range A1:D10`
Create table	`excelcli -q table create --session <id> --sheet Sheet1 --range A1:D10 --name Sales`
Add to Data Model	`excelcli -q table add-to-datamodel --session <id> --table Sales`
Create pivot	`excelcli -q pivottable create --session <id> --source Sales --dest-sheet Analysis`
Save & close	`excelcli -q session close --session <id> --save`

Primary source:

excelcli <command> --help

for authoritative parameter info.

任务	命令
打开工作簿	`excelcli -q session open <path>`
列出工作表	`excelcli -q sheet list --session <id>`
读取数据	`excelcli -q range get-values --session <id> --sheet Sheet1 --range A1:D10`
创建表格	`excelcli -q table create --session <id> --sheet Sheet1 --range A1:D10 --name Sales`
加入数据模型	`excelcli -q table add-to-datamodel --session <id> --table Sales`
创建数据透视表	`excelcli -q pivottable create --session <id> --source Sales --dest-sheet Analysis`
保存并关闭	`excelcli -q session close --session <id> --save`

主要参考来源： 执行

excelcli <command> --help

获取权威的参数信息。

Reference Documentation

参考文档

@references/behavioral-rules.md - Core execution rules and LLM guidelines
@references/anti-patterns.md - Common mistakes to avoid
@references/workflows.md - Data Model constraints and patterns

@references/behavioral-rules.md - 核心执行规则与LLM指南
@references/anti-patterns.md - 需避免的常见错误
@references/workflows.md - 数据模型约束与模式

Installation

安装

powershell

dotnet tool install --global Sbroenne.ExcelMcp.CLI

powershell

dotnet tool install --global Sbroenne.ExcelMcp.CLI
```",