文档格式化技能

字段说明见 @references/api.md。命令模板见 templates/workflow.sh。可执行入口仍是技能根目录的 main.py，scripts/format_document.py 只转发到同一个入口。

> ⚠️ 最高优先级规则：脚本只执行一次，执行完后立刻展示结果并结束。严禁二次执行、轮询或追加任何额外文字。
> ⚠️ 执行方式强约束：必须前台同步阻塞执行（foreground blocking）。严禁后台异步执行（async/background）、严禁将任务挂起后再回收结果。

能力说明

• 上传 .docx 文档，通过 JSON 配置一键应用格式化（页边距、页眉页脚、页码、h1–h6、正文、目录、表格）
• 同步接口：一次请求直接返回格式化后的 .docx 文件，无需异步轮询
• 除文件路径外，样式参数都有默认值，都不是必填。用户没提到的项直接用默认值，不要追问
• 默认只保存到本地（原文件同目录的 formatted_*.docx）。不要探测网盘，不要提示用户开通网盘
• 只有用户明确说要保存到网盘、同步网盘、上传网盘时，才追加 --save-to-cloud

面向终端用户的表达（默认）

> 默认不要把命令行写给用户。 只引导用户：提供待美化的 Word（.docx）路径或上传文件、确认字体/字号/目录等选项（可用上文询问模板）；不要列出 python main.py、--file-path 等命令，除非用户明确索要命令行。

与「仅输出脚本结果」的关系： 格式化完成后的 脚本 stdout 须原样展示；衔接话术不必夹命令。

微信登录认证

• 没有可用 Token 时，运行本技能目录里的 python wx_login.py。几秒内命令结束，浏览器在后台继续等扫码，最长 5 分钟。二维码和这个后台浏览器绑在一起，浏览器一关码就失效。
• 只让用户扫二维码，不要提供浏览器登录链接。有的客户端打不开技能目录里的图片时，按下面顺序给图，不要只发文件路径：
  1. 把脚本输出里 WECHAT_QR_MARKDOWN: 后面的整行原样放进回复。这是内嵌二维码，不依赖用户能不能访问脚本所在磁盘。
  2. 本地 PNG 只作为补充。工作目录存在时，脚本还会导出 /workspace/微信登录二维码.png。文件卡片如果没有真正预览出来，就不要再靠路径。
• 不要只用读取工具打开这张 PNG。那样只有助手自己看得到，用户看不到。
• 用户用微信扫码后，必须在手机上点「确认登录」。只扫不点等于没登录。用户表示已经扫码后，再执行原来的业务命令。
• Token 写入 ~/.taitoubiao/token.json，五个技能共用。5 分钟内不要重复启动登录，否则旧码作废。
• 接口返回登录失效时，会清掉缓存并重新出一张码。自动化请设置 TAITOUBIAO_SKIP_AUTO_LOGIN=1。

使用限制

• 仅支持 .docx 格式（不支持旧版 .doc），文件大小上限 300MB
• 同一请求 10 秒内不可重复提交（防重复）

🔴 执行流程（必须遵守）

第 1 步：确认文档路径

从用户消息中提取待格式化的 .docx 文件绝对路径。若用户未提供，主动询问。

第 2 步：只使用用户明确提到的样式

除文件路径外，全部样式都有默认值，都不是必填。

• 用户说「默认」「都默认」「直接格式化」，或只给了文件、没提样式 → 不询问，直接按默认值执行
• 用户只改了某一项（例如「上边距 2.5」「一级标题用三号」）→ 只覆盖该项，其余保持默认，不要把没提到的项再问一遍
• 页码开关和页眉开关是两件事。用户没提页眉时保持关闭；用户没提页码时保持开启

第 3 步：调用脚本（仅执行一次）

根据用户确认的参数拼装命令并执行一次。脚本是同步的，执行完即完成，不需要轮询、不需要等待、不需要重复执行。
并且必须使用前台同步阻塞方式运行，等待该命令在当前回合直接返回 stdout；禁止任何 async/background 运行方式。

执行时必须显式保证不会被系统自动转后台：

• Shell 调用必须设置足够长的阻塞等待时间（建议 block_until_ms >= 600000）
• 禁止 block_until_ms: 0，禁止任何会触发 "An async command you ran earlier has completed" 的调用方式
• 若命令被意外转后台并出现 system completion 消息，视为执行策略错误；下次必须改为长阻塞前台执行，避免用户看到重复回显

第 4 步：展示结果（立即结束）

将脚本 stdout 输出原样展示给用户（见上文「面向终端用户的表达（默认）」：衔接话术可自然语言，报告/结果正文须为脚本原文）。展示完毕后立即结束，不得做任何后续操作，不得再次执行脚本。

调用方式

python skills/document-format/main.py \
  --file-path "/absolute/path/to/document.docx" \
  --body-font "宋体" \
  --body-font-size "小四" \
  --title-font "黑体" \
  --title-font-size "四号" \
  --reset-toc true

> 所有参数都有默认值，仅 --file-path 为必填。其余参数可省略以使用默认值。

脚本参数

默认值（都已填好，都不是必填）

用户没指定时脚本使用下表。不要为了这些项停下来询问。

字号对照（--body-font-size / --title-font-size 可用中文名）

也支持一号、小一、小二。脚本按前端同一套编码提交，五号传 1050。

完整示例

示例 1：全部默认

用户输入：「帮我把 /home/user/投标文件.docx 格式化一下」

不询问样式，直接执行：

python skills/document-format/main.py \
  --file-path "/home/user/投标文件.docx"

示例 2：用户指定部分参数

用户输入：「格式化 /data/报告.docx，正文用仿宋，一级标题用三号，上边距 2.5 厘米，页眉写公司名称」

只覆盖提到的项，其余默认，不追问：

python skills/document-format/main.py \
  --file-path "/data/报告.docx" \
  --body-font "仿宋" \
  --h1-font-size "三号" \
  --top-margin 2.5 \
  --header-mode text \
  --header-text "公司名称"

示例 3：用户一次性提供所有参数

用户输入：「格式化 /docs/方案.docx，正文用微软雅黑 小四，标题用黑体 四号，不重建目录」

无需询问，直接执行：

python skills/document-format/main.py \
  --file-path "/docs/方案.docx" \
  --body-font "微软雅黑" \
  --body-font-size "小四" \
  --title-font "黑体" \
  --title-font-size "四号" \
  --reset-toc false

🚫 输出规范

> ⚠️ 核心原则：模型必须只输出脚本返回的原始结果，严禁自行生成中间状态或进度摘要。

✅ 正确：默认只保存本地（用户没有提到网盘）

# 文档格式化结果

- **原始文件**：`投标文件.docx`
- **输出文件**：`formatted_投标文件.docx`
- **工具区路径**：`/workspace/formatted_投标文件.docx`
- **文件大小**：1,234,567 字节

✅ 格式化完成，文档已保存到本地。

完整版功能欢迎访问taitoubiao.com免费体验

> 默认成功文案必须固定为：✅ 格式化完成，文档已保存到本地。
> 用户没有要求网盘时，禁止输出开通网盘、同步网盘、文件空间下载等提示。

✅ 正确：用户明确要求保存到网盘且保存成功

✅ 格式化完成，文档已保存到本地，并已同步到个人网盘。

> 禁止追加任何目录说明或括号补充（例如：（arkdrive_user_uploads目录））。

✅ 正确：用户明确要求网盘，但本机没有可用网盘

✅ 格式化完成，文档已保存到本地。

> ⚠️ **未检测到个人网盘**：文件已保存到本地，未能同步至个人网盘。
> 如需使用网盘，请单击聊天框上方的"网盘"按钮 → "立即授权并创建"开通个人网盘后，再说明要保存到网盘。

🚫 禁止：自行生成中间状态或添加额外文字

• ❌ 不得在脚本输出前后添加任何解释、总结、路径说明或下载指引
• ❌ 不得输出"正在格式化中..."、"格式化已完成，请查看文件"、"你可以直接从该路径下载使用"
• ❌ 不得添加 JSON 配置、摘要或额外说明
• ❌ 不得把 system completion / exec completed 这类系统消息再整理成第二遍结果返回
• ❌ 用户未要求网盘时，不得输出开通网盘、同步网盘或“未检测到个人网盘”
• ❌ 网盘保存成功时，不得把成功文案改写为“已自动保存到个人网盘（xxx目录）”或任何带目录括注的变体
• ❌ 不得在展示完脚本结果后输出 "NO"、"完成"、"有什么需要修改的吗" 等任何后续文字
• ❌ 展示完脚本 stdout 后立即停止，不做任何追加

异常处理