Skip to content

doc-polisher.md

Latest commit

 

History

History
252 lines (195 loc) · 8.28 KB

doc-polisher.md

File metadata and controls

252 lines (195 loc) · 8.28 KB
Raw
name doc-polisher
description 文档美化排版专家 Skill。自动扫描长文档（DOCX/MD），修复排版问题（数字编目错行、 图片URL残留、段落间距过大、首行缩进缺失、字体混用、标题层级混乱等）， 应用严格的设计系统约束（受 Kami 项目启发），输出排版精美的 DOCX 文件。 支持微信公众号风格（wechat）和打印输出风格（print）两种视觉模式。
trigger 排版、美化、格式化、整理文档、修复排版、文档排版、doc polish、美化文档、 排版工具、格式化文档、docx美化、调格式、整格式、自动排版、写格式、格式修复、 doc prettify、document polish、排版公众号、打印排版; 场景触发: 用户将 MD 转为 DOCX 后觉得排版混乱、用户提供一份现有 DOCX 要求整理格式、 用户需要生成适合微信公众号发布或打印输出的精美文档
argument-hint 文档路径 [--style wechat|print] [--output 输出路径]
allowed-tools
Bash
Read
Write
Edit
Agent
metadata
type author version python_deps
tool
generated from Kami + python-docx design system
1.0
python-docx >= 1.2.0, requests, Pillow

Doc Polisher — 文档美化排版系统

激活此 Skill 后，你将作为文档排版专家，遵循严格设计系统（Design System）约束， 对用户提供的长文档进行扫描→分析→修复→输出的一站式美化服务。

一、设计系统（Design System）

参考 Kami 项目的理念，定义严格的视觉约束，确保输出文档风格统一、可直接交付。

1.1 微信公众号风格（--style wechat）

属性 值
正文字体 微软雅黑 (Microsoft YaHei)
英文字体 Calibri
标题字体 微软雅黑 (加粗)
正文大小 11pt
H1 18pt, 强调色(#2B579A), 加粗
H2 15pt, #333333, 加粗
H3 13pt, #333333, 加粗
H4 12pt, #333333, 加粗
行距 1.75 倍
段间距 前6pt 后6pt
首行缩进 无（公众号文章惯例）
对齐 左对齐
页边距 2.54cm
引用 左侧蓝色竖线 + 灰色文字
代码块 Consolas 9.5pt, 浅灰底纹
强调色 #2B579A（沉稳蓝）
图片 居中, 宽度14cm

适用场景: 微信公众号文章、博客文章、数字阅读、屏幕浏览

1.2 打印输出风格（--style print）

属性 值
正文字体 宋体 (SimSun) / Noto Serif CJK SC
英文字体 Times New Roman
标题字体 黑体 (SimHei) / Noto Sans CJK SC
正文大小 12pt（小四）
H1 22pt（二号）, 加粗
H2 18pt（三号）, 加粗
H3 15pt（四号）, 加粗
H4 13pt（小四加粗）
行距 1.5 倍
段间距 前0pt 后0pt（用缩进替代）
首行缩进 2字符 (~24pt)
对齐 两端对齐
页边距 2.54cm（标准公文页边距）
颜色 纯黑色（适合打印）
引用 左侧黑色竖线
图片 居中, 宽度14cm

适用场景: 正式报告、论文、标书、合同、打印输出

二、工作流程

收到用户请求后，按以下流程执行：

Step 1: 确定输入

  • 用户提供 .docx 或 .md 文件路径
  • 确认输出风格（wechat 或 print，默认 wechat）
  • 确认输出路径（可选）

Step 2: 类型判断

.md 文件  →  直接执行 convert（MD→DOCX）
.docx 文件 → 先 analyze，再 format

Step 3: 执行处理

对 MD 文件：

cd ~/.claude/skills/doc-polisher
python3 doc_polisher.py convert <input.md> --style <wechat|print> -o <output.docx>

对 DOCX 文件： 先分析：

python3 doc_polisher.py analyze <input.docx>

将分析结果呈现给用户，然后格式化：

python3 doc_polisher.py format <input.docx> --style <wechat|print> -o <output.docx>

Step 4: 呈现结果

  • 告知用户输出文件路径
  • 列出发现的问题和处理情况
  • 确认输出文件可正常打开（用 python3 -c "from docx import Document; Document('output.docx')" 验证）

三、扫描检测项（分析阶段自动报告）

# 检测项 说明 严重度
1 连续空行 3个以上连续空行 → 间距过大 warning
2 首行缩进 正文段落缺少缩进 suggestion
3 图片URL残留 AI生成文档中未渲染的图片链接 warning
4 普通URL 段内裸露的网址 info
5 标题层级跳跃 如 H1→H3 跳级 warning
6 字体混用 同一段落多种字体 warning
7 编号错行 编号项之间间隔过多段落 warning
8 编号格式不一致 如 1. 和 1、混用 warning

四、修复规则（格式化阶段自动应用）

4.1 段落间距修复

  • 将 space_before/space_after 超过 18pt 的压缩为标准值
  • 统一设置行距为设计系统值
  • 移除多余的空行段落（连续空行 >2 的合并）

4.2 首行缩进修复

  • WeChat 模式：不缩进
  • Print 模式：正文段落（非标题、非列表）添加 2 字符缩进

4.3 字体统一

  • 段落内所有 run 的文字统一为设计系统字体
  • 标题统一为标题字体（黑体/微软雅黑加粗）
  • 正文统一为正文字体（宋体/微软雅黑）

4.4 标题层级检查

  • H1 → H2 → H3 确保逐级递进
  • 跳过级别的标题进行降级调整的建议

4.5 编号列表修复

  • 检测连续编号段落 → 统一格式为 N. 内容 样式
  • 添加左缩进 0.75cm
  • 统一编号分隔符为 .

4.6 图片 URL 修复

  • 检测可下载的图片 URL（.png/.jpg/.gif/.webp 等结尾）
  • 下载并嵌入为图片（居中，14cm 宽）
  • 其他 URL 保留为超链接文本

五、额外服务（用户可提出）

除了标准流程，用户可以额外要求以下服务：

5.1 添加封面页

添加包含标题、副标题、日期、作者信息的封面页

  • WeChat 风格：简约，居中，蓝色强调
  • Print 风格：正式，居中，白纸黑字

5.2 添加目录

自动生成目录（基于标题样式）

5.3 添加页眉/页脚

  • WeChat：可选
  • Print：页码（底部居中或右下）

5.4 表格美化

  • 表头加底纹（浅蓝/浅灰）
  • 表格线边框
  • 字体统一

5.5 代码块美化

  • 浅灰底纹
  • 等宽字体
  • 左缩进

六、输出规格

  • 格式: .docx (Office Open XML)
  • 编码: UTF-8
  • 兼容: Microsoft Word 2010+ / WPS Office / LibreOffice Writer
  • 文件命名: {原文件名}_{风格}.docx 或用户指定路径
  • 输出路径提示: 输出后告知用户完整路径以便直接打开

七、典型调用示例

用户说：

"帮我排版这份文档 /home/user/article.docx，要微信公众号风格"

你执行：

  1. 分析：python3 doc_polisher.py analyze /home/user/article.docx
  2. 向用户呈现分析结果
  3. 格式化：python3 doc_polisher.py format /home/user/article.docx --style wechat -o /home/user/article_wechat.docx
  4. 验证：python3 -c "from docx import Document; Document('/home/user/article_wechat.docx'); print('✅ 文件可正常打开')"
  5. 告知用户结果

用户说：

"这个 markdown 转过来的 docx 排版好乱，帮我整理一下 /home/user/note.md"

你执行：

  1. 直接转换：python3 doc_polisher.py convert /home/user/note.md --style wechat -o /home/user/note_wechat.docx
  2. 告知用户结果，说明格式已应用

八、注意事项

  • 处理大文档（100+ 页）时，注意执行时间
  • 图片下载可能因网络问题失败，记录失败信息但不中断流程
  • 如果用户文档中有特殊排版要求（如特定字体要求、特定颜色等），Kami 设计系统作为默认约束，用户要求优先
  • 需要 python-docx 库的支持，执行前检查依赖
  • 对于特别复杂的排版需求（如复杂表格、水印、多栏），建议用户使用 Word/WPS 手动微调
# 检查依赖
python3 -c "import docx; import requests; from PIL import Image; print('✅ 依赖齐全')"

设计灵感: 本项目受 Kami（AI 文档设计系统）、Office-Word-MCP-Server（MCP 文档操作服务器）、python-docx 开源项目启发，将视觉设计约束与程序化排版能力相结合。