xufeng/EapilSkillMarket
1
0 Fork 0
forked from arechen/EapilSkillMarket
Code Pull Requests Activity

Sync third-party and MCP marketplace plugins

Browse Source 
Constraint: Public skills are published only by explicit administrator action unless they are tracked third-party market sources.
Confidence: high
Scope-risk: narrow
Directive: Keep private/internal skills out of the public marketplace and preserve normal incremental market Git history.
Tested: Marketplace validation passed.
This commit is contained in:
KeyInfo Bot committed 2026-10-06 15:29:22 +08:00
1 parent be7ce9bda2
commit 36c089fee9
298 files changed
+32935 -11681
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

plugins/codex/.agents/plugins/marketplace.json
-12
View File
@@ -400,18 +400,6 @@
},
"category": "Creativity"
},
{
"name": "postgres",
"source": {
"source": "local",
"path": "./plugins/postgres"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Data & Analytics"
},
{
"name": "literature-review",
"source": {
plugins/codex/plugins/caveman/THIRD_PARTY_SOURCE.json
+2 -2
View File
@@ -2,8 +2,8 @@
"sourceId": "caveman",
"repo": "https://github.com/JuliusBrussee/caveman.git",
"ref": "main",
"commit": "6571943370f7c9d4de1946481177ee7b306cd8e8",
"commit": "99aafe151a1be72be783e662858e8a0955add59f",
"adapter": "codex-plugin",
"sourcePath": "plugins/caveman",
"syncedAt": "2026-10-04T16:00:00Z"
"syncedAt": "2026-10-06T07:26:41Z"
}
plugins/codex/plugins/design-md/.codex-plugin/plugin.json
+6 -6
View File
@@ -1,13 +1,13 @@
{
"name": "design-md",
"version": "0.1.0",
"description": "创建、编辑、验证、比较、导出及应用 Google Labs DESIGN.md 文件，从而构建可供人工智能读取的规范化设计系统。",
"version": "1.0.0",
"description": "创建或完善 DESIGN.md，维护项目设计读取入口，并应用、核对界面设计规则。",
"author": {
"name": "EAPIL",
"url": "https://git.playones.com/arechen/EapilSkillMarket"
},
"homepage": "https://git.playones.com/arechen/EapilSkillMarket",
"repository": "https://git.playones.com/arechen/EapilSkillMarket",
"homepage": "https://git.playones.com/chenmingxuan/ManySkills/src/branch/main/plugins/design-md",
"repository": "https://git.playones.com/chenmingxuan/ManySkills",
"license": "Proprietary",
"keywords": [
"eapil",
@@ -17,8 +17,8 @@
"skills": "./skills/",
"interface": {
"displayName": "DESIGN.md生成器",
"shortDescription": "创建、编辑、验证、比较、导出及应用 Google Labs DESIGN.md 文件，从而构建可供人工智能读取的规范化设计系统。",
"longDescription": "创建、编辑、验证、比较、导出及应用 Google Labs DESIGN.md 文件，从而构建可供人工智能读取的规范化设计系统。",
"shortDescription": "生成设计指南，连接 Agent 读取入口，落实并核对界面设计。",
"longDescription": "基于项目证据创建或完善 Google Labs DESIGN.md，按 UI 作用域维护 AGENTS.md 入口，将设计意图和 token 落实到代码，并区分文档校验与渲染结果验证。",
"developerName": "EAPIL",
"category": "Creativity",
"capabilities": [
plugins/codex/plugins/design-md/THIRD_PARTY_SOURCE.json
+9
View File
@@ -0,0 +1,9 @@
{
"sourceId": "design-md",
"repo": "https://git.playones.com/chenmingxuan/ManySkills.git",
"ref": "v1.0.0",
"commit": "e869eb169eeb5a7cd9e58c0e514fa2dbbf50987d",
"adapter": "codex-plugin",
"sourcePath": "plugins/design-md",
"syncedAt": "2026-10-06T07:26:41Z"
}
plugins/codex/plugins/design-md/skills/design-md/SKILL.md
+13 -85
View File
@@ -1,100 +1,28 @@
---
name: design-md
description: Create, edit, validate, compare, export, and apply Google Labs DESIGN.md files for AI-readable design systems. Use when the user asks to create or use DESIGN.md, convert brand/UI guidance into DESIGN.md, derive design rules from an existing app or screenshots, keep frontend implementation aligned with design tokens and prose, validate DESIGN.md with the @google/design.md CLI, or export DESIGN.md tokens to Tailwind, CSS, JSON, or DTCG formats.
description: Create or revise DESIGN.md, connect it to project instructions, or apply and audit its visual rules in UI work.
---
# DESIGN.md
Use this skill to make `DESIGN.md` a durable source of truth for a product's visual identity. A `DESIGN.md` combines exact machine-readable tokens in YAML front matter with human-readable design rationale in Markdown.
Make the design usable across later UI tasks: a clear visual intent, exact values where known, an instruction entrypoint, and evidence that the implementation follows it. A saved DESIGN.md is context, not an automatic loader or enforcement mechanism.
## Core Workflow
## Choose the work
1. Locate and read any existing `DESIGN.md` before UI work. Treat it as design context for implementation, review, and refactoring.
2. If creating one, gather concrete inputs first: existing CSS/Tailwind/theme files, component styles, screenshots, brand notes, typography choices, accessibility constraints, and target audience.
3. Write exact tokens in YAML front matter and explain intent in prose. Tokens provide values; prose explains how to apply them.
4. Validate with the official CLI whenever Node/npm is available. Fix errors before considering the file ready.
5. Apply tokens and prose to implementation, then update `DESIGN.md` if the code intentionally changes the design system.
- **Create or revise:** Use the user's references and actual brand/theme/component evidence. Describe distinctive intent and important states; include tokens when useful. Read [format and tooling](references/design-md-reference.md) for schema, lint, diff, or export. The [template](assets/DESIGN.md.template) is a scaffold, not a palette or visual default. Remove or resolve its prompts before delivery.
- **Connect future tasks:** When creating or maintaining a design guide, merge a short, scoped reading rule into the project's active AGENTS.md. Preserve existing instructions; use paths relative to that guide. For placement, multiple apps, and a starting snippet, read [integration and application](references/applying-design.md). Do not claim a running session will automatically reload new instructions.
- **Apply or repair drift:** Resolve the design applicable to the target UI, understand its prose and token roles, and map this task's constraints to actual theme/component code. Follow [integration and application](references/applying-design.md) for scope and implementation checks. Small, clear UI changes need only their relevant constraints, not a full design-system rewrite.
Read `references/design-md-reference.md` when creating, editing, validating, exporting, or applying a `DESIGN.md`.
Use the user's explicit choice of design. Otherwise, use the nearest applicable DESIGN.md toward the project root; consume shared or ancestor guides only when inheritance is established. This is this skill's selection policy, not a file-loading feature of the format. Separate apps can have separate design sources.
Use `assets/DESIGN.md.template` as a starting point for new files when the repo has no existing `DESIGN.md`.
## Preserve intent
## Creating DESIGN.md
Treat the accepted guide as the design target. Repair code that deviates. Change the guide only when the task intentionally changes the design or authorizes filling a genuine gap; document that change rather than retroactively legitimizing an accidental implementation. Surface conflicting or missing decisions when they materially affect the result. Preserve valid custom sections and token keys.
Prefer a specific design reference over vague adjectives. For example, "enterprise observability console with dense tables and quiet operational controls" is more useful than "modern, clean, premium." Include intentional negative constraints only when they prevent likely drift.
Bind values into the project's existing styling system; check overrides, component variants, and computed styles. Exact tokens alone do not express density, hierarchy, brand character, or responsive behavior. Prose does not replace known exact values.
Structure the file as:
## Verification and delivery
```markdown
---
version: alpha
name: Product Design System
colors:
primary: "#1A1C1E"
typography:
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
lineHeight: 1.5
---
When the guide changes, use applicable format checks; CLI lint and export do not verify the UI. When UI changes, check representative rendered screens and affected states/sizes against the task's design constraints. Use existing browser/tests where available. If rendering is unavailable, report which checks remain; do not call a code-only or document-only check visual verification.
## Overview
...
```
Use canonical `##` sections in this order when relevant: `Overview`, `Colors`, `Typography`, `Layout`, `Elevation & Depth`, `Shapes`, `Components`, `Do's and Don'ts`. Preserve custom sections when editing existing files.
Include token groups that the implementation can actually use:
- `colors`: CSS color strings such as hex, rgb(), hsl(), oklch(), named colors, or transparent.
- `typography`: objects with font family, size, weight, line height, letter spacing, and optional feature/variation settings.
- `rounded`: radius scale values such as `4px`, `8px`, or `9999px`.
- `spacing`: spacing scale values such as `4px`, `8px`, `1rem`, or domain-specific numeric values.
- `components`: common component style tokens and state variants using literal values or references like `{colors.primary}`.
## Applying DESIGN.md
When building UI from an existing `DESIGN.md`:
1. Parse the YAML tokens first for exact values.
2. Read the prose for personality, density, hierarchy, interaction emphasis, and constraints.
3. Map tokens into the local styling system: CSS variables, Tailwind theme, component props, design-token JSON, or framework-specific theme configuration.
4. Use the design's named roles, not arbitrary nearby values. Do not invent new colors, radii, shadows, or type styles unless the task requires extending the system.
5. Keep visual decisions consistent across new screens and components. When a required pattern is absent, extend the `DESIGN.md` deliberately and validate it.
## CLI
Use the official package for checks and conversion:
```powershell
npx -p @google/design.md designmd lint DESIGN.md
npx -p @google/design.md designmd diff DESIGN.md DESIGN-v2.md
npx -p @google/design.md designmd export --format css-tailwind DESIGN.md > theme.css
npx -p @google/design.md designmd export --format json-tailwind DESIGN.md > tailwind.theme.json
npx -p @google/design.md designmd export --format dtcg DESIGN.md > tokens.json
```
On macOS/Linux, `npx @google/design.md ...` is also acceptable. On Windows/PowerShell, prefer the `designmd` alias via `npx -p @google/design.md designmd ...` because the `.md` executable name can collide with Markdown file associations.
If CLI access is unavailable, manually check:
- Front matter starts and ends with exact `---` fences.
- Token references resolve to existing YAML paths.
- Component text/background color pairs meet WCAG AA contrast for normal text when possible.
- Present sections follow canonical order.
- No duplicate section headings exist.
## Editing Rules
Preserve unknown sections and custom token keys unless the user asks to remove them. Unknown content is allowed by the format and often contains project-specific design context.
Reject or repair duplicate canonical sections, broken token references, obvious misspelled top-level keys, and invalid YAML.
Use `diff` when comparing versions. Treat added errors or warnings as a regression unless the user explicitly accepts the change.
## Sources
Primary reference: https://github.com/google-labs-code/design.md
Official spec: https://github.com/google-labs-code/design.md/blob/main/docs/spec.md
Report the active design and scope, changed files, relevant rule-to-code mappings, checks performed, and any unresolved drift. Keep the mapping in the handoff or existing project docs rather than creating extra reports for every small task.
plugins/codex/plugins/design-md/skills/design-md/agents/openai.yaml
+2 -2
View File
@@ -1,4 +1,4 @@
interface:
display_name: "DESIGN.md"
short_description: "Create and apply AI-readable design systems"
default_prompt: "Use $design-md to create or apply a DESIGN.md for this UI project."
short_description: "Create, connect, and apply project design rules"
default_prompt: "Use $design-md to create or apply this project's DESIGN.md, maintain its scoped instruction entrypoint, and verify the relevant UI result."
plugins/codex/plugins/design-md/skills/design-md/assets/AGENTS.design-snippet.md
+7
View File
@@ -0,0 +1,7 @@
<!-- Adapt the UI scope and DESIGN.md link to the target project. Merge into the effective AGENTS.md without replacing existing rules. This snippet is not a finished project instruction file. -->
## UI design
For UI changes in this guide's scope, read [DESIGN.md](DESIGN.md) and apply its design intent and exact values to the relevant theme and components. Backend-only tasks do not need this visual context.
Check representative rendered results and affected states/sizes against the rules used in the task. Repair implementation drift; do not rewrite the accepted design to excuse it. If the task deliberately changes the design, update its guide and implementation consistently.
plugins/codex/plugins/design-md/skills/design-md/assets/DESIGN.md.template
+9 -79
View File
@@ -1,103 +1,33 @@
---
version: alpha
name: Product Design System
description: Replace with a short description of the product or brand identity.
colors:
primary: "#111827"
on-primary: "#FFFFFF"
secondary: "#4B5563"
tertiary: "#2563EB"
neutral: "#F9FAFB"
surface: "#FFFFFF"
on-surface: "#111827"
border: "#E5E7EB"
typography:
headline-lg:
fontFamily: Inter
fontSize: 32px
fontWeight: 700
lineHeight: 1.15
headline-md:
fontFamily: Inter
fontSize: 24px
fontWeight: 650
lineHeight: 1.2
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
lineHeight: 1.5
label-md:
fontFamily: Inter
fontSize: 14px
fontWeight: 600
lineHeight: 1.2
rounded:
sm: 4px
md: 8px
lg: 12px
full: 9999px
spacing:
xs: 4px
sm: 8px
md: 16px
lg: 24px
xl: 32px
components:
page:
backgroundColor: "{colors.neutral}"
textColor: "{colors.on-surface}"
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "{colors.on-primary}"
typography: "{typography.label-md}"
rounded: "{rounded.md}"
padding: 12px
card:
backgroundColor: "{colors.surface}"
textColor: "{colors.on-surface}"
rounded: "{rounded.lg}"
padding: 24px
divider:
backgroundColor: "{colors.border}"
height: 1px
---
<!-- Scaffold only. Replace each bracketed prompt with project evidence, or omit an irrelevant section. Do not deliver these prompts as a finished guide. Add optional YAML tokens above this comment only when real values are known. No palette, font, radius, or component treatment is a default. -->
## Overview
Describe the specific product, audience, visual reference, interaction density, and emotional target. Prefer concrete references over generic terms.
[Product, audience, specific visual reference, distinctive identity and interaction density.]
## Colors
- **Primary** is used for core text and the strongest structural elements.
- **Secondary** is used for captions, metadata, borders, and low-emphasis controls.
- **Tertiary** is used for the primary action and focused interactive emphasis.
- **Neutral** is the page foundation.
- **Surface** is used for panels, inputs, cards, and modal content.
[Actual color roles and known values. Explain accent use and the relevant text/background pairs.]
## Typography
Describe the type hierarchy, role of each family, weight strategy, line-height rhythm, casing, and how dense or relaxed text should feel.
[Verified font availability, hierarchy, density, weights and fallback behavior.]
## Layout
Describe grid behavior, max content width, gutters, spacing rhythm, responsive behavior, and whether the UI should feel dense, spacious, editorial, operational, playful, or utilitarian.
[Concrete container, spacing and responsive rules relevant to this product.]
## Elevation & Depth
Describe how hierarchy is created: shadows, borders, tonal layers, color contrast, flat surfaces, or another strategy.
[How hierarchy is expressed: borders, surfaces, elevation or another evidenced approach.]
## Shapes
Describe radius usage and exceptions. State whether the system is sharp, soft, geometric, organic, or mixed.
[Shape language and justified exceptions. Use exact values when known.]
## Components
Describe primary buttons, secondary buttons, inputs, cards, lists, tables, navigation, dialogs, tabs, chips, tooltips, and state variants that matter to the product.
[Relevant components and their important states; connect each to the design roles or tokens.]
## Do's and Don'ts
- Do keep token usage consistent across screens.
- Do preserve the intended hierarchy and interaction emphasis.
- Don't introduce new colors, radii, shadows, or type styles without updating this file.
- Don't use generic decorative effects that conflict with the overview.
[Only a few intentional constraints that prevent likely drift; accepted design changes require task evidence.]
plugins/codex/plugins/design-md/skills/design-md/references/applying-design.md
+52
View File
@@ -0,0 +1,52 @@
# Connect and apply a design
This workflow belongs to this skill. Google Labs defines the DESIGN.md representation; it does not provide automatic Codex loading or a UI-enforcement hook.
## Choose the active source
Use a design explicitly selected by the user. Otherwise, locate DESIGN.md from the target UI directory toward the project root and use the closest relevant guide. Inspect stated scope and inheritance; do not merge unrelated palettes or silently apply a sibling application's guide. If a task spans multiple apps, identify a source for each.
Where shared root and local design rules intentionally compose, use the local rules for their declared overrides. A missing local detail is not permission to borrow a conflicting style. If the choice changes the outcome and cannot be inferred, ask a focused question.
## Keep it discoverable
When creating or maintaining DESIGN.md, merge a small UI-conditioned reading rule into the active project AGENTS.md, preserving existing instructions. Start from [the snippet](../assets/AGENTS.design-snippet.md) only if helpful. Adapt it to actual UI paths and document locations; paths in links are relative to the instruction file.
For multiple apps, the root guide can route console UI work to apps/console/DESIGN.md and storefront work to apps/storefront/DESIGN.md. A nested AGENTS.md is useful for distinct local instructions, but is not a substitute for ensuring the session actually receives the route. Do not copy the full design into always-loaded instructions. Backend-only tasks do not need to load visual guidance.
Codex documents startup discovery from the project root toward its working directory. DESIGN.md is not itself an automatically discovered instruction file. Adding or changing AGENTS.md does not prove the active session has reloaded it. For lasting integration, verify in a fresh session or explicitly supply the relevant guide for the current task. Check the chosen host's own loading rules if supporting another agent.
If the project has existing agent instructions, merge into the effective guide; do not introduce AGENTS.override.md or duplicate competing loader files merely to force precedence. If the task expressly limits edits to DESIGN.md, honor that limit and provide the reading rule as a handoff instead.
## Convert intent to implementation
Understand the prose, then the exact values and semantic roles. For this task, identify the constraints that affect the result: for example a control radius, accent role, text density, border hierarchy, font family, or mobile layout. Keep a compact rule-to-code mapping in working notes or the handoff; a small change may need only a sentence.
Map tokens into the current CSS variables, theme, utility system, or component API. Reuse semantic roles instead of selecting nearby literals. Inspect the existing cascade: global selectors, inline values, utilities, theme modes, library defaults and component variants can override a correct token declaration. Exported CSS that is not imported or is overridden has not applied the design.
For known measurements, bind or use the exact value. For prose-only intent, choose an implementation consistent with its specific reference and hierarchy. A required new state can use existing roles; introduce a new token only if the task justifies it. Keep unrequested theme redesigns outside scope.
If an implementation deviates from the accepted guide, fix the implementation. Change DESIGN.md only for a requested design change or an authorized, evidenced gap. Do not rewrite the document to match accidental drift. Preserve functional behavior and accessibility while repairing styles.
## Verify the result
Use checks appropriate to the changed constraints:
- Inspect computed styles for critical exact values after all overrides are applied.
- Inspect a representative rendered page for hierarchy, density, spacing, component shape and brand character that numeric checks cannot establish.
- Exercise affected hover/focus/disabled/error states and responsive sizes when those rules matter to this change; do not expand a tiny edit into a full UI audit.
- Run existing relevant UI/accessibility/build checks when they provide useful evidence.
Source inspection can catch an obvious unbound token, but it is not rendered verification. Document lint checks the document; export checks conversion; neither establishes implementation adherence. Record actual checks, unresolved drift, and missing browser or app access. Do not claim every future model will obey the guide.
## Delivery
Identify the active design file and UI scope, integration entrypoint, relevant constraints and implementation locations, and verification evidence. Report intentionally changed design rules separately from code repairs. Do not add persistent mapping reports, full visual regression suites, or extra tooling unless the task warrants them.
## Sources
Reviewed 2026-09-30:
- [Google Labs design philosophy](https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md): design context and intent.
- [Google Labs format](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md): tokens and prose.
- [Codex instruction discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md): instruction loading; DESIGN.md integration above is this skill's policy.
plugins/codex/plugins/design-md/skills/design-md/references/design-md-reference.md
+45 -168
View File
@@ -1,198 +1,75 @@
# DESIGN.md Reference
# DESIGN.md format and tooling
Use this reference after the `design-md` skill triggers. It is a compact working guide based on the Google Labs DESIGN.md alpha specification.
Use for creating a guide or handling schema, lint, diff, and export. For discovery, instruction integration, and implementation adherence, use [applying-design.md](applying-design.md).
## Purpose
## Current format
`DESIGN.md` is a plain-text design-system file for coding agents. It has two layers:
Reviewed 2026-09-30 against the Google Labs alpha specification and CLI 0.4.0. The CLI package version is separate from `version: alpha` in a document and from this plugin's release version.
- YAML front matter for machine-readable design tokens.
- Markdown prose for design rationale, usage guidance, and constraints.
A guide has a Markdown body and optional YAML front matter. With tokens, the YAML block must be at the beginning between exact `---` lines. Tokens carry normative values; prose explains their roles and fills in design decisions they cannot express. Prose-only guides are valid; do not invent token groups to satisfy a checklist.
Tokens are the exact values. Prose explains the design intent and tells the agent how to apply the values.
When relevant, canonical `##` sections occur in this order: Overview (or Brand & Style), Colors, Typography, Layout (or Layout & Spacing), Elevation & Depth (or Elevation), Shapes, Components, Do's and Don'ts. Omit irrelevant sections; preserve custom sections. Duplicate headings are errors. Section order comes from this format, unlike AGENTS.md's free-form headings.
## File Shape
## Tokens
```markdown
---
version: alpha
name: Product Name
description: Optional one-line summary
colors:
primary: "#1A1C1E"
typography:
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
lineHeight: 1.5
rounded:
sm: 4px
spacing:
md: 16px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "{colors.on-primary}"
rounded: "{rounded.sm}"
padding: 12px
---
- `name`: design-system name; optional `version` currently uses `alpha`, and `description` is optional.
- `omitted`: optional strings or objects with `section` and optional `reason`, for deliberately absent groups. Use for genuine omissions, not to hide problems.
- `colors`: named CSS colors; semantic roles explain where to use them.
- `typography`: named objects using `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` as applicable.
- `rounded`: dimensions; `spacing`: dimensions or numbers. Supported dimension units are px, em, rem; explain unitless spacing values. Unitless lineHeight is a font-size multiplier.
- `components`: component/state properties; known properties include backgroundColor, textColor, typography, rounded, padding, size, height, width. Custom properties can produce review warnings.
## Overview
...
```
References use `{path.to.token}`. Most targets are primitive values; component typography may reference a full typography object. Resolve every reference; unknown valid token names are allowed.
The front matter block must be at the top of the file and delimited by lines containing exactly `---`.
## Token Schema
Top-level token groups:
- `version`: optional, current alpha value is `alpha`.
- `name`: design-system name.
- `description`: optional short summary.
- `colors`: map of color token names to CSS color strings.
- `typography`: map of type role names to typography objects.
- `rounded`: map of radius scale names to dimensions.
- `spacing`: map of spacing names to dimensions or numbers.
- `components`: map of component/state names to component property tokens.
Common color token names: `primary`, `secondary`, `tertiary`, `neutral`, `surface`, `on-surface`, `error`, `on-primary`.
Common typography token names: `headline-display`, `headline-lg`, `headline-md`, `body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`.
Common rounded token names: `none`, `sm`, `md`, `lg`, `xl`, `full`.
## Token Types
Color values may be any valid CSS color string. Hex `#RRGGBB` is the safest default for broad tooling support.
Dimensions are numbers with `px`, `em`, or `rem` units. Use unitless `lineHeight` only when intended as a multiplier.
Typography objects may contain:
- `fontFamily`
- `fontSize`
- `fontWeight`
- `lineHeight`
- `letterSpacing`
- `fontFeature`
- `fontVariation`
Token references use `{path.to.token}`. Most references should point to primitive values, such as `{colors.primary}`. Component tokens may reference composite typography objects, such as `{typography.label-md}`.
## Section Order
Use `##` headings. Sections are optional, but present canonical sections should appear in this order:
1. `Overview` or `Brand & Style`
2. `Colors`
3. `Typography`
4. `Layout` or `Layout & Spacing`
5. `Elevation & Depth` or `Elevation`
6. `Shapes`
7. `Components`
8. `Do's and Don'ts`
An optional `#` title may appear before the sections. It is not parsed as a design section.
## Section Guidance
`Overview`: describe the product, audience, density, personality, and emotional target. Use specific visual references. Avoid generic adjective lists.
`Colors`: define roles, not just hex values. Explain where each color appears and where it must not appear.
`Typography`: define hierarchy, font families, weights, scale, line heights, casing, data/label treatments, and reading-density decisions.
`Layout`: define grid, max widths, spacing rhythm, density, page gutters, container behavior, and responsive expectations.
`Elevation & Depth`: define whether hierarchy comes from shadows, borders, tonal layers, contrast, surface color, or no elevation.
`Shapes`: define radius, border geometry, sharp/soft language, and where exceptions are allowed.
`Components`: define buttons, inputs, cards, tables, lists, chips, tabs, dialogs, tooltips, and state variants that matter to the product.
`Do's and Don'ts`: include practical guardrails. Keep them intentional; if the list gets long, strengthen the overview and component guidance.
## Components
Known component property tokens:
- `backgroundColor`
- `textColor`
- `typography`
- `rounded`
- `padding`
- `size`
- `height`
- `width`
Represent states and variants as related component keys:
This small schema example illustrates references, not a recommended palette:
```yaml
version: alpha
name: Example only
colors:
primary: "#152820"
on-action: "#FFFFFF"
rounded:
control: 0px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "{colors.on-primary}"
rounded: "{rounded.md}"
padding: 12px
button-primary-hover:
backgroundColor: "{colors.primary-hover}"
textColor: "{colors.on-action}"
rounded: "{rounded.control}"
```
Unknown component properties are allowed but should produce a warning during review.
Choose actual values from the project's design inputs. Define meaningful hover, focus, disabled, or error states where this task needs them; do not fabricate a full component library.
## Consumer Behavior
## Authoring
Preserve unknown section headings. Preserve unknown valid token names. Accept unknown component properties with review warnings. Reject duplicate section headings. Fix broken references.
Start with the product, audience, concrete visual reference, and distinctive layout/hierarchy. Explain scarce accents, typography roles, spacing, shape, elevation, and responsive behavior in terms an implementer can check. Keep prohibitions few and specific. Include exact measurements or token roles when the input supports them; identify unresolved design decisions rather than substituting a generic theme.
## Official CLI
Preserve established custom content when editing. If brand prose and tokens disagree, resolve the intended target using the user's request and source evidence; do not silently choose whichever matches existing code.
Install or run directly:
## CLI
```bash
npm install @google/design.md
npx @google/design.md lint DESIGN.md
```
Windows/PowerShell reliable form:
Node 18+ is required. Prefer the project's already pinned compatible package. The commands below were verified against 0.4.0; they run from the target project directory. The explicit `designmd` alias also avoids Windows .md file-association problems.
```powershell
npx -p @google/design.md designmd lint DESIGN.md
npx --yes --package @google/design.md@0.4.0 designmd lint DESIGN.md
npx --yes --package @google/design.md@0.4.0 designmd diff DESIGN.md DESIGN-v2.md
npx --yes --package @google/design.md@0.4.0 designmd export --format css-vars --prefix brand DESIGN.md
npx --yes --package @google/design.md@0.4.0 designmd export --format css-tailwind DESIGN.md
npx --yes --package @google/design.md@0.4.0 designmd export --format json-tailwind DESIGN.md
npx --yes --package @google/design.md@0.4.0 designmd export --format dtcg DESIGN.md
```
Useful commands:
Inspect output before integrating it. css-vars emits custom properties; css-tailwind targets Tailwind v4, json-tailwind targets Tailwind v3 theme.extend, and dtcg emits design tokens. Exporting does not wire the result into the app. Write files with the project's UTF-8 convention; avoid overwriting a hand-maintained theme through blind redirection.
```powershell
npx -p @google/design.md designmd lint DESIGN.md
npx -p @google/design.md designmd diff DESIGN.md DESIGN-v2.md
npx -p @google/design.md designmd export --format json-tailwind DESIGN.md > tailwind.theme.json
npx -p @google/design.md designmd export --format css-tailwind DESIGN.md > theme.css
npx -p @google/design.md designmd export --format dtcg DESIGN.md > tokens.json
npx -p @google/design.md designmd spec --rules
```
In 0.4.0, lint exits 1 for errors, 0 otherwise; file-read failures exit 2. Review warnings by their meaning: missing optional groups and custom fields need not be failures. For `missing-primary`, clarify the intended primary role using an existing approved color or token reference when appropriate; do not invent a new hue to silence the warning. Preserve existing semantic names. If the design deliberately has no primary role, explain that decision rather than implying lint guarantees model behavior.
`lint` exits nonzero when errors are present. `diff` exits nonzero when the later file has regressions, such as more errors or warnings.
Export can succeed despite lint errors, so its exit status is not a validation gate. Diff detects token changes and increased error/warning counts; it does not assess changed prose intent or rendered UI. Compare prose and implementation separately.
## Authoring Checklist
Without CLI access, check YAML validity where present, reference resolution, relevant section order, duplicate headings, and documented color-pair contrast. Label this manual validation and state its limits. Use project accessibility checks for the actual rendered states.
- Use a concrete visual reference in `Overview`.
- Include exact values for reusable colors, typography, spacing, radii, and core components.
- Explain scarcity rules for accents, shadows, display type, decorative elements, and motion.
- Use token references for component values instead of duplicating literals.
- Keep prose actionable for future UI generation.
- Validate with the CLI and fix structural errors.
## Primary sources
## Applying Checklist
- Read `DESIGN.md` before editing UI.
- Bind exact tokens to CSS variables, Tailwind theme entries, framework theme objects, or component constants.
- Use prose for unstated choices such as density, hierarchy, affordance strength, and restraint.
- Avoid introducing style drift. Add new tokens only when the task expands the design system.
- Re-run lint after editing `DESIGN.md`.
## Source Links
- Repository: https://github.com/google-labs-code/design.md
- Specification: https://github.com/google-labs-code/design.md/blob/main/docs/spec.md
- Philosophy: https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md
- [Format specification](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)
- [Design philosophy](https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md)
- [CLI 0.4.0 release](https://github.com/google-labs-code/design.md/releases/tag/0.4.0)
- [Export implementation](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts) and [diff implementation](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts)
plugins/codex/plugins/docx/.codex-plugin/plugin.json
+19 -18
View File
@@ -1,39 +1,40 @@
{
"name": "docx",
"version": "1.0.2",
"description": "可以创建、编辑和分析Word文档，同时支持跟踪修改、添加注释、保持格式不变以及提取文本内容。",
"version": "2.0.0",
"description": "创建、读取和编辑 Word 文档，适配简体中文排版与 Windows。",
"author": {
"name": "EAPIL",
"url": "https://git.playones.com/arechen/EapilSkillMarket"
"name": "Anthropic; EAPIL localization",
"url": "https://github.com/anthropics"
},
"homepage": "https://git.playones.com/arechen/EapilSkillMarket",
"repository": "https://git.playones.com/arechen/EapilSkillMarket",
"homepage": "https://github.com/anthropics/skills",
"repository": "https://github.com/anthropics/skills",
"license": "Proprietary",
"keywords": [
"eapil",
"codex-skill",
"docx"
"docx",
"documents",
"zh-CN",
"windows"
],
"skills": "./skills/",
"interface": {
"displayName": "docx",
"shortDescription": "可以创建、编辑和分析Word文档，同时支持跟踪修改、添加注释、保持格式不变以及提取文本内容。",
"longDescription": "可以创建、编辑和分析Word文档，同时支持跟踪修改、添加注释、保持格式不变以及提取文本内容。",
"developerName": "EAPIL",
"shortDescription": "创建、读取和编辑 Word 文档，适配简体中文排版与 Windows。",
"longDescription": "创建、读取和编辑 Word 文档，适配简体中文排版与 Windows。 包含最新上游工具及简体中文入口、PowerShell 指引和跨平台辅助脚本。依赖需按任务检查并安装。",
"developerName": "Anthropic; EAPIL",
"category": "Productivity",
"capabilities": [
"Read",
"Write"
],
"defaultPrompt": [
"使用 docx 帮我完成这个任务。"
"使用 docx 处理这份中文文档，并检查最终输出。"
],
"websiteURL": "https://git.playones.com/arechen/EapilSkillMarket",
"privacyPolicyURL": "https://git.playones.com/arechen/EapilSkillMarket",
"termsOfServiceURL": "https://git.playones.com/arechen/EapilSkillMarket",
"websiteURL": "https://github.com/anthropics/skills",
"privacyPolicyURL": "https://github.com/anthropics/skills",
"termsOfServiceURL": "https://github.com/anthropics/skills",
"brandColor": "#2563EB",
"screenshots": [],
"composerIcon": "./assets/market-icon.svg",
"logo": "./assets/market-icon.svg"
"logo": "./assets/market-icon.svg",
"composerIcon": "./assets/market-icon.svg"
}
}
plugins/codex/plugins/docx/THIRD_PARTY_SOURCE.json
+9
View File
@@ -0,0 +1,9 @@
{
"sourceId": "docx",
"repo": "https://github.com/anthropics/skills.git",
"ref": "main",
"commit": "683bc88e56f3e09ba94f7055977f3d3aa499f202",
"adapter": "claude-skill",
"sourcePath": "skills/docx",
"syncedAt": "2026-10-06T07:26:41Z"
}
plugins/codex/plugins/docx/skills/docx/SKILL.md
+21 -210
View File
@@ -1,227 +1,38 @@
---
name: docx
description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files), especially on Windows and in Chinese/CJK language contexts."
description: 创建、读取、编辑和检查 Word 文档或模板（.docx/.dotx），包括中文排版、表格、批注和修订；适用于简体中文与 Windows PowerShell 环境。
license: Proprietary. LICENSE.txt has complete terms
---
# DOCX creation, editing, and analysis
# Word 文档
## Overview
开始操作前读取 [references/platform.md](references/platform.md)，确认 Python、Node、中文字体及需要的转换工具。命令中的脚本路径均相对本 Skill。
A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
| 任务 | 选择 |
| --- | --- |
| 新建文档 | `docx`（Node）或 `python-docx`，按所需版式选择 |
| 提取正文或表格 | `python-docx`；需要查看修订时用 Pandoc 或检查 OOXML |
| 编辑复杂模板、批注或修订 | 保留 OOXML 结构，使用随附脚本 |
| .doc 旧文件 | LibreOffice 先转换为 .docx |
## Windows and Chinese-language defaults
## 中文版式
- Prefer PowerShell-compatible commands and always quote paths: `"C:\path with spaces\file.docx"`
- Before Python text processing on Windows, set UTF-8 mode: `$env:PYTHONUTF8='1'`
- If terminal output shows mojibake for Chinese text, treat it as a console issue first; verify by writing UTF-8 files and reopening them
- For Chinese documents, prefer fonts available on Windows (`Microsoft YaHei`, `SimSun`) and preserve existing East Asian font settings when editing
- Keep language tags consistent (`zh-CN` for Simplified Chinese) to reduce Word fallback-font behavior
未指定页面时，新文档采用 A4；已有文档沿用其页面和样式。正文中文字体设置 East Asian 字体，语言为 `zh-CN`，标题使用真正的标题样式。保持全角标点、编号、金额和原文引文；中文表格不要依赖空格对齐。
## Workflow Decision Tree
`docx` 创建时注意：表格同时指定列宽和单元格宽度；`ShadingType.CLEAR` 避免黑底；列表用 numbering 配置；`ImageRun` 指定类型；分页符放进 Paragraph。每个逻辑段落独立创建，不用换行模拟段落。需要 API 细节时按需读取 [upstream-guide.md](upstream-guide.md)。
### Reading/Analyzing Content
Use "Text extraction" or "Raw XML access" sections below
## 编辑与审阅
### Creating New Document
Use "Creating a new Word document" workflow
### Editing Existing Document
- **Your own document + simple changes**
Use "Basic OOXML editing" workflow
- **Someone else's document**
Use **"Redlining workflow"** (recommended default)
- **Legal, academic, business, or government docs**
Use **"Redlining workflow"** (required)
## Reading and analyzing content
### Text extraction
If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:
```bash
# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all
```
Windows PowerShell example:
先确认要清稿、批注还是保留修订；不要因文档类型自动强制红线。原有修订与批注保持不变，除非用户要求接受、拒绝或删除。
```powershell
pandoc --track-changes=all "C:\docs\contract-zh.docx" -o "C:\docs\output.md"
python "$skill\scripts\office_package.py" unpack ".\输入.docx" ".\unpacked"
python "$skill\scripts\merge_runs.py" ".\unpacked"
# 按需编辑 word/document.xml，保持命名空间与节点顺序
python "$skill\scripts\office_package.py" pack ".\unpacked" ".\输出.docx"
python "$skill\scripts\office\validate.py" ".\输出.docx" --original ".\输入.docx"
```
### Raw XML access
You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.
`scripts/comment.py` 支持为文档添加批注；输出的定位节点需放到对应正文位置才能显示。`scripts/accept_changes.py` 仅在用户要求接受全部修订时使用，输出新文件；超时、文件未保存或仍有修订均算失败。
#### Unpacking a file
`python ooxml/scripts/unpack.py <office_file> <output_directory>`
#### Key file structures
* `word/document.xml` - Main document contents
* `word/comments.xml` - Comments referenced in document.xml
* `word/media/` - Embedded images and media files
* Tracked changes use `<w:ins>` (insertions) and `<w:del>` (deletions) tags
## Creating a new Word document
When creating a new Word document from scratch, use **docx-js**, which allows you to create Word documents using JavaScript/TypeScript.
For Chinese/CJK content in new documents:
- Use Unicode strings directly (UTF-8 source files)
- Prefer explicit CJK-capable fonts in generated runs and styles
- Keep punctuation and full-width characters unchanged unless user requests normalization
### Workflow
1. **MANDATORY - READ ENTIRE FILE**: Read [`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
3. Export as .docx using Packer.toBuffer()
## Editing an existing Word document
When editing an existing Word document, use the **Document library** (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.
### Workflow
1. **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for the Document library API and XML patterns for directly editing document files.
2. Unpack the document: `python ooxml/scripts/unpack.py <office_file> <output_directory>`
3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
4. Pack the final document: `python ooxml/scripts/pack.py <input_directory> <office_file>`
The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.
## Redlining workflow for document review
This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. **CRITICAL**: For complete tracked changes, you must implement ALL changes systematically.
**Batching Strategy**: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.
**Principle: Minimal, Precise Edits**
When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the `<w:r>` element from the original and reusing it.
**Chinese text editing note**:
- Do not split a Chinese word/phrase across insertion/deletion boundaries unless required by the requested edit
- Preserve original full-width punctuation and spacing style in unchanged runs
- Keep original East Asian font tags in unchanged runs to avoid visual jumps after redlining
Example - Changing "30 days" to "60 days" in a sentence:
```python
# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'
# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'
```
### Tracked changes workflow
1. **Get markdown representation**: Convert document to markdown with tracked changes preserved:
```bash
pandoc --track-changes=all path-to-file.docx -o current.md
```
2. **Identify and group changes**: Review the document and identify ALL changes needed, organizing them into logical batches:
**Location methods** (for finding changes in XML):
- Section/heading numbers (e.g., "Section 3.2", "Article IV")
- Paragraph identifiers if numbered
- Grep patterns with unique surrounding text
- Document structure (e.g., "first paragraph", "signature block")
- **DO NOT use markdown line numbers** - they don't map to XML structure
**Batch organization** (group 3-10 related changes per batch):
- By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
- By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
- By complexity: Start with simple text replacements, then tackle complex structural changes
- Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"
3. **Read documentation and unpack**:
- **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
- **Unpack the document**: `python ooxml/scripts/unpack.py <file.docx> <dir>`
- **Note the suggested RSID**: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.
4. **Implement changes in batches**: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:
- Makes debugging easier (smaller batch = easier to isolate errors)
- Allows incremental progress
- Maintains efficiency (batch size of 3-10 changes works well)
**Suggested batch groupings:**
- By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
- By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
- By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")
For each batch of related changes:
**a. Map text to XML**: Grep for text in `word/document.xml` to verify how text is split across `<w:r>` elements.
**b. Create and run script**: Use `get_node` to find nodes, implement changes, then `doc.save()`. See **"Document Library"** section in ooxml.md for patterns.
**Note**: Always grep `word/document.xml` immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.
5. **Pack the document**: After all batches are complete, convert the unpacked directory back to .docx:
```bash
python ooxml/scripts/pack.py unpacked reviewed-document.docx
```
6. **Final verification**: Do a comprehensive check of the complete document:
- Convert final document to markdown:
```bash
pandoc --track-changes=all reviewed-document.docx -o verification.md
```
- Verify ALL changes were applied correctly:
```bash
grep "original phrase" verification.md # Should NOT find it
grep "replacement phrase" verification.md # Should find it
```
- Check that no unintended changes were introduced
## Converting Documents to Images
To visually analyze Word documents, convert them to images using a two-step process:
1. **Convert DOCX to PDF**:
```bash
soffice --headless --convert-to pdf document.docx
```
2. **Convert PDF pages to JPEG images**:
```bash
pdftoppm -jpeg -r 150 document.pdf page
```
This creates files like `page-1.jpg`, `page-2.jpg`, etc.
Options:
- `-r 150`: Sets resolution to 150 DPI (adjust for quality/size balance)
- `-jpeg`: Output JPEG format (use `-png` for PNG if preferred)
- `-f N`: First page to convert (e.g., `-f 2` starts from page 2)
- `-l N`: Last page to convert (e.g., `-l 5` stops at page 5)
- `page`: Prefix for output files
Example for specific range:
```bash
pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page # Converts only pages 2-5
```
## Code Style Guidelines
**IMPORTANT**: When generating code for DOCX operations:
- Write concise code
- Avoid verbose variable names and redundant operations
- Avoid unnecessary print statements
## Dependencies
Required dependencies (install if not available):
- **pandoc**:
- Windows: `winget install --id JohnMacFarlane.Pandoc -e`
- Linux: `sudo apt-get install pandoc`
- **docx (npm package)**: `npm install -g docx` (for creating new documents)
- **LibreOffice**:
- Windows: `winget install --id TheDocumentFoundation.LibreOffice -e`
- Linux: `sudo apt-get install libreoffice`
- **Poppler (pdftoppm)**:
- Windows: `winget install --id oschwartz10612.Poppler -e`
- Linux: `sudo apt-get install poppler-utils`
- **defusedxml**: `pip install defusedxml` (for secure XML parsing)
最终转换为 PDF，用 `scripts/render_pdf.py` 生成预览并查看中文字体、表格、页眉页脚、分页和页码。保留可编辑 Word 文件与用户需要的最终副本。
plugins/codex/plugins/docx/skills/docx/docx-js.md
-357
View File
@@ -1,357 +0,0 @@
# DOCX Library Tutorial
Generate .docx files with JavaScript/TypeScript.
**Important: Read this entire document before starting.** Critical formatting rules and common pitfalls are covered throughout - skipping sections may result in corrupted files or rendering issues.
## Setup
Assumes docx is already installed globally
If not installed: `npm install -g docx`
## Windows and Chinese-language defaults
- Prefer UTF-8 source files (`.js`/`.ts`) for Chinese text
- On Windows PowerShell, set UTF-8 mode before generating files: `$env:PYTHONUTF8='1'`
- Prefer CJK-capable fonts for Chinese output (`Microsoft YaHei`, `SimSun`, `Noto Sans CJK SC`)
- Keep path arguments quoted on Windows (for example: `"C:\docs\output.docx"`)
```javascript
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, ImageRun, Media,
Header, Footer, AlignmentType, PageOrientation, LevelFormat, ExternalHyperlink,
InternalHyperlink, TableOfContents, HeadingLevel, BorderStyle, WidthType, TabStopType,
TabStopPosition, UnderlineType, ShadingType, VerticalAlign, SymbolRun, PageNumber,
FootnoteReferenceRun, Footnote, PageBreak } = require('docx');
// Create & Save
const doc = new Document({ sections: [{ children: [/* content */] }] });
Packer.toBuffer(doc).then(buffer => fs.writeFileSync("doc.docx", buffer)); // Node.js
Packer.toBlob(doc).then(blob => { /* download logic */ }); // Browser
```
## Text & Formatting
```javascript
// IMPORTANT: Never use \n for line breaks - always use separate Paragraph elements
// ❌ WRONG: new TextRun("Line 1\nLine 2")
// ✅ CORRECT: new Paragraph({ children: [new TextRun("Line 1")] }), new Paragraph({ children: [new TextRun("Line 2")] })
// Basic text with all formatting options
new Paragraph({
alignment: AlignmentType.CENTER,
spacing: { before: 200, after: 200 },
indent: { left: 720, right: 720 },
children: [
new TextRun({ text: "Bold", bold: true }),
new TextRun({ text: "Italic", italics: true }),
new TextRun({ text: "Underlined", underline: { type: UnderlineType.DOUBLE, color: "FF0000" } }),
new TextRun({ text: "Colored", color: "FF0000", size: 28, font: "Arial" }), // Arial default
new TextRun({ text: "Highlighted", highlight: "yellow" }),
new TextRun({ text: "Strikethrough", strike: true }),
new TextRun({ text: "x2", superScript: true }),
new TextRun({ text: "H2O", subScript: true }),
new TextRun({ text: "SMALL CAPS", smallCaps: true }),
new SymbolRun({ char: "2022", font: "Symbol" }), // Bullet •
new SymbolRun({ char: "00A9", font: "Arial" }) // Copyright © - Arial for symbols
]
})
```
## Styles & Professional Formatting
```javascript
const doc = new Document({
styles: {
default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
paragraphStyles: [
// Document title style - override built-in Title style
{ id: "Title", name: "Title", basedOn: "Normal",
run: { size: 56, bold: true, color: "000000", font: "Arial" },
paragraph: { spacing: { before: 240, after: 120 }, alignment: AlignmentType.CENTER } },
// IMPORTANT: Override built-in heading styles by using their exact IDs
{ id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 32, bold: true, color: "000000", font: "Arial" }, // 16pt
paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // Required for TOC
{ id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
run: { size: 28, bold: true, color: "000000", font: "Arial" }, // 14pt
paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 } },
// Custom styles use your own IDs
{ id: "myStyle", name: "My Style", basedOn: "Normal",
run: { size: 28, bold: true, color: "000000" },
paragraph: { spacing: { after: 120 }, alignment: AlignmentType.CENTER } }
],
characterStyles: [{ id: "myCharStyle", name: "My Char Style",
run: { color: "FF0000", bold: true, underline: { type: UnderlineType.SINGLE } } }]
},
sections: [{
properties: { page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } },
children: [
new Paragraph({ heading: HeadingLevel.TITLE, children: [new TextRun("Document Title")] }), // Uses overridden Title style
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Heading 1")] }), // Uses overridden Heading1 style
new Paragraph({ style: "myStyle", children: [new TextRun("Custom paragraph style")] }),
new Paragraph({ children: [
new TextRun("Normal with "),
new TextRun({ text: "custom char style", style: "myCharStyle" })
]})
]
}]
});
```
**Professional Font Combinations:**
- **Arial (Headers) + Arial (Body)** - Good default for English-heavy documents
- **Times New Roman (Headers) + Arial (Body)** - Classic serif headers with modern sans-serif body
- **Microsoft YaHei (Headers) + Microsoft YaHei (Body)** - Recommended for Chinese-heavy documents on Windows
- **Noto Sans CJK SC (Headers) + Noto Sans CJK SC (Body)** - Better cross-platform CJK consistency
**Key Styling Principles:**
- **Override built-in styles**: Use exact IDs like "Heading1", "Heading2", "Heading3" to override Word's built-in heading styles
- **HeadingLevel constants**: `HeadingLevel.HEADING_1` uses "Heading1" style, `HeadingLevel.HEADING_2` uses "Heading2" style, etc.
- **Include outlineLevel**: Set `outlineLevel: 0` for H1, `outlineLevel: 1` for H2, etc. to ensure TOC works correctly
- **Use custom styles** instead of inline formatting for consistency
- **Set a default font** using `styles.default.document.run.font` - for Chinese/CJK output, use a CJK-capable font
- **Establish visual hierarchy** with different font sizes (titles > headers > body)
- **Add proper spacing** with `before` and `after` paragraph spacing
- **Use colors sparingly**: Default to black (000000) and shades of gray for titles and headings (heading 1, heading 2, etc.)
- **Set consistent margins** (1440 = 1 inch is standard)
## Lists (ALWAYS USE PROPER LISTS - NEVER USE UNICODE BULLETS)
```javascript
// Bullets - ALWAYS use the numbering config, NOT unicode symbols
// CRITICAL: Use LevelFormat.BULLET constant, NOT the string "bullet"
const doc = new Document({
numbering: {
config: [
{ reference: "bullet-list",
levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
{ reference: "first-numbered-list",
levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
{ reference: "second-numbered-list", // Different reference = restarts at 1
levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.LEFT,
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] }
]
},
sections: [{
children: [
// Bullet list items
new Paragraph({ numbering: { reference: "bullet-list", level: 0 },
children: [new TextRun("First bullet point")] }),
new Paragraph({ numbering: { reference: "bullet-list", level: 0 },
children: [new TextRun("Second bullet point")] }),
// Numbered list items
new Paragraph({ numbering: { reference: "first-numbered-list", level: 0 },
children: [new TextRun("First numbered item")] }),
new Paragraph({ numbering: { reference: "first-numbered-list", level: 0 },
children: [new TextRun("Second numbered item")] }),
// ⚠️ CRITICAL: Different reference = INDEPENDENT list that restarts at 1
// Same reference = CONTINUES previous numbering
new Paragraph({ numbering: { reference: "second-numbered-list", level: 0 },
children: [new TextRun("Starts at 1 again (because different reference)")] })
]
}]
});
// ⚠️ CRITICAL NUMBERING RULE: Each reference creates an INDEPENDENT numbered list
// - Same reference = continues numbering (1, 2, 3... then 4, 5, 6...)
// - Different reference = restarts at 1 (1, 2, 3... then 1, 2, 3...)
// Use unique reference names for each separate numbered section!
// ⚠️ CRITICAL: NEVER use unicode bullets - they create fake lists that don't work properly
// new TextRun("• Item") // WRONG
// new SymbolRun({ char: "2022" }) // WRONG
// ✅ ALWAYS use numbering config with LevelFormat.BULLET for real Word lists
```
## Tables
```javascript
// Complete table with margins, borders, headers, and bullet points
const tableBorder = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
const cellBorders = { top: tableBorder, bottom: tableBorder, left: tableBorder, right: tableBorder };
new Table({
columnWidths: [4680, 4680], // ⚠️ CRITICAL: Set column widths at table level - values in DXA (twentieths of a point)
margins: { top: 100, bottom: 100, left: 180, right: 180 }, // Set once for all cells
rows: [
new TableRow({
tableHeader: true,
children: [
new TableCell({
borders: cellBorders,
width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
// ⚠️ CRITICAL: Always use ShadingType.CLEAR to prevent black backgrounds in Word.
shading: { fill: "D5E8F0", type: ShadingType.CLEAR },
verticalAlign: VerticalAlign.CENTER,
children: [new Paragraph({
alignment: AlignmentType.CENTER,
children: [new TextRun({ text: "Header", bold: true, size: 22 })]
})]
}),
new TableCell({
borders: cellBorders,
width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
shading: { fill: "D5E8F0", type: ShadingType.CLEAR },
children: [new Paragraph({
alignment: AlignmentType.CENTER,
children: [new TextRun({ text: "Bullet Points", bold: true, size: 22 })]
})]
})
]
}),
new TableRow({
children: [
new TableCell({
borders: cellBorders,
width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
children: [new Paragraph({ children: [new TextRun("Regular data")] })]
}),
new TableCell({
borders: cellBorders,
width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
children: [
new Paragraph({
numbering: { reference: "bullet-list", level: 0 },
children: [new TextRun("First bullet point")]
}),
new Paragraph({
numbering: { reference: "bullet-list", level: 0 },
children: [new TextRun("Second bullet point")]
})
]
})
]
})
]
})
```
**IMPORTANT: Table Width & Borders**
- Use BOTH `columnWidths: [width1, width2, ...]` array AND `width: { size: X, type: WidthType.DXA }` on each cell
- Values in DXA (twentieths of a point): 1440 = 1 inch, Letter usable width = 9360 DXA (with 1" margins)
- Apply borders to individual `TableCell` elements, NOT the `Table` itself
**Precomputed Column Widths (Letter size with 1" margins = 9360 DXA total):**
- **2 columns:** `columnWidths: [4680, 4680]` (equal width)
- **3 columns:** `columnWidths: [3120, 3120, 3120]` (equal width)
## Links & Navigation
```javascript
// TOC (requires headings) - CRITICAL: Use HeadingLevel only, NOT custom styles
// ❌ WRONG: new Paragraph({ heading: HeadingLevel.HEADING_1, style: "customHeader", children: [new TextRun("Title")] })
// ✅ CORRECT: new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] })
new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" }),
// External link
new Paragraph({
children: [new ExternalHyperlink({
children: [new TextRun({ text: "Google", style: "Hyperlink" })],
link: "https://www.google.com"
})]
}),
// Internal link & bookmark
new Paragraph({
children: [new InternalHyperlink({
children: [new TextRun({ text: "Go to Section", style: "Hyperlink" })],
anchor: "section1"
})]
}),
new Paragraph({
children: [new TextRun("Section Content")],
bookmark: { id: "section1", name: "section1" }
}),
```
## Images & Media
```javascript
// Basic image with sizing & positioning
// CRITICAL: Always specify 'type' parameter - it's REQUIRED for ImageRun
new Paragraph({
alignment: AlignmentType.CENTER,
children: [new ImageRun({
type: "png", // NEW REQUIREMENT: Must specify image type (png, jpg, jpeg, gif, bmp, svg)
data: fs.readFileSync("image.png"),
transformation: { width: 200, height: 150, rotation: 0 }, // rotation in degrees
altText: { title: "Logo", description: "Company logo", name: "Name" } // IMPORTANT: All three fields are required
})]
})
```
## Page Breaks
```javascript
// Manual page break
new Paragraph({ children: [new PageBreak()] }),
// Page break before paragraph
new Paragraph({
pageBreakBefore: true,
children: [new TextRun("This starts on a new page")]
})
// ⚠️ CRITICAL: NEVER use PageBreak standalone - it will create invalid XML that Word cannot open
// ❌ WRONG: new PageBreak()
// ✅ CORRECT: new Paragraph({ children: [new PageBreak()] })
```
## Headers/Footers & Page Setup
```javascript
const doc = new Document({
sections: [{
properties: {
page: {
margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }, // 1440 = 1 inch
size: { orientation: PageOrientation.LANDSCAPE },
pageNumbers: { start: 1, formatType: "decimal" } // "upperRoman", "lowerRoman", "upperLetter", "lowerLetter"
}
},
headers: {
default: new Header({ children: [new Paragraph({
alignment: AlignmentType.RIGHT,
children: [new TextRun("Header Text")]
})] })
},
footers: {
default: new Footer({ children: [new Paragraph({
alignment: AlignmentType.CENTER,
children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] }), new TextRun(" of "), new TextRun({ children: [PageNumber.TOTAL_PAGES] })]
})] })
},
children: [/* content */]
}]
});
```
## Tabs
```javascript
new Paragraph({
tabStops: [
{ type: TabStopType.LEFT, position: TabStopPosition.MAX / 4 },
{ type: TabStopType.CENTER, position: TabStopPosition.MAX / 2 },
{ type: TabStopType.RIGHT, position: TabStopPosition.MAX * 3 / 4 }
],
children: [new TextRun("Left\tCenter\tRight")]
})
```
## Constants & Quick Reference
- **Underlines:** `SINGLE`, `DOUBLE`, `WAVY`, `DASH`
- **Borders:** `SINGLE`, `DOUBLE`, `DASHED`, `DOTTED`
- **Numbering:** `DECIMAL` (1,2,3), `UPPER_ROMAN` (I,II,III), `LOWER_LETTER` (a,b,c)
- **Tabs:** `LEFT`, `CENTER`, `RIGHT`, `DECIMAL`
- **Symbols:** `"2022"` (•), `"00A9"` (©), `"00AE"` (®), `"2122"` (™), `"00B0"` (°), `"F070"` (✓), `"F0FC"` (✗)
## Critical Issues & Common Mistakes
- **CRITICAL: PageBreak must ALWAYS be inside a Paragraph** - standalone PageBreak creates invalid XML that Word cannot open
- **ALWAYS use ShadingType.CLEAR for table cell shading** - Never use ShadingType.SOLID (causes black background).
- Measurements in DXA (1440 = 1 inch) | Each table cell needs ≥1 Paragraph | TOC requires HeadingLevel styles only
- **ALWAYS use custom styles** for professional appearance and proper visual hierarchy
- **ALWAYS set a default font** using `styles.default.document.run.font` (English: Arial/Calibri; Chinese: Microsoft YaHei/SimSun/Noto Sans CJK SC)
- **ALWAYS use columnWidths array for tables** + individual cell widths for compatibility
- **NEVER use unicode symbols for bullets** - always use proper numbering configuration with `LevelFormat.BULLET` constant (NOT the string "bullet")
- **NEVER use \n for line breaks anywhere** - always use separate Paragraph elements for each line
- **ALWAYS use TextRun objects within Paragraph children** - never use text property directly on Paragraph
- **CRITICAL for images**: ImageRun REQUIRES `type` parameter - always specify "png", "jpg", "jpeg", "gif", "bmp", or "svg"
- **CRITICAL for bullets**: Must use `LevelFormat.BULLET` constant, not string "bullet", and include `text: "•"` for the bullet character
- **CRITICAL for numbering**: Each numbering reference creates an INDEPENDENT list. Same reference = continues numbering (1,2,3 then 4,5,6). Different reference = restarts at 1 (1,2,3 then 1,2,3). Use unique reference names for each separate numbered section!
- **CRITICAL for TOC**: When using TableOfContents, headings must use HeadingLevel ONLY - do NOT add custom styles to heading paragraphs or TOC will break
- **Tables**: Set `columnWidths` array + individual cell widths, apply borders to cells not table
- **Set table margins at TABLE level** for consistent cell padding (avoids repetition per cell)
plugins/codex/plugins/docx/skills/docx/ooxml.md
-635
View File
@@ -1,635 +0,0 @@
# Office Open XML Technical Reference
**Important: Read this entire document before starting.** This document covers:
- [Technical Guidelines](#technical-guidelines) - Schema compliance rules and validation requirements
- [Document Content Patterns](#document-content-patterns) - XML patterns for headings, lists, tables, formatting, etc.
- [Document Library (Python)](#document-library-python) - Recommended approach for OOXML manipulation with automatic infrastructure setup
- [Tracked Changes (Redlining)](#tracked-changes-redlining) - XML patterns for implementing tracked changes
## Technical Guidelines
### Schema Compliance
- **Element ordering in `<w:pPr>`**: `<w:pStyle>`, `<w:numPr>`, `<w:spacing>`, `<w:ind>`, `<w:jc>`
- **Whitespace**: Add `xml:space='preserve'` to `<w:t>` elements with leading/trailing spaces
- **Unicode**: Escape characters in ASCII content: `"` becomes `&#8220;`
- **Character encoding reference**: Curly quotes `""` become `&#8220;&#8221;`, apostrophe `'` becomes `&#8217;`, em-dash `—` becomes `&#8212;`
- **Tracked changes**: Use `<w:del>` and `<w:ins>` tags with `w:author="Claude"` outside `<w:r>` elements
- **Critical**: `<w:ins>` closes with `</w:ins>`, `<w:del>` closes with `</w:del>` - never mix
- **RSIDs must be 8-digit hex**: Use values like `00AB1234` (only 0-9, A-F characters)
- **trackRevisions placement**: Add `<w:trackRevisions/>` after `<w:proofState>` in settings.xml
- **Images**: Add to `word/media/`, reference in `document.xml`, set dimensions to prevent overflow
### Windows and Chinese-language defaults
- Prefer quoted Windows paths (for example: `"C:\docs\unpacked"`)
- Before Python XML editing on Windows, set UTF-8 mode: `$env:PYTHONUTF8='1'`
- Preserve East Asian font tags (`w:eastAsia`) in unchanged runs when editing Chinese text
- For mixed English/Chinese runs, keep both `w:ascii` and `w:eastAsia` to avoid fallback-font shifts
## Document Content Patterns
### Basic Structure
```xml
<w:p>
<w:r><w:t>Text content</w:t></w:r>
</w:p>
```
### Headings and Styles
```xml
<w:p>
<w:pPr>
<w:pStyle w:val="Title"/>
<w:jc w:val="center"/>
</w:pPr>
<w:r><w:t>Document Title</w:t></w:r>
</w:p>
<w:p>
<w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
<w:r><w:t>Section Heading</w:t></w:r>
</w:p>
```
### Text Formatting
```xml
<!-- Bold -->
<w:r><w:rPr><w:b/><w:bCs/></w:rPr><w:t>Bold</w:t></w:r>
<!-- Italic -->
<w:r><w:rPr><w:i/><w:iCs/></w:rPr><w:t>Italic</w:t></w:r>
<!-- Underline -->
<w:r><w:rPr><w:u w:val="single"/></w:rPr><w:t>Underlined</w:t></w:r>
<!-- Highlight -->
<w:r><w:rPr><w:highlight w:val="yellow"/></w:rPr><w:t>Highlighted</w:t></w:r>
```
### Lists
```xml
<!-- Numbered list -->
<w:p>
<w:pPr>
<w:pStyle w:val="ListParagraph"/>
<w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr>
<w:spacing w:before="240"/>
</w:pPr>
<w:r><w:t>First item</w:t></w:r>
</w:p>
<!-- Restart numbered list at 1 - use different numId -->
<w:p>
<w:pPr>
<w:pStyle w:val="ListParagraph"/>
<w:numPr><w:ilvl w:val="0"/><w:numId w:val="2"/></w:numPr>
<w:spacing w:before="240"/>
</w:pPr>
<w:r><w:t>New list item 1</w:t></w:r>
</w:p>
<!-- Bullet list (level 2) -->
<w:p>
<w:pPr>
<w:pStyle w:val="ListParagraph"/>
<w:numPr><w:ilvl w:val="1"/><w:numId w:val="1"/></w:numPr>
<w:spacing w:before="240"/>
<w:ind w:left="900"/>
</w:pPr>
<w:r><w:t>Bullet item</w:t></w:r>
</w:p>
```
### Tables
```xml
<w:tbl>
<w:tblPr>
<w:tblStyle w:val="TableGrid"/>
<w:tblW w:w="0" w:type="auto"/>
</w:tblPr>
<w:tblGrid>
<w:gridCol w:w="4675"/><w:gridCol w:w="4675"/>
</w:tblGrid>
<w:tr>
<w:tc>
<w:tcPr><w:tcW w:w="4675" w:type="dxa"/></w:tcPr>
<w:p><w:r><w:t>Cell 1</w:t></w:r></w:p>
</w:tc>
<w:tc>
<w:tcPr><w:tcW w:w="4675" w:type="dxa"/></w:tcPr>
<w:p><w:r><w:t>Cell 2</w:t></w:r></w:p>
</w:tc>
</w:tr>
</w:tbl>
```
### Layout
```xml
<!-- Page break before new section (common pattern) -->
<w:p>
<w:r>
<w:br w:type="page"/>
</w:r>
</w:p>
<w:p>
<w:pPr>
<w:pStyle w:val="Heading1"/>
</w:pPr>
<w:r>
<w:t>New Section Title</w:t>
</w:r>
</w:p>
<!-- Centered paragraph -->
<w:p>
<w:pPr>
<w:spacing w:before="240" w:after="0"/>
<w:jc w:val="center"/>
</w:pPr>
<w:r><w:t>Centered text</w:t></w:r>
</w:p>
<!-- Font change - paragraph level (applies to all runs) -->
<w:p>
<w:pPr>
<w:rPr><w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/></w:rPr>
</w:pPr>
<w:r><w:t>Monospace text</w:t></w:r>
</w:p>
<!-- Font change - run level (specific to this text) -->
<w:p>
<w:r>
<w:rPr><w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/></w:rPr>
<w:t>This text is Courier New</w:t>
</w:r>
<w:r><w:t> and this text uses default font</w:t></w:r>
</w:p>
<!-- Chinese/CJK-safe run fonts -->
<w:p>
<w:r>
<w:rPr>
<w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="Microsoft YaHei"/>
</w:rPr>
<w:t>Mixed English and Chinese text</w:t>
</w:r>
</w:p>
```
## File Updates
When adding content, update these files:
**`word/_rels/document.xml.rels`:**
```xml
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering" Target="numbering.xml"/>
<Relationship Id="rId5" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image1.png"/>
```
**`[Content_Types].xml`:**
```xml
<Default Extension="png" ContentType="image/png"/>
<Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/>
```
### Images
**CRITICAL**: Calculate dimensions to prevent page overflow and maintain aspect ratio.
```xml
<!-- Minimal required structure -->
<w:p>
<w:r>
<w:drawing>
<wp:inline>
<wp:extent cx="2743200" cy="1828800"/>
<wp:docPr id="1" name="Picture 1"/>
<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
<pic:nvPicPr>
<pic:cNvPr id="0" name="image1.png"/>
<pic:cNvPicPr/>
</pic:nvPicPr>
<pic:blipFill>
<a:blip r:embed="rId5"/>
<!-- Add for stretch fill with aspect ratio preservation -->
<a:stretch>
<a:fillRect/>
</a:stretch>
</pic:blipFill>
<pic:spPr>
<a:xfrm>
<a:ext cx="2743200" cy="1828800"/>
</a:xfrm>
<a:prstGeom prst="rect"/>
</pic:spPr>
</pic:pic>
</a:graphicData>
</a:graphic>
</wp:inline>
</w:drawing>
</w:r>
</w:p>
```
### Links (Hyperlinks)
**IMPORTANT**: All hyperlinks (both internal and external) require the Hyperlink style to be defined in styles.xml. Without this style, links will look like regular text instead of blue underlined clickable links.
**External Links:**
```xml
<!-- In document.xml -->
<w:hyperlink r:id="rId5">
<w:r>
<w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
<w:t>Link Text</w:t>
</w:r>
</w:hyperlink>
<!-- In word/_rels/document.xml.rels -->
<Relationship Id="rId5" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
Target="https://www.example.com/" TargetMode="External"/>
```
**Internal Links:**
```xml
<!-- Link to bookmark -->
<w:hyperlink w:anchor="myBookmark">
<w:r>
<w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr>
<w:t>Link Text</w:t>
</w:r>
</w:hyperlink>
<!-- Bookmark target -->
<w:bookmarkStart w:id="0" w:name="myBookmark"/>
<w:r><w:t>Target content</w:t></w:r>
<w:bookmarkEnd w:id="0"/>
```
**Hyperlink Style (required in styles.xml):**
```xml
<w:style w:type="character" w:styleId="Hyperlink">
<w:name w:val="Hyperlink"/>
<w:basedOn w:val="DefaultParagraphFont"/>
<w:uiPriority w:val="99"/>
<w:unhideWhenUsed/>
<w:rPr>
<w:color w:val="467886" w:themeColor="hyperlink"/>
<w:u w:val="single"/>
</w:rPr>
</w:style>
```
## Document Library (Python)
Use the Document class from `scripts/document.py` for all tracked changes and comments. It automatically handles infrastructure setup (people.xml, RSIDs, settings.xml, comment files, relationships, content types). Only use direct XML manipulation for complex scenarios not supported by the library.
**Working with Unicode and Entities:**
- **Searching**: Both entity notation and Unicode characters work - `contains="&#8220;Company"` and `contains="\u201cCompany"` find the same text
- **Replacing**: Use either entities (`&#8220;`) or Unicode (`\u201c`) - both work and will be converted appropriately based on the file's encoding (ascii → entities, utf-8 → Unicode)
### Initialization
**Find the docx skill root** (directory containing `scripts/` and `ooxml/`):
```bash
# Linux/macOS example
find /mnt/skills -name "document.py" -path "*/docx/scripts/*" 2>/dev/null | head -1
```
```powershell
# Windows PowerShell example
Get-ChildItem -Path "$env:USERPROFILE" -Recurse -Filter document.py -ErrorAction SilentlyContinue |
Where-Object { $_.FullName -like "*\docx\scripts\document.py" } |
Select-Object -First 1 -ExpandProperty FullName
```
**Run your script with PYTHONPATH** set to the docx skill root:
```bash
PYTHONPATH=/mnt/skills/docx python your_script.py
```
```powershell
$env:PYTHONPATH = "C:\path\to\docx"
py -3 .\your_script.py
```
**In your script**, import from the skill root:
```python
from scripts.document import Document, DocxXMLEditor
# Basic initialization (automatically creates temp copy and sets up infrastructure)
doc = Document('unpacked')
# Customize author and initials
doc = Document('unpacked', author="John Doe", initials="JD")
# Enable track revisions mode
doc = Document('unpacked', track_revisions=True)
# Specify custom RSID (auto-generated if not provided)
doc = Document('unpacked', rsid="07DC5ECB")
```
### Creating Tracked Changes
**CRITICAL**: Only mark text that actually changes. Keep ALL unchanged text outside `<w:del>`/`<w:ins>` tags. Marking unchanged text makes edits unprofessional and harder to review.
**Attribute Handling**: The Document class auto-injects attributes (w:id, w:date, w:rsidR, w:rsidDel, w16du:dateUtc, xml:space) into new elements. When preserving unchanged text from the original document, copy the original `<w:r>` element with its existing attributes to maintain document integrity.
**Method Selection Guide**:
- **Adding your own changes to regular text**: Use `replace_node()` with `<w:del>`/`<w:ins>` tags, or `suggest_deletion()` for removing entire `<w:r>` or `<w:p>` elements
- **Partially modifying another author's tracked change**: Use `replace_node()` to nest your changes inside their `<w:ins>`/`<w:del>`
- **Completely rejecting another author's insertion**: Use `revert_insertion()` on the `<w:ins>` element (NOT `suggest_deletion()`)
- **Completely rejecting another author's deletion**: Use `revert_deletion()` on the `<w:del>` element to restore deleted content using tracked changes
```python
# Minimal edit - change one word: "The report is monthly" → "The report is quarterly"
# Original: <w:r w:rsidR="00AB12CD"><w:rPr><w:rFonts w:ascii="Calibri"/></w:rPr><w:t>The report is monthly</w:t></w:r>
node = doc["word/document.xml"].get_node(tag="w:r", contains="The report is monthly")
rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else ""
replacement = f'<w:r w:rsidR="00AB12CD">{rpr}<w:t>The report is </w:t></w:r><w:del><w:r>{rpr}<w:delText>monthly</w:delText></w:r></w:del><w:ins><w:r>{rpr}<w:t>quarterly</w:t></w:r></w:ins>'
doc["word/document.xml"].replace_node(node, replacement)
# Minimal edit - change number: "within 30 days" → "within 45 days"
# Original: <w:r w:rsidR="00XYZ789"><w:rPr><w:rFonts w:ascii="Calibri"/></w:rPr><w:t>within 30 days</w:t></w:r>
node = doc["word/document.xml"].get_node(tag="w:r", contains="within 30 days")
rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else ""
replacement = f'<w:r w:rsidR="00XYZ789">{rpr}<w:t>within </w:t></w:r><w:del><w:r>{rpr}<w:delText>30</w:delText></w:r></w:del><w:ins><w:r>{rpr}<w:t>45</w:t></w:r></w:ins><w:r w:rsidR="00XYZ789">{rpr}<w:t> days</w:t></w:r>'
doc["word/document.xml"].replace_node(node, replacement)
# Complete replacement - preserve formatting even when replacing all text
node = doc["word/document.xml"].get_node(tag="w:r", contains="apple")
rpr = tags[0].toxml() if (tags := node.getElementsByTagName("w:rPr")) else ""
replacement = f'<w:del><w:r>{rpr}<w:delText>apple</w:delText></w:r></w:del><w:ins><w:r>{rpr}<w:t>banana orange</w:t></w:r></w:ins>'
doc["word/document.xml"].replace_node(node, replacement)
# Insert new content (no attributes needed - auto-injected)
node = doc["word/document.xml"].get_node(tag="w:r", contains="existing text")
doc["word/document.xml"].insert_after(node, '<w:ins><w:r><w:t>new text</w:t></w:r></w:ins>')
# Partially delete another author's insertion
# Original: <w:ins w:author="Jane Smith" w:date="..."><w:r><w:t>quarterly financial report</w:t></w:r></w:ins>
# Goal: Delete only "financial" to make it "quarterly report"
node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "5"})
# IMPORTANT: Preserve w:author="Jane Smith" on the outer <w:ins> to maintain authorship
replacement = '''<w:ins w:author="Jane Smith" w:date="2025-01-15T10:00:00Z">
<w:r><w:t>quarterly </w:t></w:r>
<w:del><w:r><w:delText>financial </w:delText></w:r></w:del>
<w:r><w:t>report</w:t></w:r>
</w:ins>'''
doc["word/document.xml"].replace_node(node, replacement)
# Change part of another author's insertion
# Original: <w:ins w:author="Jane Smith"><w:r><w:t>in silence, safe and sound</w:t></w:r></w:ins>
# Goal: Change "safe and sound" to "soft and unbound"
node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "8"})
replacement = f'''<w:ins w:author="Jane Smith" w:date="2025-01-15T10:00:00Z">
<w:r><w:t>in silence, </w:t></w:r>
</w:ins>
<w:ins>
<w:r><w:t>soft and unbound</w:t></w:r>
</w:ins>
<w:ins w:author="Jane Smith" w:date="2025-01-15T10:00:00Z">
<w:del><w:r><w:delText>safe and sound</w:delText></w:r></w:del>
</w:ins>'''
doc["word/document.xml"].replace_node(node, replacement)
# Delete entire run (use only when deleting all content; use replace_node for partial deletions)
node = doc["word/document.xml"].get_node(tag="w:r", contains="text to delete")
doc["word/document.xml"].suggest_deletion(node)
# Delete entire paragraph (in-place, handles both regular and numbered list paragraphs)
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph to delete")
doc["word/document.xml"].suggest_deletion(para)
# Add new numbered list item
target_para = doc["word/document.xml"].get_node(tag="w:p", contains="existing list item")
pPr = tags[0].toxml() if (tags := target_para.getElementsByTagName("w:pPr")) else ""
new_item = f'<w:p>{pPr}<w:r><w:t>New item</w:t></w:r></w:p>'
tracked_para = DocxXMLEditor.suggest_paragraph(new_item)
doc["word/document.xml"].insert_after(target_para, tracked_para)
# Optional: add spacing paragraph before content for better visual separation
# spacing = DocxXMLEditor.suggest_paragraph('<w:p><w:pPr><w:pStyle w:val="ListParagraph"/></w:pPr></w:p>')
# doc["word/document.xml"].insert_after(target_para, spacing + tracked_para)
```
### Adding Comments
```python
# Add comment spanning two existing tracked changes
# Note: w:id is auto-generated. Only search by w:id if you know it from XML inspection
start_node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"})
end_node = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "2"})
doc.add_comment(start=start_node, end=end_node, text="Explanation of this change")
# Add comment on a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text")
doc.add_comment(start=para, end=para, text="Comment on this paragraph")
# Add comment on newly created tracked change
# First create the tracked change
node = doc["word/document.xml"].get_node(tag="w:r", contains="old")
new_nodes = doc["word/document.xml"].replace_node(
node,
'<w:del><w:r><w:delText>old</w:delText></w:r></w:del><w:ins><w:r><w:t>new</w:t></w:r></w:ins>'
)
# Then add comment on the newly created elements
# new_nodes[0] is the <w:del>, new_nodes[1] is the <w:ins>
doc.add_comment(start=new_nodes[0], end=new_nodes[1], text="Changed old to new per requirements")
# Reply to existing comment
doc.reply_to_comment(parent_comment_id=0, text="I agree with this change")
```
### Rejecting Tracked Changes
**IMPORTANT**: Use `revert_insertion()` to reject insertions and `revert_deletion()` to restore deletions using tracked changes. Use `suggest_deletion()` only for regular unmarked content.
```python
# Reject insertion (wraps it in deletion)
# Use this when another author inserted text that you want to delete
ins = doc["word/document.xml"].get_node(tag="w:ins", attrs={"w:id": "5"})
nodes = doc["word/document.xml"].revert_insertion(ins) # Returns [ins]
# Reject deletion (creates insertion to restore deleted content)
# Use this when another author deleted text that you want to restore
del_elem = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "3"})
nodes = doc["word/document.xml"].revert_deletion(del_elem) # Returns [del_elem, new_ins]
# Reject all insertions in a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text")
nodes = doc["word/document.xml"].revert_insertion(para) # Returns [para]
# Reject all deletions in a paragraph
para = doc["word/document.xml"].get_node(tag="w:p", contains="paragraph text")
nodes = doc["word/document.xml"].revert_deletion(para) # Returns [para]
```
### Inserting Images
**CRITICAL**: The Document class works with a temporary copy at `doc.unpacked_path`. Always copy images to this temp directory, not the original unpacked folder.
```python
from PIL import Image
import shutil, os
# Initialize document first
doc = Document('unpacked')
# Copy image and calculate full-width dimensions with aspect ratio
media_dir = os.path.join(doc.unpacked_path, 'word/media')
os.makedirs(media_dir, exist_ok=True)
shutil.copy('image.png', os.path.join(media_dir, 'image1.png'))
img = Image.open(os.path.join(media_dir, 'image1.png'))
width_emus = int(6.5 * 914400) # 6.5" usable width, 914400 EMUs/inch
height_emus = int(width_emus * img.size[1] / img.size[0])
# Add relationship and content type
rels_editor = doc['word/_rels/document.xml.rels']
next_rid = rels_editor.get_next_rid()
rels_editor.append_to(rels_editor.dom.documentElement,
f'<Relationship Id="{next_rid}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image1.png"/>')
doc['[Content_Types].xml'].append_to(doc['[Content_Types].xml'].dom.documentElement,
'<Default Extension="png" ContentType="image/png"/>')
# Insert image
node = doc["word/document.xml"].get_node(tag="w:p", line_number=100)
doc["word/document.xml"].insert_after(node, f'''<w:p>
<w:r>
<w:drawing>
<wp:inline distT="0" distB="0" distL="0" distR="0">
<wp:extent cx="{width_emus}" cy="{height_emus}"/>
<wp:docPr id="1" name="Picture 1"/>
<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">
<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
<pic:nvPicPr><pic:cNvPr id="1" name="image1.png"/><pic:cNvPicPr/></pic:nvPicPr>
<pic:blipFill><a:blip r:embed="{next_rid}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill>
<pic:spPr><a:xfrm><a:ext cx="{width_emus}" cy="{height_emus}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr>
</pic:pic>
</a:graphicData>
</a:graphic>
</wp:inline>
</w:drawing>
</w:r>
</w:p>''')
```
### Getting Nodes
```python
# By text content
node = doc["word/document.xml"].get_node(tag="w:p", contains="specific text")
# By line range
para = doc["word/document.xml"].get_node(tag="w:p", line_number=range(100, 150))
# By attributes
node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"})
# By exact line number (must be line number where tag opens)
para = doc["word/document.xml"].get_node(tag="w:p", line_number=42)
# Combine filters
node = doc["word/document.xml"].get_node(tag="w:r", line_number=range(40, 60), contains="text")
# Disambiguate when text appears multiple times - add line_number range
node = doc["word/document.xml"].get_node(tag="w:r", contains="Section", line_number=range(2400, 2500))
```
### Saving
```python
# Save with automatic validation (copies back to original directory)
doc.save() # Validates by default, raises error if validation fails
# Save to different location
doc.save('modified-unpacked')
# Skip validation (debugging only - needing this in production indicates XML issues)
doc.save(validate=False)
```
### Direct DOM Manipulation
For complex scenarios not covered by the library:
```python
# Access any XML file
editor = doc["word/document.xml"]
editor = doc["word/comments.xml"]
# Direct DOM access (defusedxml.minidom.Document)
node = doc["word/document.xml"].get_node(tag="w:p", line_number=5)
parent = node.parentNode
parent.removeChild(node)
parent.appendChild(node) # Move to end
# General document manipulation (without tracked changes)
old_node = doc["word/document.xml"].get_node(tag="w:p", contains="original text")
doc["word/document.xml"].replace_node(old_node, "<w:p><w:r><w:t>replacement text</w:t></w:r></w:p>")
# Multiple insertions - use return value to maintain order
node = doc["word/document.xml"].get_node(tag="w:r", line_number=100)
nodes = doc["word/document.xml"].insert_after(node, "<w:r><w:t>A</w:t></w:r>")
nodes = doc["word/document.xml"].insert_after(nodes[-1], "<w:r><w:t>B</w:t></w:r>")
nodes = doc["word/document.xml"].insert_after(nodes[-1], "<w:r><w:t>C</w:t></w:r>")
# Results in: original_node, A, B, C
```
## Tracked Changes (Redlining)
**Use the Document class above for all tracked changes.** The patterns below are for reference when constructing replacement XML strings.
### Validation Rules
The validator checks that the document text matches the original after reverting Claude's changes. This means:
- **NEVER modify text inside another author's `<w:ins>` or `<w:del>` tags**
- **ALWAYS use nested deletions** to remove another author's insertions
- **Every edit must be properly tracked** with `<w:ins>` or `<w:del>` tags
### Tracked Change Patterns
**CRITICAL RULES**:
1. Never modify the content inside another author's tracked changes. Always use nested deletions.
2. **XML Structure**: Always place `<w:del>` and `<w:ins>` at paragraph level containing complete `<w:r>` elements. Never nest inside `<w:r>` elements - this creates invalid XML that breaks document processing.
**Text Insertion:**
```xml
<w:ins w:id="1" w:author="Claude" w:date="2025-07-30T23:05:00Z" w16du:dateUtc="2025-07-31T06:05:00Z">
<w:r w:rsidR="00792858">
<w:t>inserted text</w:t>
</w:r>
</w:ins>
```
**Text Deletion:**
```xml
<w:del w:id="2" w:author="Claude" w:date="2025-07-30T23:05:00Z" w16du:dateUtc="2025-07-31T06:05:00Z">
<w:r w:rsidDel="00792858">
<w:delText>deleted text</w:delText>
</w:r>
</w:del>
```
**Deleting Another Author's Insertion (MUST use nested structure):**
```xml
<!-- Nest deletion inside the original insertion -->
<w:ins w:author="Jane Smith" w:id="16">
<w:del w:author="Claude" w:id="40">
<w:r><w:delText>monthly</w:delText></w:r>
</w:del>
</w:ins>
<w:ins w:author="Claude" w:id="41">
<w:r><w:t>weekly</w:t></w:r>
</w:ins>
```
**Restoring Another Author's Deletion:**
```xml
<!-- Leave their deletion unchanged, add new insertion after it -->
<w:del w:author="Jane Smith" w:id="50">
<w:r><w:delText>within 30 days</w:delText></w:r>
</w:del>
<w:ins w:author="Claude" w:id="51">
<w:r><w:t>within 30 days</w:t></w:r>
</w:ins>
```
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/pack.py
-170
View File
@@ -1,170 +0,0 @@
#!/usr/bin/env python3
"""
Tool to pack a directory into a .docx, .pptx, or .xlsx file with XML formatting undone.
Example usage:
python pack.py <input_directory> <office_file> [--force]
"""
import argparse
import os
import shutil
import subprocess
import sys
import tempfile
import zipfile
from pathlib import Path
try:
import defusedxml.minidom as secure_minidom
except ImportError: # pragma: no cover - fallback for minimal environments
import xml.dom.minidom as secure_minidom
def resolve_soffice_binary():
candidates = ["soffice", "soffice.com", "soffice.exe"]
if sys.platform == "win32":
candidates = ["soffice.com", "soffice.exe", "soffice"]
for name in candidates:
resolved = shutil.which(name)
if resolved:
return resolved
if sys.platform == "win32":
for env_key in ("ProgramFiles", "ProgramFiles(x86)"):
value = os.environ.get(env_key)
if not value:
continue
root = Path(value)
for rel in ("LibreOffice/program/soffice.com", "LibreOffice/program/soffice.exe"):
candidate = root / rel
if candidate.exists():
return str(candidate)
return None
def main():
parser = argparse.ArgumentParser(description="Pack a directory into an Office file")
parser.add_argument("input_directory", help="Unpacked Office document directory")
parser.add_argument("output_file", help="Output Office file (.docx/.pptx/.xlsx)")
parser.add_argument("--force", action="store_true", help="Skip validation")
args = parser.parse_args()
try:
success = pack_document(
args.input_directory, args.output_file, validate=not args.force
)
if args.force:
print("Warning: Skipped validation, file may be corrupt", file=sys.stderr)
elif not success:
print("Contents would produce a corrupt file.", file=sys.stderr)
print("Please validate XML before repacking.", file=sys.stderr)
print("Use --force to skip validation and pack anyway.", file=sys.stderr)
sys.exit(1)
except ValueError as exc:
sys.exit(f"Error: {exc}")
def pack_document(input_dir, output_file, validate=False):
input_dir = Path(input_dir)
output_file = Path(output_file)
if not input_dir.is_dir():
raise ValueError(f"{input_dir} is not a directory")
if output_file.suffix.lower() not in {".docx", ".pptx", ".xlsx"}:
raise ValueError(f"{output_file} must be a .docx, .pptx, or .xlsx file")
with tempfile.TemporaryDirectory() as temp_dir:
temp_content_dir = Path(temp_dir) / "content"
shutil.copytree(input_dir, temp_content_dir)
for pattern in ["*.xml", "*.rels"]:
for xml_file in temp_content_dir.rglob(pattern):
condense_xml(xml_file)
output_file.parent.mkdir(parents=True, exist_ok=True)
with zipfile.ZipFile(output_file, "w", zipfile.ZIP_DEFLATED) as archive:
for file_path in temp_content_dir.rglob("*"):
if file_path.is_file():
archive.write(file_path, file_path.relative_to(temp_content_dir))
if validate and not validate_document(output_file):
if output_file.exists():
output_file.unlink()
return False
return True
def validate_document(doc_path):
match doc_path.suffix.lower():
case ".docx":
filter_name = "html:HTML"
case ".pptx":
filter_name = "html:impress_html_Export"
case ".xlsx":
filter_name = "html:HTML (StarCalc)"
case _:
return False
soffice_binary = resolve_soffice_binary()
if not soffice_binary:
print("Warning: soffice not found. Skipping validation.", file=sys.stderr)
return True
with tempfile.TemporaryDirectory() as temp_dir:
try:
result = subprocess.run(
[
soffice_binary,
"--headless",
"--convert-to",
filter_name,
"--outdir",
temp_dir,
str(doc_path),
],
capture_output=True,
timeout=30,
text=True,
check=False,
)
if not (Path(temp_dir) / f"{doc_path.stem}.html").exists():
error_msg = result.stderr.strip() or result.stdout.strip() or "Document validation failed"
print(f"Validation error: {error_msg}", file=sys.stderr)
return False
return True
except subprocess.TimeoutExpired:
print("Validation error: Timeout during conversion", file=sys.stderr)
return False
except Exception as exc:
print(f"Validation error: {exc}", file=sys.stderr)
return False
def condense_xml(xml_file):
with open(xml_file, "r", encoding="utf-8") as file_obj:
dom = secure_minidom.parse(file_obj)
for element in dom.getElementsByTagName("*"):
if element.tagName.endswith(":t"):
continue
for child in list(element.childNodes):
is_blank_text = (
child.nodeType == child.TEXT_NODE
and child.nodeValue
and child.nodeValue.strip() == ""
)
if is_blank_text or child.nodeType == child.COMMENT_NODE:
element.removeChild(child)
with open(xml_file, "wb") as file_obj:
file_obj.write(dom.toxml(encoding="UTF-8"))
if __name__ == "__main__":
main()
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/unpack.py
-96
View File
@@ -1,96 +0,0 @@
#!/usr/bin/env python3
"""Unpack and format XML contents of Office files (.docx, .pptx, .xlsx)."""
import argparse
import random
import re
import sys
import zipfile
from pathlib import Path
try:
import defusedxml.minidom as secure_minidom
except ImportError: # pragma: no cover - fallback for minimal environments
import xml.dom.minidom as secure_minidom
ENCODING_RE = re.compile(br"encoding=[\"']([^\"']+)[\"']", re.IGNORECASE)
def detect_xml_encoding(raw_bytes: bytes) -> str:
header = raw_bytes[:256]
match = ENCODING_RE.search(header)
if not match:
return "utf-8"
value = match.group(1).decode("ascii", errors="ignore").lower()
if value == "ascii":
return "ascii"
return "utf-8"
def _is_within_directory(base_dir: Path, target: Path) -> bool:
try:
target.resolve().relative_to(base_dir.resolve())
return True
except ValueError:
return False
def safe_extract_office_archive(input_file: Path, output_dir: Path) -> None:
with zipfile.ZipFile(input_file, "r") as archive:
for member in archive.infolist():
target = output_dir / member.filename
if not _is_within_directory(output_dir, target):
raise ValueError(f"Unsafe archive path detected: {member.filename}")
archive.extractall(output_dir)
def pretty_print_xml_files(output_dir: Path) -> None:
xml_files = list(output_dir.rglob("*.xml")) + list(output_dir.rglob("*.rels"))
for xml_file in xml_files:
raw = xml_file.read_bytes()
encoding = detect_xml_encoding(raw)
dom = secure_minidom.parseString(raw)
xml_file.write_bytes(dom.toprettyxml(indent=" ", encoding=encoding))
def parse_args(argv: list[str]) -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Unpack Office file and pretty-print XML")
parser.add_argument("office_file", help="Input Office file (.docx/.pptx/.xlsx)")
parser.add_argument("output_dir", help="Directory where unpacked files are written")
return parser.parse_args(argv)
def main(argv: list[str] | None = None) -> int:
args = parse_args(argv or sys.argv[1:])
input_path = Path(args.office_file)
output_path = Path(args.output_dir)
if not input_path.exists():
print(f"Error: file not found: {input_path}", file=sys.stderr)
return 1
if input_path.suffix.lower() not in {".docx", ".pptx", ".xlsx"}:
print("Error: office_file must be a .docx, .pptx, or .xlsx file", file=sys.stderr)
return 1
output_path.mkdir(parents=True, exist_ok=True)
try:
safe_extract_office_archive(input_path, output_path)
pretty_print_xml_files(output_path)
except zipfile.BadZipFile:
print(f"Error: invalid Office archive: {input_path}", file=sys.stderr)
return 1
except Exception as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
if input_path.suffix.lower() == ".docx":
suggested_rsid = "".join(random.choices("0123456789ABCDEF", k=8))
print(f"Suggested RSID for edit session: {suggested_rsid}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/validate.py
-69
View File
@@ -1,69 +0,0 @@
#!/usr/bin/env python3
"""
Command line tool to validate Office document XML files against XSD schemas and tracked changes.
Usage:
python validate.py <dir> --original <original_file>
"""
import argparse
import sys
from pathlib import Path
from validation import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator
def main():
parser = argparse.ArgumentParser(description="Validate Office document XML files")
parser.add_argument(
"unpacked_dir",
help="Path to unpacked Office document directory",
)
parser.add_argument(
"--original",
required=True,
help="Path to original file (.docx/.pptx/.xlsx)",
)
parser.add_argument(
"-v",
"--verbose",
action="store_true",
help="Enable verbose output",
)
args = parser.parse_args()
# Validate paths
unpacked_dir = Path(args.unpacked_dir)
original_file = Path(args.original)
file_extension = original_file.suffix.lower()
assert unpacked_dir.is_dir(), f"Error: {unpacked_dir} is not a directory"
assert original_file.is_file(), f"Error: {original_file} is not a file"
assert file_extension in [".docx", ".pptx", ".xlsx"], (
f"Error: {original_file} must be a .docx, .pptx, or .xlsx file"
)
# Run validations
match file_extension:
case ".docx":
validators = [DOCXSchemaValidator, RedliningValidator]
case ".pptx":
validators = [PPTXSchemaValidator]
case _:
print(f"Error: Validation not supported for file type {file_extension}")
sys.exit(1)
# Run validators
success = True
for V in validators:
validator = V(unpacked_dir, original_file, verbose=args.verbose)
if not validator.validate():
success = False
if success:
print("All validations PASSED!")
sys.exit(0 if success else 1)
if __name__ == "__main__":
main()
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/validation/docx.py
-274
View File
@@ -1,274 +0,0 @@
"""
Validator for Word document XML files against XSD schemas.
"""
import re
import tempfile
import zipfile
import lxml.etree
from .base import BaseSchemaValidator
class DOCXSchemaValidator(BaseSchemaValidator):
"""Validator for Word document XML files against XSD schemas."""
# Word-specific namespace
WORD_2006_NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
# Word-specific element to relationship type mappings
# Start with empty mapping - add specific cases as we discover them
ELEMENT_RELATIONSHIP_TYPES = {}
def validate(self):
"""Run all validation checks and return True if all pass."""
# Test 0: XML well-formedness
if not self.validate_xml():
return False
# Test 1: Namespace declarations
all_valid = True
if not self.validate_namespaces():
all_valid = False
# Test 2: Unique IDs
if not self.validate_unique_ids():
all_valid = False
# Test 3: Relationship and file reference validation
if not self.validate_file_references():
all_valid = False
# Test 4: Content type declarations
if not self.validate_content_types():
all_valid = False
# Test 5: XSD schema validation
if not self.validate_against_xsd():
all_valid = False
# Test 6: Whitespace preservation
if not self.validate_whitespace_preservation():
all_valid = False
# Test 7: Deletion validation
if not self.validate_deletions():
all_valid = False
# Test 8: Insertion validation
if not self.validate_insertions():
all_valid = False
# Test 9: Relationship ID reference validation
if not self.validate_all_relationship_ids():
all_valid = False
# Count and compare paragraphs
self.compare_paragraph_counts()
return all_valid
def validate_whitespace_preservation(self):
"""
Validate that w:t elements with whitespace have xml:space='preserve'.
"""
errors = []
for xml_file in self.xml_files:
# Only check document.xml files
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
# Find all w:t elements
for elem in root.iter(f"{{{self.WORD_2006_NAMESPACE}}}t"):
if elem.text:
text = elem.text
# Check if text starts or ends with whitespace
if re.match(r"^\s.*", text) or re.match(r".*\s$", text):
# Check if xml:space="preserve" attribute exists
xml_space_attr = f"{{{self.XML_NAMESPACE}}}space"
if (
xml_space_attr not in elem.attrib
or elem.attrib[xml_space_attr] != "preserve"
):
# Show a preview of the text
text_preview = (
repr(text)[:50] + "..."
if len(repr(text)) > 50
else repr(text)
)
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
f"Line {elem.sourceline}: w:t element with whitespace missing xml:space='preserve': {text_preview}"
)
except (lxml.etree.XMLSyntaxError, Exception) as e:
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}"
)
if errors:
print(f"FAILED - Found {len(errors)} whitespace preservation violations:")
for error in errors:
print(error)
return False
else:
if self.verbose:
print("PASSED - All whitespace is properly preserved")
return True
def validate_deletions(self):
"""
Validate that w:t elements are not within w:del elements.
For some reason, XSD validation does not catch this, so we do it manually.
"""
errors = []
for xml_file in self.xml_files:
# Only check document.xml files
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
# Find all w:t elements that are descendants of w:del elements
namespaces = {"w": self.WORD_2006_NAMESPACE}
xpath_expression = ".//w:del//w:t"
problematic_t_elements = root.xpath(
xpath_expression, namespaces=namespaces
)
for t_elem in problematic_t_elements:
if t_elem.text:
# Show a preview of the text
text_preview = (
repr(t_elem.text)[:50] + "..."
if len(repr(t_elem.text)) > 50
else repr(t_elem.text)
)
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
f"Line {t_elem.sourceline}: <w:t> found within <w:del>: {text_preview}"
)
except (lxml.etree.XMLSyntaxError, Exception) as e:
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}"
)
if errors:
print(f"FAILED - Found {len(errors)} deletion validation violations:")
for error in errors:
print(error)
return False
else:
if self.verbose:
print("PASSED - No w:t elements found within w:del elements")
return True
def count_paragraphs_in_unpacked(self):
"""Count the number of paragraphs in the unpacked document."""
count = 0
for xml_file in self.xml_files:
# Only check document.xml files
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
# Count all w:p elements
paragraphs = root.findall(f".//{{{self.WORD_2006_NAMESPACE}}}p")
count = len(paragraphs)
except Exception as e:
print(f"Error counting paragraphs in unpacked document: {e}")
return count
def count_paragraphs_in_original(self):
"""Count the number of paragraphs in the original docx file."""
count = 0
try:
# Create temporary directory to unpack original
with tempfile.TemporaryDirectory() as temp_dir:
# Unpack original docx
with zipfile.ZipFile(self.original_file, "r") as zip_ref:
zip_ref.extractall(temp_dir)
# Parse document.xml
doc_xml_path = temp_dir + "/word/document.xml"
root = lxml.etree.parse(doc_xml_path).getroot()
# Count all w:p elements
paragraphs = root.findall(f".//{{{self.WORD_2006_NAMESPACE}}}p")
count = len(paragraphs)
except Exception as e:
print(f"Error counting paragraphs in original document: {e}")
return count
def validate_insertions(self):
"""
Validate that w:delText elements are not within w:ins elements.
w:delText is only allowed in w:ins if nested within a w:del.
"""
errors = []
for xml_file in self.xml_files:
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
namespaces = {"w": self.WORD_2006_NAMESPACE}
# Find w:delText in w:ins that are NOT within w:del
invalid_elements = root.xpath(
".//w:ins//w:delText[not(ancestor::w:del)]",
namespaces=namespaces
)
for elem in invalid_elements:
text_preview = (
repr(elem.text or "")[:50] + "..."
if len(repr(elem.text or "")) > 50
else repr(elem.text or "")
)
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
f"Line {elem.sourceline}: <w:delText> within <w:ins>: {text_preview}"
)
except (lxml.etree.XMLSyntaxError, Exception) as e:
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}"
)
if errors:
print(f"FAILED - Found {len(errors)} insertion validation violations:")
for error in errors:
print(error)
return False
else:
if self.verbose:
print("PASSED - No w:delText elements within w:ins elements")
return True
def compare_paragraph_counts(self):
"""Compare paragraph counts between original and new document."""
original_count = self.count_paragraphs_in_original()
new_count = self.count_paragraphs_in_unpacked()
diff = new_count - original_count
diff_str = f"+{diff}" if diff > 0 else str(diff)
print(f"\nParagraphs: {original_count} → {new_count} ({diff_str})")
if __name__ == "__main__":
raise RuntimeError("This module should not be run directly.")
plugins/codex/plugins/docx/skills/docx/references/platform.md
+41
View File
@@ -0,0 +1,41 @@
# 简体中文与 Windows 环境
以下命令中的 `$skill` 是当前已安装 Skill 的真实目录；不要硬编码开发者机器路径。脚本使用 Python 3.10+。先检查现有 Python/Node 环境，缺少哪个依赖再安装哪个。
```powershell
$env:PYTHONUTF8 = "1"
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
python --version
node --version
```
若只有 `py`，把命令中的 `python` 替换为 `py -3`。PowerShell 调用带空格的可执行文件路径使用 `& "路径"`；Python 脚本路径作为独立参数传入，不拼接 shell 命令。中文路径、空格路径均需引号。
需要独立依赖环境时，在任务工作目录创建 `.venv`，使用 `& ".\.venv\Scripts\python.exe" -m pip install <缺失包>`。无需改变系统执行策略或激活脚本。Node 库安装到任务目录，不默认全局安装。不要假设 Codex、Claude 或容器已预装所有依赖。
## 字体与文本
- 用户未指定语言时，中文用户的说明、标题、图例和交付文案使用简体中文；引文、产品名、代码和原文专有名词保持原样。
- 新文件优先使用本机可用的微软雅黑、等线、宋体或思源黑体。先查字体；声明字体名不等于字体已安装。Word 配置 `w:rFonts/@w:eastAsia` 与 `zh-CN`，PPT 配置主题字体和文本框字体，Excel 使用 `Microsoft YaHei` 等实际存在的字体。
- PDF 优先嵌入有再分发许可的中文字体；ReportLab 简单中文文档可用 `UnicodeCIDFont('STSong-Light')`，交付前仍检查目标阅读器效果。不要用 Helvetica 绘制中文，也不要把方块字当正常输出。
- CSV 面向 Windows Excel 时可用 `utf-8-sig`；先保留已有文件编码，不要自动改写所有输入。XML、JSON 和新建脚本使用 UTF-8。
- 标点、单位、日期、人民币格式、身份证号和前导零按用户语义保留；不要默认套用美式日期或把长编号转为数字。
## 转换与预览
Office 文档转 PDF 使用随附的跨平台 `scripts/office/soffice.py`。它按 `SOFFICE_PATH`、PATH、Windows Program Files、macOS 应用目录寻找 LibreOffice，并为转换创建独立临时 profile。
```powershell
# 仅在自动检测不到时设置；不要求添加系统 PATH
$env:SOFFICE_PATH = "C:\Program Files\LibreOffice\program\soffice.com"
python "$skill\scripts\office\soffice.py" --headless --convert-to pdf --outdir ".\preview" ".\中文 文档.docx"
python "$skill\scripts\render_pdf.py" ".\preview\中文 文档.pdf" ".\preview\pages"
```
按实际需要安装 LibreOffice、`pymupdf`、`defusedxml`、`lxml` 等缺失依赖。PDF 的 `scripts/convert_pdf_to_images.py` 与其他 Skill 的 `scripts/render_pdf.py` 均使用 PyMuPDF，不需要 Poppler。`pptx` 上游缩略图脚本仍需 Poppler；无 Poppler 时走 PDF 渲染流程。
使用 Python `scripts/office_package.py unpack <输入> <空目录>` 和 `pack <包根目录> <输出>` 处理 Office ZIP，无需 `unzip`、`zip`、`rm` 或 Bash。输出必须在解包目录之外。
## 验证与交付
生成或编辑后保存到新文件；先检查内容、公式或 OOXML 结构，再渲染并查看页面，检查中文缺字、表格越界、文本遮挡和分页。转换失败或字体缺失时说明具体原因，不把“文件保存成功”当成渲染通过。保留输入，除非用户明确要求覆盖。
plugins/codex/plugins/docx/skills/docx/scripts/__init__.py
Regular → Executable
+1 -1
View File
@@ -1 +1 @@
# Make scripts directory a package for relative imports in tests
plugins/codex/plugins/docx/skills/docx/scripts/accept_changes.py
+75
View File
@@ -0,0 +1,75 @@
"""Accept tracked changes into a new DOCX using an isolated LibreOffice profile."""
import argparse
import shutil
import subprocess
import tempfile
import zipfile
from pathlib import Path
from defusedxml import ElementTree
from office.soffice import run_soffice
MACRO = '''<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "module.dtd">
<script:module xmlns:script="http://openoffice.org/2000/script" script:name="Module1" script:language="StarBasic">
Sub AcceptAllTrackedChanges()
Dim dispatcher As Object
dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")
dispatcher.executeDispatch(ThisComponent.CurrentController.Frame, ".uno:AcceptAllTrackedChanges", "", 0, Array())
ThisComponent.store()
ThisComponent.close(True)
End Sub
</script:module>'''
WORD_NS = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
def accept_changes(input_file, output_file, timeout=120):
source = Path(input_file).resolve()
output = Path(output_file).resolve()
if source == output or not source.is_file() or source.suffix.lower() != ".docx":
return None, "Input must be an existing DOCX and output must be a different file"
output.parent.mkdir(parents=True, exist_ok=True)
try:
with tempfile.TemporaryDirectory(prefix="docx-accept-", ignore_cleanup_errors=True) as temporary:
root = Path(temporary).resolve()
profile = root / "profile"
profile_arg = f"-env:UserInstallation={profile.as_uri()}"
run_soffice([profile_arg, "--headless", "--terminate_after_init"], check=True, capture_output=True, timeout=timeout)
macro_dir = profile / "user/basic/Standard"
macro_dir.mkdir(parents=True, exist_ok=True)
(macro_dir / "Module1.xba").write_text(MACRO, encoding="utf-8")
candidate = root / "accepted.docx"
shutil.copy2(source, candidate)
before = candidate.stat().st_mtime_ns
run_soffice([
profile_arg, "--headless", "--norestore",
"vnd.sun.star.script:Standard.Module1.AcceptAllTrackedChanges?language=Basic&location=application",
str(candidate),
], check=True, capture_output=True, timeout=timeout)
if candidate.stat().st_mtime_ns == before:
return None, "LibreOffice did not save the document"
with zipfile.ZipFile(candidate) as archive:
for name in archive.namelist():
if not name.startswith("word/") or not name.endswith(".xml"):
continue
document = ElementTree.fromstring(archive.read(name))
if any(element.tag in {WORD_NS + "ins", WORD_NS + "del", WORD_NS + "moveFrom", WORD_NS + "moveTo"}
or (element.tag.startswith(WORD_NS) and element.tag.endswith("Change"))
for element in document.iter()):
return None, f"Tracked changes remain in {name}"
shutil.copy2(candidate, output)
return None, f"Accepted tracked changes: {output}"
except (OSError, subprocess.SubprocessError, zipfile.BadZipFile) as exc:
return None, f"Failed to accept tracked changes: {exc}"
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("input")
parser.add_argument("output")
parser.add_argument("--timeout", type=int, default=120)
args = parser.parse_args()
_, message = accept_changes(args.input, args.output, args.timeout)
print(message)
raise SystemExit(0 if message.startswith("Accepted tracked changes:") else 1)
plugins/codex/plugins/docx/skills/docx/scripts/comment.py
Executable
+368
View File
@@ -0,0 +1,368 @@
"""Add comments to a DOCX document.
Accepts either an unpacked directory OR a .docx/.dotx file directly.
Usage:
# Against an unpacked directory (writes satellite files in place)
python comment.py unpacked/ "Comment text"
python comment.py unpacked/ "Reply text" --parent 0
# Against a .docx directly (extracts, writes satellite files, rezips)
python comment.py contract.docx "This cap is too low" -o annotated.docx
python comment.py contract.docx "Comment" --id 5 # explicit ID
The comment ID is auto-assigned (max existing + 1) unless --id is given.
Plain text is XML-escaped automatically; if you pass already-escaped text
(e.g. &amp;, &#x2019;) use --raw to skip escaping.
After running, add markers to word/document.xml so the comment is visible:
<w:commentRangeStart w:id="N"/>
... commented content ...
<w:commentRangeEnd w:id="N"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="N"/></w:r>
"""
import argparse
import random
import shutil
import sys
import tempfile
import zipfile
from datetime import datetime, timezone
from pathlib import Path
import defusedxml.minidom
from xml.parsers.expat import ExpatError
from xml.sax.saxutils import escape as xml_escape
from office.helpers import opc_target, rezip as _rezip, safe_extract as _safe_extract
TEMPLATE_DIR = Path(__file__).parent / "templates"
NS = {
"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
"w14": "http://schemas.microsoft.com/office/word/2010/wordml",
"w15": "http://schemas.microsoft.com/office/word/2012/wordml",
"w16cid": "http://schemas.microsoft.com/office/word/2016/wordml/cid",
"w16cex": "http://schemas.microsoft.com/office/word/2018/wordml/cex",
}
COMMENT_XML = """\
<w:comment w:id="{id}" w:author="{author}" w:date="{date}" w:initials="{initials}">
<w:p w14:paraId="{para_id}" w14:textId="77777777">
<w:r>
<w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
<w:annotationRef/>
</w:r>
<w:r>
<w:rPr>
<w:color w:val="000000"/>
<w:sz w:val="20"/>
<w:szCs w:val="20"/>
</w:rPr>
<w:t xml:space="preserve">{text}</w:t>
</w:r>
</w:p>
</w:comment>"""
COMMENT_MARKER_TEMPLATE = """
Add to word/document.xml (markers must be direct children of w:p, never inside w:r):
<w:commentRangeStart w:id="{cid}"/>
<w:r>...</w:r>
<w:commentRangeEnd w:id="{cid}"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="{cid}"/></w:r>"""
REPLY_MARKER_TEMPLATE = """
Nest markers inside parent {pid}'s markers (direct children of w:p, never inside w:r):
<w:commentRangeStart w:id="{pid}"/><w:commentRangeStart w:id="{cid}"/>
<w:r>...</w:r>
<w:commentRangeEnd w:id="{cid}"/><w:commentRangeEnd w:id="{pid}"/>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="{pid}"/></w:r>
<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="{cid}"/></w:r>"""
SMART_QUOTE_ENTITIES = {
"“": "&#x201C;",
"”": "&#x201D;",
"‘": "&#x2018;",
"’": "&#x2019;",
}
def _generate_hex_id() -> str:
return f"{random.randint(0, 0x7FFFFFFE):08X}"
def _encode_smart_quotes(text: str) -> str:
for char, entity in SMART_QUOTE_ENTITIES.items():
text = text.replace(char, entity)
return text
def _append_xml(xml_path: Path, root_tag: str, content: str) -> None:
dom = defusedxml.minidom.parseString(xml_path.read_text(encoding="utf-8"))
root = dom.getElementsByTagName(root_tag)[0]
ns_attrs = " ".join(f'xmlns:{k}="{v}"' for k, v in NS.items())
wrapper_dom = defusedxml.minidom.parseString(f"<root {ns_attrs}>{content}</root>")
for child in wrapper_dom.documentElement.childNodes:
if child.nodeType == child.ELEMENT_NODE:
root.appendChild(dom.importNode(child, True))
output = _encode_smart_quotes(dom.toxml(encoding="UTF-8").decode("utf-8"))
xml_path.write_text(output, encoding="utf-8")
def _find_para_id(comments_path: Path, comment_id: int) -> str | None:
dom = defusedxml.minidom.parseString(comments_path.read_text(encoding="utf-8"))
for c in dom.getElementsByTagName("w:comment"):
if c.getAttribute("w:id") == str(comment_id):
for p in c.getElementsByTagName("w:p"):
if pid := p.getAttribute("w14:paraId"):
return pid
return None
def _next_comment_id(comments_path: Path) -> int:
if not comments_path.exists():
return 0
dom = defusedxml.minidom.parseString(comments_path.read_text(encoding="utf-8"))
ids = []
for c in dom.getElementsByTagName("w:comment"):
try:
ids.append(int(c.getAttribute("w:id")))
except ValueError:
pass
return (max(ids) + 1) if ids else 0
def _get_next_rid(rels_path: Path) -> int:
dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
max_rid = 0
for rel in dom.getElementsByTagName("Relationship"):
rid = rel.getAttribute("Id")
if rid and rid.startswith("rId"):
try:
max_rid = max(max_rid, int(rid[3:]))
except ValueError:
pass
return max_rid + 1
def _has_relationship(rels_path: Path, target: str) -> bool:
dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
return any(
rel.getAttribute("Target") == target
for rel in dom.getElementsByTagName("Relationship")
)
def _has_content_type(ct_path: Path, part_name: str) -> bool:
dom = defusedxml.minidom.parseString(ct_path.read_text(encoding="utf-8"))
return any(
o.getAttribute("PartName") == part_name
for o in dom.getElementsByTagName("Override")
)
_COMMENT_RELS = [
("http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments", "comments.xml"),
("http://schemas.microsoft.com/office/2011/relationships/commentsExtended", "commentsExtended.xml"),
("http://schemas.microsoft.com/office/2016/09/relationships/commentsIds", "commentsIds.xml"),
("http://schemas.microsoft.com/office/2018/08/relationships/commentsExtensible", "commentsExtensible.xml"),
]
_COMMENT_OVERRIDES = [
("/word/comments.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"),
("/word/commentsExtended.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml"),
("/word/commentsIds.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml"),
("/word/commentsExtensible.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml"),
]
def _ensure_comment_relationships(unpacked_dir: Path) -> None:
rels_path = unpacked_dir / "word" / "_rels" / "document.xml.rels"
if not rels_path.exists():
return
dom = defusedxml.minidom.parseString(rels_path.read_text(encoding="utf-8"))
root = dom.documentElement
comment_types = {rel_type for rel_type, _ in _COMMENT_RELS}
existing = set()
for rel in dom.getElementsByTagName("Relationship"):
if rel.getAttribute("Type") not in comment_types:
continue
part = opc_target(
rel.getAttribute("Target"),
"word/document.xml",
rel.getAttribute("TargetMode"),
)
if part is not None:
existing.add(part)
next_rid = _get_next_rid(rels_path)
changed = False
for rel_type, target in _COMMENT_RELS:
if opc_target(target, "word/document.xml") in existing:
continue
rel = dom.createElement("Relationship")
rel.setAttribute("Id", f"rId{next_rid}")
rel.setAttribute("Type", rel_type)
rel.setAttribute("Target", target)
root.appendChild(rel)
next_rid += 1
changed = True
if changed:
rels_path.write_bytes(dom.toxml(encoding="UTF-8"))
def _ensure_comment_content_types(unpacked_dir: Path) -> None:
ct_path = unpacked_dir / "[Content_Types].xml"
if not ct_path.exists():
return
dom = defusedxml.minidom.parseString(ct_path.read_text(encoding="utf-8"))
root = dom.documentElement
existing = {
o.getAttribute("PartName")
for o in dom.getElementsByTagName("Override")
}
changed = False
for part_name, content_type in _COMMENT_OVERRIDES:
if part_name in existing:
continue
override = dom.createElement("Override")
override.setAttribute("PartName", part_name)
override.setAttribute("ContentType", content_type)
root.appendChild(override)
changed = True
if changed:
ct_path.write_bytes(dom.toxml(encoding="UTF-8"))
def add_comment(
unpacked_dir: Path | str,
text: str,
comment_id: int | None = None,
author: str = "Claude",
initials: str = "C",
parent_id: int | None = None,
raw: bool = False,
) -> tuple[int, str, str]:
unpacked_dir = Path(unpacked_dir)
if not raw:
text = xml_escape(text)
author = xml_escape(author, {'"': "&quot;"})
initials = xml_escape(initials, {'"': "&quot;"})
word = unpacked_dir / "word"
if not word.exists():
raise FileNotFoundError(f"{word} not found (not an unpacked .docx?)")
comments = word / "comments.xml"
if comment_id is None:
comment_id = _next_comment_id(comments)
parent_para = None
if parent_id is not None:
parent_para = _find_para_id(comments, parent_id) if comments.exists() else None
if not parent_para:
raise ValueError(f"parent comment {parent_id} not found")
para_id, durable_id = _generate_hex_id(), _generate_hex_id()
ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
if not comments.exists():
shutil.copy(TEMPLATE_DIR / "comments.xml", comments)
_ensure_comment_relationships(unpacked_dir)
_ensure_comment_content_types(unpacked_dir)
_append_xml(
comments,
"w:comments",
COMMENT_XML.format(
id=comment_id, author=author, date=ts, initials=initials,
para_id=para_id, text=text,
),
)
ext = word / "commentsExtended.xml"
if not ext.exists():
shutil.copy(TEMPLATE_DIR / "commentsExtended.xml", ext)
if parent_para is not None:
_append_xml(
ext, "w15:commentsEx",
f'<w15:commentEx w15:paraId="{para_id}" w15:paraIdParent="{parent_para}" w15:done="0"/>',
)
else:
_append_xml(
ext, "w15:commentsEx",
f'<w15:commentEx w15:paraId="{para_id}" w15:done="0"/>',
)
ids = word / "commentsIds.xml"
if not ids.exists():
shutil.copy(TEMPLATE_DIR / "commentsIds.xml", ids)
_append_xml(
ids, "w16cid:commentsIds",
f'<w16cid:commentId w16cid:paraId="{para_id}" w16cid:durableId="{durable_id}"/>',
)
extensible = word / "commentsExtensible.xml"
if not extensible.exists():
shutil.copy(TEMPLATE_DIR / "commentsExtensible.xml", extensible)
_append_xml(
extensible, "w16cex:commentsExtensible",
f'<w16cex:commentExtensible w16cex:durableId="{durable_id}" w16cex:dateUtc="{ts}"/>',
)
action = "reply" if parent_id is not None else "comment"
return comment_id, para_id, f"Added {action} id={comment_id} (paraId={para_id})"
def main() -> None:
p = argparse.ArgumentParser(description="Add a comment to a DOCX (directory or .docx file).")
p.add_argument("input", help="Unpacked DOCX directory OR a .docx/.dotx file")
p.add_argument("text", help="Comment text (plain text; XML-escaped automatically)")
p.add_argument("--raw", action="store_true",
help="Treat text as pre-escaped XML (skip automatic escaping)")
p.add_argument("--id", type=int, dest="comment_id",
help="Comment ID (default: auto-assign as max existing + 1)")
p.add_argument("--author", default="Claude", help="Author name")
p.add_argument("--initials", default="C", help="Author initials")
p.add_argument("--parent", type=int, help="Parent comment ID (makes this a reply)")
p.add_argument("-o", "--output",
help="Output .docx path (only used when input is a .docx; default: overwrite input)")
args = p.parse_args()
src = Path(args.input)
try:
if src.is_dir():
if args.output:
print("Warning: --output ignored for directory input", file=sys.stderr)
cid, _, msg = add_comment(
src, args.text, comment_id=args.comment_id,
author=args.author, initials=args.initials,
parent_id=args.parent, raw=args.raw,
)
print(msg)
elif src.is_file() and src.suffix.lower() in (".docx", ".dotx"):
out = Path(args.output) if args.output else src
with tempfile.TemporaryDirectory() as tmp:
tmp_path = Path(tmp)
with zipfile.ZipFile(src) as zf:
_safe_extract(zf, tmp_path)
cid, _, msg = add_comment(
tmp_path, args.text, comment_id=args.comment_id,
author=args.author, initials=args.initials,
parent_id=args.parent, raw=args.raw,
)
_rezip(tmp_path, out)
print(msg)
print(f"Wrote {out} (comment defined; add markers to word/document.xml to make it visible)")
else:
print(f"Error: {src} is neither a directory nor a .docx/.dotx file", file=sys.stderr)
sys.exit(1)
except (FileNotFoundError, ValueError, zipfile.BadZipFile, ExpatError) as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
if args.parent is not None:
print(REPLY_MARKER_TEMPLATE.format(pid=args.parent, cid=cid))
else:
print(COMMENT_MARKER_TEMPLATE.format(cid=cid))
if __name__ == "__main__":
main()
plugins/codex/plugins/docx/skills/docx/scripts/document.py
-1276
View File
File diff suppressed because it is too large. Load diff
plugins/codex/plugins/docx/skills/docx/scripts/merge_runs.py
Executable
+310
View File
@@ -0,0 +1,310 @@
"""Merge adjacent identically-formatted runs in a DOCX.
Word fragments paragraph text across many <w:r> elements (revision ids,
spell-check markers, editing history), which makes find-and-replace on
word/document.xml unreliable — the string you're looking for is split
across runs. This coalesces adjacent runs whose formatting (<w:rPr>) is
identical, strips rsid attributes and proofErr markers, and consolidates the
text elements — <w:t>, and <w:delText> for text inside a tracked deletion.
Rendering is unchanged. The text you search is what Word draws, which is not
always the bytes in the file: an element without xml:space="preserve" has its
edge whitespace trimmed before it reaches the page, so `<w:t>Hello </w:t>`
followed by `<w:t>world</w:t>` reads "Helloworld" and merges to exactly that.
Runs in two different <w:ins>/<w:del> wrappers are never merged: that would
rewrite tracked-change structure, collapsing separate revisions into one.
Only word/document.xml is processed (not headers, footers, or footnotes).
Usage:
python merge_runs.py unpacked/ # after unzip, before editing
python merge_runs.py document.docx # rewrite in place
python merge_runs.py document.docx -o out.docx
"""
import argparse
import sys
import tempfile
import zipfile
from pathlib import Path
import defusedxml.minidom
from office.helpers import XML_SPACE, rendered_text, rezip, safe_extract
WORDML_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
def merge_runs(input_dir: str) -> tuple[int, str]:
doc_xml = Path(input_dir) / "word" / "document.xml"
if not doc_xml.exists():
return 0, f"Error: {doc_xml} not found"
try:
dom = defusedxml.minidom.parseString(doc_xml.read_text(encoding="utf-8"))
root = dom.documentElement
run_names = _run_tag_names(root)
_remove_elements(root, "proofErr")
runs = _find_runs(root, run_names)
_strip_rsid_attrs(runs)
merge_count = 0
for container in {run.parentNode for run in runs}:
merge_count += _merge_runs_in(container, run_names)
doc_xml.write_bytes(dom.toxml(encoding="UTF-8"))
return merge_count, f"Merged {merge_count} runs"
except Exception as e:
return 0, f"Error: {e}"
def _is_element(node, tag: str) -> bool:
name = node.localName or node.tagName
return name == tag or name.endswith(f":{tag}")
def _run_tag_names(root) -> set[str]:
names = set()
for attr in root.attributes.values():
if attr.value == WORDML_NS:
if attr.name == "xmlns":
names.add("r")
elif attr.name.startswith("xmlns:"):
names.add(attr.name.split(":", 1)[1] + ":r")
return names or {"w:r", "r"}
def _find_elements(root, tag: str) -> list:
results = []
def traverse(node):
if node.nodeType == node.ELEMENT_NODE:
if _is_element(node, tag):
results.append(node)
for child in node.childNodes:
traverse(child)
traverse(root)
return results
def _find_runs(root, run_names: set[str]) -> list:
return [e for e in _find_elements(root, "r") if _is_run(e, run_names)]
def _get_child(parent, tag: str):
return next(iter(_get_children(parent, tag)), None)
def _get_children(parent, tag: str) -> list:
return [
child
for child in parent.childNodes
if child.nodeType == child.ELEMENT_NODE and _is_element(child, tag)
]
def _is_adjacent(elem1, elem2) -> bool:
node = elem1.nextSibling
while node:
if node == elem2:
return True
if node.nodeType == node.ELEMENT_NODE:
return False
if node.nodeType == node.TEXT_NODE and node.data.strip(XML_SPACE):
return False
node = node.nextSibling
return False
def _remove_elements(root, tag: str):
for elem in _find_elements(root, tag):
if elem.parentNode:
elem.parentNode.removeChild(elem)
def _strip_rsid_attrs(runs: list):
for run in runs:
for attr in list(run.attributes.values()):
if "rsid" in attr.name.lower():
run.removeAttribute(attr.name)
def _merge_runs_in(container, run_names: set[str]) -> int:
merge_count = 0
run = _first_child_run(container, run_names)
while run:
while True:
next_elem = _next_element_sibling(run)
if next_elem and _is_run(next_elem, run_names) and _can_merge(run, next_elem):
_merge_run_content(run, next_elem)
container.removeChild(next_elem)
merge_count += 1
else:
break
_consolidate_text(run)
run = _next_sibling_run(run, run_names)
return merge_count
def _first_child_run(container, run_names: set[str]):
for child in container.childNodes:
if child.nodeType == child.ELEMENT_NODE and _is_run(child, run_names):
return child
return None
def _next_element_sibling(node):
sibling = node.nextSibling
while sibling:
if sibling.nodeType == sibling.ELEMENT_NODE:
return sibling
sibling = sibling.nextSibling
return None
def _next_sibling_run(node, run_names: set[str]):
sibling = node.nextSibling
while sibling:
if sibling.nodeType == sibling.ELEMENT_NODE:
if _is_run(sibling, run_names):
return sibling
sibling = sibling.nextSibling
return None
def _is_run(node, run_names: set[str]) -> bool:
return node.tagName in run_names
def _can_merge(run1, run2) -> bool:
rpr1 = _get_child(run1, "rPr")
rpr2 = _get_child(run2, "rPr")
if (rpr1 is None) != (rpr2 is None):
return False
if rpr1 is None:
return True
return rpr1.toxml() == rpr2.toxml()
def _merge_run_content(target, source):
for child in list(source.childNodes):
if child.nodeType == child.ELEMENT_NODE:
name = child.localName or child.tagName
if name != "rPr" and not name.endswith(":rPr"):
target.appendChild(child)
def _element_text(elem) -> str:
return "".join(
child.data
for child in elem.childNodes
if child.nodeType in (child.TEXT_NODE, child.CDATA_SECTION_NODE)
)
def _has_preserve(elem) -> bool:
return elem.getAttribute("xml:space") == "preserve"
def _rendered_text(elem) -> str:
return rendered_text(_element_text(elem), _has_preserve(elem))
def _consolidate_text(run):
for tag in ("t", "delText"):
_consolidate_text_elements(run, tag)
def _consolidate_text_elements(run, tag: str):
t_elements = _get_children(run, tag)
for i in range(len(t_elements) - 1, 0, -1):
curr, prev = t_elements[i], t_elements[i - 1]
if _is_adjacent(prev, curr):
merged = _rendered_text(prev) + _rendered_text(curr)
had_preserve = _has_preserve(prev) or _has_preserve(curr)
new_text = run.ownerDocument.createTextNode(merged)
for node in list(prev.childNodes):
if node.nodeType in (node.TEXT_NODE, node.CDATA_SECTION_NODE):
prev.removeChild(node)
else:
run.insertBefore(node, curr)
prev.appendChild(new_text)
for node in list(curr.childNodes):
if node.nodeType not in (node.TEXT_NODE, node.CDATA_SECTION_NODE):
run.insertBefore(node, curr)
if merged != merged.strip(XML_SPACE) or had_preserve:
prev.setAttribute("xml:space", "preserve")
elif prev.hasAttribute("xml:space"):
prev.removeAttribute("xml:space")
run.removeChild(curr)
def _merge_or_die(path: Path) -> str:
_, msg = merge_runs(str(path))
if msg.startswith("Error"):
print(msg, file=sys.stderr)
sys.exit(1)
return msg
def main() -> None:
p = argparse.ArgumentParser(
description="Merge adjacent identically-formatted runs in a DOCX (directory or .docx file)."
)
p.add_argument("input", help="Unpacked DOCX directory OR a .docx/.dotx file")
p.add_argument(
"-o", "--output",
help="Output .docx path (only valid when input is a .docx; default: overwrite input)",
)
args = p.parse_args()
src = Path(args.input)
try:
if src.is_dir():
if args.output:
p.error("--output is only valid for .docx input; directory input is modified in place")
print(_merge_or_die(src))
elif src.is_file() and src.suffix.lower() in (".docx", ".dotx"):
out = Path(args.output) if args.output else src
with tempfile.TemporaryDirectory() as tmp:
tmp_path = Path(tmp)
with zipfile.ZipFile(src) as zf:
safe_extract(zf, tmp_path)
msg = _merge_or_die(tmp_path)
rezip(tmp_path, out)
print(f"{msg}; wrote {out}")
else:
print(f"Error: {src} is neither a directory nor a .docx/.dotx file", file=sys.stderr)
sys.exit(1)
except (OSError, ValueError, zipfile.BadZipFile) as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
plugins/codex/plugins/docx/skills/docx/scripts/office/helpers/__init__.py
+111
View File
@@ -0,0 +1,111 @@
import os
import posixpath
import re
import stat
import tempfile
import urllib.parse
import zipfile
from pathlib import Path
OOXML_FAMILY = {
".docx": "docx",
".dotx": "docx",
".pptx": "pptx",
".potx": "pptx",
".xlsx": "xlsx",
".xltx": "xlsx",
}
_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.\-]*:")
SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide"
def opc_target(target: str, source_part: str, target_mode: str = "") -> str | None:
if not target:
return None
if target_mode.lower() == "external":
return None
if _SCHEME_RE.match(target):
return None
target = urllib.parse.unquote(target)
if "\\" in target:
raise ValueError(f"relationship target is not a POSIX part name: {target!r}")
if target.startswith("/"):
joined = target.lstrip("/")
else:
joined = posixpath.join(posixpath.dirname(source_part), target)
parts: list[str] = []
for segment in posixpath.normpath(joined).split("/"):
if segment in ("", "."):
continue
if segment == "..":
if not parts:
raise ValueError(f"relationship target escapes the package: {target!r}")
parts.pop()
else:
parts.append(segment)
if not parts:
raise ValueError(f"relationship target resolves to nothing: {target!r}")
return "/".join(parts)
def rels_source_part(rels_file: Path, unpacked_dir: Path) -> str:
owner_dir = rels_file.parent.parent.relative_to(unpacked_dir)
return posixpath.join(owner_dir.as_posix(), rels_file.name[: -len(".rels")]).lstrip("./")
def part_text(data: bytes) -> str:
return data.decode("utf-8", "surrogateescape")
XML_SPACE = " \t\r\n"
def rendered_text(text: str, preserve: bool) -> str:
return text if preserve else text.strip(XML_SPACE)
def safe_extract(zf: zipfile.ZipFile, dest: Path) -> None:
dest = dest.resolve()
for m in zf.infolist():
if stat.S_ISLNK(m.external_attr >> 16):
raise ValueError(f"symlink archive entry not allowed: {m.filename!r}")
target = (dest / m.filename).resolve()
if not target.is_relative_to(dest):
raise ValueError(f"unsafe archive entry: {m.filename!r}")
zf.extract(m, dest)
def rezip(src_dir: Path, out_path: Path) -> None:
files = sorted(p for p in src_dir.rglob("*") if p.is_file())
ct = src_dir / "[Content_Types].xml"
fd, tmp_name = tempfile.mkstemp(
prefix=out_path.name + ".", suffix=".tmp", dir=out_path.parent
)
tmp_out = Path(tmp_name)
try:
with os.fdopen(fd, "wb") as fh:
with zipfile.ZipFile(fh, "w", zipfile.ZIP_DEFLATED) as zf:
if ct.exists():
zf.write(ct, ct.relative_to(src_dir), compress_type=zipfile.ZIP_STORED)
for f in files:
if f == ct:
continue
zf.write(f, f.relative_to(src_dir))
if out_path.exists():
mode = out_path.stat().st_mode & 0o777
else:
umask = os.umask(0)
os.umask(umask)
mode = 0o666 & ~umask
os.chmod(tmp_out, mode)
os.replace(tmp_out, out_path)
finally:
if tmp_out.exists():
tmp_out.unlink()
plugins/codex/plugins/docx/skills/docx/scripts/office/helpers/pptx_chart.py
+170
View File
@@ -0,0 +1,170 @@
"""Find chart XML that PowerPoint refuses but the schema accepts.
Detection only: for either fault more than one repair is valid, and only the
author knows which was meant.
"""
from __future__ import annotations
import re
from typing import Mapping
from . import part_text
_CHART_PART_RE = re.compile(r"ppt/charts/chart\d+\.xml")
_GROUPING_RE = re.compile(r"""<c:grouping\b[^>]*?\bval=["'](\w+)["']""")
_DLBL_POS_RE = re.compile(r"""<c:dLblPos\b[^>]*?\bval=["'](\w+)["']""")
def _strip_ext_lst(text: str) -> str:
out, cursor = [], 0
for lo, hi in _ext_lst_spans(text):
out.append(text[cursor:lo])
cursor = hi
out.append(text[cursor:])
return "".join(out)
_BAR_GROUP_RE = re.compile(r"<c:(bar3DChart|barChart)\b[^>]*(?<!/)>.*?</c:\1\s*>", re.DOTALL)
STACKED_GROUPINGS = frozenset({"stacked", "percentStacked"})
ILLEGAL_ON_STACKED = frozenset({"outEnd"})
LEGAL_ON_STACKED = ("ctr", "inEnd", "inBase")
def _check_stacked_label_positions(part: str, xml: str) -> list[str]:
problems: list[str] = []
for match in _BAR_GROUP_RE.finditer(xml):
block = _strip_ext_lst(match.group(0))
group = match.group(1)
grouping = _GROUPING_RE.search(block)
if grouping is None or grouping.group(1) not in STACKED_GROUPINGS:
continue
bad = [p for p in _DLBL_POS_RE.findall(block) if p in ILLEGAL_ON_STACKED]
for pos in sorted(set(bad)):
problems.append(
f'{part}: {bad.count(pos)} data label(s) use dLblPos="{pos}" on a '
f"{grouping.group(1)} {group}; PowerPoint allows only "
f"{', '.join(LEGAL_ON_STACKED)} there"
)
return problems
_ANY_CHART_GROUP_RE = re.compile(r"<c:(\w+Chart)\b[^>]*(?<!/)>.*?</c:\1\s*>", re.DOTALL)
_AXID_RE = re.compile(
r"""\s*<c:axId\b[^>]*?\bval=["'](-?\d+)["']\s*(?:/>|>\s*</c:axId\s*>)"""
)
_AXIS_DECL_RE = re.compile(
r"""<c:(catAx|valAx|serAx|dateAx)\b[^>]*(?<!/)>\s*<c:axId\b[^>]*?\bval=["'](-?\d+)["']"""
)
AXID_LIMIT = {
"barChart": 2, "lineChart": 2, "areaChart": 2, "scatterChart": 2,
"bubbleChart": 2, "radarChart": 2, "stockChart": 2,
"bar3DChart": 3, "line3DChart": 3, "area3DChart": 3,
"surfaceChart": 3, "surface3DChart": 3,
}
AXID_MINIMUM = {
"barChart": 2, "lineChart": 2, "areaChart": 2, "scatterChart": 2,
"bubbleChart": 2, "radarChart": 2, "stockChart": 2,
"bar3DChart": 2, "area3DChart": 2, "surfaceChart": 2,
"line3DChart": 3, "surface3DChart": 3,
}
def _declared_axes(xml: str) -> dict[str, list[str]]:
axes: dict[str, list[str]] = {}
for kind, axid in _AXIS_DECL_RE.findall(xml):
axes.setdefault(kind, []).append(axid)
return axes
def _canonical_ids(axes: dict[str, list[str]], limit: int) -> list[str] | None:
category = axes.get("catAx", []) + axes.get("dateAx", [])
value = axes.get("valAx", [])
series = axes.get("serAx", [])
if len(category) != 1 or len(value) != 1 or len(series) > 1:
return None
ids = [category[0], value[0]]
if limit >= 3 and series:
ids.append(series[0])
return ids
def _undeclared_axes(kind: str, block: str, axes: dict[str, list[str]]) -> list[str] | None:
if kind not in AXID_LIMIT:
return None
ids = _AXID_RE.findall(block)
declared = {i for group in axes.values() for i in group}
if len([i for i in ids if i in declared]) >= 2:
return None
return ids
def _check_chart_axis_references(part: str, xml: str) -> list[str]:
axes = _declared_axes(xml)
problems: list[str] = []
declared = {i for group in axes.values() for i in group}
for match in _ANY_CHART_GROUP_RE.finditer(xml):
kind, block = match.group(1), match.group(0)
ids = _undeclared_axes(kind, block, axes)
if ids is None:
continue
if not ids:
problems.append(
f"{part}: <c:{kind}> declares no <c:axId> this part can resolve; a chart "
f"group needs {AXID_MINIMUM[kind]}, and PowerPoint discards one with fewer"
)
continue
dead = [i for i in ids if i not in declared]
canonical = _canonical_ids(axes, AXID_LIMIT[kind])
if canonical is not None and len(canonical) >= AXID_MINIMUM[kind]:
hint = f"Fix: point them at the axes this part declares ({', '.join(canonical)})"
else:
hint = ("Fix: the part declares several axes of a kind -- declare the "
"secondary axes the series expects, or drop them")
detail = (f"of which {', '.join(dead)} name no declared axis"
if dead else f"only {len(ids)} of which this part declares")
problems.append(
f"{part}: <c:{kind}> references axId {', '.join(ids)}, {detail}, "
f"leaving fewer than two live axes; PowerPoint discards the chart. {hint}"
)
return problems
def _ext_lst_spans(text: str) -> list[tuple[int, int]]:
spans: list[tuple[int, int]] = []
depth = 0
start = 0
for match in re.finditer(r"<(/?)c:extLst\b[^>]*?(/?)>", text):
closing, self_closing = match.group(1), match.group(2)
if self_closing:
continue
if closing:
depth -= 1
if depth == 0:
spans.append((start, match.end()))
else:
if depth == 0:
start = match.start()
depth += 1
return spans
CHART_CHECKS = (_check_stacked_label_positions, _check_chart_axis_references)
def find_chart_problems(files: Mapping[str, bytes]) -> list[str]:
problems: list[str] = []
for part in sorted(n for n in files if _CHART_PART_RE.fullmatch(n)):
xml = part_text(files[part])
for check in CHART_CHECKS:
problems.extend(check(part, xml))
return problems
plugins/codex/plugins/docx/skills/docx/scripts/office/helpers/pptx_slide.py
+60
View File
@@ -0,0 +1,60 @@
"""Pick the slide-XML schema errors PowerPoint refuses the file over.
A denylist over lxml's messages, so an unrecognised error class is a miss rather
than a false alarm.
"""
from __future__ import annotations
import re
SLIDE_PART_RE = re.compile(
r"ppt/(slides|slideLayouts|slideMasters|notesSlides|notesMasters|handoutMasters)"
r"/[^/]+\.xml"
)
FATAL_SLIDE_ERRORS: tuple[tuple[re.Pattern[str], str], ...] = (
(
re.compile(r"\}tableStyleId': This element is not expected"),
"two <a:tableStyleId> in one <a:tblPr> (the schema allows one)",
),
(
re.compile(r"\}srgbClr', attribute 'val'"),
"a colour that is not six hex digits",
),
(
re.compile(r"\}txBody': Missing child element"),
"a <p:txBody> with no children",
),
(
re.compile(r"\}miter', attribute 'lim'"),
'a line join with lim="NaN"',
),
(
re.compile(r"\}uLnTx': This element is not expected"),
"<a:uLnTx> in a position the schema forbids",
),
(
re.compile(r"\}overrideClrMapping': This element is not expected"),
"<p:overrideClrMapping> in a position the schema forbids",
),
(
re.compile(r"\}nvGrpSpPr': Missing child element"),
"a <p:nvGrpSpPr> with no children",
),
)
def is_schema_verdict(error: str) -> bool:
return error.startswith("Element ")
def fatal_slide_errors(errors: set[str]) -> list[str]:
out = []
for error in sorted(errors):
for pattern, meaning in FATAL_SLIDE_ERRORS:
if pattern.search(error):
out.append(f"{meaning}: {error}")
break
return out
plugins/codex/plugins/docx/skills/docx/scripts/office/helpers/pptx_theme.py
+114
View File
@@ -0,0 +1,114 @@
"""Find masters sharing a theme part in the way PowerPoint refuses to open.
Reports only; the fix is to move <p:notesMasterIdLst> back to directly after
<p:sldIdLst> in ppt/presentation.xml.
"""
from __future__ import annotations
import posixpath
import re
from typing import Mapping
from . import part_text
THEME_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
_MASTER_RE = re.compile(
r"^ppt/(?P<group>slideMasters|notesMasters|handoutMasters)/"
r"(?:slide|notes|handout)Master(?P<num>\d+)\.xml$"
)
_GROUP_ORDER = {"slideMasters": 0, "notesMasters": 1, "handoutMasters": 2}
_RELATIONSHIP_RE = re.compile(
r"<Relationship\b[^>]*?(?:/>|>.*?</Relationship\s*>)", re.DOTALL
)
def _sort_key(name: str) -> tuple[int, int]:
m = _MASTER_RE.match(name)
assert m is not None
return (_GROUP_ORDER[m.group("group")], int(m.group("num")))
def _rels_path(part: str) -> str:
directory, base = posixpath.split(part)
return f"{directory}/_rels/{base}.rels"
def _resolve(rels_path: str, target: str) -> str:
if target.startswith("/"):
return target.lstrip("/")
part_dir = posixpath.dirname(posixpath.dirname(rels_path))
return posixpath.normpath(posixpath.join(part_dir, target))
def _theme_rel(files: Mapping[str, bytes], master: str):
rels_path = _rels_path(master)
rels = files.get(rels_path)
if rels is None:
return None
for element in _RELATIONSHIP_RE.findall(part_text(rels)):
if f'Type="{THEME_REL_TYPE}"' not in element:
continue
target = re.search(r'\bTarget="([^"]+)"', element)
if target is None:
continue
return rels_path, element, _resolve(rels_path, target.group(1))
return None
def _masters(files: Mapping[str, bytes]) -> list[str]:
return sorted((n for n in files if _MASTER_RE.match(n)), key=_sort_key)
_PRESENTATION = "ppt/presentation.xml"
_NOTES_MASTERS = "ppt/notesMasters/"
_IGNORABLE_RE = re.compile(r"<!--.*?-->|<\?.*?\?>", re.DOTALL)
_AFTER_SLDIDLST_RE = re.compile(
r"<p:sldIdLst\b(?:[^>]*/>|[^>]*>.*?</p:sldIdLst\s*>)\s*(<[^>\s/]+)", re.DOTALL
)
def _notes_master_share_is_inert(files: Mapping[str, bytes]) -> bool:
data = files.get(_PRESENTATION)
if data is None:
return False
match = _AFTER_SLDIDLST_RE.search(_IGNORABLE_RE.sub("", part_text(data)))
return match is not None and match.group(1) == "<p:notesMasterIdLst"
def _shares(files: Mapping[str, bytes]):
owner: dict[str, str] = {}
for master in _masters(files):
found = _theme_rel(files, master)
if found is None:
continue
rels_path, element, theme = found
if theme not in files:
continue
if theme in owner:
yield master, rels_path, element, theme, owner[theme]
else:
owner[theme] = master
def _is_inert(master: str, inert_notes: bool) -> bool:
return inert_notes and master.startswith(_NOTES_MASTERS)
def find_shared_master_themes(files: Mapping[str, bytes]) -> list[str]:
return [
f"{master} shares {theme} with {first}"
for master, _, _, theme, first in _shares(files)
]
def live_shared_master_themes(files: Mapping[str, bytes]) -> list[str]:
inert_notes = _notes_master_share_is_inert(files)
return [
f"{master} shares {theme} with {first}"
for master, _, _, theme, first in _shares(files)
if not _is_inert(master, inert_notes)
]
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-chart.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-main.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-picture.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/pml.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-math.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/sml.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-main.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/wml.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/xml.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-contentTypes.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-coreProperties.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-digSig.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-relationships.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/mce/mc.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/mce/mc.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/microsoft/wml-2010.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/microsoft/wml-2010.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/microsoft/wml-2012.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/microsoft/wml-2012.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/microsoft/wml-2018.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/microsoft/wml-2018.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/microsoft/wml-cex-2018.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/microsoft/wml-cex-2018.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/microsoft/wml-cid-2016.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/microsoft/wml-cid-2016.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/microsoft/wml-sdtdatahash-2020.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/schemas/microsoft/wml-symex-2015.xsd → plugins/codex/plugins/docx/skills/docx/scripts/office/schemas/microsoft/wml-symex-2015.xsd
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/scripts/office/soffice.py
+61
View File
@@ -0,0 +1,61 @@
"""Portable LibreOffice runner for Windows, macOS and Linux."""
import os
import platform
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path
def resolve_soffice_binary():
explicit = os.environ.get("SOFFICE_PATH")
if explicit:
candidate = Path(explicit).expanduser()
if candidate.is_file():
return str(candidate)
raise FileNotFoundError(f"SOFFICE_PATH does not exist: {candidate}")
names = ("soffice.com", "soffice.exe", "soffice") if platform.system() == "Windows" else ("soffice",)
for name in names:
binary = shutil.which(name)
if binary:
return binary
candidates = [Path("/Applications/LibreOffice.app/Contents/MacOS/soffice")]
if platform.system() == "Windows":
candidates = [
Path(root) / "LibreOffice/program" / name
for root in (os.environ.get("ProgramFiles"), os.environ.get("ProgramFiles(x86)")) if root
for name in ("soffice.com", "soffice.exe")
]
for candidate in candidates:
if candidate.is_file():
return str(candidate)
raise FileNotFoundError("LibreOffice not found. Install it or set SOFFICE_PATH to its executable.")
def get_soffice_env():
env = os.environ.copy()
env["PYTHONUTF8"] = "1"
if platform.system() == "Linux":
env.setdefault("SAL_USE_VCLPLUGIN", "svp")
return env
def run_soffice(args, **kwargs):
binary = resolve_soffice_binary()
kwargs.setdefault("env", get_soffice_env())
kwargs.setdefault("timeout", 120)
if any(str(arg).startswith("-env:UserInstallation=") for arg in args):
return subprocess.run([binary, *args], **kwargs)
with tempfile.TemporaryDirectory(prefix="skill-lo-", ignore_cleanup_errors=True) as profile:
profile_arg = f"-env:UserInstallation={Path(profile).resolve().as_uri()}"
return subprocess.run([binary, profile_arg, *args], **kwargs)
if __name__ == "__main__":
try:
raise SystemExit(run_soffice(sys.argv[1:]).returncode)
except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
print(str(exc), file=sys.stderr)
raise SystemExit(1)
plugins/codex/plugins/docx/skills/docx/scripts/office/validate.py
Executable
+173
View File
@@ -0,0 +1,173 @@
"""
Command line tool to validate Office document XML files against XSD schemas and tracked changes.
Usage:
python validate.py <path> [--original <original_file>] [--auto-repair] [--author NAME]
The first argument can be either:
- An unpacked directory containing the Office document XML files
- A packed Office file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx template) which will be unpacked to a temp directory
Auto-repair fixes:
- paraId/durableId values that exceed OOXML limits
- Missing xml:space="preserve" on w:t elements with whitespace
"""
import argparse
import sys
import tempfile
import zipfile
from pathlib import Path
import defusedxml.ElementTree as ET
from defusedxml.common import DefusedXmlException
from helpers import OOXML_FAMILY, rezip, safe_extract
from validators import DOCXSchemaValidator, PPTXSchemaValidator, RedliningValidator
WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
def _fail(message: str):
print(f"Error: {message}", file=sys.stderr)
sys.exit(2)
def _has_tracked_changes(unpacked_dir: Path) -> bool:
document = unpacked_dir / "word" / "document.xml"
if not document.is_file():
return False
try:
root = ET.parse(document).getroot()
except (ET.ParseError, DefusedXmlException):
return False
tracked = {f"{{{WORD_NS}}}ins", f"{{{WORD_NS}}}del"}
return any(elem.tag in tracked for elem in root.iter())
def main():
parser = argparse.ArgumentParser(description="Validate Office document XML files")
parser.add_argument(
"path",
help="Path to unpacked directory or packed Office file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx)",
)
parser.add_argument(
"--original",
required=False,
default=None,
help="Path to original file (.docx/.pptx/.xlsx or .dotx/.potx/.xltx). If omitted, all XSD errors are reported and redlining validation is skipped.",
)
parser.add_argument(
"-v",
"--verbose",
action="store_true",
help="Enable verbose output",
)
parser.add_argument(
"--auto-repair",
action="store_true",
help="Automatically repair common issues (hex IDs, whitespace preservation). "
"Modifies the input in place: repairs to a packed file are written back to it.",
)
parser.add_argument(
"--author",
default=None,
help="The name you are redlining under. Passing it turns on the "
"tracked-change check: any text differing from --original without a "
"<w:ins>/<w:del> recording it is reported. Untracked edits carry no "
"author, so the check covers them whoever made them — the name marks "
"the run as redlining work and is not used to filter. Requires "
"--original; docx only.",
)
args = parser.parse_args()
if args.author is not None and not args.original:
_fail("--author requires --original")
path = Path(args.path)
if not path.exists():
_fail(f"{path} does not exist")
original_file = None
if args.original:
original_file = Path(args.original)
if not original_file.is_file():
_fail(f"{original_file} is not a file")
if original_file.suffix.lower() not in OOXML_FAMILY:
_fail(f"{original_file} must be one of: {', '.join(sorted(OOXML_FAMILY))}")
family = OOXML_FAMILY.get((original_file or path).suffix.lower())
if family is None:
_fail(
f"Cannot determine file type from {path}. Use --original or provide one of: {', '.join(sorted(OOXML_FAMILY))}."
)
if args.author is not None and family != "docx":
_fail(f"--author only applies to docx files, not {family}")
packed_file = None
temp_dir_ctx = None
if path.is_file() and path.suffix.lower() in OOXML_FAMILY:
packed_file = path
temp_dir_ctx = tempfile.TemporaryDirectory()
unpacked_dir = Path(temp_dir_ctx.name)
try:
with zipfile.ZipFile(path, "r") as zf:
safe_extract(zf, unpacked_dir)
except (zipfile.BadZipFile, ValueError, OSError) as e:
_fail(f"cannot unpack {path}: {e}")
else:
if not path.is_dir():
_fail(f"{path} is not a directory or Office file")
unpacked_dir = path
match family:
case "docx":
validators = [
DOCXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),
]
if args.author is not None:
validators.append(
RedliningValidator(unpacked_dir, original_file, verbose=args.verbose)
)
elif original_file and _has_tracked_changes(unpacked_dir):
print(
"Note: this document has tracked changes; they were not "
"checked against the original (pass --author to check)."
)
case "pptx":
validators = [
PPTXSchemaValidator(unpacked_dir, original_file, verbose=args.verbose),
]
case "xlsx":
exts = ", ".join(k for k, v in sorted(OOXML_FAMILY.items()) if v == "xlsx")
print(
f"No XSD schema validation is performed for xlsx-family files ({exts}). "
"For formula-error checking, use scripts/recalc.py instead."
)
sys.exit(0)
case _:
print(f"Error: Validation not supported for file type {family}")
sys.exit(1)
if args.auto_repair:
total_repairs = sum(v.repair() for v in validators)
if total_repairs:
print(f"Auto-repaired {total_repairs} issue(s)")
if packed_file is not None:
rezip(unpacked_dir, packed_file)
print(f"Wrote repaired file to {packed_file}")
success = all([v.validate() for v in validators])
if temp_dir_ctx is not None:
temp_dir_ctx.cleanup()
if success:
print("All validations PASSED!")
sys.exit(0 if success else 1)
if __name__ == "__main__":
main()
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/validation/__init__.py → plugins/codex/plugins/docx/skills/docx/scripts/office/validators/__init__.py
View File
File renamed without changes.
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/validation/base.py → plugins/codex/plugins/docx/skills/docx/scripts/office/validators/base.py
+143 -219
View File
@@ -5,72 +5,74 @@ Base validator with common validation logic for document files.
import re
from pathlib import Path
import defusedxml.minidom
from functools import lru_cache
import lxml.etree
from helpers import safe_extract
@lru_cache(maxsize=None)
def _load_schema(schema_path: str):
with open(schema_path, "rb") as xsd_file:
xsd_doc = lxml.etree.parse(
xsd_file, parser=lxml.etree.XMLParser(), base_url=schema_path
)
return lxml.etree.XMLSchema(xsd_doc)
class BaseSchemaValidator:
"""Base validator with common validation logic for document files."""
# Elements whose 'id' attributes must be unique within their file
# Format: element_name -> (attribute_name, scope)
# scope can be 'file' (unique within file) or 'global' (unique across all files)
IGNORED_VALIDATION_ERRORS = [
"hyphenationZone",
"purl.org/dc/terms",
]
UNIQUE_ID_REQUIREMENTS = {
# Word elements
"comment": ("id", "file"), # Comment IDs in comments.xml
"commentrangestart": ("id", "file"), # Must match comment IDs
"commentrangeend": ("id", "file"), # Must match comment IDs
"bookmarkstart": ("id", "file"), # Bookmark start IDs
"bookmarkend": ("id", "file"), # Bookmark end IDs
# Note: ins and del (track changes) can share IDs when part of same revision
# PowerPoint elements
"sldid": ("id", "file"), # Slide IDs in presentation.xml
"sldmasterid": ("id", "global"), # Slide master IDs must be globally unique
"sldlayoutid": ("id", "global"), # Slide layout IDs must be globally unique
"cm": ("authorid", "file"), # Comment author IDs
# Excel elements
"sheet": ("sheetid", "file"), # Sheet IDs in workbook.xml
"definedname": ("id", "file"), # Named range IDs
# Drawing/Shape elements (all formats)
"cxnsp": ("id", "file"), # Connection shape IDs
"sp": ("id", "file"), # Shape IDs
"pic": ("id", "file"), # Picture IDs
"grpsp": ("id", "file"), # Group shape IDs
"comment": ("id", "file"),
"commentrangestart": ("id", "file"),
"commentrangeend": ("id", "file"),
"bookmarkstart": ("id", "file"),
"bookmarkend": ("id", "file"),
"sldid": ("id", "file"),
"sldmasterid": ("id", "global"),
"sldlayoutid": ("id", "global"),
"cm": ("authorid", "file"),
"sheet": ("sheetid", "file"),
"definedname": ("id", "file"),
"cxnsp": ("id", "file"),
"sp": ("id", "file"),
"pic": ("id", "file"),
"grpsp": ("id", "file"),
}
EXCLUDED_ID_CONTAINERS = {
"sectionlst",
}
# Mapping of element names to expected relationship types
# Subclasses should override this with format-specific mappings
ELEMENT_RELATIONSHIP_TYPES = {}
# Unified schema mappings for all Office document types
SCHEMA_MAPPINGS = {
# Document type specific schemas
"word": "ISO-IEC29500-4_2016/wml.xsd", # Word documents
"ppt": "ISO-IEC29500-4_2016/pml.xsd", # PowerPoint presentations
"xl": "ISO-IEC29500-4_2016/sml.xsd", # Excel spreadsheets
# Common file types
"word": "ISO-IEC29500-4_2016/wml.xsd",
"ppt": "ISO-IEC29500-4_2016/pml.xsd",
"xl": "ISO-IEC29500-4_2016/sml.xsd",
"[Content_Types].xml": "ecma/fouth-edition/opc-contentTypes.xsd",
"app.xml": "ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd",
"core.xml": "ecma/fouth-edition/opc-coreProperties.xsd",
"custom.xml": "ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd",
".rels": "ecma/fouth-edition/opc-relationships.xsd",
# Word-specific files
"people.xml": "microsoft/wml-2012.xsd",
"commentsIds.xml": "microsoft/wml-cid-2016.xsd",
"commentsExtensible.xml": "microsoft/wml-cex-2018.xsd",
"commentsExtended.xml": "microsoft/wml-2012.xsd",
# Chart files (common across document types)
"chart": "ISO-IEC29500-4_2016/dml-chart.xsd",
# Theme files (common across document types)
"theme": "ISO-IEC29500-4_2016/dml-main.xsd",
# Drawing and media files
"drawing": "ISO-IEC29500-4_2016/dml-main.xsd",
}
# Unified namespace constants
MC_NAMESPACE = "http://schemas.openxmlformats.org/markup-compatibility/2006"
XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace"
# Common OOXML namespaces used across validators
PACKAGE_RELATIONSHIPS_NAMESPACE = (
"http://schemas.openxmlformats.org/package/2006/relationships"
)
@@ -81,10 +83,8 @@ class BaseSchemaValidator:
"http://schemas.openxmlformats.org/package/2006/content-types"
)
# Folders where we should clean ignorable namespaces
MAIN_CONTENT_FOLDERS = {"word", "ppt", "xl"}
# All allowed OOXML namespaces (superset of all document types)
OOXML_NAMESPACES = {
"http://schemas.openxmlformats.org/officeDocument/2006/math",
"http://schemas.openxmlformats.org/officeDocument/2006/relationships",
@@ -103,15 +103,13 @@ class BaseSchemaValidator:
"http://www.w3.org/XML/1998/namespace",
}
def __init__(self, unpacked_dir, original_file, verbose=False):
def __init__(self, unpacked_dir, original_file=None, verbose=False):
self.unpacked_dir = Path(unpacked_dir).resolve()
self.original_file = Path(original_file)
self.original_file = Path(original_file) if original_file else None
self.verbose = verbose
# Set schemas directory
self.schemas_dir = Path(__file__).parent.parent.parent / "schemas"
self.schemas_dir = Path(__file__).parent.parent / "schemas"
# Get all XML and .rels files
patterns = ["*.xml", "*.rels"]
self.xml_files = [
f for pattern in patterns for f in self.unpacked_dir.rglob(pattern)
@@ -121,16 +119,51 @@ class BaseSchemaValidator:
print(f"Warning: No XML files found in {self.unpacked_dir}")
def validate(self):
"""Run all validation checks and return True if all pass."""
raise NotImplementedError("Subclasses must implement the validate method")
def repair(self) -> int:
return self.repair_whitespace_preservation()
def repair_whitespace_preservation(self) -> int:
repairs = 0
for xml_file in self.xml_files:
try:
content = xml_file.read_text(encoding="utf-8")
dom = defusedxml.minidom.parseString(content)
pending = []
for elem in dom.getElementsByTagName("*"):
local_name = elem.tagName.rsplit(":", 1)[-1]
if local_name in ("t", "delText", "instrText", "delInstrText"):
text = "".join(
child.data
for child in elem.childNodes
if child.nodeType in (child.TEXT_NODE, child.CDATA_SECTION_NODE)
)
ws = (" ", "\t", "\n", "\r")
if text and (text.startswith(ws) or text.endswith(ws)):
if elem.getAttribute("xml:space") != "preserve":
elem.setAttribute("xml:space", "preserve")
text_preview = repr(text[:30]) + "..." if len(text) > 30 else repr(text)
pending.append(f" Repaired: {xml_file.name}: Added xml:space='preserve' to {elem.tagName}: {text_preview}")
if pending:
xml_file.write_bytes(dom.toxml(encoding="UTF-8"))
for message in pending:
print(message)
repairs += len(pending)
except Exception:
pass
return repairs
def validate_xml(self):
"""Validate that all XML files are well-formed."""
errors = []
for xml_file in self.xml_files:
try:
# Try to parse the XML file
lxml.etree.parse(str(xml_file))
except lxml.etree.XMLSyntaxError as e:
errors.append(
@@ -154,13 +187,12 @@ class BaseSchemaValidator:
return True
def validate_namespaces(self):
"""Validate that namespace prefixes in Ignorable attributes are declared."""
errors = []
for xml_file in self.xml_files:
try:
root = lxml.etree.parse(str(xml_file)).getroot()
declared = set(root.nsmap.keys()) - {None} # Exclude default namespace
declared = set(root.nsmap.keys()) - {None}
for attr_val in [
v for k, v in root.attrib.items() if k.endswith("Ignorable")
@@ -184,36 +216,39 @@ class BaseSchemaValidator:
return True
def validate_unique_ids(self):
"""Validate that specific IDs are unique according to OOXML requirements."""
errors = []
global_ids = {} # Track globally unique IDs across all files
global_ids = {}
for xml_file in self.xml_files:
try:
root = lxml.etree.parse(str(xml_file)).getroot()
file_ids = {} # Track IDs that must be unique within this file
file_ids = {}
# Remove all mc:AlternateContent elements from the tree
mc_elements = root.xpath(
".//mc:AlternateContent", namespaces={"mc": self.MC_NAMESPACE}
)
for elem in mc_elements:
elem.getparent().remove(elem)
# Now check IDs in the cleaned tree
for elem in root.iter():
# Get the element name without namespace
if not hasattr(elem, "tag") or callable(elem.tag):
continue
tag = (
elem.tag.split("}")[-1].lower()
if "}" in elem.tag
else elem.tag.lower()
)
# Check if this element type has ID uniqueness requirements
if tag in self.UNIQUE_ID_REQUIREMENTS:
in_excluded_container = any(
ancestor.tag.split("}")[-1].lower() in self.EXCLUDED_ID_CONTAINERS
for ancestor in elem.iterancestors()
)
if in_excluded_container:
continue
attr_name, scope = self.UNIQUE_ID_REQUIREMENTS[tag]
# Look for the specified attribute
id_value = None
for attr, value in elem.attrib.items():
attr_local = (
@@ -227,7 +262,6 @@ class BaseSchemaValidator:
if id_value is not None:
if scope == "global":
# Check global uniqueness
if id_value in global_ids:
prev_file, prev_line, prev_tag = global_ids[
id_value
@@ -244,7 +278,6 @@ class BaseSchemaValidator:
tag,
)
elif scope == "file":
# Check file-level uniqueness
key = (tag, attr_name)
if key not in file_ids:
file_ids[key] = {}
@@ -275,12 +308,8 @@ class BaseSchemaValidator:
return True
def validate_file_references(self):
"""
Validate that all .rels files properly reference files and that all files are referenced.
"""
errors = []
# Find all .rels files
rels_files = list(self.unpacked_dir.rglob("*.rels"))
if not rels_files:
@@ -288,17 +317,15 @@ class BaseSchemaValidator:
print("PASSED - No .rels files found")
return True
# Get all files in the unpacked directory (excluding reference files)
all_files = []
for file_path in self.unpacked_dir.rglob("*"):
if (
file_path.is_file()
and file_path.name != "[Content_Types].xml"
and not file_path.name.endswith(".rels")
): # This file is not referenced by .rels
):
all_files.append(file_path.resolve())
# Track all files that are referenced by any .rels file
all_referenced_files = set()
if self.verbose:
@@ -306,16 +333,12 @@ class BaseSchemaValidator:
f"Found {len(rels_files)} .rels files and {len(all_files)} target files"
)
# Check each .rels file
for rels_file in rels_files:
try:
# Parse relationships file
rels_root = lxml.etree.parse(str(rels_file)).getroot()
# Get the directory where this .rels file is located
rels_dir = rels_file.parent
# Find all relationships and their targets
referenced_files = set()
broken_refs = []
@@ -324,20 +347,19 @@ class BaseSchemaValidator:
namespaces={"ns": self.PACKAGE_RELATIONSHIPS_NAMESPACE},
):
target = rel.get("Target")
if rel.get("TargetMode") == "External":
continue
if target and not target.startswith(
("http", "mailto:")
): # Skip external URLs
# Resolve the target path relative to the .rels file location
if rels_file.name == ".rels":
# Root .rels file - targets are relative to unpacked_dir
):
if target.startswith("/"):
target_path = self.unpacked_dir / target.lstrip("/")
elif rels_file.name == ".rels":
target_path = self.unpacked_dir / target
else:
# Other .rels files - targets are relative to their parent's parent
# e.g., word/_rels/document.xml.rels -> targets relative to word/
base_dir = rels_dir.parent
target_path = base_dir / target
# Normalize the path and check if it exists
try:
target_path = target_path.resolve()
if target_path.exists() and target_path.is_file():
@@ -348,7 +370,6 @@ class BaseSchemaValidator:
except (OSError, ValueError):
broken_refs.append((target, rel.sourceline))
# Report broken references
if broken_refs:
rel_path = rels_file.relative_to(self.unpacked_dir)
for broken_ref, line_num in broken_refs:
@@ -360,7 +381,6 @@ class BaseSchemaValidator:
rel_path = rels_file.relative_to(self.unpacked_dir)
errors.append(f" Error parsing {rel_path}: {e}")
# Check for unreferenced files (files that exist but are not referenced anywhere)
unreferenced_files = set(all_files) - all_referenced_files
if unreferenced_files:
@@ -386,31 +406,21 @@ class BaseSchemaValidator:
return True
def validate_all_relationship_ids(self):
"""
Validate that all r:id attributes in XML files reference existing IDs
in their corresponding .rels files, and optionally validate relationship types.
"""
import lxml.etree
errors = []
# Process each XML file that might contain r:id references
for xml_file in self.xml_files:
# Skip .rels files themselves
if xml_file.suffix == ".rels":
continue
# Determine the corresponding .rels file
# For dir/file.xml, it's dir/_rels/file.xml.rels
rels_dir = xml_file.parent / "_rels"
rels_file = rels_dir / f"{xml_file.name}.rels"
# Skip if there's no corresponding .rels file (that's okay)
if not rels_file.exists():
continue
try:
# Parse the .rels file to get valid relationship IDs and their types
rels_root = lxml.etree.parse(str(rels_file)).getroot()
rid_to_type = {}
@@ -420,47 +430,45 @@ class BaseSchemaValidator:
rid = rel.get("Id")
rel_type = rel.get("Type", "")
if rid:
# Check for duplicate rIds
if rid in rid_to_type:
rels_rel_path = rels_file.relative_to(self.unpacked_dir)
errors.append(
f" {rels_rel_path}: Line {rel.sourceline}: "
f"Duplicate relationship ID '{rid}' (IDs must be unique)"
)
# Extract just the type name from the full URL
type_name = (
rel_type.split("/")[-1] if "/" in rel_type else rel_type
)
rid_to_type[rid] = type_name
# Parse the XML file to find all r:id references
xml_root = lxml.etree.parse(str(xml_file)).getroot()
# Find all elements with r:id attributes
r_ns = self.OFFICE_RELATIONSHIPS_NAMESPACE
rid_attrs_to_check = ["id", "embed", "link"]
for elem in xml_root.iter():
# Check for r:id attribute (relationship ID)
rid_attr = elem.get(f"{{{self.OFFICE_RELATIONSHIPS_NAMESPACE}}}id")
if rid_attr:
if not hasattr(elem, "tag") or callable(elem.tag):
continue
for attr_name in rid_attrs_to_check:
rid_attr = elem.get(f"{{{r_ns}}}{attr_name}")
if not rid_attr:
continue
xml_rel_path = xml_file.relative_to(self.unpacked_dir)
elem_name = (
elem.tag.split("}")[-1] if "}" in elem.tag else elem.tag
)
# Check if the ID exists
if rid_attr not in rid_to_type:
errors.append(
f" {xml_rel_path}: Line {elem.sourceline}: "
f"<{elem_name}> references non-existent relationship '{rid_attr}' "
f"<{elem_name}> r:{attr_name} references non-existent relationship '{rid_attr}' "
f"(valid IDs: {', '.join(sorted(rid_to_type.keys())[:5])}{'...' if len(rid_to_type) > 5 else ''})"
)
# Check if we have type expectations for this element
elif self.ELEMENT_RELATIONSHIP_TYPES:
elif attr_name == "id" and self.ELEMENT_RELATIONSHIP_TYPES:
expected_type = self._get_expected_relationship_type(
elem_name
)
if expected_type:
actual_type = rid_to_type[rid_attr]
# Check if the actual type matches or contains the expected type
if expected_type not in actual_type.lower():
errors.append(
f" {xml_rel_path}: Line {elem.sourceline}: "
@@ -484,58 +492,41 @@ class BaseSchemaValidator:
return True
def _get_expected_relationship_type(self, element_name):
"""
Get the expected relationship type for an element.
First checks the explicit mapping, then tries pattern detection.
"""
# Normalize element name to lowercase
elem_lower = element_name.lower()
# Check explicit mapping first
if elem_lower in self.ELEMENT_RELATIONSHIP_TYPES:
return self.ELEMENT_RELATIONSHIP_TYPES[elem_lower]
# Try pattern detection for common patterns
# Pattern 1: Elements ending in "Id" often expect a relationship of the prefix type
if elem_lower.endswith("id") and len(elem_lower) > 2:
# e.g., "sldId" -> "sld", "sldMasterId" -> "sldMaster"
prefix = elem_lower[:-2] # Remove "id"
# Check if this might be a compound like "sldMasterId"
prefix = elem_lower[:-2]
if prefix.endswith("master"):
return prefix.lower()
elif prefix.endswith("layout"):
return prefix.lower()
else:
# Simple case like "sldId" -> "slide"
# Common transformations
if prefix == "sld":
return "slide"
return prefix.lower()
# Pattern 2: Elements ending in "Reference" expect a relationship of the prefix type
if elem_lower.endswith("reference") and len(elem_lower) > 9:
prefix = elem_lower[:-9] # Remove "reference"
prefix = elem_lower[:-9]
return prefix.lower()
return None
def validate_content_types(self):
"""Validate that all content files are properly declared in [Content_Types].xml."""
errors = []
# Find [Content_Types].xml file
content_types_file = self.unpacked_dir / "[Content_Types].xml"
if not content_types_file.exists():
print("FAILED - [Content_Types].xml file not found")
return False
try:
# Parse and get all declared parts and extensions
root = lxml.etree.parse(str(content_types_file)).getroot()
declared_parts = set()
declared_extensions = set()
# Get Override declarations (specific files)
for override in root.findall(
f".//{{{self.CONTENT_TYPES_NAMESPACE}}}Override"
):
@@ -543,7 +534,6 @@ class BaseSchemaValidator:
if part_name is not None:
declared_parts.add(part_name.lstrip("/"))
# Get Default declarations (by extension)
for default in root.findall(
f".//{{{self.CONTENT_TYPES_NAMESPACE}}}Default"
):
@@ -551,19 +541,17 @@ class BaseSchemaValidator:
if extension is not None:
declared_extensions.add(extension.lower())
# Root elements that require content type declaration
declarable_roots = {
"sld",
"sldLayout",
"sldMaster",
"presentation", # PowerPoint
"document", # Word
"presentation",
"document",
"workbook",
"worksheet", # Excel
"theme", # Common
"worksheet",
"theme",
}
# Common media file extensions that should be declared
media_extensions = {
"png": "image/png",
"jpg": "image/jpeg",
@@ -575,17 +563,14 @@ class BaseSchemaValidator:
"emf": "image/x-emf",
}
# Get all files in the unpacked directory
all_files = list(self.unpacked_dir.rglob("*"))
all_files = [f for f in all_files if f.is_file()]
# Check all XML files for Override declarations
for xml_file in self.xml_files:
path_str = str(xml_file.relative_to(self.unpacked_dir)).replace(
"\\", "/"
)
# Skip non-content files
if any(
skip in path_str
for skip in [".rels", "[Content_Types]", "docProps/", "_rels/"]
@@ -602,11 +587,9 @@ class BaseSchemaValidator:
)
except Exception:
continue # Skip unparseable files
continue
# Check all non-XML files for Default extension declarations
for file_path in all_files:
# Skip XML files and metadata files (already checked above)
if file_path.suffix.lower() in {".xml", ".rels"}:
continue
if file_path.name == "[Content_Types].xml":
@@ -616,7 +599,6 @@ class BaseSchemaValidator:
extension = file_path.suffix.lstrip(".").lower()
if extension and extension not in declared_extensions:
# Check if it's a known media extension that should be declared
if extension in media_extensions:
relative_path = file_path.relative_to(self.unpacked_dir)
errors.append(
@@ -639,36 +621,28 @@ class BaseSchemaValidator:
return True
def validate_file_against_xsd(self, xml_file, verbose=False):
"""Validate a single XML file against XSD schema, comparing with original.
Args:
xml_file: Path to XML file to validate
verbose: Enable verbose output
Returns:
tuple: (is_valid, new_errors_set) where is_valid is True/False/None (skipped)
"""
# Resolve both paths to handle symlinks
xml_file = Path(xml_file).resolve()
unpacked_dir = self.unpacked_dir.resolve()
# Validate current file
is_valid, current_errors = self._validate_single_file_xsd(
xml_file, unpacked_dir
)
if is_valid is None:
return None, set() # Skipped
return None, set()
elif is_valid:
return True, set() # Valid, no errors
return True, set()
# Get errors from original file for this specific file
original_errors = self._get_original_file_errors(xml_file)
# Compare with original (both are guaranteed to be sets here)
assert current_errors is not None
new_errors = current_errors - original_errors
new_errors = {
e for e in new_errors
if not any(pattern in e for pattern in self.IGNORED_VALIDATION_ERRORS)
}
if new_errors:
if verbose:
relative_path = xml_file.relative_to(unpacked_dir)
@@ -678,7 +652,6 @@ class BaseSchemaValidator:
print(f" - {truncated}")
return False, new_errors
else:
# All errors existed in original
if verbose:
print(
f"PASSED - No new errors (original had {len(current_errors)} errors)"
@@ -686,7 +659,6 @@ class BaseSchemaValidator:
return True, set()
def validate_against_xsd(self):
"""Validate XML files against XSD schemas, showing only new errors compared to original."""
new_errors = []
original_error_count = 0
valid_count = 0
@@ -705,19 +677,16 @@ class BaseSchemaValidator:
valid_count += 1
continue
elif is_valid:
# Had errors but all existed in original
original_error_count += 1
valid_count += 1
continue
# Has new errors
new_errors.append(f" {relative_path}: {len(new_file_errors)} new error(s)")
for error in list(new_file_errors)[:3]: # Show first 3 errors
for error in list(new_file_errors)[:3]:
new_errors.append(
f" - {error[:250]}..." if len(error) > 250 else f" - {error}"
)
# Print summary
if self.verbose:
print(f"Validated {len(self.xml_files)} files:")
print(f" - Valid: {valid_count}")
@@ -739,62 +708,47 @@ class BaseSchemaValidator:
return True
def _get_schema_path(self, xml_file):
"""Determine the appropriate schema path for an XML file."""
# Check exact filename match
if xml_file.name in self.SCHEMA_MAPPINGS:
return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.name]
# Check .rels files
if xml_file.suffix == ".rels":
return self.schemas_dir / self.SCHEMA_MAPPINGS[".rels"]
# Check chart files
if "charts/" in str(xml_file) and xml_file.name.startswith("chart"):
return self.schemas_dir / self.SCHEMA_MAPPINGS["chart"]
# Check theme files
if "theme/" in str(xml_file) and xml_file.name.startswith("theme"):
return self.schemas_dir / self.SCHEMA_MAPPINGS["theme"]
# Check if file is in a main content folder and use appropriate schema
if xml_file.parent.name in self.MAIN_CONTENT_FOLDERS:
return self.schemas_dir / self.SCHEMA_MAPPINGS[xml_file.parent.name]
return None
def _clean_ignorable_namespaces(self, xml_doc):
"""Remove attributes and elements not in allowed namespaces."""
# Create a clean copy
xml_string = lxml.etree.tostring(xml_doc, encoding="unicode")
xml_copy = lxml.etree.fromstring(xml_string)
# Remove attributes not in allowed namespaces
for elem in xml_copy.iter():
attrs_to_remove = []
for attr in elem.attrib:
# Check if attribute is from a namespace other than allowed ones
if "{" in attr:
ns = attr.split("}")[0][1:]
if ns not in self.OOXML_NAMESPACES:
attrs_to_remove.append(attr)
# Remove collected attributes
for attr in attrs_to_remove:
del elem.attrib[attr]
# Remove elements not in allowed namespaces
self._remove_ignorable_elements(xml_copy)
return lxml.etree.ElementTree(xml_copy)
def _remove_ignorable_elements(self, root):
"""Recursively remove all elements not in allowed namespaces."""
elements_to_remove = []
# Find elements to remove
for elem in list(root):
# Skip non-element nodes (comments, processing instructions, etc.)
if not hasattr(elem, "tag") or callable(elem.tag):
continue
@@ -805,47 +759,36 @@ class BaseSchemaValidator:
elements_to_remove.append(elem)
continue
# Recursively clean child elements
self._remove_ignorable_elements(elem)
# Remove collected elements
for elem in elements_to_remove:
root.remove(elem)
def _preprocess_for_mc_ignorable(self, xml_doc):
"""Preprocess XML to handle mc:Ignorable attribute properly."""
# Remove mc:Ignorable attributes before validation
root = xml_doc.getroot()
# Remove mc:Ignorable attribute from root
if f"{{{self.MC_NAMESPACE}}}Ignorable" in root.attrib:
del root.attrib[f"{{{self.MC_NAMESPACE}}}Ignorable"]
return xml_doc
def _validate_single_file_xsd(self, xml_file, base_path):
"""Validate a single XML file against XSD schema. Returns (is_valid, errors_set)."""
schema_path = self._get_schema_path(xml_file)
def _preprocess_for_schema(self, xml_doc, relative_path):
return xml_doc
def _validate_single_file_xsd(self, xml_file, base_path, schema_path=None):
schema_path = schema_path or self._get_schema_path(xml_file)
if not schema_path:
return None, None # Skip file
return None, None
try:
# Load schema
with open(schema_path, "rb") as xsd_file:
parser = lxml.etree.XMLParser()
xsd_doc = lxml.etree.parse(
xsd_file, parser=parser, base_url=str(schema_path)
)
schema = lxml.etree.XMLSchema(xsd_doc)
schema = _load_schema(str(schema_path))
# Load and preprocess XML
with open(xml_file, "r") as f:
xml_doc = lxml.etree.parse(f)
xml_doc, _ = self._remove_template_tags_from_text_nodes(xml_doc)
xml_doc = self._preprocess_for_mc_ignorable(xml_doc)
# Clean ignorable namespaces if needed
relative_path = xml_file.relative_to(base_path)
if (
relative_path.parts
@@ -853,32 +796,26 @@ class BaseSchemaValidator:
):
xml_doc = self._clean_ignorable_namespaces(xml_doc)
# Validate
xml_doc = self._preprocess_for_schema(xml_doc, relative_path)
if schema.validate(xml_doc):
return True, set()
else:
errors = set()
for error in schema.error_log:
# Store normalized error message (without line numbers for comparison)
errors.add(error.message)
return False, errors
except Exception as e:
return False, {str(e)}
def _get_original_file_errors(self, xml_file):
"""Get XSD validation errors from a single file in the original document.
def _get_original_file_errors(self, xml_file, schema_path=None):
if self.original_file is None:
return set()
Args:
xml_file: Path to the XML file in unpacked_dir to check
Returns:
set: Set of error messages from the original file
"""
import tempfile
import zipfile
# Resolve both paths to handle symlinks (e.g., /var vs /private/var on macOS)
xml_file = Path(xml_file).resolve()
unpacked_dir = self.unpacked_dir.resolve()
relative_path = xml_file.relative_to(unpacked_dir)
@@ -886,37 +823,26 @@ class BaseSchemaValidator:
with tempfile.TemporaryDirectory() as temp_dir:
temp_path = Path(temp_dir)
# Extract original file
with zipfile.ZipFile(self.original_file, "r") as zip_ref:
zip_ref.extractall(temp_path)
try:
with zipfile.ZipFile(self.original_file, "r") as zip_ref:
safe_extract(zip_ref, temp_path)
except (zipfile.BadZipFile, ValueError, OSError):
return set()
# Find corresponding file in original
original_xml_file = temp_path / relative_path
if not original_xml_file.exists():
# File didn't exist in original, so no original errors
return set()
# Validate the specific file in original
is_valid, errors = self._validate_single_file_xsd(
original_xml_file, temp_path
original_xml_file, temp_path, schema_path=schema_path
)
return errors if errors else set()
def _remove_template_tags_from_text_nodes(self, xml_doc):
"""Remove template tags from XML text nodes and collect warnings.
Template tags follow the pattern {{ ... }} and are used as placeholders
for content replacement. They should be removed from text content before
XSD validation while preserving XML structure.
Returns:
tuple: (cleaned_xml_doc, warnings_list)
"""
warnings = []
template_pattern = re.compile(r"\{\{[^}]*\}\}")
# Create a copy of the document to avoid modifying the original
xml_string = lxml.etree.tostring(xml_doc, encoding="unicode")
xml_copy = lxml.etree.fromstring(xml_string)
@@ -932,9 +858,7 @@ class BaseSchemaValidator:
return template_pattern.sub("", text)
return text
# Process all text nodes in the document
for elem in xml_copy.iter():
# Skip processing if this is a w:t element
if not hasattr(elem, "tag") or callable(elem.tag):
continue
tag_str = str(elem.tag)
plugins/codex/plugins/docx/skills/docx/scripts/office/validators/docx.py
+466
View File
@@ -0,0 +1,466 @@
"""
Validator for Word document XML files against XSD schemas.
"""
import random
import re
import tempfile
import zipfile
from pathlib import Path
import defusedxml.minidom
import lxml.etree
from helpers import safe_extract
from .base import BaseSchemaValidator
class DOCXSchemaValidator(BaseSchemaValidator):
WORD_2006_NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
W14_NAMESPACE = "http://schemas.microsoft.com/office/word/2010/wordml"
W16CID_NAMESPACE = "http://schemas.microsoft.com/office/word/2016/wordml/cid"
ELEMENT_RELATIONSHIP_TYPES = {}
def validate(self):
if not self.validate_xml():
return False
all_valid = True
if not self.validate_namespaces():
all_valid = False
if not self.validate_unique_ids():
all_valid = False
if not self.validate_file_references():
all_valid = False
if not self.validate_content_types():
all_valid = False
if not self.validate_against_xsd():
all_valid = False
if not self.validate_whitespace_preservation():
all_valid = False
if not self.validate_deletions():
all_valid = False
if not self.validate_insertions():
all_valid = False
if not self.validate_all_relationship_ids():
all_valid = False
if not self.validate_id_constraints():
all_valid = False
if not self.validate_comment_markers():
all_valid = False
self.compare_paragraph_counts()
return all_valid
def validate_whitespace_preservation(self):
errors = []
for xml_file in self.xml_files:
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
for elem in root.iter(f"{{{self.WORD_2006_NAMESPACE}}}t"):
if elem.text:
text = elem.text
if re.search(r"^[ \t\n\r]", text) or re.search(
r"[ \t\n\r]$", text
):
xml_space_attr = f"{{{self.XML_NAMESPACE}}}space"
if (
xml_space_attr not in elem.attrib
or elem.attrib[xml_space_attr] != "preserve"
):
text_preview = (
repr(text)[:50] + "..."
if len(repr(text)) > 50
else repr(text)
)
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
f"Line {elem.sourceline}: w:t element with whitespace missing xml:space='preserve': {text_preview}"
)
except (lxml.etree.XMLSyntaxError, Exception) as e:
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}"
)
if errors:
print(f"FAILED - Found {len(errors)} whitespace preservation violations:")
for error in errors:
print(error)
return False
else:
if self.verbose:
print("PASSED - All whitespace is properly preserved")
return True
def validate_deletions(self):
errors = []
for xml_file in self.xml_files:
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
namespaces = {"w": self.WORD_2006_NAMESPACE}
for t_elem in root.xpath(".//w:del//w:t", namespaces=namespaces):
if t_elem.text:
text_preview = (
repr(t_elem.text)[:50] + "..."
if len(repr(t_elem.text)) > 50
else repr(t_elem.text)
)
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
f"Line {t_elem.sourceline}: <w:t> found within <w:del>: {text_preview}"
)
for instr_elem in root.xpath(
".//w:del//w:instrText", namespaces=namespaces
):
text_preview = (
repr(instr_elem.text or "")[:50] + "..."
if len(repr(instr_elem.text or "")) > 50
else repr(instr_elem.text or "")
)
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
f"Line {instr_elem.sourceline}: <w:instrText> found within <w:del> (use <w:delInstrText>): {text_preview}"
)
except (lxml.etree.XMLSyntaxError, Exception) as e:
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}"
)
if errors:
print(f"FAILED - Found {len(errors)} deletion validation violations:")
for error in errors:
print(error)
return False
else:
if self.verbose:
print("PASSED - No w:t elements found within w:del elements")
return True
def count_paragraphs_in_unpacked(self):
count = 0
for xml_file in self.xml_files:
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
paragraphs = root.findall(f".//{{{self.WORD_2006_NAMESPACE}}}p")
count = len(paragraphs)
except Exception as e:
print(f"Error counting paragraphs in unpacked document: {e}")
return count
def count_paragraphs_in_original(self):
original = self.original_file
if original is None:
return 0
count = 0
try:
with tempfile.TemporaryDirectory() as temp_dir:
with zipfile.ZipFile(original, "r") as zip_ref:
safe_extract(zip_ref, Path(temp_dir))
doc_xml_path = temp_dir + "/word/document.xml"
root = lxml.etree.parse(doc_xml_path).getroot()
paragraphs = root.findall(f".//{{{self.WORD_2006_NAMESPACE}}}p")
count = len(paragraphs)
except Exception as e:
print(f"Error counting paragraphs in original document: {e}")
return count
def validate_insertions(self):
errors = []
for xml_file in self.xml_files:
if xml_file.name != "document.xml":
continue
try:
root = lxml.etree.parse(str(xml_file)).getroot()
namespaces = {"w": self.WORD_2006_NAMESPACE}
invalid_elements = root.xpath(
".//w:ins//w:delText[not(ancestor::w:del)]", namespaces=namespaces
)
for elem in invalid_elements:
text_preview = (
repr(elem.text or "")[:50] + "..."
if len(repr(elem.text or "")) > 50
else repr(elem.text or "")
)
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
f"Line {elem.sourceline}: <w:delText> within <w:ins>: {text_preview}"
)
except (lxml.etree.XMLSyntaxError, Exception) as e:
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: Error: {e}"
)
if errors:
print(f"FAILED - Found {len(errors)} insertion validation violations:")
for error in errors:
print(error)
return False
else:
if self.verbose:
print("PASSED - No w:delText elements within w:ins elements")
return True
def compare_paragraph_counts(self):
new_count = self.count_paragraphs_in_unpacked()
if self.original_file is None:
print(f"\nParagraphs: {new_count}")
return
original_count = self.count_paragraphs_in_original()
diff = new_count - original_count
diff_str = f"+{diff}" if diff > 0 else str(diff)
print(f"\nParagraphs: {original_count} → {new_count} ({diff_str})")
def _parse_id_value(self, val: str, base: int = 16) -> int:
return int(val, base)
def validate_id_constraints(self):
errors = []
para_id_attr = f"{{{self.W14_NAMESPACE}}}paraId"
durable_id_attr = f"{{{self.W16CID_NAMESPACE}}}durableId"
for xml_file in self.xml_files:
try:
for elem in lxml.etree.parse(str(xml_file)).iter():
if val := elem.get(para_id_attr):
try:
if self._parse_id_value(val, base=16) >= 0x80000000:
errors.append(
f" {xml_file.name}:{elem.sourceline}: paraId={val} >= 0x80000000"
)
except ValueError:
errors.append(
f" {xml_file.name}:{elem.sourceline}: "
f"paraId={val} is not valid hex"
)
if val := elem.get(durable_id_attr):
if xml_file.name == "numbering.xml":
try:
if self._parse_id_value(val, base=10) >= 0x7FFFFFFF:
errors.append(
f" {xml_file.name}:{elem.sourceline}: "
f"durableId={val} >= 0x7FFFFFFF"
)
except ValueError:
errors.append(
f" {xml_file.name}:{elem.sourceline}: "
f"durableId={val} must be decimal in numbering.xml"
)
else:
try:
if self._parse_id_value(val, base=16) >= 0x7FFFFFFF:
errors.append(
f" {xml_file.name}:{elem.sourceline}: "
f"durableId={val} >= 0x7FFFFFFF"
)
except ValueError:
errors.append(
f" {xml_file.name}:{elem.sourceline}: "
f"durableId={val} is not valid hex"
)
except lxml.etree.XMLSyntaxError:
continue
if errors:
print(f"FAILED - {len(errors)} ID constraint violations:")
for e in errors:
print(e)
elif self.verbose:
print("PASSED - All paraId/durableId values within constraints")
return not errors
def validate_comment_markers(self):
errors = []
document_xml = None
comments_xml = None
for xml_file in self.xml_files:
if xml_file.name == "document.xml" and "word" in str(xml_file):
document_xml = xml_file
elif xml_file.name == "comments.xml":
comments_xml = xml_file
if not document_xml:
if self.verbose:
print("PASSED - No document.xml found (skipping comment validation)")
return True
try:
doc_root = lxml.etree.parse(str(document_xml)).getroot()
namespaces = {"w": self.WORD_2006_NAMESPACE}
range_starts = {
elem.get(f"{{{self.WORD_2006_NAMESPACE}}}id")
for elem in doc_root.xpath(
".//w:commentRangeStart", namespaces=namespaces
)
}
range_ends = {
elem.get(f"{{{self.WORD_2006_NAMESPACE}}}id")
for elem in doc_root.xpath(
".//w:commentRangeEnd", namespaces=namespaces
)
}
references = {
elem.get(f"{{{self.WORD_2006_NAMESPACE}}}id")
for elem in doc_root.xpath(
".//w:commentReference", namespaces=namespaces
)
}
orphaned_ends = range_ends - range_starts
for comment_id in sorted(
orphaned_ends, key=lambda x: int(x) if x and x.isdigit() else 0
):
errors.append(
f' document.xml: commentRangeEnd id="{comment_id}" has no matching commentRangeStart'
)
orphaned_starts = range_starts - range_ends
for comment_id in sorted(
orphaned_starts, key=lambda x: int(x) if x and x.isdigit() else 0
):
errors.append(
f' document.xml: commentRangeStart id="{comment_id}" has no matching commentRangeEnd'
)
comment_ids = set()
if comments_xml and comments_xml.exists():
comments_root = lxml.etree.parse(str(comments_xml)).getroot()
comment_ids = {
elem.get(f"{{{self.WORD_2006_NAMESPACE}}}id")
for elem in comments_root.xpath(
".//w:comment", namespaces=namespaces
)
}
marker_ids = range_starts | range_ends | references
invalid_refs = marker_ids - comment_ids
for comment_id in sorted(
invalid_refs, key=lambda x: int(x) if x and x.isdigit() else 0
):
if comment_id:
errors.append(
f' document.xml: marker id="{comment_id}" references non-existent comment'
)
except (lxml.etree.XMLSyntaxError, Exception) as e:
errors.append(f" Error parsing XML: {e}")
if errors:
print(f"FAILED - {len(errors)} comment marker violations:")
for error in errors:
print(error)
return False
else:
if self.verbose:
print("PASSED - All comment markers properly paired")
return True
def repair(self) -> int:
repairs = super().repair()
repairs += self.repair_durableId()
return repairs
def repair_durableId(self) -> int:
DURABLE_ID_ATTRS = ("w16cid:durableId", "w16cex:durableId")
repairs = 0
renames: dict = {}
for xml_file in self.xml_files:
try:
content = xml_file.read_text(encoding="utf-8")
dom = defusedxml.minidom.parseString(content)
is_numbering = xml_file.name == "numbering.xml"
base = 10 if is_numbering else 16
pending = []
seen_in_file = set()
modified = False
for elem in dom.getElementsByTagName("*"):
for attr_name in DURABLE_ID_ATTRS:
if not elem.hasAttribute(attr_name):
continue
durable_id = elem.getAttribute(attr_name)
try:
key = self._parse_id_value(durable_id, base=base)
needs_repair = key >= 0x7FFFFFFF
except ValueError:
key = durable_id
needs_repair = True
if needs_repair:
if key in seen_in_file:
value = random.randint(1, 0x7FFFFFFE)
else:
seen_in_file.add(key)
if key not in renames:
renames[key] = random.randint(1, 0x7FFFFFFE)
value = renames[key]
new_id = str(value) if is_numbering else f"{value:08X}"
elem.setAttribute(attr_name, new_id)
pending.append(
f" Repaired: {xml_file.name}: durableId {durable_id} → {new_id}"
)
modified = True
if modified:
xml_file.write_bytes(dom.toxml(encoding="UTF-8"))
for message in pending:
print(message)
repairs += len(pending)
except Exception:
pass
return repairs
if __name__ == "__main__":
raise RuntimeError("This module should not be run directly.")
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/validation/pptx.py → plugins/codex/plugins/docx/skills/docx/scripts/office/validators/pptx.py
+175 -49
View File
@@ -3,19 +3,19 @@ Validator for PowerPoint presentation XML files against XSD schemas.
"""
import re
from pathlib import Path
from helpers import opc_target, rels_source_part, safe_extract
from .base import BaseSchemaValidator
class PPTXSchemaValidator(BaseSchemaValidator):
"""Validator for PowerPoint presentation XML files against XSD schemas."""
# PowerPoint presentation namespace
PRESENTATIONML_NAMESPACE = (
"http://schemas.openxmlformats.org/presentationml/2006/main"
)
# PowerPoint-specific element to relationship type mappings
ELEMENT_RELATIONSHIP_TYPES = {
"sldid": "slide",
"sldmasterid": "slidemaster",
@@ -26,60 +26,209 @@ class PPTXSchemaValidator(BaseSchemaValidator):
}
def validate(self):
"""Run all validation checks and return True if all pass."""
# Test 0: XML well-formedness
if not self.validate_xml():
return False
# Test 1: Namespace declarations
all_valid = True
if not self.validate_namespaces():
all_valid = False
# Test 2: Unique IDs
if not self.validate_unique_ids():
all_valid = False
# Test 3: UUID ID validation
if not self.validate_uuid_ids():
all_valid = False
# Test 4: Relationship and file reference validation
if not self.validate_file_references():
all_valid = False
# Test 5: Slide layout ID validation
if not self.validate_slide_layout_ids():
all_valid = False
# Test 6: Content type declarations
if not self.validate_content_types():
all_valid = False
# Test 7: XSD schema validation
if not self.validate_against_xsd():
all_valid = False
# Test 8: Notes slide reference validation
if not self.validate_notes_slide_references():
all_valid = False
# Test 9: Relationship ID reference validation
if not self.validate_all_relationship_ids():
all_valid = False
# Test 10: Duplicate slide layout references validation
if not self.validate_no_duplicate_slide_layouts():
all_valid = False
if not self.validate_master_theme_uniqueness():
all_valid = False
if not self.validate_charts():
all_valid = False
if not self.validate_slides():
all_valid = False
return all_valid
def _package_map(self) -> dict:
wanted = []
wanted += list(self.unpacked_dir.glob("[[]Content_Types[]].xml"))
wanted += list(self.unpacked_dir.glob("ppt/presentation.xml"))
wanted += list(self.unpacked_dir.glob("ppt/theme/*.xml"))
wanted += list(self.unpacked_dir.glob("ppt/theme/_rels/*.rels"))
wanted += list(self.unpacked_dir.glob("ppt/charts/chart*.xml"))
for group in ("slideMasters", "notesMasters", "handoutMasters"):
wanted += list(self.unpacked_dir.glob(f"ppt/{group}/*.xml"))
wanted += list(self.unpacked_dir.glob(f"ppt/{group}/_rels/*.rels"))
return {
p.relative_to(self.unpacked_dir).as_posix(): p.read_bytes()
for p in wanted
if p.is_file()
}
def validate_master_theme_uniqueness(self):
from helpers.pptx_theme import _NOTES_MASTERS, live_shared_master_themes
shared = live_shared_master_themes(self._package_map())
if shared:
print(f"FAILED - Found {len(shared)} master(s) sharing a theme part:")
for message in shared:
print(f" {message}")
if any(m.startswith(_NOTES_MASTERS) for m in shared):
print(" Fix: in ppt/presentation.xml, move <p:notesMasterIdLst> back to "
"directly after <p:sldIdLst>. PowerPoint reads that happily.")
else:
print(" Fix: give each master its own theme part.")
return False
if self.verbose:
print("PASSED - No master shares a theme part in a way PowerPoint refuses")
return True
def validate_charts(self):
from helpers.pptx_chart import find_chart_problems
problems = find_chart_problems(self._package_map())
if problems:
print(f"FAILED - Found {len(problems)} chart problem(s) PowerPoint rejects:")
for message in problems:
print(f" {message}")
return False
if self.verbose:
print("PASSED - Charts satisfy the constraints PowerPoint enforces")
return True
def _original_slide_defects(self, schema) -> set[str]:
import tempfile
import zipfile
from helpers.pptx_slide import SLIDE_PART_RE, fatal_slide_errors
if self.original_file is None:
return set()
found: set[str] = set()
with tempfile.TemporaryDirectory() as temp_dir:
temp_path = Path(temp_dir)
try:
with zipfile.ZipFile(self.original_file, "r") as zf:
safe_extract(zf, temp_path)
except (zipfile.BadZipFile, ValueError, OSError):
return set()
for part in sorted(temp_path.rglob("*.xml")):
relative = part.relative_to(temp_path).as_posix()
if not SLIDE_PART_RE.fullmatch(relative):
continue
ok, errors = self._validate_single_file_xsd(
part.resolve(), temp_path.resolve(), schema_path=schema
)
if ok is None or ok or not errors:
continue
found |= set(fatal_slide_errors(set(errors)))
return found
def validate_slides(self):
from helpers.pptx_slide import (
SLIDE_PART_RE,
fatal_slide_errors,
is_schema_verdict,
)
schema = self.schemas_dir / self.SCHEMA_MAPPINGS["ppt"]
inherited = self._original_slide_defects(schema)
problems: list[str] = []
broken: list[str] = []
for xml_file in self.xml_files:
relative = xml_file.relative_to(self.unpacked_dir).as_posix()
if not SLIDE_PART_RE.fullmatch(relative):
continue
ok, errors = self._validate_single_file_xsd(
xml_file.resolve(), self.unpacked_dir.resolve(), schema_path=schema
)
if ok is None or not errors:
continue
unreadable = [f"{relative}: {e}" for e in errors if not is_schema_verdict(e)]
if unreadable:
broken.extend(unreadable)
continue
if ok:
continue
for message in fatal_slide_errors(set(errors)):
if message in inherited:
continue
problems.append(f"{relative}: {message}")
if broken:
print(f"FAILED - Could not check {len(broken)} slide part(s):")
for message in sorted(broken):
print(f" {message[:240]}")
if problems:
print(f"FAILED - Found {len(problems)} slide problem(s) PowerPoint rejects:")
for message in sorted(problems):
print(f" {message[:240]}")
if broken or problems:
return False
if self.verbose:
print("PASSED - Slide XML has none of the defects PowerPoint refuses")
return True
def _get_schema_path(self, xml_file):
if xml_file.parent.name == "charts" and xml_file.name.startswith("chart"):
return None
return super()._get_schema_path(xml_file)
def _preprocess_for_schema(self, xml_doc, relative_path):
if relative_path.as_posix() != "ppt/presentation.xml":
return xml_doc
root = xml_doc.getroot()
ns = f"{{{self.PRESENTATIONML_NAMESPACE}}}"
notes = root.find(f"{ns}notesMasterIdLst")
slides = root.find(f"{ns}sldIdLst")
if notes is None or slides is None:
return xml_doc
children = list(root)
if children.index(notes) < children.index(slides):
return xml_doc
root.remove(notes)
root.insert(list(root).index(slides), notes)
return xml_doc
def validate_uuid_ids(self):
"""Validate that ID attributes that look like UUIDs contain only hex values."""
import lxml.etree
errors = []
# UUID pattern: 8-4-4-4-12 hex digits with optional braces/hyphens
uuid_pattern = re.compile(
r"^[\{\(]?[0-9A-Fa-f]{8}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{4}-?[0-9A-Fa-f]{12}[\}\)]?$"
)
@@ -88,15 +237,11 @@ class PPTXSchemaValidator(BaseSchemaValidator):
try:
root = lxml.etree.parse(str(xml_file)).getroot()
# Check all elements for ID attributes
for elem in root.iter():
for attr, value in elem.attrib.items():
# Check if this is an ID attribute
attr_name = attr.split("}")[-1].lower()
if attr_name == "id" or attr_name.endswith("id"):
# Check if value looks like a UUID (has the right length and pattern structure)
if self._looks_like_uuid(value):
# Validate that it contains only hex characters in the right positions
if not uuid_pattern.match(value):
errors.append(
f" {xml_file.relative_to(self.unpacked_dir)}: "
@@ -119,19 +264,14 @@ class PPTXSchemaValidator(BaseSchemaValidator):
return True
def _looks_like_uuid(self, value):
"""Check if a value has the general structure of a UUID."""
# Remove common UUID delimiters
clean_value = value.strip("{}()").replace("-", "")
# Check if it's 32 hex-like characters (could include invalid hex chars)
return len(clean_value) == 32 and all(c.isalnum() for c in clean_value)
def validate_slide_layout_ids(self):
"""Validate that sldLayoutId elements in slide masters reference valid slide layouts."""
import lxml.etree
errors = []
# Find all slide master files
slide_masters = list(self.unpacked_dir.glob("ppt/slideMasters/*.xml"))
if not slide_masters:
@@ -141,10 +281,8 @@ class PPTXSchemaValidator(BaseSchemaValidator):
for slide_master in slide_masters:
try:
# Parse the slide master file
root = lxml.etree.parse(str(slide_master)).getroot()
# Find the corresponding _rels file for this slide master
rels_file = slide_master.parent / "_rels" / f"{slide_master.name}.rels"
if not rels_file.exists():
@@ -154,10 +292,8 @@ class PPTXSchemaValidator(BaseSchemaValidator):
)
continue
# Parse the relationships file
rels_root = lxml.etree.parse(str(rels_file)).getroot()
# Build a set of valid relationship IDs that point to slide layouts
valid_layout_rids = set()
for rel in rels_root.findall(
f".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship"
@@ -166,7 +302,6 @@ class PPTXSchemaValidator(BaseSchemaValidator):
if "slideLayout" in rel_type:
valid_layout_rids.add(rel.get("Id"))
# Find all sldLayoutId elements in the slide master
for sld_layout_id in root.findall(
f".//{{{self.PRESENTATIONML_NAMESPACE}}}sldLayoutId"
):
@@ -201,7 +336,6 @@ class PPTXSchemaValidator(BaseSchemaValidator):
return True
def validate_no_duplicate_slide_layouts(self):
"""Validate that each slide has exactly one slideLayout reference."""
import lxml.etree
errors = []
@@ -211,7 +345,6 @@ class PPTXSchemaValidator(BaseSchemaValidator):
try:
root = lxml.etree.parse(str(rels_file)).getroot()
# Find all slideLayout relationships
layout_rels = [
rel
for rel in root.findall(
@@ -241,13 +374,11 @@ class PPTXSchemaValidator(BaseSchemaValidator):
return True
def validate_notes_slide_references(self):
"""Validate that each notesSlide file is referenced by only one slide."""
import lxml.etree
errors = []
notes_slide_references = {} # Track which slides reference each notesSlide
notes_slide_references = {}
# Find all slide relationship files
slide_rels_files = list(self.unpacked_dir.glob("ppt/slides/_rels/*.xml.rels"))
if not slide_rels_files:
@@ -257,28 +388,24 @@ class PPTXSchemaValidator(BaseSchemaValidator):
for rels_file in slide_rels_files:
try:
# Parse the relationships file
root = lxml.etree.parse(str(rels_file)).getroot()
# Find all notesSlide relationships
for rel in root.findall(
f".//{{{self.PACKAGE_RELATIONSHIPS_NAMESPACE}}}Relationship"
):
rel_type = rel.get("Type", "")
if "notesSlide" in rel_type:
target = rel.get("Target", "")
if target:
# Normalize the target path to handle relative paths
normalized_target = target.replace("../", "")
# Track which slide references this notesSlide
part = opc_target(
rel.get("Target", ""),
rels_source_part(rels_file, self.unpacked_dir),
rel.get("TargetMode", ""),
)
if part:
slide_name = rels_file.stem.replace(
".xml", ""
) # e.g., "slide1"
)
if normalized_target not in notes_slide_references:
notes_slide_references[normalized_target] = []
notes_slide_references[normalized_target].append(
notes_slide_references.setdefault(part, []).append(
(slide_name, rels_file)
)
@@ -287,7 +414,6 @@ class PPTXSchemaValidator(BaseSchemaValidator):
f" {rels_file.relative_to(self.unpacked_dir)}: Error: {e}"
)
# Check for duplicate references
for target, references in notes_slide_references.items():
if len(references) > 1:
slide_names = [ref[0] for ref in references]
plugins/codex/plugins/docx/skills/docx/ooxml/scripts/validation/redlining.py → plugins/codex/plugins/docx/skills/docx/scripts/office/validators/redlining.py
+101 -81
View File
@@ -1,5 +1,14 @@
"""
Validator for tracked changes in Word documents.
Detects untracked edits in word/document.xml: text that differs from the
original without a <w:ins>/<w:del> wrapper recording it. The tracked changes
that are new relative to the original are undone, and the result is compared
against the original; whatever text still differs was edited without being
tracked.
Only the document body is compared. Headers, footers, footnotes and endnotes
are separate parts and are not checked.
"""
import subprocess
@@ -7,9 +16,13 @@ import tempfile
import zipfile
from pathlib import Path
import defusedxml.ElementTree as ET
from defusedxml.common import DefusedXmlException
from helpers import rendered_text, safe_extract
class RedliningValidator:
"""Validator for tracked changes in Word documents."""
def __init__(self, unpacked_dir, original_docx, verbose=False):
self.unpacked_dir = Path(unpacked_dir)
@@ -19,55 +32,21 @@ class RedliningValidator:
"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
}
def repair(self) -> int:
return 0
def validate(self):
"""Main validation method that returns True if valid, False otherwise."""
# Verify unpacked directory exists and has correct structure
modified_file = self.unpacked_dir / "word" / "document.xml"
if not modified_file.exists():
print(f"FAILED - Modified document.xml not found at {modified_file}")
return False
# First, check if there are any tracked changes by Claude to validate
try:
import xml.etree.ElementTree as ET
tree = ET.parse(modified_file)
root = tree.getroot()
# Check for w:del or w:ins tags authored by Claude
del_elements = root.findall(".//w:del", self.namespaces)
ins_elements = root.findall(".//w:ins", self.namespaces)
# Filter to only include changes by Claude
claude_del_elements = [
elem
for elem in del_elements
if elem.get(f"{{{self.namespaces['w']}}}author") == "Claude"
]
claude_ins_elements = [
elem
for elem in ins_elements
if elem.get(f"{{{self.namespaces['w']}}}author") == "Claude"
]
# Redlining validation is only needed if tracked changes by Claude have been used.
if not claude_del_elements and not claude_ins_elements:
if self.verbose:
print("PASSED - No tracked changes by Claude found.")
return True
except Exception:
# If we can't parse the XML, continue with full validation
pass
# Create temporary directory for unpacking original docx
with tempfile.TemporaryDirectory() as temp_dir:
temp_path = Path(temp_dir)
# Unpack original docx
try:
with zipfile.ZipFile(self.original_docx, "r") as zip_ref:
zip_ref.extractall(temp_path)
safe_extract(zip_ref, temp_path)
except Exception as e:
print(f"FAILED - Error unpacking original docx: {e}")
return False
@@ -79,28 +58,22 @@ class RedliningValidator:
)
return False
# Parse both XML files using xml.etree.ElementTree for redlining validation
try:
import xml.etree.ElementTree as ET
modified_tree = ET.parse(modified_file)
modified_root = modified_tree.getroot()
original_tree = ET.parse(original_file)
original_root = original_tree.getroot()
except ET.ParseError as e:
except (ET.ParseError, DefusedXmlException) as e:
print(f"FAILED - Error parsing XML files: {e}")
return False
# Remove Claude's tracked changes from both documents
self._remove_claude_tracked_changes(original_root)
self._remove_claude_tracked_changes(modified_root)
new_changes = self._new_tracked_changes(original_root, modified_root)
self._remove_tracked_changes(modified_root, new_changes)
# Extract and compare text content
modified_text = self._extract_text_content(modified_root)
original_text = self._extract_text_content(original_root)
if modified_text != original_text:
# Show detailed character-level differences for each paragraph
error_message = self._generate_detailed_diff(
original_text, modified_text
)
@@ -108,26 +81,95 @@ class RedliningValidator:
return False
if self.verbose:
print("PASSED - All changes by Claude are properly tracked")
print(
f"PASSED - All {len(new_changes)} change(s) against the original "
"are properly tracked"
)
return True
def _tracked_change_elements(self, root):
ins_tag = f"{{{self.namespaces['w']}}}ins"
del_tag = f"{{{self.namespaces['w']}}}del"
return [elem for elem in root.iter() if elem.tag in (ins_tag, del_tag)]
def _rendered_text(self, elem):
preserve = elem.get("{http://www.w3.org/XML/1998/namespace}space") == "preserve"
return rendered_text(elem.text or "", preserve)
def _text_elements(self, elem):
w = self.namespaces["w"]
return [
node
for node in elem.iter()
if node.tag in (f"{{{w}}}t", f"{{{w}}}delText")
]
def _tracked_change_key(self, elem):
w = self.namespaces["w"]
text = "".join(self._rendered_text(node) for node in self._text_elements(elem))
return (elem.tag, elem.get(f"{{{w}}}author"), elem.get(f"{{{w}}}date"), text)
def _new_tracked_changes(self, original_root, modified_root):
original = self._tracked_change_elements(original_root)
modified = self._tracked_change_elements(modified_root)
pool = {}
for elem in original:
pool.setdefault(self._tracked_change_key(elem), []).append(elem)
matched, leftover = set(), []
for elem in modified:
bucket = pool.get(self._tracked_change_key(elem))
if bucket:
matched.add(bucket.pop())
else:
leftover.append(elem)
def group(elem):
return self._tracked_change_key(elem)[:3]
def text_of(elems):
return "".join(self._tracked_change_key(e)[3] for e in elems)
unmatched_original = {}
for elem in original:
if elem not in matched:
unmatched_original.setdefault(group(elem), []).append(elem)
by_group = {}
for elem in leftover:
by_group.setdefault(group(elem), []).append(elem)
new = set()
for key, elems in by_group.items():
rebuilt = text_of(elems)
if rebuilt and rebuilt == text_of(unmatched_original.get(key, [])):
continue
new.update(elems)
return new
def _generate_detailed_diff(self, original_text, modified_text):
"""Generate detailed word-level differences using git word diff."""
error_parts = [
"FAILED - Document text doesn't match after removing Claude's tracked changes",
"FAILED - Document text doesn't match after removing the tracked changes",
"",
"Likely causes:",
" 1. Modified text inside another author's <w:ins> or <w:del> tags",
" 2. Made edits without proper tracked changes",
" 3. Didn't nest <w:del> inside <w:ins> when deleting another's insertion",
" 4. Rewrote another author's <w:ins>/<w:del> and changed its text on",
" the way. A tracked change from the original is recognised by its",
" author, date and text; anything that doesn't reproduce one exactly",
" reads as new, and the text it carried is reported missing.",
"",
"For pre-redlined documents, use correct patterns:",
" - To reject another's INSERTION: Nest <w:del> inside their <w:ins>",
" - To reject PART of one: nest <w:del> around only the runs you reject.",
" Their <w:ins> may be split around it, so long as the pieces keep",
" their author and date and still spell out the same text.",
" - To restore another's DELETION: Add new <w:ins> AFTER their <w:del>",
"",
]
# Show git word diff
git_diff = self._get_git_word_diff(original_text, modified_text)
if git_diff:
error_parts.extend(["Differences:", "============", git_diff])
@@ -137,26 +179,23 @@ class RedliningValidator:
return "\n".join(error_parts)
def _get_git_word_diff(self, original_text, modified_text):
"""Generate word diff using git with character-level precision."""
try:
with tempfile.TemporaryDirectory() as temp_dir:
temp_path = Path(temp_dir)
# Create two files
original_file = temp_path / "original.txt"
modified_file = temp_path / "modified.txt"
original_file.write_text(original_text, encoding="utf-8")
modified_file.write_text(modified_text, encoding="utf-8")
# Try character-level diff first for precise differences
result = subprocess.run(
[
"git",
"diff",
"--word-diff=plain",
"--word-diff-regex=.", # Character-by-character diff
"-U0", # Zero lines of context - show only changed lines
"--word-diff-regex=.",
"-U0",
"--no-index",
str(original_file),
str(modified_file),
@@ -166,9 +205,7 @@ class RedliningValidator:
)
if result.stdout.strip():
# Clean up the output - remove git diff header lines
lines = result.stdout.split("\n")
# Skip the header lines (diff --git, index, +++, ---, @@)
content_lines = []
in_content = False
for line in lines:
@@ -181,13 +218,12 @@ class RedliningValidator:
if content_lines:
return "\n".join(content_lines)
# Fallback to word-level diff if character-level is too verbose
result = subprocess.run(
[
"git",
"diff",
"--word-diff=plain",
"-U0", # Zero lines of context
"-U0",
"--no-index",
str(original_file),
str(modified_file),
@@ -209,66 +245,50 @@ class RedliningValidator:
return "\n".join(content_lines)
except (subprocess.CalledProcessError, FileNotFoundError, Exception):
# Git not available or other error, return None to use fallback
pass
return None
def _remove_claude_tracked_changes(self, root):
"""Remove tracked changes authored by Claude from the XML root."""
def _remove_tracked_changes(self, root, targets):
ins_tag = f"{{{self.namespaces['w']}}}ins"
del_tag = f"{{{self.namespaces['w']}}}del"
author_attr = f"{{{self.namespaces['w']}}}author"
# Remove w:ins elements
for parent in root.iter():
to_remove = []
for child in parent:
if child.tag == ins_tag and child.get(author_attr) == "Claude":
if child.tag == ins_tag and child in targets:
to_remove.append(child)
for elem in to_remove:
parent.remove(elem)
# Unwrap content in w:del elements where author is "Claude"
deltext_tag = f"{{{self.namespaces['w']}}}delText"
t_tag = f"{{{self.namespaces['w']}}}t"
for parent in root.iter():
to_process = []
for child in parent:
if child.tag == del_tag and child.get(author_attr) == "Claude":
if child.tag == del_tag and child in targets:
to_process.append((child, list(parent).index(child)))
# Process in reverse order to maintain indices
for del_elem, del_index in reversed(to_process):
# Convert w:delText to w:t before moving
for elem in del_elem.iter():
if elem.tag == deltext_tag:
elem.tag = t_tag
# Move all children of w:del to its parent before removing w:del
for child in reversed(list(del_elem)):
parent.insert(del_index, child)
parent.remove(del_elem)
def _extract_text_content(self, root):
"""Extract text content from Word XML, preserving paragraph structure.
Empty paragraphs are skipped to avoid false positives when tracked
insertions add only structural elements without text content.
"""
p_tag = f"{{{self.namespaces['w']}}}p"
t_tag = f"{{{self.namespaces['w']}}}t"
paragraphs = []
for p_elem in root.findall(f".//{p_tag}"):
# Get all text elements within this paragraph
text_parts = []
for t_elem in p_elem.findall(f".//{t_tag}"):
if t_elem.text:
text_parts.append(t_elem.text)
text_parts.append(self._rendered_text(t_elem))
paragraph_text = "".join(text_parts)
# Skip empty paragraphs - they don't affect content validation
if paragraph_text:
paragraphs.append(paragraph_text)
plugins/codex/plugins/docx/skills/docx/scripts/office_package.py
+52
View File
@@ -0,0 +1,52 @@
"""Unpack or repack an OOXML document without shell-specific ZIP commands."""
import argparse
import os
import tempfile
import zipfile
from pathlib import Path, PurePosixPath
def unpack(source, destination):
root = Path(destination).resolve()
if root.exists() and any(root.iterdir()):
raise ValueError("Unpack destination must be empty")
with zipfile.ZipFile(source) as archive:
for info in archive.infolist():
name = PurePosixPath(info.filename.replace("\\", "/"))
if name.is_absolute() or ".." in name.parts or any(":" in part for part in name.parts):
raise ValueError(f"Unsafe ZIP entry: {info.filename}")
if (info.external_attr >> 16) & 0o170000 == 0o120000:
raise ValueError(f"ZIP symlink is not supported: {info.filename}")
archive.extractall(root)
def pack(source, destination):
root = Path(source).resolve()
output = Path(destination).resolve()
if output.is_relative_to(root):
raise ValueError("Output must be outside the unpacked directory")
if not (root / "[Content_Types].xml").is_file():
raise ValueError("Source must be the package root containing [Content_Types].xml")
output.parent.mkdir(parents=True, exist_ok=True)
fd, temporary = tempfile.mkstemp(suffix=output.suffix, dir=output.parent)
os.close(fd)
try:
with zipfile.ZipFile(temporary, "w", zipfile.ZIP_DEFLATED) as archive:
for file in sorted(root.rglob("*")):
if file.is_symlink():
raise ValueError(f"Package symlink is not supported: {file}")
if file.is_file():
archive.write(file, file.relative_to(root).as_posix())
os.replace(temporary, output)
finally:
Path(temporary).unlink(missing_ok=True)
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("action", choices=("unpack", "pack"))
parser.add_argument("input")
parser.add_argument("output")
args = parser.parse_args()
{"unpack": unpack, "pack": pack}[args.action](args.input, args.output)
plugins/codex/plugins/docx/skills/docx/scripts/render_pdf.py
+29
View File
@@ -0,0 +1,29 @@
"""Render PDF pages without Poppler; requires PyMuPDF."""
import argparse
from pathlib import Path
import pymupdf
def convert(pdf_path, output_dir, max_dim=1600):
if max_dim <= 0:
raise ValueError("max_dim must be positive")
output = Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
with pymupdf.open(pdf_path) as document:
for index, page in enumerate(document):
scale = min(max_dim / page.rect.width, max_dim / page.rect.height)
pixmap = page.get_pixmap(matrix=pymupdf.Matrix(scale, scale), alpha=False)
target = output / f"page_{index + 1}.png"
pixmap.save(str(target))
print(target)
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("input")
parser.add_argument("output")
parser.add_argument("--max-dim", type=int, default=1600)
args = parser.parse_args()
convert(args.input, args.output, args.max_dim)
plugins/codex/plugins/docx/skills/docx/scripts/templates/comments.xml
+2 -2
View File
@@ -1,3 +1,3 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml version="1.0" ?>
<w:comments xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl w16du wp14">
</w:comments>
</w:comments>
plugins/codex/plugins/docx/skills/docx/scripts/templates/commentsExtended.xml
+2 -2
View File
@@ -1,3 +1,3 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml version="1.0" ?>
<w15:commentsEx xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl w16du wp14">
</w15:commentsEx>
</w15:commentsEx>
plugins/codex/plugins/docx/skills/docx/scripts/templates/commentsExtensible.xml
+2 -2
View File
@@ -1,3 +1,3 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml version="1.0" ?>
<w16cex:commentsExtensible xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" xmlns:cr="http://schemas.microsoft.com/office/comments/2020/reactions" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl cr w16du wp14">
</w16cex:commentsExtensible>
</w16cex:commentsExtensible>
plugins/codex/plugins/docx/skills/docx/scripts/templates/commentsIds.xml
+2 -2
View File
@@ -1,3 +1,3 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml version="1.0" ?>
<w16cid:commentsIds xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl w16du wp14">
</w16cid:commentsIds>
</w16cid:commentsIds>
plugins/codex/plugins/docx/skills/docx/scripts/templates/people.xml
+2 -2
View File
@@ -1,3 +1,3 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml version="1.0" ?>
<w15:people xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">
</w15:people>
</w15:people>
plugins/codex/plugins/docx/skills/docx/scripts/utilities.py
-374
View File
@@ -1,374 +0,0 @@
#!/usr/bin/env python3
"""
Utilities for editing OOXML documents.
This module provides XMLEditor, a tool for manipulating XML files with support for
line-number-based node finding and DOM manipulation. Each element is automatically
annotated with its original line and column position during parsing.
Example usage:
editor = XMLEditor("document.xml")
# Find node by line number or range
elem = editor.get_node(tag="w:r", line_number=519)
elem = editor.get_node(tag="w:p", line_number=range(100, 200))
# Find node by text content
elem = editor.get_node(tag="w:p", contains="specific text")
# Find node by attributes
elem = editor.get_node(tag="w:r", attrs={"w:id": "target"})
# Combine filters
elem = editor.get_node(tag="w:p", line_number=range(1, 50), contains="text")
# Replace, insert, or manipulate
new_elem = editor.replace_node(elem, "<w:r><w:t>new text</w:t></w:r>")
editor.insert_after(new_elem, "<w:r><w:t>more</w:t></w:r>")
# Save changes
editor.save()
"""
import html
from pathlib import Path
from typing import Optional, Union
import defusedxml.minidom
import defusedxml.sax
class XMLEditor:
"""
Editor for manipulating OOXML XML files with line-number-based node finding.
This class parses XML files and tracks the original line and column position
of each element. This enables finding nodes by their line number in the original
file, which is useful when working with Read tool output.
Attributes:
xml_path: Path to the XML file being edited
encoding: Detected encoding of the XML file ('ascii' or 'utf-8')
dom: Parsed DOM tree with parse_position attributes on elements
"""
def __init__(self, xml_path):
"""
Initialize with path to XML file and parse with line number tracking.
Args:
xml_path: Path to XML file to edit (str or Path)
Raises:
ValueError: If the XML file does not exist
"""
self.xml_path = Path(xml_path)
if not self.xml_path.exists():
raise ValueError(f"XML file not found: {xml_path}")
with open(self.xml_path, "rb") as f:
header = f.read(200).decode("utf-8", errors="ignore")
self.encoding = "ascii" if 'encoding="ascii"' in header else "utf-8"
parser = _create_line_tracking_parser()
self.dom = defusedxml.minidom.parse(str(self.xml_path), parser)
def get_node(
self,
tag: str,
attrs: Optional[dict[str, str]] = None,
line_number: Optional[Union[int, range]] = None,
contains: Optional[str] = None,
):
"""
Get a DOM element by tag and identifier.
Finds an element by either its line number in the original file or by
matching attribute values. Exactly one match must be found.
Args:
tag: The XML tag name (e.g., "w:del", "w:ins", "w:r")
attrs: Dictionary of attribute name-value pairs to match (e.g., {"w:id": "1"})
line_number: Line number (int) or line range (range) in original XML file (1-indexed)
contains: Text string that must appear in any text node within the element.
Supports both entity notation (&#8220;) and Unicode characters (\u201c).
Returns:
defusedxml.minidom.Element: The matching DOM element
Raises:
ValueError: If node not found or multiple matches found
Example:
elem = editor.get_node(tag="w:r", line_number=519)
elem = editor.get_node(tag="w:r", line_number=range(100, 200))
elem = editor.get_node(tag="w:del", attrs={"w:id": "1"})
elem = editor.get_node(tag="w:p", attrs={"w14:paraId": "12345678"})
elem = editor.get_node(tag="w:commentRangeStart", attrs={"w:id": "0"})
elem = editor.get_node(tag="w:p", contains="specific text")
elem = editor.get_node(tag="w:t", contains="&#8220;Agreement") # Entity notation
elem = editor.get_node(tag="w:t", contains="\u201cAgreement") # Unicode character
"""
matches = []
for elem in self.dom.getElementsByTagName(tag):
# Check line_number filter
if line_number is not None:
parse_pos = getattr(elem, "parse_position", (None,))
elem_line = parse_pos[0]
# Handle both single line number and range
if isinstance(line_number, range):
if elem_line not in line_number:
continue
else:
if elem_line != line_number:
continue
# Check attrs filter
if attrs is not None:
if not all(
elem.getAttribute(attr_name) == attr_value
for attr_name, attr_value in attrs.items()
):
continue
# Check contains filter
if contains is not None:
elem_text = self._get_element_text(elem)
# Normalize the search string: convert HTML entities to Unicode characters
# This allows searching for both "&#8220;Rowan" and ""Rowan"
normalized_contains = html.unescape(contains)
if normalized_contains not in elem_text:
continue
# If all applicable filters passed, this is a match
matches.append(elem)
if not matches:
# Build descriptive error message
filters = []
if line_number is not None:
line_str = (
f"lines {line_number.start}-{line_number.stop - 1}"
if isinstance(line_number, range)
else f"line {line_number}"
)
filters.append(f"at {line_str}")
if attrs is not None:
filters.append(f"with attributes {attrs}")
if contains is not None:
filters.append(f"containing '{contains}'")
filter_desc = " ".join(filters) if filters else ""
base_msg = f"Node not found: <{tag}> {filter_desc}".strip()
# Add helpful hint based on filters used
if contains:
hint = "Text may be split across elements or use different wording."
elif line_number:
hint = "Line numbers may have changed if document was modified."
elif attrs:
hint = "Verify attribute values are correct."
else:
hint = "Try adding filters (attrs, line_number, or contains)."
raise ValueError(f"{base_msg}. {hint}")
if len(matches) > 1:
raise ValueError(
f"Multiple nodes found: <{tag}>. "
f"Add more filters (attrs, line_number, or contains) to narrow the search."
)
return matches[0]
def _get_element_text(self, elem):
"""
Recursively extract all text content from an element.
Skips text nodes that contain only whitespace (spaces, tabs, newlines),
which typically represent XML formatting rather than document content.
Args:
elem: defusedxml.minidom.Element to extract text from
Returns:
str: Concatenated text from all non-whitespace text nodes within the element
"""
text_parts = []
for node in elem.childNodes:
if node.nodeType == node.TEXT_NODE:
# Skip whitespace-only text nodes (XML formatting)
if node.data.strip():
text_parts.append(node.data)
elif node.nodeType == node.ELEMENT_NODE:
text_parts.append(self._get_element_text(node))
return "".join(text_parts)
def replace_node(self, elem, new_content):
"""
Replace a DOM element with new XML content.
Args:
elem: defusedxml.minidom.Element to replace
new_content: String containing XML to replace the node with
Returns:
List[defusedxml.minidom.Node]: All inserted nodes
Example:
new_nodes = editor.replace_node(old_elem, "<w:r><w:t>text</w:t></w:r>")
"""
parent = elem.parentNode
nodes = self._parse_fragment(new_content)
for node in nodes:
parent.insertBefore(node, elem)
parent.removeChild(elem)
return nodes
def insert_after(self, elem, xml_content):
"""
Insert XML content after a DOM element.
Args:
elem: defusedxml.minidom.Element to insert after
xml_content: String containing XML to insert
Returns:
List[defusedxml.minidom.Node]: All inserted nodes
Example:
new_nodes = editor.insert_after(elem, "<w:r><w:t>text</w:t></w:r>")
"""
parent = elem.parentNode
next_sibling = elem.nextSibling
nodes = self._parse_fragment(xml_content)
for node in nodes:
if next_sibling:
parent.insertBefore(node, next_sibling)
else:
parent.appendChild(node)
return nodes
def insert_before(self, elem, xml_content):
"""
Insert XML content before a DOM element.
Args:
elem: defusedxml.minidom.Element to insert before
xml_content: String containing XML to insert
Returns:
List[defusedxml.minidom.Node]: All inserted nodes
Example:
new_nodes = editor.insert_before(elem, "<w:r><w:t>text</w:t></w:r>")
"""
parent = elem.parentNode
nodes = self._parse_fragment(xml_content)
for node in nodes:
parent.insertBefore(node, elem)
return nodes
def append_to(self, elem, xml_content):
"""
Append XML content as a child of a DOM element.
Args:
elem: defusedxml.minidom.Element to append to
xml_content: String containing XML to append
Returns:
List[defusedxml.minidom.Node]: All inserted nodes
Example:
new_nodes = editor.append_to(elem, "<w:r><w:t>text</w:t></w:r>")
"""
nodes = self._parse_fragment(xml_content)
for node in nodes:
elem.appendChild(node)
return nodes
def get_next_rid(self):
"""Get the next available rId for relationships files."""
max_id = 0
for rel_elem in self.dom.getElementsByTagName("Relationship"):
rel_id = rel_elem.getAttribute("Id")
if rel_id.startswith("rId"):
try:
max_id = max(max_id, int(rel_id[3:]))
except ValueError:
pass
return f"rId{max_id + 1}"
def save(self):
"""
Save the edited XML back to the file.
Serializes the DOM tree and writes it back to the original file path,
preserving the original encoding (ascii or utf-8).
"""
content = self.dom.toxml(encoding=self.encoding)
self.xml_path.write_bytes(content)
def _parse_fragment(self, xml_content):
"""
Parse XML fragment and return list of imported nodes.
Args:
xml_content: String containing XML fragment
Returns:
List of defusedxml.minidom.Node objects imported into this document
Raises:
AssertionError: If fragment contains no element nodes
"""
# Extract namespace declarations from the root document element
root_elem = self.dom.documentElement
namespaces = []
if root_elem and root_elem.attributes:
for i in range(root_elem.attributes.length):
attr = root_elem.attributes.item(i)
if attr.name.startswith("xmlns"): # type: ignore
namespaces.append(f'{attr.name}="{attr.value}"') # type: ignore
ns_decl = " ".join(namespaces)
wrapper = f"<root {ns_decl}>{xml_content}</root>"
fragment_doc = defusedxml.minidom.parseString(wrapper)
nodes = [
self.dom.importNode(child, deep=True)
for child in fragment_doc.documentElement.childNodes # type: ignore
]
elements = [n for n in nodes if n.nodeType == n.ELEMENT_NODE]
assert elements, "Fragment must contain at least one element"
return nodes
def _create_line_tracking_parser():
"""
Create a SAX parser that tracks line and column numbers for each element.
Monkey patches the SAX content handler to store the current line and column
position from the underlying expat parser onto each element as a parse_position
attribute (line, column) tuple.
Returns:
defusedxml.sax.xmlreader.XMLReader: Configured SAX parser
"""
def set_content_handler(dom_handler):
def startElementNS(name, tagName, attrs):
orig_start_cb(name, tagName, attrs)
cur_elem = dom_handler.elementStack[-1]
cur_elem.parse_position = (
parser._parser.CurrentLineNumber, # type: ignore
parser._parser.CurrentColumnNumber, # type: ignore
)
orig_start_cb = dom_handler.startElementNS
dom_handler.startElementNS = startElementNS
orig_set_content_handler(dom_handler)
parser = defusedxml.sax.make_parser()
orig_set_content_handler = parser.setContentHandler
parser.setContentHandler = set_content_handler # type: ignore
return parser
plugins/codex/plugins/docx/skills/docx/upstream-guide.md
+91
View File
@@ -0,0 +1,91 @@
---
name: docx
description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
license: Proprietary. LICENSE.txt has complete terms
---
# DOCX creation, editing, and analysis
A `.docx` is a ZIP archive of XML files. Choose your approach by task:
| Task | Approach |
|---|---|
| **Create** a new document | Write a `docx` (npm) script — see gotchas below |
| **Edit** an existing document | `unzip` → edit `word/document.xml` → `zip` (docx-js cannot open existing files) |
| **Read** content | `pandoc -t markdown file.docx` |
> Script paths below are relative to this skill's directory.
## Creating with docx-js — gotchas
`docx` is preinstalled — do not run `npm install` first; write the script and `require('docx')` directly. Only if that require fails: `npm install docx`. The model knows the API; these are the footguns:
- **Page size defaults to A4.** For US Letter set `page: { size: { width: 12240, height: 15840 } }` (DXA; 1440 = 1″).
- **Landscape:** pass portrait dimensions and `orientation: PageOrientation.LANDSCAPE` — docx-js swaps width/height internally.
- **Tables need dual widths:** set `columnWidths` on the table AND `width` on every cell, both in `WidthType.DXA` (PERCENTAGE breaks in Google Docs). Column widths must sum to the table width.
- **Table shading:** use `ShadingType.CLEAR`, never `SOLID` (renders black).
- **Lists:** never insert `•` literally; use a `numbering` config with `LevelFormat.BULLET`.
- **`ImageRun` requires `type:`** (`"png"`, `"jpg"`, …).
- **`PageBreak` must be inside a `Paragraph`.**
- **Never use `\n`** — use separate `Paragraph` elements.
- **TOC:** headings must use built-in `HeadingLevel.*`; custom heading styles need `outlineLevel` set or they won't appear.
- **Don't use a table as a horizontal rule** — use a paragraph bottom border instead.
- **Dot-leader / right-aligned-on-same-line:** use `PositionalTab` (`alignment: PositionalTabAlignment.RIGHT`, `leader: PositionalTabLeader.DOT`) inside a `TextRun`, not literal `.` or space padding.
## Verify the output
After writing a `.docx`, render it and look at it:
```bash
python scripts/office/soffice.py --headless --convert-to pdf output.docx
pdftoppm -jpeg -r 100 output.pdf page
ls page-*.jpg # then Read the images
```
`pdftoppm` zero-pads page numbers to the width of the page count (`page-01.jpg`…`page-12.jpg`).
## Editing existing documents
Legacy `.doc` files must be converted first: `python scripts/office/soffice.py --headless --convert-to docx file.doc`.
```bash
unzip -q doc.docx -d unpacked/
find unpacked -type l -delete # strip symlink entries — docx from external parties is untrusted
python scripts/merge_runs.py unpacked/ # coalesce fragmented runs so text is findable
# edit unpacked/word/document.xml in place — do NOT reformat or pretty-print
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx # XSD checks; --auto-repair fixes common issues
# redlining? add --author "<the name you redlined under>" to check every edit is tracked
```
Word splits text across many `<w:r>` runs (revision ids, spell-check markers), so a phrase you can see in the document often doesn't exist as a contiguous string in the XML. `merge_runs.py` merges adjacent identically-formatted runs in `word/document.xml` without changing content or rendering; it also accepts a `.docx` directly (`python scripts/merge_runs.py doc.docx -o merged.docx`).
**Tracked changes:** when redlining, validate with `--author "<the name you redlined under>"` (needs `--original`) — it reports any text you changed without a `<w:ins>`/`<w:del>` around it, which is easy to do by accident and invisible in the accepted view. Wrap runs in `<w:ins>`/`<w:del>` with `w:id`, `w:author`, `w:date` attributes. Inside `<w:del>`, the text element is `<w:delText>`, not `<w:t>`. A deleted paragraph mark (`<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>`) means "merge this paragraph into the next" — so deleting a paragraph outright is that plus a `<w:del>` around every run. The `<w:del/>` must come before the rPr's other children; their order is schema-enforced.
To produce a clean copy with all tracked changes accepted: `python scripts/accept_changes.py in.docx out.docx`.
Accepting a deleted paragraph mark should join that paragraph to the one below it, so a paragraph whose runs are *all* deleted vanishes. Word does this; `accept_changes.py` and `pandoc --track-changes=accept` don't always. Both fail the same way — they strip the deleted text but leave the emptied paragraph behind, which reads as a stray empty bullet when it was auto-numbered:
- `pandoc --track-changes=accept` never joins the paragraphs.
- `accept_changes.py` (LibreOffice) joins them correctly, except when the deleted paragraph is followed by an empty spacer paragraph.
An empty bullet in either view is an artifact of that view, not a defect in the document. Check paragraph deletions in the XML.
## Comments
Comments require six cross-linked files. Use the helper — directory mode when you'll also be editing `document.xml` (saves an unzip/rezip cycle), `.docx`-direct mode otherwise:
```bash
# Against an already-unpacked directory (preferred when also placing markers)
python scripts/comment.py unpacked/ "Fees & expenses cap is too low"
python scripts/comment.py unpacked/ "Agreed" --parent 0
# Against a .docx directly
python scripts/comment.py contract.docx "This cap is too low" -o annotated.docx
```
The script writes `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, `commentsExtensible.xml`, the relationships, and the content-type overrides. Comment IDs are auto-assigned. It then prints the `<w:commentRangeStart>`/`<w:commentRangeEnd>`/`<w:commentReference>` snippet to add to `word/document.xml` so the comment anchors to specific text — until you place those markers, the comment exists but is not visible.
## Dependencies
`docx` (npm, preinstalled — install only if `require('docx')` fails) · `pandoc` · LibreOffice (`soffice`) · `pdftoppm` (Poppler)
plugins/codex/plugins/eapil-gpt2-image/.codex-plugin/plugin.json
+6 -6
View File
@@ -1,13 +1,13 @@
{
"name": "eapil-gpt2-image",
"version": "2.0.0",
"description": "通过 公司提供的 OpenAI 兼容的图像 API 生成或编辑图像时使用，这包括针对 gpt-image-2、/v1/images/generations、/v1/images/edits 的请求，以及使用 Python 图像 API 进行的相关操作，还包括图像提示、掩码的处理、多部分图像的上传、图像文件的保存，以及解码 b64_json 格式的图像响应等内容。",
"version": "1.0.0",
"description": "通过 EAPIL 图像 API 生成、编辑图像或完善提示词，保留精确文字、参考图角色和用户设计意图。",
"author": {
"name": "EAPIL",
"url": "https://git.playones.com/arechen/EapilSkillMarket"
},
"homepage": "https://git.playones.com/arechen/EapilSkillMarket",
"repository": "https://git.playones.com/arechen/EapilSkillMarket",
"homepage": "https://git.playones.com/chenmingxuan/ManySkills/src/branch/main/plugins/eapil-gpt2-image",
"repository": "https://git.playones.com/chenmingxuan/ManySkills",
"license": "Proprietary",
"keywords": [
"eapil",
@@ -17,8 +17,8 @@
"skills": "./skills/",
"interface": {
"displayName": "eapil-gpt2-image",
"shortDescription": "通过 公司提供的 OpenAI 兼容的图像 API 生成或编辑图像时使用，这包括针对 gpt-image-2、/v1/images/generations、/v1/images/edits 的请求，以及使用 Python 图像 API 进行的相关操作，还包括图像提示、掩码的处理、多部分图像的上传、图像文件的保存，以及解码 b64_json 格式的图像响应等内容。",
"longDescription": "通过 公司提供的 OpenAI 兼容的图像 API 生成或编辑图像时使用，这包括针对 gpt-image-2、/v1/images/generations、/v1/images/edits 的请求，以及使用 Python 图像 API 进行的相关操作，还包括图像提示、掩码的处理、多部分图像的上传、图像文件的保存，以及解码 b64_json 格式的图像响应等内容。",
"shortDescription": "按需完善提示词，生成或编辑图像，并检查实际输出。",
"longDescription": "使用 EAPIL 的 gpt-image-2 调用别名完成图像生成和参考图编辑；按需补足提示词，协调实际画幅，保留文字与编辑约束，并保存和检查返回图像。",
"developerName": "EAPIL",
"category": "Creativity",
"capabilities": [
plugins/codex/plugins/eapil-gpt2-image/THIRD_PARTY_SOURCE.json
+9
View File
@@ -0,0 +1,9 @@
{
"sourceId": "eapil-gpt2-image",
"repo": "https://git.playones.com/chenmingxuan/ManySkills.git",
"ref": "v1.0.0",
"commit": "e869eb169eeb5a7cd9e58c0e514fa2dbbf50987d",
"adapter": "codex-plugin",
"sourcePath": "plugins/eapil-gpt2-image",
"syncedAt": "2026-10-06T07:26:41Z"
}
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/SKILL.md
+17 -199
View File
@@ -1,216 +1,34 @@
---
name: eapil-gpt2-image
description: Use when generating or editing images through the EAPIL/Playones OpenAI-compatible Images API, including gpt-image-2, image prompt enhancement, reference-image edits, masks, multipart image uploads, local prompt galleries, saved image files, or decoded b64_json image responses.
description: Generate or edit images through the EAPIL Images API, or refine prompts for that workflow, including exact text and reference-image edits.
---
# EAPIL GPT Image 2
# EAPIL image generation and editing
## Overview
Use `https://api-n-cd.playones.com/v1` with the provider's `gpt-image-2` alias. An alias does not identify the underlying model build. Public GPT Image 2.5 guidance informs prompting; its model IDs and capabilities are not evidence of EAPIL gateway support.
Call the deployed OpenAI-compatible Images API at `https://api-n-cd.playones.com/v1` for `gpt-image-2` image generation and image editing. The endpoint and model are fixed. The API key must come from the user at runtime, either as a temporary direct key or from an environment variable.
## Follow the requested outcome
This skill includes a local prompt reference library under `references/`, adapted from `https://github.com/wuyoscar/gpt_image_2_skill`, for prompt enhancement before generation.
- **Generate or edit:** Execute a sufficiently specified request. Refine an underspecified prompt only enough to express the user's intent; do not require a separate enhancement interview or approval when the user already asked to generate. Honor requests to review first.
- **Improve a prompt only:** Deliver the prompt without an image API call. If the user requests verbatim execution, preserve their prompt unchanged.
- **Edit:** Inspect supplied images before deciding what to change. Identify each reference's role and send it in that order; state the requested changes and important identity, text, geometry or composition that must remain. An independent Images API call needs the relevant source image again; conversation history alone is not an image input.
## Hard Rules
Ask only for missing decisions that materially affect the result. Do not invent product claims, prices, dates, scientific data or a new visual direction during enhancement. Preserve exact in-image wording and language; Chinese review text is not a request to translate image text. Provide a bilingual comparison when requested or useful, without a mandatory three-section template.
- Use base URL `https://api-n-cd.playones.com/v1`.
- Use model `gpt-image-2`.
- Accept keys in this order: direct `--api-key`, `EAPIL_API_KEY`, then `OPENAI_API_KEY`.
- Recommend `EAPIL_API_KEY` for repeated EAPIL use, but do not refuse generation only because the user supplied a direct key or only has `OPENAI_API_KEY` set.
- Never write real API keys into skill files, source files, docs, commits, screenshots, or logs.
- Never print the full `Authorization` header or full base64 image data.
- Save decoded images into the user's opened project root by default. Do not leave final images in `/tmp` unless the user asks.
- For image edits, use multipart form data. Do not force `Content-Type` in direct `curl`; let `curl -F` set the multipart boundary.
- Before generating or editing, ask whether the user wants prompt enhancement. If enhanced, show the final prompt with Chinese comparison and wait for explicit confirm/approval before calling the API.
For a specific prompt-design gap, read the relevant part of [craft.md](references/craft.md). For inspiration or a requested genre, use [gallery.md](references/gallery.md) to select relevant examples. Detailed prompts and straightforward edits do not need gallery loading. Gallery values, layouts and styles are examples, not defaults.
## API Key Policy
## Execute the request
Preferred long-term setup:
Read [API usage](references/api-usage.md) for commands, parameters, masks, response handling or errors. Prefer the bundled dependency-free [Python helper](scripts/eapil_gpt2_image.py); locate it relative to this skill, then run from the user's project so output paths resolve there. Use `--prompt-file` for long or multiline prompts rather than embedding them in shell code.
```bash
export EAPIL_API_KEY="<user-provided-key>"
```
Set the actual `--size` to match the requested canvas; aspect ratio in prose does not change the API parameter. Keep quality and output format separate from visual descriptions. Preserve the existing endpoint and alias unless the user intentionally changes the integration. Do not add official-only parameters or silently replace unsupported settings with a different canvas.
Accepted fallback if already configured:
Keys resolve from `--api-key`, then `EAPIL_API_KEY`, then `OPENAI_API_KEY`. Accept the user's configured source; keep credentials out of files, logs and responses. Use an environment variable for repeated calls. Save final image files into the opened project by default, or the user's requested location. Do not overwrite a source/reference image when producing an edit.
```bash
export OPENAI_API_KEY="<user-provided-key>"
```
## Check and deliver
Accepted temporary key for a one-off call:
Open the returned images and check the constraints that matter: exact text, subject, composition, reference identity, edit boundaries and output size; verify actual transparency when requested. File saving alone does not prove image quality. If image inspection is unavailable, report that limit.
```bash
python3 scripts/eapil_gpt2_image.py generate \
--api-key "<user-provided-key>" \
--prompt "A realistic white-and-orange cat near a sunny window" \
--output white-orange-cat.png
```
For an observed defect, make a focused correction with the relevant image and preserved constraints. Stay within the user's requested number of outputs or agreed iteration budget; do not start repeated paid retries solely because an idealized result is possible. A timeout can leave a billed generation with an unknown outcome.
When a user pastes a key in chat, use it only for the current command. Recommend moving it to `EAPIL_API_KEY`, but do not block the generation.
## Prompt Enhancement Workflow
For every generation or editing request:
1. Confirm operation: generation or editing.
2. Ask: `Do you want prompt enhancement before I generate/edit the image?`
3. If the user says no, use the user's prompt unchanged.
4. If the user says yes, read `references/gallery.md` to choose the nearest category.
5. Read `references/craft.md` and the relevant `references/gallery-*.md` category file. For hybrid requests, read at most two or three relevant category files.
6. Draft an enhanced prompt using the user's intent, concrete visual constraints, and relevant gallery patterns.
7. Show the enhanced prompt in this exact three-section format:
```markdown
**API execution prompt**
<The exact prompt that will be sent to the API. Keep required in-image text in the user-requested language.>
**中文对照**
<中文对照仅供用户确认理解，review only. Do not send this section to the API unless the user explicitly asks to use it.>
**In-image text**
- "<exact visible text>" — <language>, keep exactly
```
8. Wait for the user to confirm the prompt is acceptable before API execution.
9. Run the bundled Python script from the user's opened project root unless there is a reason to use direct `curl`.
10. Save returned images as local image files in the project root, using a clear filename.
For edits, the enhanced prompt must be surgical: state what changes, what stays unchanged, and any identity/layout/text/lighting/pose/composition invariants.
Visible text inside the generated image must follow the user's requested language. The Chinese comparison is a review aid, not an instruction to translate on-image text. If the user asks for English poster copy, keep that exact English copy in `API execution prompt` and list it under `In-image text`; if the user asks for Simplified Chinese, Traditional Chinese, Japanese, or any other language in the image, preserve that exact language and wording.
## Prompt References
- `references/gallery.md`: category routing index for the full local prompt gallery.
- `references/craft.md`: cross-category prompt-craft checklist.
- `references/gallery-*.md`: concrete examples by category, including posters, UI mockups, photography, product, research figures, diagrams, anime, fashion, architecture, and edit workflows.
- `references/openai-cookbook.md`: official OpenAI image prompting guide mirror from the upstream reference set.
- `references/ATTRIBUTION.md`: source and license notes.
Use these files for prompt enhancement only. Do not import external CLI assumptions from the upstream skill; this skill keeps the EAPIL endpoint, model, and dependency-free script.
## Python Script
Prefer the bundled dependency-free Python script for stable calls: `scripts/eapil_gpt2_image.py`.
Run it from the user's project root so relative `--output` paths save into that project. It resolves the key from `--api-key`, `EAPIL_API_KEY`, or `OPENAI_API_KEY`, calls the fixed endpoint/model, decodes `b64_json` or data URL responses, writes image files, and prints JSON summaries with output paths and byte counts.
Generation:
```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py generate \
--prompt "A realistic white-and-orange cat sitting near a sunny window, natural light, detailed fur" \
--output white-orange-cat.png
```
Generation with a temporary direct key:
```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py generate \
--api-key "<user-provided-key>" \
--prompt "A clean product photo of a white ceramic mug on a walnut desk, soft morning light" \
--quality high \
--output white-mug.png
```
Edit:
```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py edit \
--image input.png \
--prompt "Turn the cat's scarf blue while preserving the cat, pose, background, and lighting" \
--output edited-cat.png
```
Multi-reference edit:
```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py edit \
--image person.png \
--image product.png \
--prompt "Place the product from image 2 beside the person in image 1. Match lighting and preserve both identities." \
--output combined.png
```
Edit with mask:
```bash
python3 /root/.config/opencode/skills/eapil-gpt2-image/scripts/eapil_gpt2_image.py edit \
--image input.png \
--mask mask.png \
--prompt "Fill the masked region with a small green plant matching the original lighting and perspective" \
--output masked-edit.png
```
Common options:
| Option | Applies to | Notes |
|---|---|---|
| `--api-key` | both | Temporary one-off key; prefer `EAPIL_API_KEY` for repeated use. |
| `--size` | both | Default `1024x1024`. |
| `--quality` | both | `auto`, `low`, `medium`, `high`; omit when unsure about gateway support. |
| `--n` | both | Multiple outputs are saved as `_0`, `_1`, etc. |
| `--background` | both | Forwarded only when supplied. |
| `--moderation` | generation | Forwarded only when supplied. |
| `--output-format` | both | `png`, `jpeg`, or `webp`. |
| `--output-compression` | both | Forwarded only when supplied. |
| `--user` | both | Optional end-user identifier. |
## Direct API Calls
Use `POST /images/generations` with JSON if making a direct request instead of the Python script.
```bash
curl -sS "https://api-n-cd.playones.com/v1/images/generations" \
-H "Authorization: Bearer ${EAPIL_API_KEY:-$OPENAI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean product photo of a white ceramic mug on a walnut desk, soft morning light",
"size": "1024x1024",
"response_format": "b64_json"
}'
```
Use `POST /images/edits` with multipart form fields for edits. Include one or more `image` files and optionally a `mask` file.
```bash
curl -sS "https://api-n-cd.playones.com/v1/images/edits" \
-H "Authorization: Bearer ${EAPIL_API_KEY:-$OPENAI_API_KEY}" \
-F "model=gpt-image-2" \
-F "image=@input.png" \
-F "prompt=Replace the background with a minimal warm studio backdrop while preserving the subject" \
-F "size=1024x1024" \
-F "response_format=b64_json"
```
## Error Checks
- `401` or `403`: missing, expired, or unauthorized key.
- `404`: wrong endpoint path or deployed gateway route unavailable.
- `400`: malformed JSON, unsupported field, missing prompt, invalid multipart form, bad image format, or an optional parameter the gateway does not accept.
- Empty `data`: upstream returned no image result; inspect the response body and request log if available.
- Multipart failures: remove any manual `Content-Type` header and use `curl -F`.
## Prompt Guidance
- Generation prompts should specify canvas/aspect, subject, style, composition, lighting, background, exact text, and exclusions.
- Put required in-image text in straight quotes.
- When prompt enhancement is used, provide `API execution prompt`, `中文对照`, and `In-image text` sections before asking for confirmation.
- The Chinese comparison must not translate or replace visible image text unless the user explicitly requested Chinese visible text.
- For posters, UI, research figures, data visualizations, product renders, and Chinese text, use `references/craft.md` plus the closest gallery category before drafting.
- Edit prompts should state both what changes and what must remain unchanged.
- Prefer `response_format=b64_json` for deterministic file saving.
## Common Mistakes
- Hardcoding the user's key: always reject this, even for "fully runnable" examples.
- Refusing a user-provided key just because it is not in `EAPIL_API_KEY`.
- Ignoring `OPENAI_API_KEY` when it is already configured.
- Generating immediately after prompt enhancement without user confirm/approval.
- Sending the `中文对照` section to the API when it is only meant for review.
- Translating required `In-image text` away from the user-requested language.
- Printing raw base64 responses: summarize length or save to a file instead.
- Saving generated images outside the project root without telling the user.
- Adding unsupported convenience fields without checking the endpoint behavior.
- Setting multipart `Content-Type` manually in direct `curl`: this can break boundary parsing.
Show saved images inline when supported and provide their local paths. Report material deviations and intentional prompt changes briefly. Do not claim identity preservation, exact text or a particular backend version without evidence. See [current official guidance](references/openai-cookbook.md) for source context and [attribution](references/ATTRIBUTION.md) for the retained gallery.
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/ATTRIBUTION.md
+2
View File
@@ -6,6 +6,8 @@ The prompt craft and gallery reference files in this directory are adapted from:
- Upstream skill path: `skills/gpt-image/references/`
- Retrieved for local integration on 2026-05-01
Maintenance review: 2026-09-30. The gallery entries and their original source labels remain retained. `craft.md` has been rewritten as this repository's task-dependent guidance, removing mandatory case remixing and unsupported prompt rituals. The former `openai-cookbook.md` mirror has been replaced by a dated, linked summary of current official guidance; its historical MIT provenance is preserved there. These updates do not establish the model behind the EAPIL alias.
The upstream repository describes its prompt patterns and gallery documentation as CC BY 4.0 unless a referenced upstream source states otherwise. Some individual gallery entries preserve author/source metadata from community examples or OpenAI Cookbook examples. Keep those source labels when adapting examples into prompts, docs, or generated prompt workflows.
These files are local prompt references only. Execution behavior for this skill remains defined by `../SKILL.md` and `../scripts/eapil_gpt2_image.py`, including the fixed EAPIL base URL and `gpt-image-2` model.
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/api-usage.md
+71
View File
@@ -0,0 +1,71 @@
# EAPIL Images API usage
## Integration boundary
The helper uses base URL `https://api-n-cd.playones.com/v1` and model alias `gpt-image-2`: JSON `POST /images/generations`, multipart `POST /images/edits`, requesting `b64_json`. These are this integration's existing contract. The provider may change the underlying model without changing its alias; neither an image's appearance nor public OpenAI documentation proves that mapping.
Reviewed against public documentation on 2026-09-30. Keep public model capabilities separate from verified gateway behavior. The script forwards explicit optional parameters; forwarding is not evidence the provider supports them. Do not change the alias to `gpt-image-2.5-*` or add new quality values merely because they exist in the public API.
## Commands
Resolve `<skill-dir>` from this installed skill's location. Run from the user's opened project. Commands below use PowerShell and `python`; use the interpreter available on the target host. This repository requires `rtk proxy` before external commands.
Generation:
```powershell
python '<skill-dir>/scripts/eapil_gpt2_image.py' generate --prompt 'A small white ceramic vase, on the supplied brand background, soft side light.' --size 1024x1536 --output vase.png
```
Long, multiline or multilingual text:
```powershell
python '<skill-dir>/scripts/eapil_gpt2_image.py' generate --prompt-file prompt.txt --size 960x1280 --output menu.png
```
`prompt.txt` must contain the actual execution prompt in UTF-8, with an optional BOM. `--prompt` and `--prompt-file` are mutually exclusive. The helper does not translate or enhance the text. A review translation belongs outside this file. Create it using a file-writing tool, rather than shell interpolation of user text. In verbatim mode, do not rewrite the supplied prompt.
Reference edit, with order matching the prompt's roles:
```powershell
python '<skill-dir>/scripts/eapil_gpt2_image.py' edit --image scene.png --image jacket.png --prompt-file edit-prompt.txt --size 1536x1024 --output scene-edited.png
```
Optional localized edit:
```powershell
python '<skill-dir>/scripts/eapil_gpt2_image.py' edit --image source.png --mask mask.png --prompt 'Change only the selected scarf to blue; preserve the person, pose, text, background and lighting.' --output scarf-edited.png
```
For direct multipart calls, let the client set the boundary; do not force a boundary-less Content-Type. The helper handles the boundary itself. The public guide requires matching image/mask format and dimensions and an alpha channel in the mask; when there are multiple images, the mask applies to the first. Prepare a PNG base and same-dimension PNG alpha mask for portability, with transparent areas marking the edit region. Confirm the provider accepts masks. A mask is guidance, not a guarantee that all outside pixels remain identical.
## Parameters and canvas
| Option | Behavior |
|---|---|
| `--api-key` | Temporary explicit key; otherwise `EAPIL_API_KEY`, then `OPENAI_API_KEY`. Prefer an environment variable so the key is not in command history. |
| `--size` | Default `1024x1024`; set explicitly for another canvas. The helper does not infer it from the prompt. |
| `--quality` | Existing choices `auto`, `low`, `medium`, `high`; absent means omitted. |
| `--n` | Positive number of requested outputs; default 1. Returned multiples use `_0`, `_1`, etc. |
| `--output-format` | `png`, `jpeg`, `webp`; default filename uses the selected format, or png. Match an explicit filename's extension to the expected format. |
| `--output-compression` | Integer 0–100; optional, provider-dependent. |
| `--background` | Optional forwarded field; transparent output depends on actual backend support and a compatible format. |
| `--moderation` | Optional, generation only. |
| `--user` | Optional end-user identifier. |
Orientation examples: `1024x1536` is 2:3 portrait, `1536x1024` is 3:2 landscape. They are not exact 3:4 or 16:9 replacements. Under published GPT Image dimension rules, `960x1280` matches 3:4 and `1536x864` matches 16:9. Custom sizes still need gateway support; these examples are not live EAPIL verification.
Public custom-size limits include multiples of 16, ratios within 1:3–3:1, maximum edge 3840 and 655,360–8,294,400 total pixels; sizes above 2560x1440 are experimental. These are upstream constraints, not a promise the gateway exposes every size. If a required size is rejected, report the conflict and choose a user-acceptable alternative; do not silently distort or crop the brief. Prompt words such as "4K" or "8K" cannot change request dimensions.
Source: [OpenAI image generation](https://developers.openai.com/api/docs/guides/image-generation).
## Results and recovery
The helper saves Base64 or Base64 image data URLs. Remote image URLs are not downloaded. It checks decoded data for nonempty content and recognized PNG/JPEG/WebP signatures; this is not full image decoding or visual verification. Inspect the saved output with an image viewer. Check actual dimensions, text and any requested alpha channel using available image tools.
- `401`/`403`: check configured key and access without printing it.
- `400`: inspect the relevant error for unsupported size/optional fields, invalid input or multipart issues. Do not drop user-critical constraints as an automatic fallback.
- `404`: provider route or model availability may differ; verify deployment rather than guessing another model ID.
- Empty/malformed image data: report the failure; do not present an empty file as success.
- Timeout/transport failure: the outcome may be unknown. Check provider status/logs where available before resending a potentially billed request.
No automatic network retry is built in. Keep new calls within the requested output/iteration budget. Show concise errors rather than raw responses containing credentials, image data or echoed private content.
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/craft.md
+22 -334
View File
@@ -1,355 +1,43 @@
# GPT Image 2 Prompt Craft
# Image prompt craft
Cross-cutting principles distilled from the full 162-prompt Gallery Atlas. Use this file as the prompt-design checklist; use `gallery.md` as the routing index for the split concrete Scale/case atlas as `gallery-*.md` files.
Use a section only when it resolves a gap in the current task. These are repository recommendations, informed by [official guidance](openai-cookbook.md) and the attributed [gallery](gallery.md), not a model-specific syntax or a guarantee of results.
## Table of contents
## Refine without replacing the brief
0. Use the Scale before writing from scratch
1. Exact text goes in quotes
2. Put canvas, aspect ratio, and layout before subject
3. JSON / config-style prompts are a core pattern
4. Use fixed-region schemas for infographics and educational boards
5. Research/data figures need diagram grammar
6. UI prompts should read like product specs
7. Multi-panel boards need consistency constraints
8. Camera and capture context unlock photorealism
9. Scene density beats adjectives
10. Style anchors should be specific and bounded
11. Promotional hierarchy for commercial posters
12. Material, lighting, and palette are separate controls
13. Edit endpoint prompts must preserve invariants
14. Negation is for strong priors
15. Category-specific mini-schemas
16. Dense Chinese and multilingual layouts need extra constraints
17. Attribution and gallery metadata
18. Safety and copyright notes
Keep the user's subject, intended use, language, style and hard constraints. Add concrete information only where it helps the image meet that brief: a focal subject, an important spatial relationship, a material or a lighting condition. Leave creative latitude where the user did. More scene objects and adjectives are not automatically better.
## 0. Use the Scale before writing from scratch
Natural language is sufficient. Short labeled sections help complex layouts; JSON is optional when the user wants reusable structured input. A schema's version, render flags or the words "8K" do not configure image resolution. Set actual size and quality through the API. Do not require English translation, a noun quota, a fixed prompt order or a prescribed number of examples.
Before drafting a prompt, open `gallery.md` as the category index, then read 3–8 nearby cases from the matching `gallery-<category>.md` file. The skill should not behave like a bare CLI wrapper: it should remix the repo's collected patterns.
When a visual reference is useful, describe the attributes to transfer: palette, linework, camera position, texture, spacing or medium. Do not copy an example's unrelated brand, text, numbers, components or composition into the user's request.
Fast routing examples:
- Anime/manga or multi-character boards → No. 1–12.
- Product/food commercial render, especially structured config prompts → No. 56–58.
- Brand, poster, typography, dense Chinese copy → No. 33–44, 59–61, 66–73.
- Research, data, technical, scientific figures → No. 75–95, 107–128.
- UI / app / dashboard mockups → No. 102–106.
- Edit endpoint / reference transformations → No. 100–101.
## Text and layout
## 1. Exact text goes in quotes
Quote the exact visible strings and associate each with a location or hierarchy. Keep supplied punctuation, prices, units and language verbatim. Say whether additional copy is allowed. If line breaks or repeated appearances matter, specify them. Reserve adequate space and contrast for required text rather than adding decorative microtext.
GPT Image 2 renders typography well when literal copy is explicit.
Repository example, for a brief that supplies these facts:
Weak:
> Create a tea poster with the brand name and promo copy.
> Create a portrait tea menu. At the top display "山川茶事"; below it display "冷泡系列". Show two clearly separated entries: "中杯 16 元" and "大杯 19 元". Preserve these exact strings. Use the supplied brand palette and keep the menu readable at its intended display size. Add no other copy.
Strong:
> Design a 3:4 vertical poster. The poster must accurately display the following exact Chinese copy: "山川茶事" / "冷泡系列" / "中杯 16 元" / "大杯 19 元".
The API canvas must also be portrait. When the user requires an exact ratio, choose matching dimensions supported by the gateway; do not silently substitute a different ratio. If only orientation is specified, established portrait/landscape sizes can be suitable.
Rules:
- Wrap every displayed string in `"…"`.
- Keep user-supplied Chinese verbatim; do not paraphrase.
- Separate text blocks with `/`, bullets, or layout labels.
- For dense text, include title, subtitle, module labels, legend labels, numbers, fine print, and any required axes/tabs.
- If text is only decorative, say so. If it must be readable, say `crisp`, `legible`, `large enough`, and `no garbled characters`.
For information graphics, specify the important zones, labels and relationships. For data or research figures, use supplied data and explicit visual encodings; inspect values, axes and arrow directions after generation. Model-generated charts are not a substitute for precise plotting when the output must preserve quantitative data exactly.
## 2. Put canvas, aspect ratio, and layout before subject
For UI mockups, use the product's supplied design rules and real copy. Describe relevant hierarchy and states; do not add a default dashboard of rounded cards or fictional account values. A raster mockup is not an implemented interface.
The strongest gallery prompts allocate space before describing surface detail.
For a multi-panel sheet, specify panel count/order and shared identity or style only where needed. Do not overpack a small canvas with more panels or copy than can remain readable.
Useful first clauses:
- `Landscape 16:9 academic concept figure…` (No. 75–95).
- `Design a 3:4 vertical poster…` (No. 33–45).
- `Create a square 3×3 grid…` (No. 22, No. 25).
- `A 6-panel film storyboard laid out as a 3×2 grid…` (No. 28).
- `Create one tall manga chapter proof sheet containing 19 numbered miniature pages…` (No. 10).
## Photography and product images
When structure matters, state the structure before the subject. Otherwise the model spends detail budget on the object and improvises the layout.
Use meaningful capture and material details when they serve the brief: viewpoint, subject scale, light direction, contact shadows, surface finish or depth of field. Avoid conflicting camera descriptions. Preserve approved packaging, logos and product geometry from references; do not invent marketing claims or labels.
## 3. JSON / config-style prompts are a core pattern
A request for an informal photo does not require a named phone or lens. A request for a sparse scene does not require a quota of background objects. Use targeted exclusions for likely errors rather than a long universal negative prompt.
Do not omit this. The gallery uses JSON-like structured prompts for premium product and food rendering (No. 57, No. 58). This pattern works when the output has many interacting systems: environment, subject, materials, lighting, particles, motion, and render goals.
## Reference edits
When to use:
- Product hero renders with material/lighting precision.
- Food photography with suspended ingredients or motion.
- Complex scenes where you want a controllable schema rather than prose.
- Any prompt that benefits from reusable slots.
Inspect the actual inputs. Distinguish the base image from subject, style, garment, logo or layout references. List roles by input order and use repeated `--image` arguments in that order. For example, if requested:
Recommended schema:
> Image 1 is the base scene; image 2 supplies only the jacket. Replace the jacket worn by the person in image 1 with the jacket from image 2. Preserve the person's face, pose, other clothing, background, camera angle and existing text. Match the base scene's lighting and contact shadows.
```text
/* PRODUCT_RENDER_CONFIG: Short Name
VERSION: 1.0.0
AESTHETIC: Premium Commercial Photography */
{
"GLOBAL_SETTINGS": {
"aspect_ratio": "2:3 vertical",
"style": "hyper-realistic commercial photography",
"clarity": "sharp foreground, micro-texture visibility",
"render_flags": ["8K_UHD", "sharp_foreground", "editorial_finish"]
},
"ENVIRONMENT": {
"background": "warm gradient studio backdrop",
"lighting": "directional softbox with glossy highlights",
"atmosphere": ["floating particles", "cinematic bokeh"]
},
"CORE_ASSETS": {
"primary_subject": "hero product",
"materials": ["brushed metal", "condensation", "paper label"],
"composition": "diagonal zero-gravity arrangement"
},
"MOTION_OR_DETAIL_SYSTEMS": [
{ "object": "ingredient fragments", "state": "suspended mid-air" },
{ "object": "liquid splash", "behavior": "thick glossy arc" }
],
"OUTPUT": {
"mood": "premium, indulgent, editorial",
"avoid": ["cheap e-commerce banner", "plastic CGI", "fake brand logos"]
}
}
```
For local edits, identify the target object/region and the surrounding elements to preserve. Use a mask when available and appropriate; it guides editing but does not promise pixel-perfect isolation. See [API usage](api-usage.md) for mask requirements. A new request does not automatically remember previous Images API inputs; pass the chosen base or latest accepted output again.
Craft rules:
- Keys should describe visual subsystems, not implementation internals.
- A short header comment can carry `VERSION:` and `AESTHETIC:`. The version is not for code execution; it makes the prompt feel like a deliberate spec and helps future agents compare variants.
- Values should be concrete visual constraints, not vague praise.
- Arrays are good for visible elements; nested objects are good for materials, physics, lighting, and output goals.
- Use `render_flags` / `quality_flags` for output-level constraints such as `8K_UHD`, `sharp_foreground`, `micro_texture`, `editorial_finish`, or `no_CGI_tell`.
- JSON does not have to be machine-valid if comments help the model, but keep it clean and readable.
- Still include aspect ratio and output mood inside the schema.
## 4. Use fixed-region schemas for infographics and educational boards
Several high-performing prompts are not just descriptions; they are layout contracts. See the museum catalog disassembly infographic (No. 68), field guides (No. 69, No. 74), travel/cooking cards (No. 70, No. 72), and anatomy/science posters (No. 122–127).
Pattern:
1. Name the artifact type: `museum catalog-style Chinese disassembly infographic`, `field guide`, `classroom wall chart`.
2. Define the fixed layout zones: top title, left disassembly, right summary, bottom legend, etc.
3. Specify annotation behavior: lead lines, numbered labels, close-up details, material notes.
4. Specify style boundary: museum board, scientific poster, editorial card — not generic poster / anime / e-commerce.
5. Add exact label text where correctness matters.
This is stronger than saying “make an infographic about X”.
Educational anatomy / science poster pattern:
- Name the subject exactly (`human muscular system`, `periodic table spectral variant`, `geological strata cross-section`).
- Include view constraints where relevant, e.g. `anterior and posterior views` for anatomy.
- Add scale/context notes such as `Adult height reference 175 cm` when the prompt needs scientific believability.
- Require classroom-wall-chart clarity: clean hierarchy, thin labels, legend, muted academic palette, and no gore/excessive realism.
## 5. Research/data figures need diagram grammar
For academic and technical figures, use the language of diagrams, not illustration only.
Include:
- Orientation and venue style: `Landscape 16:9`, `NeurIPS camera-ready`, `conference-paper figure`.
- Structural primitives: columns, zones, stacks, panels, nodes, ribbons, heatmaps, bars, dashed dividers.
- Directed relationships: arrows, residual arcs, feedback loops, dashed attack paths, numbered flow markers.
- Exact labels: module names, axes, legend values, titles, subtitles.
- Visual semantics: color meanings, line styles, thickness ∝ quantity, benign vs attack flows.
- Cleanliness constraints: `large readable labels`, `white background`, `uncluttered`, `publication-grade`.
Examples:
- No. 79 uses left/right encoder-decoder columns with exact block labels.
- No. 81 uses zones, worker nodes, tool registry, memory panels, and trace timeline.
- No. 86 uses Sankey source blocks, processing blocks, final splits, and proportional ribbons.
- No. 95 uses four columns plus benign/injection arrow semantics.
Security / agent-safety figure pattern:
- Show the attack surface as an explicit visual object, e.g. `Attacker-controlled document`, `Public Slack message`, or `Web page`.
- If illustrating prompt injection, quote the payload visibly as a harmless example string such as `<!-- IGNORE previous instructions... -->`, then label it `injected instructions` / `payload`.
- Separate benign flow and attack flow with line semantics: solid slate-gray for benign, dashed terracotta/red for injection path.
- Keep the figure explanatory/defensive; do not turn the payload into operational instructions.
Data visualization mini-schema (No. 107–111):
- Name the chart family first: `small-multiples grid`, `network graph`, `chord diagram`, `treemap`, `geographic choropleth`.
- Specify canvas and structure: `4×3`, node groups, ribbon groups, nested rectangles, map regions.
- Provide exact labels, panel names, legend values, units, and axis labels.
- Explain visual encoding: line = temperature, bars = precipitation, ribbon thickness ∝ flow, color = category/region/value.
- Require consistent scales/alignment across repeated panels.
- Keep styling editorial and readable: white background, generous margins, restrained palette, publication-grade labels.
## 6. UI prompts should read like product specs
The UI/UX examples (No. 102–106) succeed because they specify product context, device frame, information architecture, real copy, and data.
Pattern:
- Fictional product name to avoid real-brand leakage.
- Device/canvas: `1290x2796 smartphone screen`, `16:10 monitor canvas`.
- Palette and component system.
- Top header phrasing: explicitly name the header area and its copy, e.g. `Include a top header with the in-image text "AURAE", "Good morning, Lina", and "Total balance $12,480.36"`.
- Cards, charts, nav, transaction/activity rows.
- Exact values and labels: balances, percentages, axis labels, button names.
- Quality constraints: `crisp typography`, `clean spacing`, `precise icon alignment`, `production-quality mockup`.
Avoid generic UI words alone (`modern`, `clean`, `beautiful`). Add rows, labels, charts, and plausible product data.
## 7. Multi-panel boards need consistency constraints
For grids, proof sheets, storyboards, character sheets, and worldbuilding boards, the key is not “many images”; it is coherence across panels.
Examples:
- No. 5: 16-panel expression grid.
- No. 9: ten-panel character grid.
- No. 10: 19-page manga proof sheet.
- No. 22: 3×3 dark-fantasy worldbuilding set.
- No. 28: 6-panel storyboard with shot/camera metadata.
- No. 31: official character reference sheet.
- No. 107: 4×3 small-multiples data grid with consistent axes.
Rules:
- State the grid/page count exactly: `3×3`, `4×3`, `3×2`, `16-panel`, `19 numbered miniature pages`.
- For data grids, use the exact phrase `small-multiples grid`, specify rows/columns, and require consistent axes/labels across mini-panels.
- Give each panel a role or beat.
- Specify shared art direction, palette, costume motifs, symbols, lighting, and character identity.
- For storyboards, add camera language: WIDE, OTS, CU, low angle, aerial, match cut, pan/tilt/static, duration.
- For character sheets, require front/side/back views, expression variations, parts breakdown, palette, and setting notes.
## 8. Camera and capture context unlock photorealism
The strongest photorealistic prompts name how the image was captured, not just that it is realistic.
Useful phrases:
| Phrase | Effect |
|---|---|
| `RAW, unprocessed, full iPhone camera quality` | Reduces AI polish; adds casual realism. |
| `amateur iPhone photo` | Tourist / spectator feel. |
| `shot from the crowd at a distance` | Real-event perspective. |
| `eye level with a 28 mm lens feel` | Architectural realism. |
| `low three-quarter angle` | Product/vehicle hero composition. |
| `natural morning side light` | Beauty/lifestyle softness. |
Pick one dominant capture frame. Too many camera specs can conflict.
## 9. Scene density beats adjectives
Vague: `a convenience store at night`.
Strong: name concrete objects, surfaces, and situational details: freezer stickers, promotional posters, trash cans, entrance mats, glass reflections, shared bikes, water droplets, phone glow, wet asphalt.
Rule of thumb: include 5–12 concrete nouns for the scene and 2–4 material/lighting constraints. Do not stack empty adjectives like `stunning`, `professional`, `beautiful`, `high quality` without visual anchors.
## 10. Style anchors should be specific and bounded
Name an aesthetic, medium, movement, or production context:
- `MAPPA-style digital 2D animation`, `Studio Pierrot Naruto-Shippuden aesthetic`.
- `New Chinese visual style, light-luxury and restrained`.
- `Swiss grid discipline meets friendly risograph community poster`.
- `gongbi-level architectural detail combined with loose ink atmosphere`.
- `traditional Japanese irezumi tattoo aesthetics`.
- `NeurIPS camera-ready style`.
If using a living studio/IP aesthetic, keep characters original and avoid direct copying where the output is meant for publication.
## 11. Promotional hierarchy for commercial posters
Posters, ads, menus, and campaign visuals should specify hierarchy.
Include:
- Product/event name largest.
- Prefer the wording `Exact readable text:` when every displayed string matters, especially event posters and wayfinding.
- Claim/tagline.
- SKU / variants / modules.
- Prices or dates if relevant.
- CTA or ordering/info module.
- Fine print.
- Distance readability: `legible from a distance`, `clear promotional hierarchy`.
- Add a targeted avoid-line for text failures: `avoid unreadable microtext`, `avoid fake sponsor logos`, `avoid garbled characters`.
This prevents flat banner layouts where every text block has the same weight.
Three-glances test for hero posters:
- First glance: the silhouette/theme is immediately recognizable.
- Second glance: the viewer can read the narrative world, product/event promise, or campaign message.
- Third glance: close inspection reveals texture, small labels, background details, and aftertaste.
Use this for cinematic posters, city posters, fashion/editorial covers, and premium narrative ads where detail must work at multiple viewing distances.
## 12. Material, lighting, and palette are separate controls
Do not compress them into “premium”. Split them:
- Materials: brushed steel, brass, ruby jewel accents, travertine, linen, glass thickness, condensation, rice paper.
- Lighting: softbox, rim light, natural morning side light, neon reflections, warm-copper highlights, cold blue-grey evening.
- Palette: muted teal/rust/bone, cream/warm stone/pale green, slate/amber/teal, indigo/red-orange/cream.
This is especially important for product renders, interiors, architecture, tattoo flash, beauty lifestyle, and technical exploded views.
Brand/label control:
- For original commercial images, say `No visible brand logos` when you do not want fake trademarks.
- If tiny labels are acceptable but should not hallucinate brands, use `no readable fake labels except a tiny generic mark "AM ROUTINE"`.
- For event posters, avoid fake sponsor strips unless the prompt supplies exact sponsor names.
## 13. Edit endpoint prompts must preserve invariants
For `images.edit`, be surgical. State what changes and what must remain unchanged.
Pattern:
> Make it a winter evening with heavy snowfall, snow dusted on the board and pieces, breath vapor in the air, cold blue-grey lighting, chess position still clearly readable.
Rules:
- Name the target transformation first.
- Preserve identity/layout/position/readability explicitly.
- If editing a poster/mockup, preserve original text unless translation/replacement is requested.
- Use `-i` reference images; use masks for localized changes.
Reference-based unlocks:
- `maintain composition and image details consistently`
- `same subject, absolutely consistent in appearance and coloring`
- `in the original positions`
- `change only X; keep everything else the same`
Multi-reference rule:
- Identify each input by index and role: `Image 1: product photo`, `Image 2: style reference`, `Image 3: logo/packaging`.
- Say exactly how references interact: apply style from Image 2 to subject from Image 1; place logo from Image 3 on the package; preserve layout from Image 1.
- Repeat invariants on each iteration if identity, text, geometry, or brand elements must not drift.
## 14. Negation is for strong priors
Use explicit avoid-lines when the model has a likely bad default.
Examples:
- `Avoid anime style, avoid modern cyberpunk, avoid random fake kanji clutter.`
- `Avoid motorcycle aggression, sci-fi excess, fake brand logos, and toy-like proportions.`
- `Avoid generic festival chaos, fake sponsor logos, and unreadable microtext.`
- `No gore, no body horror, no actual person, no photorealistic skin photo.`
Avoid lists should be short and targeted. Too many negatives can dominate the prompt.
## 15. Category-specific mini-schemas
Reusable category formulas from the atlas:
- **Anime/Manga:** style anchor + original characters + action/pose + environment + palette + line/cel-shading direction + safety/IP boundary.
- **Gaming:** game-camera context + HUD elements + playable scene detail + screenshot/monitor realism.
- **Cyberpunk/Retro:** board/grid format + named subcharacters/items + neon material vocabulary + original designs.
- **Brand systems:** logo/wordmark + color palette + type system + packaging/social/touchpoints in one showcase board.
- **Photography:** capture device + time/place + ordinary imperfections + real-world props.
- **Architecture/Interior:** room type + camera/lens + materials + light direction + negative space + realistic shadows.
- **Technical illustration:** exploded/cutaway structure + ordered components + numbered callouts + materials + blueprint/plate style.
- **Tattoo:** tattooable placement + linework/shading/color tradition + negative-space gaps + flash-sheet presentation + no real skin photo. Use exact style tokens where helpful, e.g. `BLACK & GREY`, `FOREARM SLEEVE`, `NEGATIVE SPACE`, `traditional Japanese irezumi`, `dark surrealism`.
## 16. Dense Chinese and multilingual layouts need extra constraints
For Chinese-heavy outputs:
- Say `Simplified Chinese` or `Traditional Chinese` if it matters.
- Provide all copy exactly.
- Specify layout modules and hierarchy.
- Require readable, neat text without garbled characters, typos, English, or pinyin unless desired.
- Use high quality for final assets.
Chinese calligraphy or brush-signage prompts should specify style (`brush style`, `calligraphy-style labels`, `rice-paper texture`) and avoid fake clutter.
## 17. Attribution and gallery metadata
Every split `gallery-*.md` entry preserves either `Curated` metadata for repo-curated/reworked entries or visible `Author + Source` attribution when it came from an outside source. When adapting an outside-source pattern into README/gallery entries, keep attribution in the metadata/footer.
Use `Curated` for repo-created, repo-curated, or substantially reworked prompts/images; keep `Author + Source` for outside-source entries.
## 18. Safety and copyright notes
- Real-person likeness edits often fail at the API moderation layer; surface the API error verbatim.
- Keep adult/fashion prompts clearly adult, tasteful, non-explicit, and non-nude.
- Brand/IP aesthetics appear in the gallery; use original characters/products when creating reusable or public examples.
- For research/security figures, preserve benign framing and avoid operational instructions beyond defensive illustration.
Inspect results before iterating. Correct the observed defect, repeat the constraints vulnerable to drift, and retain the accepted parts. When a user asks for a design change, update those constraints intentionally rather than retaining obsolete ones. Check spelling, reference identity, geometry, affected region and requested aspect/alpha behavior; do not treat words such as "exact" as verification.
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-anime-and-manga.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 1–12 · Count: 12
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 1 · MAPPA-style anime action still (Jujutsu-Kaisen aesthetic)
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-architecture-and-interior.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 117–121 · Count: 5
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 117 · Japanese Minimalist Living Room
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-beauty-and-lifestyle.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 153–154 · Count: 2
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 153 · Quiet-luxury skincare morning tray
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-brand-systems-and-identity.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 60–62 · Count: 3
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 60 · Moss Radio brand identity showcase board
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-character-design.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 31–32 · Count: 2
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 31 · Official character reference sheet
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-cinematic-and-animation.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 26–30 · Count: 5
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 26 · Pixar-style 3D animation still (kitten)
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-cinematic-film-references.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 147–152 · Count: 6
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 147 · Symmetric Pastel: The Grand Conservatory
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-data-visualization.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 107–111 · Count: 5
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 107 · Small Multiples Climate Grid
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-edit-endpoint-showcase.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 100–101 · Count: 2
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 100 · Chess board → winter evening (edit via `/v1/images/edits`) 🆕
plugins/codex/plugins/eapil-gpt2-image/skills/eapil-gpt2-image/references/gallery-events-and-experience.md
+1 -1
View File
@@ -2,7 +2,7 @@
Range: No. 155–156 · Count: 2
Load this file only when the request matches this category. For cross-cutting writing rules, pair it with `craft.md`.
Load this file only when the request matches this category. Use a relevant part of `craft.md` only if additional guidance is needed. Examples are optional inspiration; retain their source labels.
### No. 155 · Zoo visitor wayfinding map
Loaded 100 of 298 files, more files were not shown because too many files have changed in this diff. Show more