How OfficeCLI's Three-Layer Architecture Works: L1 View, L2 DOM, and L3 Raw XML

OfficeCLI uses a progressive escalation model with three layers—L1 View for reading, L2 DOM for structured modifications, and L3 Raw XML for direct XML manipulation—allowing users to interact with Office documents at exactly the right level of abstraction for their task.

The iOfficeAI/OfficeCLI repository implements a sophisticated three-layer architecture designed to minimize complexity when working with OpenXML documents. This progressive-complexity model separates document interactions into distinct abstraction levels, from high-level semantic views to raw XML access. By escalating from L1 to L3 only when necessary, the CLI optimizes token consumption for LLM-driven agents while shielding users from the intricacies of raw Office OpenXML unless absolutely required.

Understanding the Three-Layer Model

According to [SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md), the architecture follows a progressive escalation philosophy: start at L1, move to L2 when writes are needed, and fall back to L3 only as a last resort.

Layer	Abstraction	Primary Commands	Use Case
L1 – View	Semantic, human-readable representations	view, get, query	Inspection and analysis
L2 – DOM	Logical object model with structured editing	set, add, remove, move, swap	Most document modifications
L3 – Raw XML	Direct OpenXML part access	raw, raw-set	Unsupported edge cases

L1 View Layer: High-Level Inspection

The L1 View layer provides semantic, human-readable representations of documents without touching underlying XML. This is the cheapest layer token-wise and performs no mutations.

Key capabilities include:

• Text extraction and structural outline generation
• CSS-like selectors for querying document content
• Statistics and issue detection
• Annotated views showing semantic structure

Use L1 when you need to extract plain text, check document statistics, query specific elements (e.g., "find all Heading1 paragraphs"), or analyze document structure without modification.

L2 DOM Layer: Structured Editing

The L2 DOM layer operates on the document's logical object model, addressing every element and attribute via stable paths. This layer automatically handles schema validation and token-efficient updates.

L2 supports rich editing verbs:

• set: Modify properties or attributes
• add: Insert new elements
• remove: Delete elements
• move and swap: Reorganize content

The layer supports dotted-attribute aliases (e.g., font.color, pbdr.top) that map directly to OOXML attributes, eliminating the need to memorize raw XML namespaces. Use L2 for formatting changes, inserting shapes, updating cell values, and routine document modifications.

L3 Raw XML Layer: Direct Manipulation

The L3 Raw XML layer provides direct access to underlying OpenXML parts using XPath expressions and exact XML snippets. This layer requires you to write valid XPath and XML but offers complete control over the document structure.

Use L3 only when L2 cannot express the required change—such as injecting custom elements without CLI shortcuts, tweaking obscure attributes, or performing specific XML transformations that bypass the DOM abstraction.

Command Examples by Layer

The following examples demonstrate the progressive complexity across all three layers, assuming files named report.docx, slides.pptx, or data.xlsx.

L1 View Commands

# Extract plain text from a Word document

officecli view report.docx text

# List shapes on the first slide with depth limit

officecli get slides.pptx '/slide[1]' --depth 1

# Query paragraphs using CSS-like selectors

officecli query report.docx 'paragraph[style=Heading1]'

# Display document statistics (pages, words, shapes)

officecli view slides.pptx stats

L2 DOM Editing Commands

# Change slide background color using property alias

officecli set slides.pptx '/slide[1]' --prop fill=FFCC00

# Add styled paragraph to Word document

officecli add report.docx /body --type paragraph \
  --prop text="Executive Summary" --prop style=Heading1

# Update Excel cell value and formatting

officecli set data.xlsx '/Sheet1/A1' --prop value="Revenue" --prop bold=true

# Insert chart into PowerPoint slide

officecli add slides.pptx '/slide[2]' --type chart \
  --prop chartType=bar --prop title="Q4 Sales"

L3 Raw XML Commands

# Inject custom XML fragment into Word document part

officecli raw-set report.docx document \
  --xpath "/w:document/w:body/w:p[last()]" \
  --action append \
  --xml '<w:p><w:r><w:t>Custom XML added</w:t></w:r></w:p>'

# Modify attribute with no L2 shortcut using XPath

officecli raw-set slides.pptx slide \
  --xpath "/p:sld/p:spTree/p:sp[@id='12345']/p:spPr/a:solidFill/a:srgbClr" \
  --action setattr \
  --xml 'val="00FF00"'

Architecture Implementation Details

The three-layer architecture is documented across several key files in the repository:

• SKILL.md: Contains the definitive description of the progressive escalation model, property aliases, and layer selection guidelines.
• README.md: Summarizes L1/L2/L3 concepts, lists available view modes, and provides quick-start examples.
• sdk/node/README.md: Demonstrates how the layered approach is exposed programmatically in the Node.js SDK.
• sdk/python/README.md: Mirrors the CLI documentation for Python implementations, maintaining the same three-layer abstraction.

As implemented in iOfficeAI/OfficeCLI, L2 handles schema validation automatically, ensuring that modifications produce valid OpenXML. L3 bypasses these safeguards, requiring you to ensure XML validity manually.

Summary

• Start with L1 for all read-only operations including text extraction, statistical analysis, and CSS-like queries.
• Escalate to L2 when modifying documents using structured commands (set, add, remove) with dotted-attribute aliases for token efficiency.
• Reserve L3 for edge cases requiring direct XPath manipulation and raw XML injection when the DOM layer lacks expressiveness.
• Progressive escalation minimizes token consumption and complexity, making OfficeCLI optimal for both manual usage and LLM-driven automation.

Frequently Asked Questions

What is the difference between OfficeCLI L1 and L2 layers?

L1 (View) is read-only and provides semantic representations like plain text or document outlines without touching XML. L2 (DOM) enables structured modifications using commands like set and add with automatic schema validation. Use L1 for inspection and L2 for any document mutations.

When should I use L3 Raw XML instead of L2 DOM?

Use L3 Raw XML only when L2 cannot express the required change, such as adding custom elements without CLI shortcuts, modifying obscure attributes that lack dotted-attribute aliases, or performing specific XML transformations. L3 requires manual XPath and valid OpenXML but offers complete structural control.

How does OfficeCLI handle schema validation across layers?

L2 automatically validates changes against the OpenXML schema, ensuring document integrity. L3 bypasses these safeguards, placing responsibility on you to provide valid XML. L1 never modifies documents, so validation is not applicable.

Can I mix L2 DOM and L3 Raw XML commands in the same workflow?

Yes, you can interleave commands across layers within the same workflow. Process a document using L2 for standard modifications, then drop to L3 only for specific unsupported operations. However, since L3 changes raw XML directly, subsequent L2 commands may not recognize L3 modifications if they alter the DOM structure unexpectedly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}