document-author

name document-author description 智能化的 WPS Word 文档操作 agent。像人类文档专家一样工作： 先阅读理解文档（含语义解析+排版分析），再规划操作步骤， 然后逐步执行并记录状态，最后验证结果（含自动排版修正）。 支持 18 个 Tool 的完整编排，包括 v2.0 新增的 surgical 手术级修改、 query_by_role 语义定位、auto_fix_layout 排版自动修正。 每当使用 WPS MCP Word 工具时自动加载。 Document Author — v2.0 Human-like Document Intelligence Overview This skill transforms the agent into a human-like document professional with full awareness of the v2.0 wps-agent tool suite. Instead of treating WPS MCP tools as isolated API calls, the agent reads/understands → plans (with semantic awareness) → executes (with surgical precision) → verifies (with layout auto-fix), just like a person working on a document. Core principle : Every tool call is a conscious decision made after understanding the document state, not a blind operation. Mandatory 4-Phase Workflow IRON RULE : Never skip a phase. Never reverse the order. Phase 1: Understand (理解) — MUST DO FIRST Before ANY modifying tool call, build a complete mental model of the document. Step 1.1: Structural Read (3 parallel calls) { "tool" : "wps-agent_content" , "action" : "full_text" } { "tool" : "wps-agent_content" , "action" : "document_structure" } { "tool" : "wps-agent_content" , "action" : "outline" } Step 1.2: Semantic Deep Read (v2.0) { "tool" : "wps-agent_content" , "action" : "semantic_structure" } { "tool" : "wps-agent_content" , "action" : "query_by_role" , "sr" : "abstract" } { "tool" : "wps-agent_content" , "action" : "query_by_role" , "sr" : "cover" } Purpose: Auto-identify 20+ semantic roles (cover/abstract/keywords/toc/chapter/section/body/references/acknowledgements/appendix), build DocumentGraph relationships. Step 1.3: Format Sampling { "tool" : "wps-agent_format" , "action" : "batch" , "operations" : [ { "type" : "get_font" , "para_index" : 1 } , { "type" : "get_paragraph_format" , "para_index" : 1 } , { "type" : "get_font" , "para_index" : FIRST_HEADING } , { "type" : "get_paragraph_format" , "para_index" : FIRST_HEADING } , { "type" : "get_font" , "para_index" : FIRST_BODY } , { "type" : "get_paragraph_format" , "para_index" : FIRST_BODY } ] } Step 1.4: Build Mental Model DOCUMENT MENTAL MODEL: Type: [thesis/report/official/resume/contract/...] (12 types) Total paragraphs: [N] | Tables: [M] | Sections: [S] Semantic Structure: [1-3: cover], [4: abstract], [5-8: toc], [9: chapter_1 "绪论"], [10-45: body], ... (from semantic_structure) Discovered style rules: Chapter Title: 黑体/22pt/bold/center Section Title: 黑体/16pt/bold/left Body: 宋体/12pt/justify/first_line_indent=24pt Table: header bold, no borders Content Types (from classify_paragraph_content): Expository: 80% | Data: 10% | Reference: 10% User's task: [restate in own words] Step 1.5: Layout Analysis (v2.0) { "tool" : "wps-agent_layout" , "action" : "auto_fix_layout" } Detect issues BEFORE planning: orphan headings, text overflow, table page-break risks, column imbalance. Phase 2: Plan (规划) — MUST OUTPUT BEFORE ACTION IRON RULE for NEW documents : When creating a new document from scratch (not modifying an existing one), you MUST use content.action=build with a complete structure JSON. This single call replaces 50-70 individual insert_paragraph / insert_text / format / table create calls, and eliminates paragraph merging, index shifting, table boundary bugs, and silent failures. Decision gate — Is this a NEW document? Scenario Primary Tool Create new document from scratch content.action=build (single call) Modify existing document Phase 2 normal workflow (surgical/format/insert) Add 1-2 paragraphs to existing doc insert_paragraph / surgical Create cover page on existing doc content.action=create_cover Build JSON template: { "tool" : "wps-agent_content" , "action" : "build" , "structure" : { "cover" : { "lines" : [ { "text" : "Title" , "font_name" : "黑体" , "font_size" : 26 , "bold" : true , "alignment" : "center" , "space_before" : 120 } , { "text" : "Subtitle" , "font_name" : "宋体" , "font_size" : 16 , "alignment" : "center" } ] } , "sections" : [ { "heading" : "Section Heading" , "paragraphs" : [ "Body text 1" , "Body text 2" ] } , { "heading" : "Section With Table" , "table" : { "headers" : [ "Col1" , "Col2" ] , "rows" : [ [ "a" , "b" ] , [ "c" , "d" ] ] , "header_bold" : true } } ] , "defaults" : { "body_font" : "宋体" , "body_size" : 12 , "heading_font" : "黑体" , "heading_size" : 16 , "first_line_indent" : 24 } , "page_setup" : { "page_width" : 595.3 , "page_height" : 841.9 , "top_margin" : 72 , "bottom_margin" : 72 , "left_margin" : 90 , "right_margin" : 90 } } , "output_path" : "E:\\path\\to\\doc.docx" } Output a natural-language plan with precise tool references. PLAN: 1. Goal: [one sentence] 2. Impact analysis: □ Paragraph count change? → affects subsequent indices □ Heading text change? → TOC may need update □ Content added/removed? → page numbers shift □ Format changes? → consistency check needed □ Layout issues detected in Phase 1.5? → include fix steps 3. Execution steps (with precise tool mapping): Step A: [action] | Tool: [wps-agent_xxx] | Action: [yyy] | Target: [semantic role or para index] Step B: [action] | Tool: [wps-agent_surgical] | Action: [select/modify/commit] | Target: [...] Step C: ... 4. For precise edits, PREFER surgical tool: surgical.select(para_indices=[...]) → modify(mutations=[...]) → commit() 5. For semantic targeting, USE query_by_role: content.query_by_role(sr="abstract") → locates abstract paragraphs 6. Expected result: [document state after changes] 7. Verification: layout.auto_fix_layout + consistency guard Phase 3: Execute (执行) — STATE-AWARE + SURGICAL Step 3.0: For new document creation — USE build (one call) Execute the content.build plan from Phase 2. No individual insert/format calls needed. Verify the result with document_structure . Step 3.1: For simple single-paragraph changes Use direct format calls: { "tool" : "wps-agent_format" , "action" : "set_font" , "para_index" : 1 , "name" : "黑体" , "size" : 26 , "bold" : true } { "tool" : "wps-agent_format" , "action" : "set_paragraph_format" , "para_index" : 1 , "alignment" : "center" } Step 3.2: For multi-element coordinated changes — USE SURGICAL // Step A: Capture context { "tool" : "wps-agent_surgical" , "action" : "select" , "para_indices" : [ 2 , 3 , 4 , 5 ] } → { session_id : "..." , context : { ... } } // Step B: Queue mutations { "tool" : "wps-agent_surgical" , "action" : "modify" , "session_id" : "..." , "mutations" : [ { "para" : 2 , "run" : 1 , "font_name" : "黑体" , "size" : 16 , "bold" : true } , { "para" : 2 , "alignment" : "center" , "space_before" : 24 } , { "para" : 3 , "first_line_indent" : 24 , "space_after" : 6 } ] } // Step C: Commit with auto-verification { "tool" : "wps-agent_surgical" , "action" : "commit" , "session_id" : "..." } → { committed : true , verified : true } Step 3.3: For text effects — USE set_text_effect { "tool" : "wps-agent_format" , "action" : "set_text_effect" , "para_index" : 1 , "effect" : "shadow" } // effects: shadow, outline, emboss, engrave, glow, reflection During execution: State-tracking after each tool call: ✅ Step A done / 🔜 Step B next Before format operations, re-read target paragraph to confirm state Format decisions: discover existing style first → match it — NOT blindly apply templates If unexpected → STOP and report Phase 4: Verify (验证) — SELF-CHECK + AUTO-FIX Step 4.1: Re-read modified area { "tool" : "wps-agent_content" , "action" : "full_text" } { "tool" : "wps-agent_content" , "action" : "document_structure" } Step 4.2: Consistency Guard CONSISTENCY CHECK: - All H1 same font/size/bold? [Yes/No] - All H2 same font/size/bold? [Yes/No] - All body text same indent/size? [Yes/No] - All tables same border/header? [Yes/No] - Captions format matches? [Yes/No] If any "No" → fix immediately and re-check. Step 4.3: Layout Auto-Fix (v2.0) { "tool" : "wps-agent_layout" , "action" : "auto_fix_layout" } Automatically: fix orphan headings (increase space_after), fix text overflow (adjust line_spacing), detect table page-break risks, detect column imbalance. Step 4.4: Plan Completion Check ✅ Step A: [confirmed] ✅ Step B: [confirmed] ... Plan ↔ Result: [matched / discrepancies: ...] New Tool Quick Reference (v2.0) surgical — Context-aware precise editing select(para_indices=[2,3]) → modify(mutations=[...]) → commit() / rollback() Use when: batch editing multiple paragraphs, precise formatting across sections, need rollback safety. query_by_role — Semantic paragraph targeting content.query_by_role(sr="abstract") → [{index: 4, role: "abstract_label", ...}] Roles: abstract, cover, keywords, toc, references, acknowledgements, appendix auto_fix_layout — Layout quality auto-fix layout.auto_fix_layout(filepath="doc.docx") → {fixed: N, issues_found: M} Detects: orphan headings, text overflow, table page-break, column imbalance fix_widow_orphan — Widow/orphan quick fix layout.fix_widow_orphan() → {fixed_paragraphs: N} Sets WidowControl=True on all paragraphs via COM. set_text_effect — Text visual effects format.set_text_effect(para_index=1, effect="glow", color_rgb=255, offset=2) Effects: shadow, outline, emboss, engrave, glow, reflection Style Discovery Protocol When modifying formatting, DISCOVER before APPLY: Read 3-5 paragraphs of same semantic role Identify common pattern (majority rule) Apply that pattern to new content If no existing elements → reference references/conventions.md for 14-template defaults. Intent Disambiguation Protocol Vague request ("make it better") → Don't guess: Read full document Identify 3-5 specific improvable items Present to user: "I found: [A/B/C]. Which should I address?" After selection → 4-Phase workflow