操作手册 Word 生成器
生成用户操作手册/使用指南 .docx。核心特点是步骤化指令 + 三类彩色提示框 + 截图标注规范。所有层级标题统一黑色加粗。
触发条件
- 用户要求生成"操作手册"、"使用指南"、"用户手册"、"user manual"、"operation guide"
- 用户需要将某个系统/工具的操作流程文档化
标准结构
- 封面 — 手册名称、版本号、适用系统/版本、日期
- 概述 — 本文档目的、适用范围、前置技能要求
- 环境准备 — 软硬件要求、安装步骤、账号权限
- 操作步骤 — 按模块分组，每步 Step 编号 + 截图标注 + 预期结果
- 验证方法 — 操作→预期结果→验证方式对照表
- 故障排除 — 常见错误 + 解决方法
- 附录 — 术语表、快捷键、相关文档
环境
/home/ubuntu/.venv-docx/bin/python generate_manual.py
排版组件
标题（全部黑色加粗）
BLACK = RGBColor(0x00, 0x00, 0x00)
def h1(doc, text): # 一级：18pt
add_p(doc, text, fs=18, bold=True, color=BLACK, sb=12, sa=10)
def h2(doc, text): # 二级：15pt
add_p(doc, text, fs=15, bold=True, color=BLACK, sb=10, sa=8)
def h3(doc, text): # 三级：13pt
add_p(doc, text, fs=13, bold=True, color=BLACK, sb=8, sa=6)
三类提示框（操作手册核心元素）
def TIP(doc, text):
"""💡 正向提示——浅黄底 #FFF8E1"""
p = doc.add_paragraph()
pPr = p._element.get_or_add_pPr()
add_element_shading(pPr, 'FFF8E1')
run = p.add_run('💡 提示：' + text)
run.font.size = Pt(10); run.font.name = '微软雅黑'
run.element.rPr.rFonts.set(qn('w:eastAsia'), '微软雅黑')
def WARN(doc, text):
"""⚠️ 危险警告——浅红底 #FFEBEE，深红文字"""
p = doc.add_paragraph()
pPr = p._element.get_or_add_pPr()
add_element_shading(pPr, 'FFEBEE')
run = p.add_run('⚠️ 警告：' + text)
run.font.size = Pt(10); run.font.name = '微软雅黑'
run.element.rPr.rFonts.set(qn('w:eastAsia'), '微软雅黑')
run.font.color.rgb = RGBColor(0xC6, 0x28, 0x28)
def NOTE(doc, text):
"""📌 中性说明——浅蓝底 #E8F0FE"""
p = doc.add_paragraph()
pPr = p._element.get_or_add_pPr()
add_element_shading(pPr, 'E8F0FE')
run = p.add_run('📌 说明：' + text)
run.font.size = Pt(10); run.font.name = '微软雅黑'
run.element.rPr.rFonts.set(qn('w:eastAsia'), '微软雅黑')
run.font.color.rgb = RGBColor(0x1A, 0x56, 0xDB)
三种提示框的使用场景：
| 类型 | 用途 | 示例 |
|------|------|------|
| 💡 TIP | 操作技巧、快捷方式、推荐做法 | "你也可以用 Ctrl+P 快速打开" |
| ⚠️ WARN | 危险操作、数据丢失风险、不可逆步骤 | "执行前请备份数据库" |
| 📌 NOTE | 背景知识、版本差异、补充说明 | "此功能需要管理员权限" |
步骤块（操作手册核心）
def step(doc, number, desc_text, screenshot_hint=None, expected_result=None):
"""操作步骤块：Step 编号 + 操作指令 + 截图标注提示 + 预期结果"""
h3(doc, f'Step {number}')
add_p(doc, f'【操作】{desc_text}', fs=11, bold=True, sa=4)
if screenshot_hint:
add_p(doc, f'[ 截图标注：{screenshot_hint} ]', fs=9,
color=RGBColor(0x88, 0x88, 0x88), align=C, sa=4)
if expected_result:
NOTE(doc, f'预期结果：{expected_result}')
使用示例：
step(doc, 1,
'点击左侧导航栏「系统设置」菜单',
'红框标注「系统设置」菜单位置',
'页面右侧出现设置面板，默认显示「基本设置」标签页')
step(doc, 2,
'在「安全配置」区域，勾选「启用双因素认证」复选框',
'红框标注复选框位置',
'复选框变为选中状态（蓝色对勾）')
操作-验证对照表
关键操作步骤结束后放一张对照表：
# 表头：操作 | 预期结果 | 验证方法
verify_table(doc, [
['操作', '预期结果', '验证方法'],
['点击「保存」', '弹出绿色提示「保存成功」', '检查页面顶部提示条颜色'],
['重启服务', '服务状态变为「运行中」', '执行 systemctl status xxx'],
['上传文件', '文件列表出现新文件', '刷新页面，检查文件列表第一行'],
])
代码块（终端命令等）
def code(doc, text):
"""灰底 #F5F5F5 + Consolas 9pt + 蓝色左边框"""
p = doc.add_paragraph()
p.paragraph_format.left_indent = Cm(0.8)
pPr = p._p.get_or_add_pPr()
set_shading(pPr, 'F5F5F5')
# 蓝色左边框
pBdr = OxmlElement('w:pBdr')
left = OxmlElement('w:left')
left.set(qn('w:val'), 'single')
left.set(qn('w:sz'), '12')
left.set(qn('w:space'), '4')
left.set(qn('w:color'), '2B579A')
pBdr.append(left); pPr.append(pBdr)
run = p.add_run(text)
run.font.name = 'Consolas'; run.font.size = Pt(9)
run.font.color.rgb = RGBColor(0x33, 0x33, 0x33)
封面
for _ in range(8):
doc.add_paragraph()
add_p(doc, manual_name, fs=28, bold=True, color=BLACK, align=C, sa=4)
add_p(doc, f'版本：{version} | 适用系统：{platform}', fs=12,
color=RGBColor(0x88, 0x88, 0x88), align=C, sa=20)
DIV(doc)
add_p(doc, f'编制：{author} 日期：{date_str}', fs=11,
color=RGBColor(0x99, 0x99, 0x99), align=C)
语言风格铁律
操作手册语言必须严格遵守以下规则：
- 动词开头：用祈使句——「点击保存」不用「用户需要点击保存」
- 第二人称：用「你」不用「用户」——「你可以…」不用「用户可以…」
- 一致性：同一概念全文统一术语，不要「登录」和「登陆」混用
- 简洁：删除冗余修饰词——「输入密码」不用「请输入您的密码」
- 主动语态：「系统弹出提示」不用「提示被系统弹出」
截图标注规范
- 关键操作必须有截图（用户提供截图文件时嵌入，无截图时用占位符
[截图标注：xxx]） - 标注：红色框线(
#E74C3C)圈出点击目标，蓝色箭头(#2B579A)指向关键元素 - 截图工具：推荐 Snipaste（标注）、ShareX
生成流程
- 向用户确认：手册名称、版本、系统平台
- 用户提供操作内容（文字描述 + 截图文件路径（可选））
- 写 Python 生成脚本到 ~/generate_manual.py
/home/ubuntu/.venv-docx/bin/python ~/generate_manual.py- 验证文件存在 → 复制到 ~/sync/ → MEDIA: 发送
注意事项
- 标题全部黑色，不要用蓝色
- 每个 run 都要设
qn('w:eastAsia')中文字体 - 步骤编号用「Step 1」「Step 2」或「① ② ③」，不要阿拉伯数字裸编号
- TIP/WARN/NOTE 三种提示框颜色不同，不要混用
- 操作-验证对照表放在每个模块末尾
- 如有截图文件，嵌入后加图题「图 X-1 操作界面」
