wuling-overseas-dealer-expansion-skill/references/encoding-and-excel-writeback.md

# Text Encoding and Excel Write-Back Rules

These rules are mandatory for every script, temporary repair, and manual write-back that touches Excel text fields such as customer notes, outreach status, follow-up status, Chinese summaries, or HTML previews.

Why this exists

Windows PowerShell inline scripts can corrupt Chinese text when a command contains Chinese literals inside a here-string, heredoc-like block, or inline Python source. The corrupted text appears in Excel or HTML as repeated question marks. This has already happened in the workbook notes after email status write-back, so future runs must treat encoding as a hard safety rule.

Hard rules

• Do not write Chinese customer notes, status text, field names, or HTML labels by embedding Chinese literals directly inside PowerShell inline Python scripts.
• For temporary Python scripts launched from PowerShell, use one of these safe methods:
  • read Chinese text from an existing UTF-8 file;
  • build Chinese strings with Unicode escape sequences such as \u90ae\u4ef6\u53d1\u9001\u8bb0\u5f55;
  • call a shared skill script that already stores its source as UTF-8;
  • pass structured JSON generated by a UTF-8 script, not handwritten Chinese snippets from the shell command.
• Use encoding="utf-8" or encoding="utf-8-sig" explicitly when reading or writing JSON, Markdown, HTML, CSV, or text artifacts.
• Before saving Excel after any text write-back, scan the target values for repeated question marks. If found, abort the save or immediately repair before reporting success.
• After saving Excel, reopen the workbook and scan all written cells for repeated question marks. Verification must include 备注, 建联状态, 下次跟进, 客户属性, 客户类型, and generated HTML preview labels when applicable.
• Do not trust a successful SMTP send, workbook save, or preview generation as proof that text is clean. Encoding verification is a separate step.
• When a workbook is locked, write a pending JSON file using UTF-8 and do not handwrite Chinese additions later from PowerShell. The later write-back must consume the pending JSON or a UTF-8 script.

Required verification snippets

Every write-back report should include these counts:

• question_mark_cells: number of workbook cells containing repeated question marks after save.
• question_mark_note_rows: number of note rows containing repeated question marks after save.
• html_question_mark_groups: number of repeated-question-mark groups in generated HTML previews.

If any count is greater than zero, the task is not complete.

Recommended note construction

For email write-back notes, prefer structured data first:

{
  "event": "email_sent",
  "sent_at": "2026-07-29 12:40:58",
  "template_kind": "auto_channel_partner",
  "emails": ["example@company.com"],
  "send_log": "runs/YYYYMMDD/<run_id>/send-log.jsonl"
}

Then render the Chinese note inside a UTF-8 Python module or via Unicode escapes. Do not render it inside a PowerShell command containing raw Chinese.

Standard clean Chinese phrases

Use these meanings consistently when rendering from safe code:

• email send record: 邮件发送记录：... 已按...模板发送至 ...；发送日志：...。
• email status repair: 邮件状态修复：发送日志确认已于 ... 向 ... 发送邮件；原状态为 ...。
• wait for reply: 等待回复
• sent email status: 已发送邮件

Failure handling

If repeated question marks appear:

1. Stop further write-back or sending-related status updates.
2. Backup the workbook before repair.
3. Reconstruct the affected notes from source JSON/send logs, not from the corrupted text.
4. Save and rescan the entire workbook.
5. Only report completion when question_mark_cells = 0.