# open-office-skill

**Repository Path**: changluJava/open-office-skill

## Basic Information

- **Project Name**: open-office-skill
- **Description**: Open-source Office document processing Skill for AI Agents and Sandboxes, with DOCX, PPTX, XLSX, PDF, conversion, rendering, and offline-first runtime support.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# open-office-skill

> 面向 AI Agent / Sandbox 的开源 Office 精细操作 Skill。当前版本：**0.1.5**。

[中文](README.md) | [English](README.en.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.5-blue.svg)](VERSION)
[![Skill](https://img.shields.io/badge/Skill-open--office--skill-blue.svg)](skills/open-office-skill/)

## 一、项目背景

AI Agent 正在从“生成文字”走向真实办公执行：理解已有 Word / Excel / PowerPoint / PDF，做局部修改、数据分析、跨格式重构、正式交付和质量验收。

传统方案通常要么只有粗粒度“生成文件”，要么把业务场景写死成模板/固定 Workflow。`open-office-skill` 希望让 Agent 像熟练办公人员一样工作：**先理解任务和材料，再选择正确工作方法，组合精细 Office 能力，并对最终交付负责。**

## 二、核心设计理念

> **完整精细的 Office 原子能力 + 少量从真实案例抽取的场景 SOP + 可验证的质量闭环。**

项目不是 Office 模板生成器。

- **Atomic Capability 不缺失**：段落、Run、表格、单元格、公式、Sheet、Shape、图片、位置尺寸、图表、PDF 页面等应可精细操作；
- **SOP 来自真实案例**：沉淀真实工作步骤，去掉行业、指标、固定章节、固定配色和企业模板；
- **少量 SOP 覆盖大量场景**：优先 `1 个主 SOP + 最少辅助 SOP + 原子能力`，而不是按业务名称不断新增 Workflow；
- **局部修改优先**：发现单点问题优先定位并 Patch，不默认整份重建；
- **质量是独立阶段**：文件保存成功不代表任务成功；
- **真实任务驱动演进**：通过人为触发的 Skill Feedback SOP 从 Agent 上下文提取下一版本改进点。

## 三、统一方法论

### 面向人的五步模型

```text
Understand → Structure → Operate → Validate → Deliver
```

也就是：理解目标与材料 → 组织合适结构 → 执行 Office 操作 → 验证质量 → 输出可直接使用的交付物。

### 面向 Agent 的七步执行协议

```text
Understand
  ↓
Inspect
  ↓
Classify
  ↓
Plan
  ↓
Execute
  ↓
Validate
  ↓
Deliver
```

即 **U-I-C-P-E-V-D**。

### 六类 Task Model

| Task Model | 本质 | 典型任务 |
|---|---|---|
| Generate | 从无到有 | 报告、方案、预算表、PPT |
| Edit | 修改已有文件 | 排版修复、公式修复、单页重做 |
| Analyze | 从材料获取结论 | 销售分析、质量分析、文档理解 |
| Transform | 重构表达形式 | Word→PPT、Excel→管理汇报 |
| Convert | 格式转换 | Word→PDF、PDF→图片 |
| Workflow | 多文件连续处理 | Excel→分析→PPT→PDF |

Task Model 是**分类和路由语言**，不是六个固定模板或六个大脚本，可以组合。

## 四、四条核心执行原则

### Read Before Write

有已有文件时默认先 Inspect，理解现有结构、内容和约束后再修改。

### Minimal Change

Edit 默认执行：

```text
Inspect → Locate → Patch → Validate
```

用户只要求修改一处，就不无理由改变其他内容。

### Evidence First

Analyze 默认遵循：

```text
Data → Fact → Calculation → Insight → Recommendation
```

无法被数据和材料支持的原因只能作为假设。

### Transform ≠ Convert

`Word → PDF` 的重点是保真；`Word → PPT` 的重点是理解、提炼、重组与新的视觉表达，不能机械复制源文档结构。

## 五、真实办公场景覆盖

市场上大量 Office 任务名称不同，但工作模式高度重复。项目按真实工作方法覆盖场景，而不是按文件 API 数量宣传。

| 真实办公场景 | 主 Task Model | 核心 SOP / 能力组合 |
|---|---|---|
| Excel 经营/销售/质量/统计分析并形成洞察 | Analyze | 数据分析 SOP + XLSX inspect/analyze + 按需报告/演示 |
| Excel 清洗、去重、公式修复、报表整理 | Edit + Analyze | 表格清洗 SOP + xlsx/edit/format + validation |
| 根据材料写报告、方案、总结、会议纪要 | Generate | 从材料创作文档 SOP + DOCX 原子能力 |
| 修改已有 Word、局部润色和排版 | Edit | 文档审阅 SOP + docx/inspect/edit + Minimal Change |
| 从 Word/PDF/Excel/分析结果制作 PPT | Transform + Generate | 演示制作 SOP + PPTX primitives + audit/render |
| 优化已有 PPT、单页重构、统一视觉 | Edit | 演示重构 SOP + pptx/inspect/edit/audit |
| 多份 Office/PDF/图片整合成统一交付物 | Workflow | 多源整合 SOP + Shared Facts + 目标格式 SOP |
| Office↔PDF、合并拆分、水印、页码 | Convert | 格式转换 SOP + conversion/PDF tools |
| 正式交付前检查并局部返修 | Validation | Content/Data/Structure/Visual 四级质量契约 |

## 六、Scenario SOP 与 Atomic Capability

```text
真实业务任务
      ↓
Task Model 分类
      ↓
1 个主 Scenario SOP + 最少辅助 SOP
      ↓
Atomic Office Engine
├── DOCX create / inspect / edit / format / replace
├── XLSX create / inspect / analyze / edit / format
├── PPTX create primitives / inspect / edit / format / audit
├── PDF create / inspect / merge / split / stamp
└── Convert / render / layout / verify
      ↓
Content / Data / Structure / Visual
      ↓
Local Repair
      ↓
Deliver
```

SOP 固定的是工作方法，不固定业务指标、章节数、PPT 页数、配色、图表或企业模板。底层能力不会因为 SOP 收敛而减少。

## 七、Workflow：跨文件一致性

跨文件不是简单串联。例如：

```text
Excel → Analyze → Word → PPT → PDF
```

应维护统一 **Shared Facts**：指标、值、单位、时间范围、计算口径、来源和结论。不同交付物从同一事实层派生，避免 Word、PPT 和 PDF 中出现数值/结论漂移。

目前由 `SKILL.md + SOP Router` 作为轻量 Orchestrator；**暂不引入一个重型万能 workflow.py**。只有真实案例反复证明轻量路由不足时才升级。

## 八、质量契约

正式交付按任务需要验证：

- **Content**：内容、事实、关键文本、名称、日期、结论；
- **Data**：数值、公式、汇总、单位、图表数据源和口径；
- **Structure**：文件内部结构、Sheet/Section/Slide/Page 和引用关系；
- **Visual**：真实渲染后的溢出、重叠、乱码、分页、可读性和图片变形。

```text
Execute → Validate → Fail? → Local Repair → Validate → Deliver
```

## 九、核心能力矩阵

| 能力域 | 当前主要能力 |
|---|---|
| DOCX | create / inspect / fine-grained edit / format / replace |
| XLSX | create / inspect / generic analyze / fine-grained edit / format |
| PPTX | primitive create / inspect / fine-grained edit / format / structural audit |
| PDF | create / inspect / merge / split / stamp |
| 转换 | Pandoc / LibreOffice Headless / collision-safe output |
| 渲染 | PDF → PNG / render boundary audit |
| 质量 | check_pdf / render_audit / verify / render review / local repair SOP |
| 环境 | offline-first init / runtime probe / smoke / ready cache |
| 方法 | Task Model + U-I-C-P-E-V-D + 场景 SOP 路由 + Skill Feedback Meta SOP |

详细能力见 [`references/capabilities.md`](references/capabilities.md)。

## 十、快速开始

```bash
cd skills/open-office-skill
python3 auto/init.py
export PATH="$HOME/.local/bin:$PATH"
office-run scripts/common/smoke.py
```

### 精细修改

```bash
office-run scripts/xlsx/edit.py input.xlsx operations.json output.xlsx
office-run scripts/docx/edit.py input.docx operations.json output.docx
office-run scripts/pptx/edit.py input.pptx operations.json output.pptx
```

### Excel 通用画像

```bash
office-run scripts/xlsx/analyze.py input.xlsx --output analysis.json
```

### 交付质量验证

```bash
office-run scripts/pptx/audit.py output.pptx --safe-margin-ratio 0.02
office-run scripts/quality/verify.py output.pptx --no-blank --max-bottom 0.96
```

## 十一、0.1.5 核心升级

0.1.5 是一次**真实 DOCX 修复失败驱动的 Tool 可靠性版本**，仍坚持“精细原子能力 + 真实场景 SOP + 独立质量闭环”：

- `docx/inspect.py --deep`：直接看到 Run 级字体/字号/颜色、分节、页眉页脚、表格 merge/grid/nesting，减少 Agent 手工解压 OOXML；
- DOCX 原子操作增强：固定表格 grid 布局、CJK 字体映射、Section 方向/页边距、Header/Footer、实时 PAGE 字段、字符单位首行缩进；
- `add_table` 先写数据再 merge，规避合并后 python-docx 索引折叠问题；
- `check_pdf.py` 对 expected text 做空白归一化，并增加 `--bbox-margin` 可选文本边界断言；
- 文档修改 SOP 增加“局部 Edit vs 系统性 Rebuild”判断，不把 Minimal Change 误解成“永远禁止重建”；
- 明确 `format.py` 是全局归一化 Tool，不承担复杂结构修复；
- 新增硬性工程门槛：**任何 Tool 修改都必须有针对性单元/回归测试实际通过。**

这次没有新增固定“乱排版文档模板”，目录页码两轮回填也只作为观察型 SOP 流程保留。

## 十二、当前核心设计思路与未来方向

### 当前设计思路

> **市场真实场景告诉我们用户在做什么；真实案例告诉我们最优步骤；Task Model 抽象共性；Scenario SOP 指导工作；Atomic Capability 完成精细操作；Validation 保证最终可直接交付；Feedback 驱动下一版本。**

### 未来方向

1. **补齐 Inspect / Document Model**：基于真实案例审计 Word Section/Header/Footer/Styles、Excel Pivot/Data Validation/Conditional Formatting、PPT Master/Theme、PDF OCR/Form/Encryption 等结构能力，不能“报告里有就宣称支持”；
2. **继续补齐精细原子能力**：真实任务出现通用临时代码时优先沉淀 Atomic Capability；
3. **质量契约继续工具化**：提高 Content/Data/Structure/Visual 的机器验证覆盖率；
4. **增强跨文件一致性**：逐步沉淀 Shared Facts、来源和指标口径管理；
5. **建立真实任务 Benchmark**：用任务成功率、数据正确性、内容正确性、结构、视觉、指令遵循和跨文件一致性衡量 Skill，而不是 API 数量；
6. **继续真实案例驱动 SOP**：已有 SOP 优先优化，只有新工作方法反复出现才新增 SOP；
7. **保持轻量 Orchestrator**：除非真实执行反复证明必要，否则不引入大一统工作流引擎。

## 十三、仓库结构与版本治理

```text
open-office-skill/
├── README.md                       # 中文
├── README.en.md                    # English
├── CHANGELOG.md                    # English
├── CHANGELOG.zh-CN.md              # 中文
├── VERSION                         # 0.1.5
├── docs/
│   ├── research/                   # 市场/方法研究，仅仓库级
│   ├── design/
│   ├── versions/
│   └── iterations/
│       └── 0.1.5/
│           ├── retrospective.md
│           └── 0.1.5.md
└── skills/open-office-skill/       # Agent 运行时 Skill，不含迭代记录
```

版本迭代记录永远只放 `docs/`，不进入 Skill 包。

## License

MIT License。第三方依赖保持各自上游许可证，详见 Skill 内 `THIRD_PARTY_NOTICES.md`。