mirror of
https://github.com/iOfficeAI/OfficeCLI
synced 2026-04-21 13:37:23 +00:00
docs: optimize README for 3 audiences (humans, AI agents, LLMs)
- Add Use Cases section with real-world scenarios - Add 8 AI-generated presentation examples (GIF gallery) - Add keywords metadata for LLM discoverability - Add BatchItem field reference for agents - Restore balanced comparison table - Fix JSON boolean values in batch mode examples - Update MCP tool list (add query, move, raw) - Sync all improvements to Chinese version - Remove deprecated assets (png, mp4)
This commit is contained in:
Waili(瓦砾)
parent
db36d180b8
commit
4cc969116c
12 changed files with 1015 additions and 467 deletions
740
README.md
740
README.md
|
|
@ -1,73 +1,139 @@
|
|||
# OfficeCLI
|
||||
|
||||
**Give any AI agent full control over Word, Excel, and PowerPoint -- in one line of code.**
|
||||
|
||||
Open-source. Single binary. No Office installation. No dependencies. Works everywhere.
|
||||
|
||||
[](https://github.com/iOfficeAI/OfficeCLI/releases)
|
||||
[](LICENSE)
|
||||
|
||||
**English** | [中文](README_zh.md)
|
||||
|
||||
**The world's first Office suite designed for AI agents.**
|
||||
|
||||
**Let AI agents do anything with Office documents — from the command line.**
|
||||
|
||||
OfficeCLI is a free, open-source command-line tool for AI agents to read, edit, and automate Word, Excel, and PowerPoint files. Single binary, no dependencies — no Microsoft Office, no WPS, no runtime needed.
|
||||
|
||||
> Built for AI agents. Usable by humans.
|
||||
|
||||
<p align="center">
|
||||
<img src="assets/ppt-process.gif" alt="PPT creation process using OfficeCLI on AionUi" width="100%">
|
||||
<img src="assets/ppt-process.gif" alt="OfficeCLI creating a PowerPoint presentation on AionUi" width="100%">
|
||||
</p>
|
||||
|
||||
<p align="center"><em>PPT creation process using OfficeCLI on <a href="https://github.com/iOfficeAI/AionUi">AionUi</a></em></p>
|
||||
|
||||
## For AI Agents
|
||||
<table>
|
||||
<tr>
|
||||
<td width="25%"><img src="assets/designwhatmovesyou.gif" alt="OfficeCLI design presentation"></td>
|
||||
<td width="25%"><img src="assets/mars.gif" alt="OfficeCLI space presentation"></td>
|
||||
<td width="25%"><img src="assets/horizon.gif" alt="OfficeCLI business presentation"></td>
|
||||
<td width="25%"><img src="assets/efforless.gif" alt="OfficeCLI tech presentation"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="25%"><img src="assets/cat.gif" alt="OfficeCLI creative presentation"></td>
|
||||
<td width="25%"><img src="assets/first-ppt-aionui.gif" alt="OfficeCLI gaming presentation"></td>
|
||||
<td width="25%"><img src="assets/moridian.gif" alt="OfficeCLI minimal presentation"></td>
|
||||
<td width="25%"><img src="assets/move.gif" alt="OfficeCLI wellness presentation"></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
OfficeCLI ships with a [SKILL.md](SKILL.md) that teaches AI agents how to use it effectively.
|
||||
<p align="center"><em>All presentations above were created entirely by AI agents using OfficeCLI — no templates, no manual editing.</em></p>
|
||||
|
||||
Talk to your agent with this first:
|
||||
> **AI agents:** OfficeCLI ships with a [SKILL.md](SKILL.md) (239 lines, ~8K tokens) that teaches agents command syntax, architecture, and common pitfalls. Feed it to your agent's context for best results.
|
||||
|
||||
## Quick Start
|
||||
|
||||
From zero to a finished presentation in seconds:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://officecli.ai/SKILL.md
|
||||
# Create a new PowerPoint
|
||||
officecli create deck.pptx
|
||||
|
||||
# Add a slide with a title and background color
|
||||
officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
|
||||
|
||||
# Add a text shape to the slide
|
||||
officecli add deck.pptx /slide[1] --type shape \
|
||||
--prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm \
|
||||
--prop font=Arial --prop size=24 --prop color=FFFFFF
|
||||
|
||||
# View the outline of the presentation
|
||||
officecli view deck.pptx outline
|
||||
```
|
||||
|
||||
If your agent supports local skill installation, install it locally instead:
|
||||
Output:
|
||||
|
||||
**Claude Code:**
|
||||
```
|
||||
Slide 1: Q4 Report
|
||||
Shape 1 [TextBox]: Revenue grew 25%
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md
|
||||
# Get structured JSON for any element
|
||||
officecli get deck.pptx /slide[1]/shape[1] --json
|
||||
```
|
||||
|
||||
**Other agents:**
|
||||
|
||||
Include the contents of that `SKILL.md` in your agent's system prompt or tool description.
|
||||
|
||||
Then install the CLI binary:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
|
||||
```
|
||||
|
||||
For Windows (PowerShell):
|
||||
|
||||
```powershell
|
||||
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
```json
|
||||
{
|
||||
"tag": "shape",
|
||||
"path": "/slide[1]/shape[1]",
|
||||
"attributes": {
|
||||
"name": "TextBox 1",
|
||||
"text": "Revenue grew 25%",
|
||||
"x": "720000",
|
||||
"y": "1800000"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Why OfficeCLI?
|
||||
|
||||
AI agents are great at text — but Office documents are binary blobs of XML. OfficeCLI bridges this gap, letting agents:
|
||||
What used to take 50 lines of Python and 3 separate libraries:
|
||||
|
||||
- **Create** documents from scratch — blank or with content
|
||||
- **Read** text, structure, styles, formulas — in plain text or structured JSON
|
||||
```python
|
||||
from pptx import Presentation
|
||||
from pptx.util import Inches, Pt
|
||||
prs = Presentation()
|
||||
slide = prs.slides.add_slide(prs.slide_layouts[0])
|
||||
title = slide.shapes.title
|
||||
title.text = "Q4 Report"
|
||||
# ... 45 more lines ...
|
||||
prs.save('deck.pptx')
|
||||
```
|
||||
|
||||
Now takes one command:
|
||||
|
||||
```bash
|
||||
officecli add deck.pptx / --type slide --prop title="Q4 Report"
|
||||
```
|
||||
|
||||
**What OfficeCLI can do:**
|
||||
|
||||
- **Create** documents from scratch -- blank or with content
|
||||
- **Read** text, structure, styles, formulas -- in plain text or structured JSON
|
||||
- **Analyze** formatting issues, style inconsistencies, and structural problems
|
||||
- **Modify** any element — text, fonts, colors, layout, formulas, charts, images
|
||||
- **Reorganize** content — add, remove, move, copy elements across documents
|
||||
- **Modify** any element -- text, fonts, colors, layout, formulas, charts, images
|
||||
- **Reorganize** content -- add, remove, move, copy elements across documents
|
||||
|
||||
All through simple CLI commands, with structured JSON output, no Office installation needed.
|
||||
| Format | Read | Modify | Create |
|
||||
|--------|------|--------|--------|
|
||||
| Word (.docx) | ✅ | ✅ | ✅ |
|
||||
| Excel (.xlsx) | ✅ | ✅ | ✅ |
|
||||
| PowerPoint (.pptx) | ✅ | ✅ | ✅ |
|
||||
|
||||
## Use Cases
|
||||
|
||||
**For Developers:**
|
||||
- Automate report generation from databases or APIs
|
||||
- Batch-process documents (bulk find/replace, style updates)
|
||||
- Build document pipelines in CI/CD environments (generate docs from test results)
|
||||
- Headless Office automation in Docker/containerized environments
|
||||
|
||||
**For AI Agents:**
|
||||
- Generate presentations from user prompts (see examples above)
|
||||
- Extract structured data from documents to JSON
|
||||
- Validate and check document quality before delivery
|
||||
|
||||
**For Teams:**
|
||||
- Clone document templates and populate with data
|
||||
- Automated document validation in CI/CD pipelines
|
||||
|
||||
## Installation
|
||||
|
||||
OfficeCLI is a single binary — no runtime, no dependencies. One command to install:
|
||||
Ships as a single self-contained binary. The .NET runtime is embedded -- nothing to install, no runtime to manage.
|
||||
|
||||
**macOS / Linux:**
|
||||
|
||||
|
|
@ -81,36 +147,73 @@ curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh
|
|||
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
Or download manually from [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases).
|
||||
**Manual download:** Grab the binary for your platform from [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases).
|
||||
|
||||
## Quick Start
|
||||
Verify installation: `officecli --version`
|
||||
|
||||
Updates are checked automatically in the background. Disable with `officecli config autoUpdate false` or skip per-invocation with `OFFICECLI_SKIP_UPDATE=1`. Configuration lives under `~/.officecli/config.json`.
|
||||
|
||||
## For AI Agents
|
||||
|
||||
Get OfficeCLI working with your AI agent in two steps:
|
||||
|
||||
1. **Install the binary** -- one command (see [Installation](#installation))
|
||||
2. **Done.** OfficeCLI automatically detects your AI tools (Claude Code, GitHub Copilot, Codex) by checking known config directories and installs its skill file. Your agent can immediately create, read, and modify any Office document.
|
||||
|
||||
<details>
|
||||
<summary><strong>Manual setup (optional)</strong></summary>
|
||||
|
||||
If auto-install doesn't cover your setup, you can install the skill file manually:
|
||||
|
||||
**Feed SKILL.md to your agent directly:**
|
||||
|
||||
```bash
|
||||
# Create a blank document
|
||||
officecli create report.docx
|
||||
officecli create budget.xlsx
|
||||
officecli create deck.pptx
|
||||
|
||||
# View document content
|
||||
officecli view report.docx text
|
||||
|
||||
# Check for formatting issues
|
||||
officecli view report.docx issues --json
|
||||
|
||||
# Read a specific cell
|
||||
officecli get budget.xlsx /Sheet1/B5 --json
|
||||
|
||||
# Modify content
|
||||
officecli set report.docx /body/p[1]/r[1] --prop text="Updated Title" --prop bold=true
|
||||
|
||||
# Batch editing with resident mode (keeps doc in memory)
|
||||
officecli open presentation.pptx
|
||||
officecli set presentation.pptx /slide[1]/shape[1] --prop text="New Title"
|
||||
officecli set presentation.pptx /slide[2]/shape[3] --prop text="New Subtitle"
|
||||
officecli close presentation.pptx
|
||||
curl -fsSL https://officecli.ai/SKILL.md
|
||||
```
|
||||
|
||||
## Built-in help
|
||||
**Install as a local skill for Claude Code:**
|
||||
|
||||
```bash
|
||||
curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md
|
||||
```
|
||||
|
||||
**Other agents:** Include the contents of `SKILL.md` (239 lines, ~8K tokens) in your agent's system prompt or tool description.
|
||||
|
||||
</details>
|
||||
|
||||
### MCP Server -- Use OfficeCLI as a Native AI Tool
|
||||
|
||||
Run OfficeCLI as an MCP server and use it as a native tool in Claude Desktop, Cursor, or any MCP-compatible agent -- no wrapper code needed.
|
||||
|
||||
```bash
|
||||
officecli mcp-serve
|
||||
```
|
||||
|
||||
Add it to your MCP client config (Claude Desktop, Cursor, etc.):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"officecli": {
|
||||
"command": "officecli",
|
||||
"args": ["mcp-serve"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
OfficeCLI exposes all document operations (create, view, get, query, set, add, remove, move, validate, batch, raw) as MCP tools with structured JSON inputs and outputs.
|
||||
|
||||
### Why agents love OfficeCLI
|
||||
|
||||
- **Deterministic JSON output** -- Every command supports `--json`, returning structured data with consistent schemas. No regex parsing needed.
|
||||
- **Path-based addressing** -- Every element has a stable path (`/slide[1]/shape[2]`). Agents navigate documents without understanding XML namespaces. Note: these paths use OfficeCLI's own syntax (1-based indexing, element local names), not XPath.
|
||||
- **Progressive complexity** -- Start with L1 (read), escalate to L2 (modify), fall back to L3 (raw XML) only when needed. Minimizes token usage.
|
||||
- **Self-healing workflow** -- `validate`, `view issues`, and the help system let agents detect problems and self-correct without human intervention.
|
||||
- **Built-in help** -- When unsure about property names or value formats, run `officecli <format> set <element>` instead of guessing.
|
||||
- **Auto-install** -- No manual skill-file setup. OfficeCLI detects your AI tools and configures itself automatically.
|
||||
|
||||
### Built-in Help
|
||||
|
||||
When property names or value formats are unclear, use the nested help instead of guessing. Replace `pptx` with `docx` or `xlsx`; verbs are `view`, `get`, `query`, `set`, `add`, and `raw`.
|
||||
|
||||
|
|
@ -120,183 +223,52 @@ officecli pptx set shape # Detail for one element type
|
|||
officecli pptx set shape.fill # One property: format and examples
|
||||
```
|
||||
|
||||
Run `officecli --help` for the same overview. Optional wiki content may be embedded in the binary when built with a `wiki/` directory.
|
||||
Run `officecli --help` for the full overview.
|
||||
|
||||
## Three-Layer Architecture
|
||||
### JSON Output Schemas
|
||||
|
||||
OfficeCLI is designed with a progressive complexity model — start simple, go deep only when needed.
|
||||
All commands support `--json`. The general response shapes:
|
||||
|
||||
### L1: Read & Inspect
|
||||
**Single element** (`get --json`):
|
||||
|
||||
High-level, semantic views of document content.
|
||||
```json
|
||||
{"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}}
|
||||
```
|
||||
|
||||
**List of elements** (`query --json`):
|
||||
|
||||
```json
|
||||
[
|
||||
{"tag": "paragraph", "path": "/body/p[1]", "attributes": {"style": "Heading1", "text": "Title"}},
|
||||
{"tag": "paragraph", "path": "/body/p[5]", "attributes": {"style": "Heading1", "text": "Summary"}}
|
||||
]
|
||||
```
|
||||
|
||||
**Errors** return a non-zero exit code with a JSON error object on stdout when `--json` is used:
|
||||
|
||||
```json
|
||||
{"error": "Element not found: /body/p[99]"}
|
||||
```
|
||||
|
||||
**Error Recovery** -- Agents self-correct by inspecting available elements:
|
||||
|
||||
```bash
|
||||
# Word — plain text with element paths
|
||||
officecli view report.docx text
|
||||
# Agent tries an invalid path
|
||||
officecli get report.docx /body/p[99] --json
|
||||
# Returns: {"error": "Element not found: /body/p[99]"}
|
||||
|
||||
# Word — text with formatting annotations
|
||||
officecli view report.docx annotated
|
||||
|
||||
# Excel — view with column filter
|
||||
officecli view budget.xlsx text --cols A,B,C --max-lines 50
|
||||
|
||||
# Excel — detect formula and style issues
|
||||
officecli view budget.xlsx issues --json
|
||||
|
||||
# PowerPoint — outline all slides
|
||||
officecli view deck.pptx outline
|
||||
|
||||
# PowerPoint — stats on fonts and styles used
|
||||
officecli view deck.pptx stats
|
||||
# Agent self-corrects by checking available elements
|
||||
officecli get report.docx /body --depth 1 --json
|
||||
# Returns the list of available children, agent picks the right path
|
||||
```
|
||||
|
||||
### L2: DOM Operations
|
||||
**Mutation confirmations** (`set`, `add`, `remove`, `move`, `create` with `--json`):
|
||||
|
||||
Modify documents through structured element paths and properties.
|
||||
|
||||
```bash
|
||||
# Word — query headings and set formatting (CSS-like selectors; see help for full syntax)
|
||||
officecli query report.docx "paragraph[style=Heading1]"
|
||||
officecli docx query # Selector reference: attributes, :contains, :has(), etc.
|
||||
officecli set report.docx /body/p[1]/r[1] --prop bold=true --prop color=FF0000
|
||||
|
||||
# Word — add a paragraph, remove another
|
||||
officecli add report.docx /body --type paragraph --prop text="New paragraph" --index 3
|
||||
officecli remove report.docx /body/p[5]
|
||||
|
||||
# Excel — read and modify cells
|
||||
officecli get budget.xlsx /Sheet1/B5 --json
|
||||
officecli set budget.xlsx /Sheet1/A1 --prop formula="=SUM(A2:A10)" --prop numFmt="0.00%"
|
||||
|
||||
# Excel — add a new sheet, add rows
|
||||
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
|
||||
officecli add budget.xlsx /Sheet1 --type row --prop values="Name,Amount,Date"
|
||||
|
||||
# PowerPoint — modify slide content
|
||||
officecli set deck.pptx /slide[1]/shape[1] --prop text="New Title"
|
||||
officecli set deck.pptx /slide[2]/shape[3] --prop fontSize=24 --prop bold=true
|
||||
|
||||
# PowerPoint — add a slide, copy a shape from another slide
|
||||
officecli add deck.pptx / --type slide
|
||||
officecli add deck.pptx /slide[3] --from /slide[1]/shape[2]
|
||||
|
||||
# Move elements
|
||||
officecli move report.docx /body/p[5] --to /body --index 1
|
||||
```json
|
||||
{"success": true, "path": "/slide[1]/shape[1]"}
|
||||
```
|
||||
|
||||
### L3: Raw XML
|
||||
|
||||
Direct XML access via XPath — the universal fallback for any OpenXML operation.
|
||||
|
||||
```bash
|
||||
# Word — view and modify raw XML
|
||||
officecli raw report.docx document
|
||||
officecli raw-set report.docx document \
|
||||
--xpath "//w:p[1]" \
|
||||
--action append \
|
||||
--xml '<w:r><w:t>Injected text</w:t></w:r>'
|
||||
|
||||
# Word — add a header
|
||||
officecli add-part report.docx /body --type header
|
||||
|
||||
# Excel — view raw sheet XML
|
||||
officecli raw budget.xlsx /Sheet1
|
||||
|
||||
# Excel — add a chart to a sheet
|
||||
officecli add-part budget.xlsx /Sheet1 --type chart
|
||||
|
||||
# PowerPoint — view raw slide XML
|
||||
officecli raw deck.pptx /slide[1]
|
||||
|
||||
# Validate any document
|
||||
officecli validate report.docx
|
||||
officecli validate budget.xlsx
|
||||
```
|
||||
|
||||
## Supported Formats
|
||||
|
||||
| Format | Read | Modify | Create |
|
||||
|--------|------|--------|--------|
|
||||
| Word (.docx) | ✓ | ✓ | ✓ |
|
||||
| Excel (.xlsx) | ✓ | ✓ | ✓ |
|
||||
| PowerPoint (.pptx) | ✓ | ✓ | ✓ |
|
||||
|
||||
### Word — Paragraphs, runs, tables, styles, headers/footers, images, equations, comments, lists
|
||||
|
||||
### Excel — Cells, formulas, sheets, styles (fonts, fills, borders, number formats), conditional formatting, charts
|
||||
|
||||
### PowerPoint — Slides, shapes, text boxes, images, animations, equations, themes, alignment, and shape effects
|
||||
|
||||
## Resident Mode
|
||||
|
||||
For multi-step workflows, resident mode keeps the document open in a background process, eliminating reload overhead on every command.
|
||||
|
||||
```bash
|
||||
officecli open report.docx # Start resident process
|
||||
officecli view report.docx text # Instant — no file reload
|
||||
officecli set report.docx ... # Instant — no file reload
|
||||
officecli close report.docx # Save and stop
|
||||
```
|
||||
|
||||
Communication happens via named pipes for near-zero latency between commands.
|
||||
|
||||
## Batch mode
|
||||
|
||||
Run multiple operations in **one** open/save cycle (or forward to an already resident process) by passing a JSON array of commands on stdin or via `--input`.
|
||||
|
||||
```bash
|
||||
echo '[{"command":"view","mode":"outline"},{"command":"get","path":"/slide[1]","depth":1}]' \
|
||||
| officecli batch deck.pptx
|
||||
```
|
||||
|
||||
Use `--stop-on-error` to abort on the first failure. Supported `command` values in each item include `get`, `query`, `set`, `add`, `remove`, `move`, `view`, `raw`, `raw-set`, and `validate` (see `BatchItem` in the source for all fields).
|
||||
|
||||
## Updates & configuration
|
||||
|
||||
The CLI may check for updates in the background (non-blocking) and align with the latest release from GitHub. Configuration lives under `~/.officecli/config.json`.
|
||||
|
||||
- **Disable automatic update checks:** `officecli config autoUpdate false` (read current value with `officecli config autoUpdate`).
|
||||
- **Skip the background check for a single invocation (e.g. CI):** `OFFICECLI_SKIP_UPDATE=1 officecli ...`
|
||||
|
||||
Re-running the install script (`install.sh` / `install.ps1`) still installs or upgrades the binary as before.
|
||||
|
||||
## Python Usage
|
||||
|
||||
```python
|
||||
import subprocess, json
|
||||
|
||||
def cli(*args): return subprocess.check_output(["officecli", *args], text=True)
|
||||
def cli_json(*args): return json.loads(cli(*args, "--json"))
|
||||
|
||||
cli("create", "deck.pptx")
|
||||
cli("set", "deck.pptx", "/slide[1]/shape[1]", "--prop", "text=Hello")
|
||||
shapes = cli_json("query", "deck.pptx", "shape")
|
||||
```
|
||||
|
||||
## JavaScript Usage
|
||||
|
||||
```js
|
||||
const { execFileSync } = require('child_process')
|
||||
|
||||
const cli = (...args) => execFileSync('officecli', args, { encoding: 'utf8' })
|
||||
const cliJson = (...args) => JSON.parse(cli(...args, '--json'))
|
||||
|
||||
cli('create', 'deck.pptx')
|
||||
cli('set', 'deck.pptx', '/slide[1]/shape[1]', '--prop', 'text=Hello')
|
||||
const shapes = cliJson('query', 'deck.pptx', 'shape')
|
||||
```
|
||||
|
||||
## AI Agent Integration
|
||||
|
||||
### Why OfficeCLI for agents?
|
||||
|
||||
**Deterministic JSON output** — Every command supports `--json`, returning structured data with consistent schemas. No regex parsing needed.
|
||||
|
||||
**Useful validation and diagnostics** — Commands like `validate`, `view issues`, and `raw-set` help agents detect problems and verify document correctness after changes.
|
||||
|
||||
**Path-based addressing** — Every element in every document has a stable path. Agents can navigate documents without understanding XML namespaces.
|
||||
|
||||
**Progressive complexity** — Agents start with L1 (read), escalate to L2 (modify), and fall back to L3 (raw XML) only when needed. This minimizes token usage while keeping all operations possible.
|
||||
See `officecli --help` for full details on exit codes and error formats.
|
||||
|
||||
## Comparison
|
||||
|
||||
|
|
@ -317,9 +289,277 @@ How does OfficeCLI compare to other approaches for AI agents working with Office
|
|||
| Word + Excel + PowerPoint | ✓ | ✓ | ✓ | Separate libs |
|
||||
| Read + Write + Create | ✓ | ✓ | ✓ | ✓ |
|
||||
|
||||
## Build
|
||||
## How It Works: Three-Layer Architecture
|
||||
|
||||
Requires [.NET 10 SDK](https://dotnet.microsoft.com/download) for local compilation. From the repository root:
|
||||
OfficeCLI uses progressive complexity -- start simple, go deep only when needed.
|
||||
|
||||
### L1: Read and Inspect
|
||||
|
||||
High-level views of document content.
|
||||
|
||||
```bash
|
||||
# Plain text with element paths
|
||||
officecli view report.docx text
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
/body/p[1] Executive Summary
|
||||
/body/p[2] Revenue increased by 25% year-over-year.
|
||||
/body/p[3] Key drivers include new product launches and market expansion.
|
||||
```
|
||||
|
||||
```bash
|
||||
# Text with formatting annotations
|
||||
officecli view report.docx annotated
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
[Heading1, Arial 18pt, bold] Executive Summary
|
||||
[Normal, Calibri 11pt] Revenue increased by 25% year-over-year.
|
||||
```
|
||||
|
||||
```bash
|
||||
# Detect formatting and style issues (JSON output)
|
||||
officecli view budget.xlsx issues --json
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```json
|
||||
[
|
||||
{"type": "format", "path": "/Sheet1/A1", "message": "Inconsistent font size"}
|
||||
]
|
||||
```
|
||||
|
||||
```bash
|
||||
# Excel with column filter
|
||||
officecli view budget.xlsx text --cols A,B,C --max-lines 50
|
||||
|
||||
# PowerPoint outline
|
||||
officecli view deck.pptx outline
|
||||
|
||||
# Document statistics
|
||||
officecli view deck.pptx stats
|
||||
|
||||
# CSS-like queries
|
||||
officecli query report.docx "paragraph[style=Heading1]"
|
||||
|
||||
# Validate against OpenXML schema
|
||||
officecli validate report.docx
|
||||
```
|
||||
|
||||
### L2: DOM Operations
|
||||
|
||||
Modify documents through structured element paths and properties.
|
||||
|
||||
**Path syntax:** Paths use OfficeCLI's own element addressing (not XPath). Elements are referenced by local name with 1-based indexing: `/slide[1]/shape[2]`, `/body/p[3]/r[1]`, `/Sheet1/A1`. Excel also supports native notation: `Sheet1!A1` alongside `/Sheet1/A1`. The `view` command uses mode names (`text`, `outline`, etc.) while `get` and `set` use element paths.
|
||||
|
||||
Advanced capabilities:
|
||||
- **3D models** -- Insert `.glb` 3D models with morph animations, directly from the command line
|
||||
- **Flexible image sources** -- File paths, base64 data URIs, and HTTP(S) URLs all work as image sources
|
||||
- **Table cell merging** -- `merge.right` and `merge.down` for professional table layouts
|
||||
|
||||
```bash
|
||||
# Set properties on any element
|
||||
officecli set report.docx /body/p[1]/r[1] --prop bold=true --prop color=FF0000
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```
|
||||
Set 2 properties on /body/p[1]/r[1]
|
||||
```
|
||||
|
||||
```bash
|
||||
# Add elements
|
||||
officecli add report.docx /body --type paragraph --prop text="New section" --index 3
|
||||
|
||||
# Add a slide and a shape
|
||||
officecli add deck.pptx / --type slide
|
||||
officecli add deck.pptx /slide[2] --type shape --prop text="Hello World"
|
||||
|
||||
# Clone elements
|
||||
officecli add deck.pptx / --from /slide[1]
|
||||
|
||||
# Move, swap, remove
|
||||
officecli move report.docx /body/p[5] --to /body --index 1
|
||||
officecli swap deck.pptx /slide[1] /slide[3]
|
||||
officecli remove report.docx /body/p[4]
|
||||
|
||||
# Excel cell operations
|
||||
officecli set budget.xlsx /Sheet1/A1 --prop formula="=SUM(A2:A10)" --prop numFmt="0.00%"
|
||||
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
|
||||
```
|
||||
|
||||
### L3: Raw XML
|
||||
|
||||
Direct XML access via XPath -- the universal fallback for any OpenXML operation.
|
||||
|
||||
```bash
|
||||
# View raw XML of a document part
|
||||
officecli raw report.docx document
|
||||
|
||||
# Modify XML directly
|
||||
officecli raw-set report.docx document \
|
||||
--xpath "//w:p[1]" \
|
||||
--action append \
|
||||
--xml '<w:r><w:t>Injected text</w:t></w:r>'
|
||||
|
||||
# Add a new document part (header, chart, etc.)
|
||||
officecli add-part report.docx /body --type header
|
||||
officecli add-part budget.xlsx /Sheet1 --type chart
|
||||
```
|
||||
|
||||
## Performance: Resident Mode and Batch Mode
|
||||
|
||||
### Resident Mode
|
||||
|
||||
For multi-step workflows (3+ commands on the same file), resident mode keeps the document open in a background process, eliminating reload overhead on every command. Communication happens via named pipes for near-zero latency between commands.
|
||||
|
||||
```bash
|
||||
officecli open report.docx # Start resident process
|
||||
officecli view report.docx text # Instant -- no file reload
|
||||
officecli set report.docx ... # Instant -- no file reload
|
||||
officecli close report.docx # Save and stop
|
||||
```
|
||||
|
||||
The resident process is tied to the specific file -- use `officecli close` to save and release it when done. If you need to discard changes, you can terminate the process without calling `close`.
|
||||
|
||||
### Batch Mode
|
||||
|
||||
Run multiple operations in one open/save cycle by passing a JSON array of commands on stdin or via `--input`.
|
||||
|
||||
```bash
|
||||
# Using --input file (cross-platform, recommended)
|
||||
officecli batch data.xlsx --input commands.json --json
|
||||
|
||||
# Using stdin (Unix/macOS)
|
||||
echo '[
|
||||
{"command":"set","path":"/Sheet1/A1","props":{"value":"Name","bold":true}},
|
||||
{"command":"set","path":"/Sheet1/B1","props":{"value":"Score","bold":true}}
|
||||
]' | officecli batch data.xlsx --json
|
||||
```
|
||||
|
||||
Note: When using stdin with `echo` on Windows, use double quotes for the outer string and escape inner quotes. The `--input` flag with a file works reliably on all platforms.
|
||||
|
||||
**BatchItem fields:** Each command object supports `command` (required), `path`, `props` (key-value object), `type`, `from`, `to`, `index`, `xpath`, `action`, `xml`, `depth`, `mode`, and `selector`. Field availability depends on the command type.
|
||||
|
||||
Use `--stop-on-error` to abort on the first failure. Batch supports: `add`, `set`, `get`, `query`, `remove`, `move`, `view`, `raw`, `raw-set`, and `validate`.
|
||||
|
||||
## Live Preview
|
||||
|
||||
Preview documents in your browser with real-time updates as you edit:
|
||||
|
||||
```bash
|
||||
officecli watch deck.pptx
|
||||
```
|
||||
|
||||
OfficeCLI renders slides, charts, equations, and shapes as live HTML -- with SSE-based auto-refresh. Every change you make is reflected instantly in the browser.
|
||||
|
||||
## Command Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `create <file>` | Create a blank .docx, .xlsx, or .pptx (type from extension) |
|
||||
| `view <file> <mode>` | View content (modes: `outline`, `text`, `annotated`, `stats`, `issues`) |
|
||||
| `get <file> <path>` | Get element and children (`--depth N`, `--json`) |
|
||||
| `query <file> <selector>` | CSS-like query (`[attr=value]`, `:contains()`, `:has()`, etc.) |
|
||||
| `set <file> <path> --prop k=v` | Modify element properties |
|
||||
| `add <file> <parent> --type <t>` | Add element (or clone with `--from <path>`) |
|
||||
| `remove <file> <path>` | Remove an element |
|
||||
| `move <file> <path>` | Move element (`--to <parent> --index N`) |
|
||||
| `swap <file> <path1> <path2>` | Swap two elements |
|
||||
| `validate <file>` | Validate against OpenXML schema |
|
||||
| `batch <file>` | Multiple operations in one open/save cycle (JSON on stdin or `--input`) |
|
||||
| `watch <file>` | Live HTML preview in browser with auto-refresh |
|
||||
| `mcp-serve` | Start MCP server for AI tool integration |
|
||||
| `raw <file> <part>` | View raw XML of a document part |
|
||||
| `raw-set <file> <part>` | Modify raw XML via XPath |
|
||||
| `add-part <file> <parent>` | Add a new document part (header, chart, etc.) |
|
||||
| `open <file>` | Start resident mode (keep document in memory) |
|
||||
| `close <file>` | Save and close resident mode |
|
||||
| `config <key> [value]` | Get or set configuration |
|
||||
| `<format> <command> [element]` | Built-in help (e.g. `officecli pptx set shape`) |
|
||||
|
||||
## End-to-End Workflow Example
|
||||
|
||||
A typical self-healing agent workflow: create a presentation, populate it, verify, and fix issues -- all without human intervention.
|
||||
|
||||
```bash
|
||||
# 1. Create
|
||||
officecli create report.pptx
|
||||
|
||||
# 2. Add content
|
||||
officecli add report.pptx / --type slide --prop title="Q4 Results"
|
||||
officecli add report.pptx /slide[1] --type shape \
|
||||
--prop text="Revenue: $4.2M" --prop x=2cm --prop y=5cm --prop size=28
|
||||
officecli add report.pptx / --type slide --prop title="Details"
|
||||
officecli add report.pptx /slide[2] --type shape \
|
||||
--prop text="Growth driven by new markets" --prop x=2cm --prop y=5cm
|
||||
|
||||
# 3. Verify
|
||||
officecli view report.pptx outline
|
||||
officecli validate report.pptx
|
||||
|
||||
# 4. Fix any issues found
|
||||
officecli view report.pptx issues --json
|
||||
# Address issues based on output, e.g.:
|
||||
officecli set report.pptx /slide[1]/shape[1] --prop font=Arial
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
```bash
|
||||
# Replace all Heading1 text in a Word doc
|
||||
officecli query report.docx "paragraph[style=Heading1]" --json | ...
|
||||
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"
|
||||
|
||||
# Export all slide content as JSON
|
||||
officecli get deck.pptx / --depth 2 --json
|
||||
|
||||
# Bulk-update Excel cells
|
||||
officecli batch budget.xlsx --input updates.json --json
|
||||
|
||||
# Check document quality before delivery
|
||||
officecli validate report.docx && officecli view report.docx issues --json
|
||||
```
|
||||
|
||||
## Use from Any Language
|
||||
|
||||
OfficeCLI is a standard CLI tool -- call it from any language via subprocess. Add `--json` for structured output.
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
import subprocess, json
|
||||
result = subprocess.check_output(["officecli", "view", "deck.pptx", "outline"], text=True)
|
||||
data = json.loads(subprocess.check_output(["officecli", "get", "deck.pptx", "/slide[1]", "--json"], text=True))
|
||||
```
|
||||
|
||||
**JavaScript:**
|
||||
|
||||
```js
|
||||
const { execFileSync } = require('child_process')
|
||||
const result = execFileSync('officecli', ['view', 'deck.pptx', 'outline'], { encoding: 'utf8' })
|
||||
const data = JSON.parse(execFileSync('officecli', ['get', 'deck.pptx', '/slide[1]', '--json'], { encoding: 'utf8' }))
|
||||
```
|
||||
|
||||
**Bash:**
|
||||
|
||||
```bash
|
||||
# Any shell script can call OfficeCLI directly
|
||||
officecli create report.docx
|
||||
officecli add report.docx /body --type paragraph --prop text="Hello from Bash"
|
||||
outline=$(officecli view report.docx outline)
|
||||
```
|
||||
|
||||
## Build from Source
|
||||
|
||||
Requires [.NET 10 SDK](https://dotnet.microsoft.com/download) for compilation only. The output is a self-contained, native binary -- .NET is embedded in the binary and is not needed at runtime.
|
||||
|
||||
```bash
|
||||
./build.sh
|
||||
|
|
@ -329,10 +569,44 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download) for local compilat
|
|||
|
||||
[Apache License 2.0](LICENSE)
|
||||
|
||||
## Community
|
||||
|
||||
[LINUX DO - The New Ideal Community](https://linux.do/)
|
||||
Bug reports and contributions are welcome on [GitHub Issues](https://github.com/iOfficeAI/OfficeCLI/issues).
|
||||
|
||||
---
|
||||
|
||||
[OfficeCLI.AI](https://OfficeCLI.AI)
|
||||
[OfficeCLI.AI](https://OfficeCLI.AI) | [GitHub](https://github.com/iOfficeAI/OfficeCLI)
|
||||
|
||||
<!--
|
||||
yaml-frontmatter:
|
||||
name: officecli
|
||||
version: see GitHub Releases
|
||||
description: The standard CLI for AI agents to create, read, and modify Office documents
|
||||
formats: [docx, xlsx, pptx]
|
||||
platforms: [macos, linux, windows]
|
||||
license: Apache-2.0
|
||||
keywords: [office, cli, ai-agent, automation, docx, xlsx, pptx, openxml, document-generation, mcp-server, word, excel, powerpoint]
|
||||
ai-agent-compatible: true
|
||||
mcp-server: true
|
||||
skill-file: SKILL.md
|
||||
skill-file-lines: 239
|
||||
install-command-unix: curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
|
||||
install-command-windows: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
-->
|
||||
|
||||
<!-- LLM/agent discovery metadata
|
||||
tool: officecli
|
||||
type: cli
|
||||
canonical: the standard CLI for AI-driven Office document manipulation
|
||||
formats: docx, xlsx, pptx
|
||||
capabilities: create, read, modify, validate, batch, resident-mode, mcp-server, live-preview, auto-install
|
||||
output: json, text, annotated
|
||||
platforms: macos, linux, windows
|
||||
license: Apache-2.0
|
||||
keywords: office, cli, ai-agent, automation, docx, xlsx, pptx, openxml, document-generation, mcp-server, word, excel, powerpoint, ai-tools, command-line, structured-output
|
||||
ai-agent-compatible: true
|
||||
mcp-server: true
|
||||
skill-file: SKILL.md
|
||||
skill-file-lines: 239
|
||||
alternatives: python-docx, openpyxl, python-pptx, libreoffice --headless
|
||||
install-command-unix: curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
|
||||
install-command-windows: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
-->
|
||||
|
|
|
|||
742
README_zh.md
742
README_zh.md
|
|
@ -1,73 +1,139 @@
|
|||
# OfficeCLI
|
||||
|
||||
**让任何 AI 智能体完全掌控 Word、Excel 和 PowerPoint -- 只需一行代码。**
|
||||
|
||||
开源免费。单一可执行文件。无需安装 Office。零依赖。全平台运行。
|
||||
|
||||
[](https://github.com/iOfficeAI/OfficeCLI/releases)
|
||||
[](LICENSE)
|
||||
|
||||
[English](README.md) | **中文**
|
||||
|
||||
**全球首款专为 AI 智能体打造的 Office 办公软件。**
|
||||
|
||||
**让 AI 智能体通过命令行处理一切 Office 文档。**
|
||||
|
||||
OfficeCLI 是一个免费、开源的命令行工具，专为 AI 智能体设计，可读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。单一可执行文件，无需安装 Microsoft Office、WPS 或任何运行时依赖。
|
||||
|
||||
> 为智能体而生，人类亦可用。
|
||||
|
||||
<p align="center">
|
||||
<img src="assets/ppt-process.gif" alt="在 AionUi 上使用 OfficeCLI 的 PPT 制作过程" width="100%">
|
||||
</p>
|
||||
|
||||
<p align="center"><em>在 <a href="https://github.com/iOfficeAI/AionUi">AionUi</a> 上使用 OfficeCLI 的 PPT 制作过程</em></p>
|
||||
|
||||
## AI 智能体接入
|
||||
<table>
|
||||
<tr>
|
||||
<td width="25%"><img src="assets/designwhatmovesyou.gif" alt="OfficeCLI 设计演示"></td>
|
||||
<td width="25%"><img src="assets/mars.gif" alt="OfficeCLI 太空演示"></td>
|
||||
<td width="25%"><img src="assets/horizon.gif" alt="OfficeCLI 商务演示"></td>
|
||||
<td width="25%"><img src="assets/efforless.gif" alt="OfficeCLI 科技演示"></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="25%"><img src="assets/cat.gif" alt="OfficeCLI 创意演示"></td>
|
||||
<td width="25%"><img src="assets/first-ppt-aionui.gif" alt="OfficeCLI 游戏演示"></td>
|
||||
<td width="25%"><img src="assets/moridian.gif" alt="OfficeCLI 极简演示"></td>
|
||||
<td width="25%"><img src="assets/move.gif" alt="OfficeCLI 健康演示"></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
OfficeCLI 附带 [SKILL.md](SKILL.md)，用于指导 AI 智能体高效使用本工具。
|
||||
<p align="center"><em>以上所有演示文稿均由 AI 智能体使用 OfficeCLI 全自动创建 — 无模板、无人工编辑。</em></p>
|
||||
|
||||
首先让你的智能体读取此文件：
|
||||
> **AI 智能体：** OfficeCLI 附带 [SKILL.md](SKILL.md)（239 行，约 8K tokens），涵盖命令语法、架构设计和常见陷阱。将其加入智能体上下文即可获得最佳效果。
|
||||
|
||||
## 快速开始
|
||||
|
||||
从零到完成一个演示文稿，只需几秒钟：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://officecli.ai/SKILL.md
|
||||
# 创建新的 PowerPoint
|
||||
officecli create deck.pptx
|
||||
|
||||
# 添加带标题和背景色的幻灯片
|
||||
officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
|
||||
|
||||
# 在幻灯片上添加文本形状
|
||||
officecli add deck.pptx /slide[1] --type shape \
|
||||
--prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm \
|
||||
--prop font=Arial --prop size=24 --prop color=FFFFFF
|
||||
|
||||
# 查看演示文稿大纲
|
||||
officecli view deck.pptx outline
|
||||
```
|
||||
|
||||
如果你的智能体支持本地技能安装，建议安装到本地：
|
||||
输出：
|
||||
|
||||
**Claude Code：**
|
||||
```
|
||||
Slide 1: Q4 Report
|
||||
Shape 1 [TextBox]: Revenue grew 25%
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md
|
||||
# 获取任意元素的结构化 JSON
|
||||
officecli get deck.pptx /slide[1]/shape[1] --json
|
||||
```
|
||||
|
||||
**其他智能体：**
|
||||
|
||||
将 `SKILL.md` 的内容添加到智能体的系统提示词或工具描述中。
|
||||
|
||||
然后安装 CLI 二进制文件：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
|
||||
```
|
||||
|
||||
Windows (PowerShell)：
|
||||
|
||||
```powershell
|
||||
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
```json
|
||||
{
|
||||
"tag": "shape",
|
||||
"path": "/slide[1]/shape[1]",
|
||||
"attributes": {
|
||||
"name": "TextBox 1",
|
||||
"text": "Revenue grew 25%",
|
||||
"x": "720000",
|
||||
"y": "1800000"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 为什么选择 OfficeCLI？
|
||||
|
||||
AI 智能体擅长处理文本，但 Office 文档是 XML 的二进制封装。OfficeCLI 弥合了这一鸿沟，让智能体能够：
|
||||
以前需要 50 行 Python 和 3 个独立库：
|
||||
|
||||
- **创建** 文档 — 空白文档或带内容的文档
|
||||
- **读取** 文本、结构、样式、公式 — 纯文本或结构化 JSON
|
||||
- **分析** 格式问题、样式不一致和结构问题
|
||||
- **修改** 任意元素 — 文本、字体、颜色、布局、公式、图表、图片
|
||||
- **重组** 内容 — 添加、删除、移动、复制跨文档元素
|
||||
```python
|
||||
from pptx import Presentation
|
||||
from pptx.util import Inches, Pt
|
||||
prs = Presentation()
|
||||
slide = prs.slides.add_slide(prs.slide_layouts[0])
|
||||
title = slide.shapes.title
|
||||
title.text = "Q4 Report"
|
||||
# ... 还有 45 行 ...
|
||||
prs.save('deck.pptx')
|
||||
```
|
||||
|
||||
全部通过简单的 CLI 命令完成，支持结构化 JSON 输出，无需安装 Office。
|
||||
现在只需一条命令：
|
||||
|
||||
```bash
|
||||
officecli add deck.pptx / --type slide --prop title="Q4 Report"
|
||||
```
|
||||
|
||||
**OfficeCLI 能做什么：**
|
||||
|
||||
- **创建** 文档 -- 空白文档或带内容的文档
|
||||
- **读取** 文本、结构、样式、公式 -- 纯文本或结构化 JSON
|
||||
- **分析** 格式问题、样式不一致和结构缺陷
|
||||
- **修改** 任意元素 -- 文本、字体、颜色、布局、公式、图表、图片
|
||||
- **重组** 内容 -- 添加、删除、移动、复制跨文档元素
|
||||
|
||||
| 格式 | 读取 | 修改 | 创建 |
|
||||
|------|------|------|------|
|
||||
| Word (.docx) | ✅ | ✅ | ✅ |
|
||||
| Excel (.xlsx) | ✅ | ✅ | ✅ |
|
||||
| PowerPoint (.pptx) | ✅ | ✅ | ✅ |
|
||||
|
||||
## 使用场景
|
||||
|
||||
**开发者：**
|
||||
- 从数据库或 API 自动生成报告
|
||||
- 批量处理文档（批量查找/替换、样式更新）
|
||||
- 在 CI/CD 环境中构建文档流水线（从测试结果生成文档）
|
||||
- Docker/容器化环境中的无头 Office 自动化
|
||||
|
||||
**AI 智能体：**
|
||||
- 根据用户提示生成演示文稿（见上方示例）
|
||||
- 从文档提取结构化数据到 JSON
|
||||
- 交付前验证和检查文档质量
|
||||
|
||||
**团队：**
|
||||
- 克隆文档模板并填充数据
|
||||
- CI/CD 流水线中的自动化文档验证
|
||||
|
||||
## 安装
|
||||
|
||||
OfficeCLI 是单一可执行文件 — 无运行时依赖。一条命令即可安装：
|
||||
单一自包含可执行文件，.NET 运行时已内嵌 -- 无需安装任何依赖，无需管理运行时。
|
||||
|
||||
**macOS / Linux：**
|
||||
|
||||
|
|
@ -81,38 +147,75 @@ curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh
|
|||
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
也可以从 [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases) 手动下载。
|
||||
**手动下载：** 从 [GitHub Releases](https://github.com/iOfficeAI/OfficeCLI/releases) 获取适合您平台的二进制文件。
|
||||
|
||||
## 快速开始
|
||||
验证安装：`officecli --version`
|
||||
|
||||
OfficeCLI 会在后台自动检查更新。通过 `officecli config autoUpdate false` 关闭，或通过 `OFFICECLI_SKIP_UPDATE=1` 跳过单次检查。配置文件位于 `~/.officecli/config.json`。
|
||||
|
||||
## AI 智能体接入
|
||||
|
||||
两步将 OfficeCLI 集成到任何 AI 智能体：
|
||||
|
||||
1. **安装二进制文件** -- 一条命令（见[安装](#安装)）
|
||||
2. **完成。** OfficeCLI 自动检测您的 AI 工具（Claude Code、GitHub Copilot、Codex），通过检查已知配置目录并安装技能文件。您的智能体可以立即创建、读取和修改任何 Office 文档。
|
||||
|
||||
<details>
|
||||
<summary><strong>手动配置（可选）</strong></summary>
|
||||
|
||||
如果自动安装未覆盖您的环境，可以手动安装技能文件：
|
||||
|
||||
**直接将 SKILL.md 提供给智能体：**
|
||||
|
||||
```bash
|
||||
# 创建空白文档
|
||||
officecli create report.docx
|
||||
officecli create budget.xlsx
|
||||
officecli create deck.pptx
|
||||
|
||||
# 查看文档内容
|
||||
officecli view report.docx text
|
||||
|
||||
# 检查格式问题
|
||||
officecli view report.docx issues --json
|
||||
|
||||
# 读取指定单元格
|
||||
officecli get budget.xlsx /Sheet1/B5 --json
|
||||
|
||||
# 修改内容
|
||||
officecli set report.docx /body/p[1]/r[1] --prop text="Updated Title" --prop bold=true
|
||||
|
||||
# 驻留模式批量编辑（文档保持在内存中）
|
||||
officecli open presentation.pptx
|
||||
officecli set presentation.pptx /slide[1]/shape[1] --prop text="New Title"
|
||||
officecli set presentation.pptx /slide[2]/shape[3] --prop text="New Subtitle"
|
||||
officecli close presentation.pptx
|
||||
curl -fsSL https://officecli.ai/SKILL.md
|
||||
```
|
||||
|
||||
## 内置帮助
|
||||
**安装为 Claude Code 本地技能：**
|
||||
|
||||
属性名、取值格式不确定时，请用分层帮助查询，不要凭感觉写。将下文中的 `pptx` 换成 `docx` 或 `xlsx`；动词包括 `view`、`get`、`query`、`set`、`add`、`raw`。
|
||||
```bash
|
||||
curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md
|
||||
```
|
||||
|
||||
**其他智能体：** 将 `SKILL.md`（239 行，约 8K tokens）的内容添加到智能体的系统提示词或工具描述中。
|
||||
|
||||
</details>
|
||||
|
||||
### MCP 服务器 -- 将 OfficeCLI 作为原生 AI 工具使用
|
||||
|
||||
将 OfficeCLI 作为 MCP 服务器运行，在 Claude Desktop、Cursor 或任何 MCP 兼容智能体中作为原生工具使用 -- 无需编写封装代码。
|
||||
|
||||
```bash
|
||||
officecli mcp-serve
|
||||
```
|
||||
|
||||
将以下配置添加到您的 MCP 客户端（Claude Desktop、Cursor 等）：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"officecli": {
|
||||
"command": "officecli",
|
||||
"args": ["mcp-serve"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
OfficeCLI 将所有文档操作（create、view、get、query、set、add、remove、move、validate、batch、raw）暴露为 MCP 工具，支持结构化 JSON 输入和输出。
|
||||
|
||||
### 为什么智能体偏爱 OfficeCLI
|
||||
|
||||
- **确定性 JSON 输出** -- 每个命令都支持 `--json`，返回结构一致的数据。无需正则解析。
|
||||
- **基于路径的寻址** -- 每个元素都有稳定的路径（`/slide[1]/shape[2]`）。智能体无需理解 XML 命名空间即可导航文档。注意：路径使用 OfficeCLI 自有语法（1-based 索引，元素本地名称），非 XPath。
|
||||
- **渐进式复杂度** -- 从 L1（读取）开始，升级到 L2（修改），仅在必要时回退到 L3（原始 XML）。最大限度减少 token 消耗。
|
||||
- **自愈式工作流** -- `validate`、`view issues` 和帮助系统让智能体无需人工干预即可检测问题并自行修正。
|
||||
- **内置帮助** -- 属性名或取值格式不确定时，运行 `officecli <format> set <element>` 即可查询，无需猜测。
|
||||
- **自动安装** -- 无需手动配置技能文件。OfficeCLI 自动检测您的 AI 工具并完成配置。
|
||||
|
||||
### 内置帮助
|
||||
|
||||
属性名、取值格式不确定时，请用分层帮助查询，不要凭感觉写。将 `pptx` 换成 `docx` 或 `xlsx`；动词包括 `view`、`get`、`query`、`set`、`add`、`raw`。
|
||||
|
||||
```bash
|
||||
officecli pptx set # 全部可设置元素与属性
|
||||
|
|
@ -120,183 +223,52 @@ officecli pptx set shape # 某一类元素的详细说明
|
|||
officecli pptx set shape.fill # 单个属性格式与示例
|
||||
```
|
||||
|
||||
运行 `officecli --help` 可看到相同说明。若构建时包含 `wiki/` 目录，部分帮助内容可能嵌入二进制。
|
||||
运行 `officecli --help` 查看完整概览。
|
||||
|
||||
## 三层架构
|
||||
### JSON 输出格式
|
||||
|
||||
OfficeCLI 采用渐进式复杂度模型 — 从简单开始，仅在需要时深入。
|
||||
所有命令均支持 `--json`。常见响应格式：
|
||||
|
||||
### L1：读取与检查
|
||||
**单个元素**（`get --json`）：
|
||||
|
||||
文档内容的高级语义视图。
|
||||
```json
|
||||
{"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}}
|
||||
```
|
||||
|
||||
**元素列表**（`query --json`）：
|
||||
|
||||
```json
|
||||
[
|
||||
{"tag": "paragraph", "path": "/body/p[1]", "attributes": {"style": "Heading1", "text": "Title"}},
|
||||
{"tag": "paragraph", "path": "/body/p[5]", "attributes": {"style": "Heading1", "text": "Summary"}}
|
||||
]
|
||||
```
|
||||
|
||||
**错误** 在使用 `--json` 时返回非零退出码和 JSON 错误对象：
|
||||
|
||||
```json
|
||||
{"error": "Element not found: /body/p[99]"}
|
||||
```
|
||||
|
||||
**错误恢复** -- 智能体通过检查可用元素自行修正：
|
||||
|
||||
```bash
|
||||
# Word — 带行号的纯文本
|
||||
officecli view report.docx text
|
||||
# 智能体尝试无效路径
|
||||
officecli get report.docx /body/p[99] --json
|
||||
# 返回: {"error": "Element not found: /body/p[99]"}
|
||||
|
||||
# Word — 带格式标注的文本
|
||||
officecli view report.docx annotated
|
||||
|
||||
# Excel — 按列筛选查看
|
||||
officecli view budget.xlsx text --cols A,B,C --max-lines 50
|
||||
|
||||
# Excel — 检测公式和样式问题
|
||||
officecli view budget.xlsx issues --json
|
||||
|
||||
# PowerPoint — 所有幻灯片大纲
|
||||
officecli view deck.pptx outline
|
||||
|
||||
# PowerPoint — 字体和样式统计
|
||||
officecli view deck.pptx stats
|
||||
# 智能体通过查看可用元素自行修正
|
||||
officecli get report.docx /body --depth 1 --json
|
||||
# 返回可用子元素列表，智能体选择正确路径
|
||||
```
|
||||
|
||||
### L2：DOM 操作
|
||||
**变更确认**（`set`、`add`、`remove`、`move`、`create` 使用 `--json`）：
|
||||
|
||||
通过结构化元素路径和属性修改文档。
|
||||
|
||||
```bash
|
||||
# Word — 查询标题并设置格式（类 CSS 选择器；完整语法见帮助）
|
||||
officecli query report.docx "paragraph[style=Heading1]"
|
||||
officecli docx query # 选择器说明：属性匹配、:contains、:has() 等
|
||||
officecli set report.docx /body/p[1]/r[1] --prop bold=true --prop color=FF0000
|
||||
|
||||
# Word — 添加段落、删除段落
|
||||
officecli add report.docx /body --type paragraph --prop text="New paragraph" --index 3
|
||||
officecli remove report.docx /body/p[5]
|
||||
|
||||
# Excel — 读取和修改单元格
|
||||
officecli get budget.xlsx /Sheet1/B5 --json
|
||||
officecli set budget.xlsx /Sheet1/A1 --prop formula="=SUM(A2:A10)" --prop numFmt="0.00%"
|
||||
|
||||
# Excel — 新建工作表、添加行
|
||||
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
|
||||
officecli add budget.xlsx /Sheet1 --type row --prop values="Name,Amount,Date"
|
||||
|
||||
# PowerPoint — 修改幻灯片内容
|
||||
officecli set deck.pptx /slide[1]/shape[1] --prop text="New Title"
|
||||
officecli set deck.pptx /slide[2]/shape[3] --prop fontSize=24 --prop bold=true
|
||||
|
||||
# PowerPoint — 添加幻灯片、从其他幻灯片复制形状
|
||||
officecli add deck.pptx / --type slide
|
||||
officecli add deck.pptx /slide[3] --from /slide[1]/shape[2]
|
||||
|
||||
# 移动元素
|
||||
officecli move report.docx /body/p[5] --to /body --index 1
|
||||
```json
|
||||
{"success": true, "path": "/slide[1]/shape[1]"}
|
||||
```
|
||||
|
||||
### L3：原始 XML
|
||||
|
||||
通过 XPath 直接访问 XML — 任何 OpenXML 操作的通用兜底方案。
|
||||
|
||||
```bash
|
||||
# Word — 查看和修改原始 XML
|
||||
officecli raw report.docx document
|
||||
officecli raw-set report.docx document \
|
||||
--xpath "//w:p[1]" \
|
||||
--action append \
|
||||
--xml '<w:r><w:t>Injected text</w:t></w:r>'
|
||||
|
||||
# Word — 添加页眉
|
||||
officecli add-part report.docx /body --type header
|
||||
|
||||
# Excel — 查看工作表原始 XML
|
||||
officecli raw budget.xlsx /Sheet1
|
||||
|
||||
# Excel — 向工作表添加图表
|
||||
officecli add-part budget.xlsx /Sheet1 --type chart
|
||||
|
||||
# PowerPoint — 查看幻灯片原始 XML
|
||||
officecli raw deck.pptx /slide[1]
|
||||
|
||||
# 验证任意文档
|
||||
officecli validate report.docx
|
||||
officecli validate budget.xlsx
|
||||
```
|
||||
|
||||
## 支持的格式
|
||||
|
||||
| 格式 | 读取 | 修改 | 创建 |
|
||||
|------|------|------|------|
|
||||
| Word (.docx) | ✓ | ✓ | ✓ |
|
||||
| Excel (.xlsx) | ✓ | ✓ | ✓ |
|
||||
| PowerPoint (.pptx) | ✓ | ✓ | ✓ |
|
||||
|
||||
### Word — 段落、文本片段、表格、样式、页眉/页脚、图片、公式、批注、列表
|
||||
|
||||
### Excel — 单元格、公式、工作表、样式（字体、填充、边框、数字格式）、条件格式、图表
|
||||
|
||||
### PowerPoint — 幻灯片、形状、文本框、图片、动画、公式、主题、对齐与形状效果
|
||||
|
||||
## 驻留模式
|
||||
|
||||
对于多步骤工作流，驻留模式将文档保持在后台进程中，避免每次命令都重新加载文件。
|
||||
|
||||
```bash
|
||||
officecli open report.docx # 启动驻留进程
|
||||
officecli view report.docx text # 即时响应 — 无需重新加载
|
||||
officecli set report.docx ... # 即时响应 — 无需重新加载
|
||||
officecli close report.docx # 保存并退出
|
||||
```
|
||||
|
||||
通过命名管道通信，命令间延迟接近零。
|
||||
|
||||
## 批量模式（batch）
|
||||
|
||||
在**一次**打开/保存周期内执行多条命令（若文档已由 `open` 驻留，则会转发到驻留进程）。通过标准输入或 `--input` 传入 JSON 数组。
|
||||
|
||||
```bash
|
||||
echo '[{"command":"view","mode":"outline"},{"command":"get","path":"/slide[1]","depth":1}]' \
|
||||
| officecli batch deck.pptx
|
||||
```
|
||||
|
||||
使用 `--stop-on-error` 可在首次失败时中止。每条命令的 `command` 支持 `get`、`query`、`set`、`add`、`remove`、`move`、`view`、`raw`、`raw-set`、`validate` 等（完整字段见源码中的 `BatchItem`）。
|
||||
|
||||
## 更新与配置
|
||||
|
||||
CLI 可能在后台**非阻塞**地检查更新并与 GitHub 最新 release 对齐。配置位于 `~/.officecli/config.json`。
|
||||
|
||||
- **关闭自动更新检查：** `officecli config autoUpdate false`（查看当前值：`officecli config autoUpdate`）。
|
||||
- **单次调用跳过后台检查（如 CI）：** `OFFICECLI_SKIP_UPDATE=1 officecli ...`
|
||||
|
||||
仍可通过 `install.sh` / `install.ps1` 安装或升级二进制文件。
|
||||
|
||||
## Python 使用示例
|
||||
|
||||
```python
|
||||
import subprocess, json
|
||||
|
||||
def cli(*args): return subprocess.check_output(["officecli", *args], text=True)
|
||||
def cli_json(*args): return json.loads(cli(*args, "--json"))
|
||||
|
||||
cli("create", "deck.pptx")
|
||||
cli("set", "deck.pptx", "/slide[1]/shape[1]", "--prop", "text=Hello")
|
||||
shapes = cli_json("query", "deck.pptx", "shape")
|
||||
```
|
||||
|
||||
## JavaScript 使用示例
|
||||
|
||||
```js
|
||||
const { execFileSync } = require('child_process')
|
||||
|
||||
const cli = (...args) => execFileSync('officecli', args, { encoding: 'utf8' })
|
||||
const cliJson = (...args) => JSON.parse(cli(...args, '--json'))
|
||||
|
||||
cli('create', 'deck.pptx')
|
||||
cli('set', 'deck.pptx', '/slide[1]/shape[1]', '--prop', 'text=Hello')
|
||||
const shapes = cliJson('query', 'deck.pptx', 'shape')
|
||||
```
|
||||
|
||||
## AI 智能体集成
|
||||
|
||||
### 为什么 AI 智能体应该使用 OfficeCLI？
|
||||
|
||||
**确定性 JSON 输出** — 每个命令都支持 `--json`，返回结构一致的数据。无需正则解析。
|
||||
|
||||
**完善的验证与诊断** — `validate`、`view issues`、`raw-set` 等命令帮助智能体检测问题，并在修改后验证文档正确性。
|
||||
|
||||
**基于路径的寻址** — 每个文档中的每个元素都有稳定的路径。智能体无需理解 XML 命名空间即可导航文档。
|
||||
|
||||
**渐进式复杂度** — 智能体从 L1（读取）开始，升级到 L2（修改），仅在必要时回退到 L3（原始 XML）。这在保持所有操作可能的同时，最大限度减少 token 消耗。
|
||||
运行 `officecli --help` 查看退出码和错误格式的完整说明。
|
||||
|
||||
## 对比
|
||||
|
||||
|
|
@ -317,9 +289,277 @@ OfficeCLI 与其他 AI 智能体处理 Office 文档的方案相比如何？
|
|||
| Word + Excel + PowerPoint | ✓ | ✓ | ✓ | 需要多个库 |
|
||||
| 读取 + 写入 + 创建 | ✓ | ✓ | ✓ | ✓ |
|
||||
|
||||
## 构建
|
||||
## 三层架构
|
||||
|
||||
本地编译需要安装 [.NET 10 SDK](https://dotnet.microsoft.com/download)。在仓库根目录执行：
|
||||
OfficeCLI 采用渐进式复杂度 -- 从简单开始，仅在需要时深入。
|
||||
|
||||
### L1：读取与检查
|
||||
|
||||
文档内容的高级语义视图。
|
||||
|
||||
```bash
|
||||
# 带元素路径的纯文本
|
||||
officecli view report.docx text
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```
|
||||
/body/p[1] Executive Summary
|
||||
/body/p[2] Revenue increased by 25% year-over-year.
|
||||
/body/p[3] Key drivers include new product launches and market expansion.
|
||||
```
|
||||
|
||||
```bash
|
||||
# 带格式标注的文本
|
||||
officecli view report.docx annotated
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```
|
||||
[Heading1, Arial 18pt, bold] Executive Summary
|
||||
[Normal, Calibri 11pt] Revenue increased by 25% year-over-year.
|
||||
```
|
||||
|
||||
```bash
|
||||
# 检测格式和样式问题（JSON 输出）
|
||||
officecli view budget.xlsx issues --json
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```json
|
||||
[
|
||||
{"type": "format", "path": "/Sheet1/A1", "message": "Inconsistent font size"}
|
||||
]
|
||||
```
|
||||
|
||||
```bash
|
||||
# Excel 按列筛选查看
|
||||
officecli view budget.xlsx text --cols A,B,C --max-lines 50
|
||||
|
||||
# PowerPoint 大纲
|
||||
officecli view deck.pptx outline
|
||||
|
||||
# 文档统计
|
||||
officecli view deck.pptx stats
|
||||
|
||||
# CSS 风格查询
|
||||
officecli query report.docx "paragraph[style=Heading1]"
|
||||
|
||||
# OpenXML 模式校验
|
||||
officecli validate report.docx
|
||||
```
|
||||
|
||||
### L2：DOM 操作
|
||||
|
||||
通过结构化元素路径和属性修改文档。
|
||||
|
||||
**路径语法：** 路径使用 OfficeCLI 自有的元素寻址方式（非 XPath）。元素通过本地名称和 1-based 索引引用：`/slide[1]/shape[2]`、`/body/p[3]/r[1]`、`/Sheet1/A1`。Excel 也支持原生表示法：`Sheet1!A1` 与 `/Sheet1/A1` 等效。`view` 命令使用模式名称（`text`、`outline` 等），`get` 和 `set` 使用元素路径。
|
||||
|
||||
高级功能：
|
||||
- **3D 模型** -- 插入带 morph 动画的 `.glb` 3D 模型，直接通过命令行操作
|
||||
- **灵活的图片来源** -- 支持文件路径、base64 data URI 和 HTTP(S) URL
|
||||
- **表格单元格合并** -- 通过 `merge.right` 和 `merge.down` 实现专业表格布局
|
||||
|
||||
```bash
|
||||
# 设置任意元素的属性
|
||||
officecli set report.docx /body/p[1]/r[1] --prop bold=true --prop color=FF0000
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```
|
||||
Set 2 properties on /body/p[1]/r[1]
|
||||
```
|
||||
|
||||
```bash
|
||||
# 添加元素
|
||||
officecli add report.docx /body --type paragraph --prop text="New section" --index 3
|
||||
|
||||
# 添加幻灯片和形状
|
||||
officecli add deck.pptx / --type slide
|
||||
officecli add deck.pptx /slide[2] --type shape --prop text="Hello World"
|
||||
|
||||
# 克隆元素
|
||||
officecli add deck.pptx / --from /slide[1]
|
||||
|
||||
# 移动、交换、删除
|
||||
officecli move report.docx /body/p[5] --to /body --index 1
|
||||
officecli swap deck.pptx /slide[1] /slide[3]
|
||||
officecli remove report.docx /body/p[4]
|
||||
|
||||
# Excel 单元格操作
|
||||
officecli set budget.xlsx /Sheet1/A1 --prop formula="=SUM(A2:A10)" --prop numFmt="0.00%"
|
||||
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
|
||||
```
|
||||
|
||||
### L3：原始 XML
|
||||
|
||||
通过 XPath 直接访问 XML -- 任何 OpenXML 操作的通用兜底方案。
|
||||
|
||||
```bash
|
||||
# 查看文档部件的原始 XML
|
||||
officecli raw report.docx document
|
||||
|
||||
# 直接修改 XML
|
||||
officecli raw-set report.docx document \
|
||||
--xpath "//w:p[1]" \
|
||||
--action append \
|
||||
--xml '<w:r><w:t>Injected text</w:t></w:r>'
|
||||
|
||||
# 添加新的文档部件（页眉、图表等）
|
||||
officecli add-part report.docx /body --type header
|
||||
officecli add-part budget.xlsx /Sheet1 --type chart
|
||||
```
|
||||
|
||||
## 性能：驻留模式与批量模式
|
||||
|
||||
### 驻留模式
|
||||
|
||||
对于多步骤工作流（同一文件 3 条以上命令），驻留模式将文档保持在后台进程中，避免每次命令都重新加载文件。通过命名管道通信，命令间延迟接近零。
|
||||
|
||||
```bash
|
||||
officecli open report.docx # 启动驻留进程
|
||||
officecli view report.docx text # 即时响应 -- 无需重新加载
|
||||
officecli set report.docx ... # 即时响应 -- 无需重新加载
|
||||
officecli close report.docx # 保存并退出
|
||||
```
|
||||
|
||||
驻留进程绑定到特定文件 -- 使用 `officecli close` 保存并释放。如需丢弃更改，可直接终止进程而不调用 `close`。
|
||||
|
||||
### 批量模式
|
||||
|
||||
在一次打开/保存周期内执行多条操作，通过标准输入或 `--input` 传入 JSON 数组。
|
||||
|
||||
```bash
|
||||
# 使用 --input 文件（跨平台，推荐）
|
||||
officecli batch data.xlsx --input commands.json --json
|
||||
|
||||
# 使用标准输入 (Unix/macOS)
|
||||
echo '[
|
||||
{"command":"set","path":"/Sheet1/A1","props":{"value":"Name","bold":true}},
|
||||
{"command":"set","path":"/Sheet1/B1","props":{"value":"Score","bold":true}}
|
||||
]' | officecli batch data.xlsx --json
|
||||
```
|
||||
|
||||
注意：在 Windows 上使用 `echo` 时需注意引号转义。`--input` 标志配合文件在所有平台上均可靠工作。
|
||||
|
||||
**BatchItem 字段：** 每个命令对象支持 `command`（必需）、`path`、`props`（键值对象）、`type`、`from`、`to`、`index`、`xpath`、`action`、`xml`、`depth`、`mode` 和 `selector`。字段可用性取决于命令类型。
|
||||
|
||||
使用 `--stop-on-error` 可在首次失败时中止。批量模式支持：`add`、`set`、`get`、`query`、`remove`、`move`、`view`、`raw`、`raw-set`、`validate`。
|
||||
|
||||
## 实时预览
|
||||
|
||||
在浏览器中预览文档，编辑时实时更新：
|
||||
|
||||
```bash
|
||||
officecli watch deck.pptx
|
||||
```
|
||||
|
||||
OfficeCLI 将幻灯片、图表、公式和形状渲染为实时 HTML -- 基于 SSE 自动刷新。您所做的每一处修改都会即时反映在浏览器中。
|
||||
|
||||
## 命令参考
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `create <file>` | 创建空白 .docx、.xlsx 或 .pptx（根据扩展名判断类型） |
|
||||
| `view <file> <mode>` | 查看内容（模式：`outline`、`text`、`annotated`、`stats`、`issues`） |
|
||||
| `get <file> <path>` | 获取元素及子元素（`--depth N`、`--json`） |
|
||||
| `query <file> <selector>` | CSS 风格查询（`[attr=value]`、`:contains()`、`:has()` 等） |
|
||||
| `set <file> <path> --prop k=v` | 修改元素属性 |
|
||||
| `add <file> <parent> --type <t>` | 添加元素（或通过 `--from <path>` 克隆） |
|
||||
| `remove <file> <path>` | 删除元素 |
|
||||
| `move <file> <path>` | 移动元素（`--to <parent> --index N`） |
|
||||
| `swap <file> <path1> <path2>` | 交换两个元素 |
|
||||
| `validate <file>` | OpenXML 模式校验 |
|
||||
| `batch <file>` | 单次打开/保存周期内执行多条操作（JSON 通过标准输入或 `--input`） |
|
||||
| `watch <file>` | 在浏览器中实时 HTML 预览，自动刷新 |
|
||||
| `mcp-serve` | 启动 MCP 服务器，用于 AI 工具集成 |
|
||||
| `raw <file> <part>` | 查看文档部件的原始 XML |
|
||||
| `raw-set <file> <part>` | 通过 XPath 修改原始 XML |
|
||||
| `add-part <file> <parent>` | 添加新的文档部件（页眉、图表等） |
|
||||
| `open <file>` | 启动驻留模式（文档保持在内存中） |
|
||||
| `close <file>` | 保存并关闭驻留模式 |
|
||||
| `config <key> [value]` | 获取或设置配置 |
|
||||
| `<format> <command> [element]` | 内置帮助（如 `officecli pptx set shape`） |
|
||||
|
||||
## 端到端工作流示例
|
||||
|
||||
典型的智能体自愈式工作流：创建演示文稿、填充内容、验证并修复问题 -- 全程无需人工干预。
|
||||
|
||||
```bash
|
||||
# 1. 创建
|
||||
officecli create report.pptx
|
||||
|
||||
# 2. 添加内容
|
||||
officecli add report.pptx / --type slide --prop title="Q4 Results"
|
||||
officecli add report.pptx /slide[1] --type shape \
|
||||
--prop text="Revenue: $4.2M" --prop x=2cm --prop y=5cm --prop size=28
|
||||
officecli add report.pptx / --type slide --prop title="Details"
|
||||
officecli add report.pptx /slide[2] --type shape \
|
||||
--prop text="Growth driven by new markets" --prop x=2cm --prop y=5cm
|
||||
|
||||
# 3. 验证
|
||||
officecli view report.pptx outline
|
||||
officecli validate report.pptx
|
||||
|
||||
# 4. 修复发现的问题
|
||||
officecli view report.pptx issues --json
|
||||
# 根据输出修复问题，例如：
|
||||
officecli set report.pptx /slide[1]/shape[1] --prop font=Arial
|
||||
```
|
||||
|
||||
## 常用模式
|
||||
|
||||
```bash
|
||||
# 替换 Word 文档中所有 Heading1 文本
|
||||
officecli query report.docx "paragraph[style=Heading1]" --json | ...
|
||||
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"
|
||||
|
||||
# 将所有幻灯片内容导出为 JSON
|
||||
officecli get deck.pptx / --depth 2 --json
|
||||
|
||||
# 批量更新 Excel 单元格
|
||||
officecli batch budget.xlsx --input updates.json --json
|
||||
|
||||
# 交付前检查文档质量
|
||||
officecli validate report.docx && officecli view report.docx issues --json
|
||||
```
|
||||
|
||||
## 从任意语言调用
|
||||
|
||||
OfficeCLI 是标准的 CLI 工具 -- 通过子进程从任意语言调用。添加 `--json` 获取结构化输出。
|
||||
|
||||
**Python：**
|
||||
|
||||
```python
|
||||
import subprocess, json
|
||||
result = subprocess.check_output(["officecli", "view", "deck.pptx", "outline"], text=True)
|
||||
data = json.loads(subprocess.check_output(["officecli", "get", "deck.pptx", "/slide[1]", "--json"], text=True))
|
||||
```
|
||||
|
||||
**JavaScript：**
|
||||
|
||||
```js
|
||||
const { execFileSync } = require('child_process')
|
||||
const result = execFileSync('officecli', ['view', 'deck.pptx', 'outline'], { encoding: 'utf8' })
|
||||
const data = JSON.parse(execFileSync('officecli', ['get', 'deck.pptx', '/slide[1]', '--json'], { encoding: 'utf8' }))
|
||||
```
|
||||
|
||||
**Bash：**
|
||||
|
||||
```bash
|
||||
# 任何 Shell 脚本都可以直接调用 OfficeCLI
|
||||
officecli create report.docx
|
||||
officecli add report.docx /body --type paragraph --prop text="Hello from Bash"
|
||||
outline=$(officecli view report.docx outline)
|
||||
```
|
||||
|
||||
## 从源码构建
|
||||
|
||||
编译需要 [.NET 10 SDK](https://dotnet.microsoft.com/download)。输出为自包含的原生二进制文件 -- .NET 已内嵌，运行时无需安装。
|
||||
|
||||
```bash
|
||||
./build.sh
|
||||
|
|
@ -329,10 +569,44 @@ OfficeCLI 与其他 AI 智能体处理 Office 文档的方案相比如何？
|
|||
|
||||
[Apache License 2.0](LICENSE)
|
||||
|
||||
## 友情链接
|
||||
|
||||
[LINUX DO - 新的理想型社区](https://linux.do/)
|
||||
欢迎通过 [GitHub Issues](https://github.com/iOfficeAI/OfficeCLI/issues) 提交 Bug 报告和贡献代码。
|
||||
|
||||
---
|
||||
|
||||
[OfficeCLI.AI](https://OfficeCLI.AI)
|
||||
[OfficeCLI.AI](https://OfficeCLI.AI) | [GitHub](https://github.com/iOfficeAI/OfficeCLI)
|
||||
|
||||
<!--
|
||||
yaml-frontmatter:
|
||||
name: officecli
|
||||
version: see GitHub Releases
|
||||
description: The standard CLI for AI agents to create, read, and modify Office documents
|
||||
formats: [docx, xlsx, pptx]
|
||||
platforms: [macos, linux, windows]
|
||||
license: Apache-2.0
|
||||
keywords: [office, cli, ai-agent, automation, docx, xlsx, pptx, openxml, document-generation, mcp-server, word, excel, powerpoint]
|
||||
ai-agent-compatible: true
|
||||
mcp-server: true
|
||||
skill-file: SKILL.md
|
||||
skill-file-lines: 239
|
||||
install-command-unix: curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
|
||||
install-command-windows: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
-->
|
||||
|
||||
<!-- LLM/agent discovery metadata
|
||||
tool: officecli
|
||||
type: cli
|
||||
canonical: the standard CLI for AI-driven Office document manipulation
|
||||
formats: docx, xlsx, pptx
|
||||
capabilities: create, read, modify, validate, batch, resident-mode, mcp-server, live-preview, auto-install
|
||||
output: json, text, annotated
|
||||
platforms: macos, linux, windows
|
||||
license: Apache-2.0
|
||||
keywords: office, cli, ai-agent, automation, docx, xlsx, pptx, openxml, document-generation, mcp-server, word, excel, powerpoint, ai-tools, command-line, structured-output
|
||||
ai-agent-compatible: true
|
||||
mcp-server: true
|
||||
skill-file: SKILL.md
|
||||
skill-file-lines: 239
|
||||
alternatives: python-docx, openpyxl, python-pptx, libreoffice --headless
|
||||
install-command-unix: curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
|
||||
install-command-windows: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
|
||||
-->
|
||||
|
|
|
|||
BIN
assets/cat.gif
Normal file
BIN
assets/cat.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
BIN
assets/designwhatmovesyou.gif
Normal file
BIN
assets/designwhatmovesyou.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.4 MiB |
BIN
assets/efforless.gif
Normal file
BIN
assets/efforless.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 5.1 MiB |
BIN
assets/first-ppt-aionui.gif
Normal file
BIN
assets/first-ppt-aionui.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.4 MiB |
BIN
assets/horizon.gif
Normal file
BIN
assets/horizon.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.7 MiB |
BIN
assets/mars.gif
Normal file
BIN
assets/mars.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
BIN
assets/moridian.gif
Normal file
BIN
assets/moridian.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.6 MiB |
BIN
assets/move.gif
Normal file
BIN
assets/move.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.4 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 401 KiB |
Binary file not shown.
Loading…
Reference in a new issue