Skip to content

ARCHITECTURE.en.md

Latest commit

 

History

History
142 lines (105 loc) · 5.88 KB

ARCHITECTURE.en.md

File metadata and controls

142 lines (105 loc) · 5.88 KB
Raw

Word AI Architecture

Language Preview
English Word AI system goals, components, PatchSet transactions, and Office.js session architecture.
中文 Word AI 的系统目标、组件分工、PatchSet 事务和 Office.js 会话架构。

Word AI is not a document generator. It is a document transaction system for AI-assisted editing of existing Word documents.

Goals

  • Preserve the original DOCX package structure.
  • Avoid full-document rebuilds and Markdown/HTML round-trips.
  • Keep writes constrained to explicit anchors.
  • Make every write auditable, reversible, and structurally validated.
  • Give agents rich read tools while forcing formal writes through PatchSet.
  • Support both offline DOCX file transactions and live Word session edits through Office.js.

Components

MCP Client

Codex, OpenAI Agents, or another MCP client reads document structure, identifies target anchors, asks the model to generate replacement text, and submits a constrained PatchSet.

MCP Server / Python Facade

The Python MCP facade exposes 63 tools:

  • package inspection and health checks
  • heading, paragraph, bookmark, and content-control navigation
  • table, style, numbering, field, image, hyperlink, comment, note, and revision inspection
  • PatchSet assessment, dry-run, backup, apply, validation, rollback, and diff
  • live Word session listing, snapshot, content-control reads, PatchSet preview/apply, selection wrapping, rollback, and command status
  • optional OfficeCLI auxiliary evidence: HTML rendering, screenshot sidecar export, issues, query, and validation

All paths are scoped to the configured primary root plus explicit --allow-root directories. Relative paths resolve under the primary root; absolute paths must be inside one of the allowed roots.

The facade exists for MCP compatibility, local path policy, Office.js bridge endpoints, installation ergonomics, and live-session command queues. Offline file transactions are delegated to the .NET backend by default.

Python OOXML Reference / Fallback

The Python OOXML layer remains available for read/index helpers and fallback/reference behavior:

  • read DOCX package parts
  • resolve content controls, paragraphs, and tables
  • provide sidecar indexes and text diffs
  • fall back for constrained PatchSet writes only when .NET is unavailable and WORD_AI_ENGINE=auto

.NET Open XML SDK Engine

The .NET 8 engine is the authoritative offline DOCX transaction backend. It supports the same PatchSet model and uses typed Open XML APIs plus OpenXmlValidator checks. The runtime selects backends in this order:

  1. WORD_AI_DOTNET_EXE or a packaged native executable under native/<rid>/ or dist/native/<rid>/.
  2. WORD_AI_DOTNET_DLL or the local Release DLL.
  3. Local source project via dotnet run --project.
  4. Python fallback only when .NET is unavailable and WORD_AI_ENGINE=auto.

Office.js Taskpane

The Word add-in is the session layer:

  • wrap current selection as a content control
  • assign stable tags and titles
  • list open-document content controls
  • connect to the local Office bridge
  • build, assess, dry-run, and apply PatchSets
  • register the currently open Word document as a live session
  • poll queued Codex commands from the local bridge
  • apply supported operations to the currently open Word document after a live preflight and SHA-256 precondition checks
  • return an audit object and rollback PatchSet for live session writes

Office Bridge

The local HTTP bridge is a convenience layer for the taskpane. It does not bypass MCP rules. File-level writes still flow through:

health -> assess -> dry-run -> backup -> apply -> validate -> diff

Bridge endpoints:

  • /office/read
  • /office/build-patchset
  • /office/assess-patchset
  • /office/preview-patchset
  • /office/apply-patchset
  • /office/session/register
  • /office/session/heartbeat
  • /office/session/poll
  • /office/session/result
  • /office/session/list

All /office/* POST requests require a local token.

Live Word session flow:

Codex MCP client
  -> word_session_* tool
  -> .wordai/sessions/commands/*.json
  -> Office.js taskpane polling loop
  -> Word.run(...)
  -> /office/session/result
  -> Codex receives audit / rollback / error

PatchSet Lifecycle

Source DOCX
  -> inspect and read target anchor
  -> model generates PatchSet
  -> assess risks and preconditions
  -> dry-run to temporary candidate
  -> validate structure
  -> backup source
  -> apply to a new output DOCX
  -> write audit JSON
  -> compare structure and text diff

Live Word session writes use the same PatchSet shape but do not create a new DOCX file. They target the document currently open in Word and are limited to content-control text operations. word_session_apply_patchset performs a live preflight first, re-checks expected_old_sha256, applies through Office.js, and returns audit plus rollback PatchSet.

Safety Boundaries

Word AI blocks or reports risk for:

  • missing source hash when preconditions are required
  • missing target old-text hash for high-risk operations
  • complex content controls with tables, fields, comments, images, or tracked changes
  • unauthorized package part changes
  • unexpected content-control/table/paragraph drift outside touched targets
  • tracked changes, field, image, comment, and table count drift unless explicitly authorized

Production Recommendations

  • Use the .NET Open XML SDK native binary as the authoritative batch editing engine.
  • Set WORD_AI_ENGINE=dotnet in production so missing backends fail fast instead of falling back.
  • Store document indexes in SQLite, PostgreSQL, or another durable store for large document sets.
  • Use render/PDF diff for release-grade validation.
  • Use Word COM, Aspose, or Syncfusion for field refresh and PDF export where Office.js APIs are insufficient.
  • Put write tools behind human approval, RBAC, audit logging, and network controls.