Word 光标插入

写报告时，把一段话或一个 Excel/CSV 表格精准插进 Word 光标处——一键连接正在打开的 Word，单调用完成「查上下文+插入」，幂等防重复、亚秒级响应。告别手动复制粘贴和满屏找插入位置。

Word Cursor Insert

⚡ 写报告神器：把一段话、一个 Excel/CSV 表格，精准塞进 Word 光标所在位置。连接你正在编辑的 Word，自动识别上下文，单调用完成插入，重复执行也不会多插——快、准、稳。

Overview

Insert data into the cursor of the Word document the user currently has open. Two modes: (1) a CSV/list becomes a formatted Word table (title + bold header + borders + autofit); (2) a short value becomes inline plain text (e.g. filling a blank inside a sentence). The workflow is context-aware (it inspects the cursor surroundings before inserting) and fast (Python + pywin32, bounded-window context read, single tool call).

When to use

• "把这份清单 / 表 / CSV 写到 Word 光标处"
• "人数统计一下 插到 Word 光标" / "把统计结果填到 Word 里"
• Any request to place a spreadsheet / list / computed value at the Word insertion point.

Critical environment rules (see references/gotchas.md)

• NEVER use PowerShell for Word COM here: its stdout is garbled and results are lost. Always use Python + pywin32. Python stdout is clean.
• Read cursor context with a BOUNDED window (~300 chars), never doc.Range(0, sel.Start). Cost must stay O(window), independent of doc size.
• Do NOT re-run a COM call because the terminal looked garbled — that duplicates the insertion. Judge success from stdout/result only.
• Pass data via files (ASCII temp path); do not put long Chinese strings on the command line.
• 一眼能定就直接跑，别深思：结果形态明显时（标量填空 / 表格中转），直接执行 单调用快路径，不要追加分析、验证或解释性思考步骤。一次调用已含计算+查上下文+ 幂等判重，无需任何前置/后置回合。

Workflow

0. Decide the result SHAPE first (this drives every later step, and is where over-engineering creeps in):

• Result is ONE scalar — a count, a sum, a single number/word to fill a blank (e.g. "统计人数填到光标" → 7) → inline TEXT mode. Do NOT export to CSV; just compute the value and pass it via --text "...". This is the common, fast path.
• Result is a multi-row LIST / TABLE → table mode; prepare a CSV (step 1).

1. (Table mode ONLY) Reference a tabular file — Excel or CSV, same path: word_cursor_insert.py 表.xlsx [--no-title] (or 表.csv [--no-title]). Format is auto-detected by extension, so there is ONE table-insert path; no CSV export, no second flag. (Text mode skips this step entirely — no file, no temp.)
2. Inspect context — done by the insert script in the SAME call (it prints the bounded before/after context and sel.Information(12)). Do NOT run a separate context-inspection call beforehand; that just duplicates a Word COM round trip. One call = inspect + insert.
3. Confirm mode from context:
   • Cursor inside a sentence expecting ONE value → inline text mode (typical for a scalar result).
   • Free location / list source → table mode.
4. Insert via scripts/word_cursor_insert.py (run with the managed venv python):
   • Table: word_cursor_insert.py <csv_path> [--no-title]
   • Text : word_cursor_insert.py --text "7" [--newline] The script prints a short verification (title / rows / cols / first / last). Trust it and stop — do NOT run a separate verification read of the document; that is a redundant round trip. Do not re-run.
5. Report the outcome to the user (e.g. "已插入标题 + 19 行表格" or "光标处已填入 7").

Fast path: one-call insert (your report workflow)

When writing reports you typically drop ONE of these at the cursor: (A) a paragraph of text / a single value → inline TEXT (B) an Excel table → a Word TABLE Collapse read-source + insert into a SINGLE call. Fixed skeleton — you only fill the marked line:

python

import win32com.client, time
t0=time.time()
# === fill THIS one line with what goes at the cursor ===
val = 7                              # (A) 标量/文本；或 val = sum(...) / "段落…"
# val = read_table(r"X:\表.xlsx")   # (B) 表格：read_table 自动识别 xlsx/csv
# =======================================================
word = win32com.client.GetActiveObject("Word.Application")
doc = word.ActiveDocument; sel = word.Selection
# 有界窗口判重(只查光标前后, 避免整段 in 误判, 如"17"含"7")
win=60; s=sel.Start; e=sel.End; dend=doc.Content.End
before = doc.Range(max(s-win,0), s).Text if s>0 else ""
after = doc.Range(e, min(e+win,dend)).Text if e<dend else ""
if str(val) in (before + after):
    act = "SKIP(已存在, 幂等)"          # 防重复: 不预检、不盲清, 同一次调用内判重
else:
    sel.TypeText(str(val)); act = f"INSERTED {val}"
print("elapsed_s:", round(time.time()-t0,3), "|", act)  # 1 call: 算+查上下文+插

• (A) text / paragraph: --text "..." [--newline], or the skeleton above. Long Chinese paragraphs: read them from a temp file; don't pass very long strings on the command line.
• (B) table (Excel or CSV): word_cursor_insert.py 表.xlsx [--no-title] (or 表.csv) reads the file and inserts it as a Word table (bold header + borders
  • autofit). Format is auto-detected by extension; rows relayed as-is — NO computation. The script modes (Workflow step 4) stay the default for clarity; the skeleton is the fast path when the source must be read/computed first.

Prerequisites

pywin32 must be installed in the managed venv: ~/.workbuddy/binaries/python/envs/default/Scripts/pip install pywin32 Run scripts with ~/.workbuddy/binaries/python/envs/default/Scripts/python.exe.

Notes

• CSV title heuristic: if the first row has exactly one non-empty cell and there are more than 2 rows, treat row 0 as the title and row 1 as the header.
• Table insertion always starts on a new paragraph after the cursor; inline text mode inserts at the cursor with no paragraph break (add --newline to force one).