A Document You Can Navigate: OfficeCLI's Three-Layer Model
OfficeCLI's three-layer model answers a practical question: how can an AI agent move from a human request to a precise change in a Word document, Excel workbook, or PowerPoint deck without treating the file as either plain text or raw XML? The answer is a progressive interface. The agent first asks the document what it contains, then addresses a meaningful node, and only then reaches into package-level XML when the higher layers cannot express the job. Understanding that escalation helps readers choose the least fragile operation for the task in front of them.
The semantic layer turns a file into something to ask questions about
The first layer is for orientation. OfficeCLI can present a document as text, annotated text, an outline, statistics, or a list of issues. These views answer different questions before any edit occurs. Text shows what is written. An outline shows the document's broad structure. Statistics provide a compact account of its size and contents. An annotated view exposes formatting information that plain text hides. Issues identify problems that deserve attention, such as content, structure, or layout concerns.
That distinction matters because an agent usually begins with incomplete knowledge. A request such as “update the sales slide” does not identify a slide number, a shape, or the current layout. A request such as “fix the report table” says even less about the table's position, merged cells, or surrounding paragraphs. A semantic view lets the agent observe first. It can discover whether the expected heading exists, how many slides are in the deck, which worksheet contains the relevant data, or whether the file already carries warnings.
The views also let an agent match the amount of inspection to the uncertainty. If the problem is “which sheet contains this value?”, a text view may be enough. If the problem is “what will be affected by changing this paragraph?”, an outline or structured read is more useful. If the problem is “why does this document look unfinished?”, an issue view can expose a different class of evidence from a text search. This is a better starting point than opening every package part and asking the agent to infer the document's logical structure from implementation details.
The common handler contract gives these views a shared home. OfficeCLI's Word, Excel, and PowerPoint handlers all expose semantic reading operations, structured JSON variants, querying, mutations, raw package access, validation, and saving. The shared vocabulary does not make the formats identical. A paragraph has different rules from a spreadsheet cell, and a shape on a slide has different spatial behavior from either. The contract instead puts the format difference at the point where it belongs: inside the handler that understands the artifact, not in every caller that wants to inspect it.
This separation is useful for both humans and agents. A human can use a text or outline view to decide what to edit. An agent can request the same information as structured JSON and carry the result into its next decision. A get operation can return a document node with a tag, a path, and attributes such as text or position. A query operation can select a set of nodes using a CSS-like selector. The output is more useful than a raw XML dump because it preserves the document's meaning at the level of the requested task.
The difference between a semantic view and a raw representation is easiest to see in a small example. A Word file may store a heading as a paragraph with runs, properties, and style references. An agent trying to change the heading does not usually need to understand every relationship in the package; it needs to know that a heading exists, where it is, what text it carries, and which property expresses the intended change. A spreadsheet cell similarly has a value, type, formula, style, and position, but a request to change a formula should not require the agent to reconstruct the workbook's XML parts. The semantic layer hides irrelevant structure while leaving the relevant structure available for the next step.
Suppose a workbook contains a summary sheet and several data sheets. Reading the workbook's text view can establish which sheet names and values are present; an outline or query can then narrow the target to a table, chart, or cell. For a presentation, an outline can reveal slide and shape structure before the agent touches a title placeholder. For a Word report, annotated text can show whether a heading is styled as a heading or merely made to look large. In each case, inspection prevents the agent from using a plausible but wrong address.
The semantic layer also gives the agent a safer stopping point. Not every request requires a mutation. An issue report may reveal that the document is already structurally sound but has unresolved content. A query may confirm that a value appears in several places, which changes a one-cell edit into a deliberate multi-target operation. A text view may expose a leftover placeholder before any visual rendering is attempted. These are not conveniences around the “real” editing API; they are the observations that make an edit explainable.
Paths make ordinary edits precise; raw XML widens the boundary
Once the agent knows what it is looking at, the second layer makes the target addressable. OfficeCLI uses document paths built from element names and positions. A Word paragraph might be /body/p[3], a PowerPoint shape /slide[1]/shape[2], and an Excel cell /Sheet1/A1. The indexing is 1-based for document elements, which keeps the path readable as a description of the artifact rather than as an array offset hidden in a programming language.
The path is more than a locator for reading. It is the shared handle used by get, set, add, remove, move, and copy operations. That creates a small semantic DOM: the agent can inspect a node, change one of its properties, insert a related node, or reorganize existing content while staying at the document level. A table cell can receive text and formatting; a slide shape can receive text, color, and position; a worksheet can receive a value or formula. The operation is expressed in a common style, while the handler translates it into the format's actual package structures.
This does not mean that a path is a universal XPath expression. OfficeCLI's addressing uses document element names and its own indexing rules; the raw layer has a separate XPath-based interface for package XML. Keeping those concepts distinct prevents a common category error: a path such as /slide[1]/shape[2] identifies a semantic object in the handler's model, while an XPath identifies an XML node inside a particular package part. The former is designed for ordinary document operations; the latter depends on the internal representation of that part.
The model is designed for feedback rather than blind command emission. A typical edit can be expressed as “find the target, read its current attributes, set the smallest necessary property, and read it back.” If the path does not exist, the result can report not_found. If a property value is invalid, the result can identify that condition. If a property is not supported for the chosen element, OfficeCLI can return a warning or an unsupported-property signal instead of silently claiming that the requested formatting landed. The agent can then correct the request, choose a different node, or decide that the task belongs at a lower layer.
Help and JSON reinforce this model. The embedded help schemas describe element types and their settable properties, so an agent does not have to guess the vocabulary for a node. JSON envelopes give programs a stable way to distinguish a successful data response from an error or a successful mutation with caveats. This is a small but important design choice: the feedback loop needs to know not only what changed, but also what the tool declined to apply.
It also supports a round-trip style of work. An agent can read a node, retain the returned path and relevant attributes, and use that information to formulate a minimal update. If the update fails, the error is part of the next observation instead of an opaque process crash. If the update succeeds with a warning, the agent can preserve the warning in its decision about whether to continue. The path and result together form a narrow conversation with the document: the agent does not need to keep a complete internal copy of the package to make one justified change.
Stable identifiers improve the model where the underlying format provides them. Some elements can be addressed by a durable identifier rather than a position, which helps when inserting or deleting neighboring elements would otherwise shift indices. But stable IDs are not universal. Where an artifact exposes no suitable identifier, positional paths remain the fallback. That means a path saved for later may need to be re-resolved after a structural edit, especially in a live editing workflow. The path system reduces ambiguity; it does not eliminate document drift.
The third layer exists because a semantic model cannot anticipate every feature in a mature document format. raw can expose a package part, and raw-set can apply an XPath-based operation when a high-level element or property is not available. This is valuable for unusual designs, relationships, or features that the higher-level vocabulary does not yet cover. It is also where the abstraction becomes deliberately less protective.
At the raw layer, the caller must understand more of the file's internal logic. XML elements have schema-defined order. Parts are connected through relationships. A change that looks locally correct can leave a dangling relationship, an invalid child order, or a package that one consumer repairs on open. OfficeCLI therefore keeps validation in the same general workflow. Raw access expands what can be attempted; it does not convert every attempted edit into a trustworthy artifact.
The repository's examples make that boundary concrete. A PowerPoint presentation can be built with high-level slide and shape operations, but a design-heavy showcase uses raw XML to express detailed gradient backgrounds, specialized strokes, and exact drawing properties. The raw commands provide control that the high-level surface does not yet model, at the price of more responsibility for the author. The result is a reasoned escalation, not evidence that the high-level model failed: common document work remains easier to inspect and maintain when it stays semantic.
Word revisions show a different kind of specialization. A tracked insertion, deletion, formatting change, or move is not merely a new string or a removed node. It carries author, date, type, and review behavior that Word understands. OfficeCLI exposes those semantics through its Word handler, including accept and reject operations. The example demonstrates that the shared path idea can reach specialized behavior, while the revision vocabulary remains Word-specific rather than pretending to be a universal feature of all three formats.
The same boundary appears in diagrams. A native Mermaid flowchart or sequence diagram can become editable PowerPoint shapes, while an image route can use a browser renderer to cover a wider set of diagram types at the cost of raster editability. The important point is not the feature count. It is that the representation chosen for the output changes what the agent can inspect and repair later. A group of shapes remains individually editable; a picture is easier to place as one object but requires regeneration when its internal content changes.
The three layers should therefore be chosen by responsibility, not by prestige. Use semantic views when the main uncertainty is what the document contains. Use path-based operations when the requested change is expressible as a document-level property or structural action. Use raw OOXML when the feature genuinely lies outside the higher-level model and the caller is prepared to validate relationships and consumer behavior. This sequence keeps the agent close to the artifact's meaning for as long as possible.
That choice also sets up the next systems question. A path can identify the right node, but a real workflow may issue many commands against the same file, from several transports, while a document remains open in memory. The meaning of “the change succeeded” then depends on who owns the live state, when it is saved, and what an external reader can see.