edit-document

name	edit-document
description	Use this skill whenever the user wants to write, edit, format, summarize, comment on, or review the Word document open in the side pane. Routes user intent to the single right office_* tool so the model picks one high-leverage call instead of chaining many low-level reads and writes.
license	MIT
metadata	{"category":"office-routing","primary-interface":"office_* tools"}
triggers	["Word","document","文档","Word文档","写一份","修改","总结","评审","排版","套模板"]

Edit Document

This document is open in Word right now. You have office_* tools that read and write it directly. Route the user's intent to one well-chosen tool before reaching for many.

Intent → tool routing

User intent	First tool	Notes
"Write me a report / proposal / outline / draft / 写一份" (no current content matters)	office_build_paragraphs	Single call. Pass the full structure as an array of paragraphs each with its own style and list mode. Do NOT call office_get_document_outline or office_get_document_text first — the document is empty or will be replaced.
"Rewrite this paragraph / make this concise" (selection-driven)	office_replace_selection	Read selection with office_get_selection only if you need surrounding context.
"Change all X to Y" (global text edit)	office_find_replace	One call. Don't pre-read the full text.
"Edit paragraph N / the second heading"	office_replace_paragraph_by_index	Call office_get_document_outline first to map text to paragraph index.
"Add a comment / review note / 批注"	office_add_comment	For "comment on this paragraph / the selected text", OMIT anchor so the whole selection is covered. Pass anchor only to target a different specific phrase (first match, that substring only).
"Reply to / resolve comments"	office_get_comments → office_reply_comment / office_resolve_comment
"Summarize / explain / 总结 / 解释"	office_get_document_outline first, then office_get_document_text only for the sections the user asked about	Never load full text just to summarize a large doc.
"Make this bold / italic"	office_apply_inline_format
"Make this Heading 2 / Quote"	office_apply_paragraph_style
"Turn these lines into a bullet / numbered list"	office_apply_list	Or pass `list: "bullet"
"Accept / reject 修订 / tracked changes"	office_get_revisions then office_resolve_revision({ index, action: "accept"|"reject" })	For "全部接受 / accept all changes", pass action: "accept-all" AND confirmAcceptAll: true only after the user explicitly asks for it. Requires WordApiDesktop 1.1+.
"Add / insert a link / 加链接 / hyperlink"	office_insert_hyperlink	Pass anchor to wrap an existing phrase; omit to wrap the current selection. displayText overrides what the link shows.
"Insert image / 插入图片"	office_insert_image	Bytes must already be base64-encoded — pi-office does NOT fetch URLs. Always include altText unless the image is purely decorative.
"Make a new table / 做个表 / N × M table"	office_build_table	Single call with a 2D array. Use office_set_cell only to update an existing table.
"诊断 / debug / 排查 / 为什么连不上 / /pioffice:doctor"	office_doctor	Read-only. Prints a multi-line health report; show the full result back to the user verbatim so they can act on the ✗ rows.

Anti-patterns (do NOT do these)

1. Reflexive read before a write. If the user said "write me a 5-section product brief", go straight to office_build_paragraphs. Reading the document first wastes a turn.

2. Chaining N small writes instead of one batch. office_build_paragraphs accepts paragraphs with per-item style and list mode. Use it for any multi-paragraph composition. Do not insert one paragraph, then apply a style, then insert another paragraph.

3. Re-pasting the result in chat after a write. After office_build_paragraphs, the user sees the document. Reply with at most ~3 lines:

   • one sentence confirming the doc is built,
   • optionally a comma-separated list of top-level sections as citation links [Section](pi://goto?heading=Section),
   • optionally one sentence offering a sensible next step. Do NOT re-emit the full content.

4. Asking for confirmation before reading. Read tools (office_get_*) are silent and safe. Use them freely; do not ask "should I read the document first?"

5. Calling office_get_document_text on a long doc. Use office_get_document_outline first. Only fetch text for the section the user asked about.

Destructive operations need explicit confirmation

office_build_paragraphs({position: "replace-document"}) wipes the entire document body before inserting. The tool refuses this call unless you also pass confirmReplaceDocument: true. Only set that flag when the user has clearly said something like "重写整篇 / 替换文档 / rebuild from scratch / start over". If they only said "draft / write / add", use position: "end" (default) or position: "start" instead — those preserve existing content.

When the document is empty

office_get_document_outline returning [] means "blank document, no need to preserve anything." Skip straight to office_build_paragraphs.

Asking the user

If the request has a genuine fork you cannot settle from context — two or more plausible directions that would change what you build — call office_ask_user once (pass options for a choice, multiSelect to let them pick several). Use it sparingly: not as a reflex, not to confirm a default you can reasonably pick, and never to ask permission for an edit (the approval gate handles that). If the user skips, proceed with the most sensible default instead of asking again.

When in doubt

Pick the single tool whose name most directly matches the user's verb:

• "write" / "draft" / "generate" / "create" → office_build_paragraphs
• "rewrite" / "edit" / "改" → office_replace_*
• "find" / "replace" / "change all" → office_find_replace
• "comment" / "review" / "批注" → office_add_comment / office_get_comments
• "tracked changes" / "修订" / "review revisions" → office_get_revisions → office_resolve_revision
• "link" / "hyperlink" / "加链接" → office_insert_hyperlink
• "image" / "picture" / "图片" → office_insert_image
• "table" / "做表" → office_build_table (new) or office_set_cell (update)
• "summarize" / "read" / "总结" → outline first, full text only as needed

One well-chosen tool beats five guesses.