Content
# WPS Agent
> Transform WPS Office into an AI-driven document assistant. Based on the MCP protocol, through COM + Offline dual-mode control Word/Excel/PPT, support semantic understanding, surgical-level modification, AI intelligent layout.
**Comprehensive rating: 9.2/10** | 18 MCP Tools | 200+ Action
---
## Overview
- **Word**: Document CRUD, paragraph/run/selected area/outline operation, style management, table full functionality, search and replace, page layout, revisions/comments, footnotes/bookmarks/field codes, watermarks, images, document properties
- **Excel**: Workbook/worksheet CRUD, cell/area read/write, formatting, charts, sorting, filtering, conditional formatting, formulas, freeze panes
- **PPT**: Presentation CRUD, slide management, text box/table/image operation, speaker notes
- **Semantic Understanding**: 20+ semantic role recognition (cover/abstract/keywords/directory/chapter/section/body/reference/acknowledgment/appendix), document type classification (12 types), content nature classification (discussion/data/formula/code/reference)
- **Surgical-level Modification**: Context capture → batch modification → verification → rollback (`surgical` tool)
- **Layout Analysis**: Page geometry, text overflow, table cross-page line breaks, column imbalance, orphan detection → automatic correction
- **Cross-document**: Inter-document paragraph/table/text copying, Word↔Excel data migration, Word outline→PPT generation, document text/format comparison
- **AI Layout**: Analyze document structure, apply 14 Chinese preset templates, natural language layout, automatic directory/title numbering, quality verification
- **AI Content**: Generate/summarize/rewritten/expanded/translated document content through LLM
- **Dual-mode**: Online (WPS COM real-time operation) + Offline (XML native read/write, no WPS required)
---
## Architecture
```
opencode (AI Agent) ← You speak human language, it adjusts tools
↕ MCP stdio
mcp_server.py (18 Tools) ← MCP protocol layer
↕ Python import
wps_bridge/ ← COM automation layer
├── app.py # Word COM singleton
├── document.py / content.py / formatting.py / table.py
├── layout.py / search.py / review.py
├── docspace.py / transfer.py / migrate.py / compare.py
├── excel_app.py / ppt_app.py / utils.py
intelligence/ ← AI intelligence layer
├── chinese_rules.py # 12 preset templates
├── content_generator.py # AI content generation
├── llm_client.py # LLM API client
├── template_manager.py # Template extraction management
└── layout_analyzer.py # Document analysis
↕ COM (pywin32)
WPS Office (Windows)
└── opencode_config/ ← Agent intelligent behavior layer
├── AGENTS.md # WPS Agent exclusive Agent configuration (automatically triggers document-author)
└── skills/document-author/ # 4-Phase human-like workflow (understanding → planning → execution → verification)
├── Kwps.Application (Word)
├── Ket.Application (Excel)
└── Kwpp.Application (PPT)
```
---
## Installation
```bash
# 1. Clone
git clone https://github.com/alllyx520-bot/wps-agent.git
cd wps-agent
# 2. Create virtual environment
conda create -n wps-agent python=3.11 -y
conda activate wps-agent
# 3. Install dependencies
pip install -r requirements.txt
```
## MCP Client Configuration
Add the following configuration to the `mcp` section in `opencode.jsonc`:
```json
"wps-agent": {
"type": "local",
"command": [
"E:\\Anaconda\\envs\\wps-agent\\python.exe",
"E:\\AAAprojects\\自由测试\\wps-agent\\mcp_server.py"
],
"environment": {
"WPS_AGENT_LLM_KEY": "Your API-Key"
}
}
```
## Tool Quick Reference
### Word Core Tools
| Tool | Main Action |
|------|------------|
| `document` | info/list/open/create/save/close/activate/export_pdf/doc_properties |
| `content` | full_text/paragraph/outline/runs_detail/document_structure/full_structure/semantic_structure/query_by_role/insert_text/create_cover/replace_range/snapshot/rollback/batch |
| `format` | get_font/set_font/get_run_font/set_run_font/get_paragraph_format/set_paragraph_format/apply_style/clear_formatting/copy_format/batch/add_watermark/remove_watermark/add_hyperlink/set_tab_stops/set_bullet_list/set_text_effect |
| `style` | list/get/create/modify |
| `table` | count/info/read/create/set_cell_text/format_cell/set_header/format_borders/merge_cells/alternate_rows/batch_read |
| `search` | find/replace/goto_heading |
| `layout` | page_setup/section_info/columns/header_footer/page_numbers/page_break/image_wrap/line_numbers/fix_widow_orphan/auto_fix_layout |
| `review` | track_changes_toggle/comments_list/comment_add/revisions_accept_all |
| `reference` | add_footnote/add_endnote/add_bookmark/list_bookmarks/insert_field |
### Surgical Tools
| Tool | Main Action |
|------|------------|
| `surgical` | select (by paragraph index/semantic role) → modify (queued modification) → commit (batch execution + verification) / rollback (recovery) |
### Advanced Tools
| Tool | Main Action |
|------|------------|
| `content_control` | count/list_controls/info/add/set_text/set_checkbox/select_dropdown/delete |
| `field_codes` | insert_field/insert_quote/insert_doc_property/insert_seq/insert_style_ref/insert_ref/insert_if/list_fields/unlink_field |
### Offline Tools
| Tool | Main Action |
|------|------------|
| `offline_docx` | build/build_cover/validate/analyze/auto_format/apply_template/replace_text/get_text/get_statistics/full_structure/semantic_structure |
### Cross-application Tools
| Tool | Main Action |
|------|------------|
| `docspace` | list_all/activate/close_all/save_all |
| `transfer` | copy_paragraphs/copy_table/copy_range |
| `migrate` | word_table_to_excel/excel_range_to_word_table/word_outline_to_ppt |
| `compare` | text_diff/format_diff |
### Excel / PPT Tools
| Tool | Main Action |
|------|------------|
| `excel` | create/open/cell_read/cell_write/range_read/range_write/formula_set/chart_add/sort/auto_filter/conditional_format/freeze_panes |
| `presentation` | create/add_slide/set_title/set_body/insert_image/insert_table/add_notes/apply_theme |
### AI Tools
| Tool | Main Action |
|------|------------|
| `ai_format` | analyze/suggest/apply_template/reformat/auto_toc/auto_numbering/validate/generate_content/summarize_document/auto_enhance |
---
## Built-in Templates
| Template Name | Applicable Scenario |
|--------|---------|
| `official` | Official documents (GB/T 9704) — Fangzheng Xiaobiao Song title, three号仿宋正文, three-level title system |
| `thesis` | Academic papers — Three-level titles (chapter/section/article), Song body small four positive text, 1.5倍 line spacing |
| `report` | Business reports — Microsoft Yahei, 1.3倍 line spacing, modern and concise style |
| `resume` | Resumes — Bold name, chapter title, compact layout |
| `contract` | Contracts/agreements — Bold title, clear hierarchy of clauses |
| `letter` | Official letters/business letters — Imitation Song body positive text, standard letter format |
| `proposal` | Project proposals — Cover + multi-level titles, formal layout |
| `meeting_minutes` | Meeting minutes — Concise and clear, clear agenda |
| `press_release` | Press releases — Title/subtitle/source/body, news specifications |
| `manual` | User manuals — Three-level titles (chapter/section/step), compact layout |
| `exam` | Test papers — Large title bold, positive text clear |
| `bid` | Bidding documents — Formal and rigorous, clear hierarchy |
| `notice` | Notices/announcements — Imitation Song body positive text, standard official document format |
| `work_report` | Work summary — Clear hierarchy, reporting style |
## Intelligent Document Operation: Skills + AGENTS.md Collaboration
The `opencode_config/` directory stores the behavior configuration of the opencode AI agent. Through the collaboration of Skill and AGENTS.md, human-like intelligent document operation is achieved:
```
User says "Change the reference format to national standard"
│
▼
┌─ AGENTS.md §10.1.2 ───────────────────┐
│ Detects WPS Word operation → Automatically loads │
│ document-author skill │
└───────────┬────────────────────────────┘
▼
┌─ document-author Skill ─────────────────┐
│ Phase 1: Understanding → batch read full text + outline + format │
│ Phase 2: Planning → output modification plan + impact analysis │
│ Phase 3: Execution → step-by-step operation, record status │
│ Phase 4: Verification → re-read + consistency check + automatic correction │
└───────────┬────────────────────────────┘
▼
WPS MCP Tools (content/format/table/...)
```
**Core Capabilities:**
| Capability | Description |
|------|------|
| **Document Style Discovery** | Automatically infer the document's own format rules after reading 20% of the content, without blindly applying standard templates |
| **Semantic Role Labeling** | Automatically identify paragraph types (cover/title/body/references...), using semantic references instead of digital indexing |
| **Consistency Guardian** | Automatically compare and correct inconsistent formats of similar elements after each modification |
| **Impact Prediction** | Automatically analyze the impact of operations on related elements (directory/page numbers/cross-references) before execution |
| **Intent Clarification** | Fuzzy instructions are not guessed, but candidate solutions are analyzed and confirmed before execution |
| **Layered Polishing** | Pass 1: Content correctness → Pass 2: Unified format → Pass 3: Detailed polishing → Pass 4: Visual enhancement |
**Deployment Method**: Copy the files under `opencode_config/` to `~/.config/opencode/`.
```bash
cd wps-agent
robocopy opencode_config\ %USERPROFILE%\.config\opencode\ /E
```
Restart opencode, and WPS Word operations will automatically follow the 4-Phase workflow.
## Project Structure
```
wps-agent/
├── mcp_server.py # MCP service entry (18 tools)
├── config.yaml # Configuration file
├── requirements.txt # Python dependencies
├── README.md
├── .gitignore
├── wps_bridge/ # COM automation bridge layer
│ ├── app.py # Word COM singleton (with reconnection)
│ ├── document.py # Document CRUD + images/bookmarks/watermarks
│ ├── content.py # Text read/write + batch operations
│ ├── formatting.py # Font/paragraph format + format brush + batch
│ ├── table.py # Table full functionality
│ ├── layout.py # Page settings/header/footer/page numbers
│ ├── search.py # Find and replace
│ ├── review.py # Revisions/comments
│ ├── docspace.py # Unified document space
│ ├── transfer.py # Cross-document copying
│ ├── migrate.py # Word↔Excel migration + Word→PPT
│ ├── compare.py # Document comparison
│ ├── excel_app.py # Excel full functionality COM bridge
│ ├── ppt_app.py # PPT COM bridge
│ └── utils.py # COM auxiliary functions
└── intelligence/ # AI intelligence layer
├── llm_client.py # LLM API client (supporting DeepSeek/OpenAI)
├── chinese_rules.py # 12 preset Chinese layout templates
├── template_manager.py # Template extraction/saving/loading/comparison
├── content_generator.py # AI generation/summarization/rewrite/expansion/translation
├── format_suggester.py # Format suggestions
└── layout_analyzer.py # Document analysis + natural language analysis
└── opencode_config/ # opencode AI configuration (skills/commands/agents)
├── AGENTS.md # Agent behavior rules (including document-author 4-Phase workflow)
├── skills/ # 9 skills (including document-author document intelligence)
├── commands/ # 4 custom commands
└── agents/ # 2 custom agents
```
---
## License
MIT
