Agent tool for Office documents (DOCX / XLSX / PPTX) used by AIOrchestrator: create/open, view (outline/text/annotated/stats/issues), path-based DOM get/query/set/add/remove/move/swap, validate, batch, schema-driven help, template merge, save/restore — one document open at a time.
The class AIOrchestrator.API.OfficeTool is an agent tool: its public methods become
LLM-callable tools via reflection + XML docs (see OfficePorting.md and the
Agent Tools Guide).
It is a plugin: hosts load it dynamically from their Tools/ folder (startup scan +
hot-add watcher) — see the plugin architecture doc shipped with AIOffice
(Tools/ToolPluginArchitecture.md). It also ships as the NuGet package Graphene.OfficeTool
for hosts that reference tools statically (e.g. AgentBridge).
The document engine (OfficeCli.Core + OfficeCli.Handlers) is vendored byte-identical from
the OfficeCLI project (Apache-2.0) as a separate
Library project (ExternalDependencies/officecli, officecli.dll) that this adapter
references — deterministic JSON output, path-based addressing (/slide[1]/shape[2]),
schema-driven property validation, template merge, dump/batch round-trip and HTML rendering,
without the CLI shell.
Do not edit files under ExternalDependencies/officecli/: they are upstream-copied
(fidelity rules in VENDOR.md). The only allowed operations are DELETE (Program.cs,
sync-exclude.txt) and the csproj transform Exe → Library + InternalsVisibleTo
(applied automatically by the sync).
OfficeTool.cs is the minimal adapter (state, Dispose, helpers — no engine code): its
public method surface is regenerated by update-vendor.ps1 from the deterministic
analysis of the vendored CLI commands (which methods must be exposed, per vendor version).
The adapter reaches the engine's internal APIs through the InternalsVisibleTo grant added
by the sync transform; the sandbox boundary (SandboxPath.Resolve/ToAgent) is preserved in
every generated method. Do not edit the block between the @@ADAPTER_SURFACE markers by hand.
using OfficeCli.Handlers; // DocumentHandlerFactory
using OfficeCli.Core; // IDocumentHandler, CliException
using var handler = DocumentHandlerFactory.Open("/tmp/report.docx", editable: true);
var outline = handler.ViewOutline();
var json = handler.Get("/body/p[1]", depth: 1);
handler.Set("/body/p[1]", new Dictionary<string, object?> { ["bold"] = "true" });
handler.Save();The vendor tracks the stable release (the "Source code (zip)" asset of
https://github.com/iOfficeAI/OfficeCLI/releases), never the repository branch.
.\update-vendor.ps1 # latest release: sync + analysis + generation + build + tests
.\update-vendor.ps1 -Tag v1.0.144 # pin a specific release
The updater vendors the release byte-identical, converts the vendored csproj to Library,
regenerates the adapter surface (methods + XML docs) from the deterministic command
analysis, verifies embedded-resource parity and the LoadSkill contract, builds the plugin
and runs the OfficeTool.Tests harness. Nothing is committed or pushed — review, fix
reported gaps (new commands need a template in update-vendor.ps1, nothing else), then
commit (CI publishes the NuGet package). Full procedure: VENDOR.md.
| Path | Content |
|---|---|
OfficeTool.cs |
the agent tool class (AIOrchestrator.API.OfficeTool) — generated surface |
ExternalDependencies/officecli/ |
vendored engine project (byte-identical to upstream minus Program.cs, csproj converted to Library) |
skills/ |
agent skills (embedded by the officecli project as skills/… resources) |
schemas/help/ |
help schemas (embedded as schemas/help/… resources) |
OfficeTool.Tests/ |
deterministic end-to-end harness (docx/xlsx/pptx) |
OfficePorting.md |
porting guide: officecli → OfficeTool methods |
VENDOR.md |
upstream sync procedure + fidelity rules |
sync-from-upstream.ps1, update-vendor.ps1, sync-exclude.txt |
vendor update + adapter generation tooling |
NOTICE.md |
Apache-2.0 attribution for the vendored engine |