office-excel

# Office Excel

## Tool Route

Use the bundled Office tools as the default artifact path. Do not install OfficeCLI, pandas, or openpyxl when the built-in tools cover the task.

- Use `read_files` with one `paths` item for a broad workbook read; use `metadata_only:true` when only prepared metadata is needed.
- Use `create_xlsx` for a new `.xlsx`, including multiple sheets, live formulas, number formats, widths, common cell styling, and native editable charts in each sheet's `charts` array. Pass `preview:false` when the required `office_review` will provide the visual evidence.
- Calling `create_xlsx` is mandatory for a supported new workbook. Bash or local code may prepare input rows or perform calculations that the tool cannot express, but must not construct, rewrite, or patch the final `.xlsx` package.
- Call `create_xlsx` exactly once for one requested workbook. Include the complete initial workbook and chart plan in that call. If QA finds a correction, use `office_read` and `edit_office` on the exact returned path; a file created in this conversation is refined in place. Do not restart with a second `create_xlsx`, create a “可编辑” duplicate, or publish an intermediate workbook.
- Use `office_read` `mode:"get"` with one `targets` array to batch-check representative formulas and computed/cached values; `mode:"text"` exposes displayed values, not formula definitions.
- Use `edit_office` for `.xlsx`; it creates a separate working copy when the source was not already produced by this conversation.
- After every create or edit, use `office_review` with `action:"check_and_render"` when visible layout matters, or `action:"check"` for structural-only validation. For a new workbook, reuse the sheet order supplied to `create_xlsx`; use `office_read` `mode:"outline"` when inspecting an existing workbook or after structural edits. Pass one-based worksheet positions in `office_review.pages`, never a worksheet name or cell range.

### Artifact identity and convergence

- Treat the `artifact_path` in the latest create/edit `<office-artifact>` receipt as the only current artifact identity. Pass that exact path verbatim to `office_read`, `office_review`, `edit_office`, and `publish_outputs`; do not reconstruct, shorten, or guess a path.
- Batch all required worksheet pages into one review when possible. Do not repeat `office_review` for an unchanged `artifact_revision` and the same page set; a page that failed to render may be retried once by itself.
- Continue editing only when the latest review identifies a concrete blocking defect and a targeted repair. Consolidate related repairs into one edit batch, then review the new revision. When structure is valid and only warnings or subjective polish remain, stop editing and publish.
- If `publish_outputs` returns `E_OUTPUT_NOT_PRODUCED`, do not edit, review, or regenerate the workbook. Retry publication once with an exact `eligible_current_turn_paths` entry from the error. If no eligible path is returned or that retry fails, report the preserved artifact and the delivery blocker; never guess another path or claim publication succeeded.

Use existing local compute only for transformations the Office tools do not express; do not add package dependencies during a workbook task. The built-in engine supports `.xlsx`, not legacy `.xls`, macro-enabled `.xlsm` editing, or macro execution. Require conversion for `.xls`. An `.xlsm` may be attached for broad read-only inspection through `read_files` only, but do not pass it to `office_read`, `edit_office`, or `office_review`; preserve the source, never execute its macros, and require target-Excel editing/review with macros disabled when its VBA project, external links, or signature must remain intact.

For an attached `.xlsm` capability-boundary request, first call `read_files` with the actual supplied workspace path and `metadata_only:true`. Then give the complete user-visible boundary result: name the untouched source, state explicitly that no VBA or macro was executed, and require target-Excel editing plus external-link and digital-signature review. End with the group protocol's required capability-boundary handback. Do not publish outputs, convert or copy the package, run shell/process tools, create an `.xlsx` substitute, or ask another actor to retry the unsupported edit.

## Integrity Rules

1. Inspect sheet order, formulas, cached values, data types, named ranges, hidden rows/columns, merges, freezes, filters, validations, conditional formatting, charts, and print settings before editing.
2. Preserve identifiers, phone numbers, ZIP codes, account codes, leading zeros, and numbers longer than 15 digits as text when appropriate.
3. Keep derived values as formulas when the recipient must audit or update the workbook. Do not replace formulas with cached values.
4. Match an existing template's conventions and edit only the requested cells or ranges.
5. Treat external links, pivots, macros, dynamic arrays, and newer formula functions as fidelity-sensitive. If calculation or preservation cannot be verified, say so explicitly.

## Delivery Check

Check representative formulas and ranges, error cells, data/number formats, widths, wrapped labels, hidden logic, validation rules, print areas, issue output, and the final path. A clean formula evaluation does not prove business correctness; verify assumptions and sample results separately.

## Analytical Report Contract

For KPI reports, monthly reports, dashboards, or sample-driven workbooks:

- Use editable sample/source data with enough periods and categories to support the requested trend and comparison; label synthetic data clearly.
- Put a visible editable `假设与参数` block or sheet inside the workbook; at minimum include reporting period, currency/units, a sample-data label, metric definitions, and editable targets or thresholds. Make target/comparison formulas reference those cells, and never leave assumptions only in the chat handoff.
- Keep derived metrics as live form