从截图生成用户手册 / 截图 → 用户手册
输入：截图 + 一份示例手册。输出：一份模仿示例手册风格和结构，但内容来自截图的全新用户手册。
输入：screenshots + one example manual。输出：a new manual that copies the example's style and structure while its content comes from the images。
本文件为双语：指令为中文，关键规则也以英文重复。生成的手册语言为用户要求的语言；如果未指定，则使用参考手册的语言。
1. 输入 / Inputs
| 输入 | 必需 | 备注 |
|---|---|---|
| 截图 | ✅ | 文件夹或文件列表。排序提示：文件名、时间戳、EXIF。 |
| 示例用户手册 | ✅ | .pdf, .docx, .md, .txt, .html。是风格和结构的来源。 |
| 产品/流程名称 | ➖ | 如果没有，则从屏幕内容推断，并向用户确认。 |
| 目标受众和语言 | ➖ | 如果没有，则从参考手册推断。 |
| 输出格式 | ➖ | 默认：Markdown（可选 .docx / 可打印的 .html）。 |
| 品牌信息 | ➖ | 公司、文档编号、修订版本——如果没有提供，则保留占位符。 |
对于缺失的信息，先尝试推断，然后才提问。只询问那些无法从屏幕和参考手册中推断出的信息；最多问3个问题。
先推断再提问。最多问3个问题，仅限于图片和参考手册无法回答的内容。
信息优先级 / Source priority
如果存在矛盾，按此顺序决定——优先级高的胜出：
- 用户明确提供的信息
- 截图
- 机器/产品照片
- 参考手册的模板信息
- 通用技术知识（仅可在必须避免留空占位符时使用；不算捏造，但需要确认）
冲突时：用户明确陈述 > 截图 > 照片 > 参考模板 > 通用知识。
两种模式 / Two modes
| 模式 | 何时使用 | 保留什么 |
|---|---|---|
| 样式模式 | 参考文件是简单的 .md/.txt | 标题布局、步骤语气、警告格式 |
| 模板模式 | 参考文件是企业级 PDF/DOCX（包含封面、目录、页眉、文档编号） | 章节顺序、编号、文档标识、表格/警告格式完全保留；内容用真实产品信息填充 |
模板模式下不要复制PDF。 将模板作为骨架，内容从截图生成。如果章节已存在，则保留并完善；如果缺失，则按照文档设计添加新章节。
在模板模式下：保持章节顺序、编号和文档标识；绝不复制PDF中的句子——用截图显示的内容填充。
2. 输出 / Outputs
<输出文件夹>/
├── kilavuz.md # 主要交付物——新用户手册
├── images/ # 复制并重命名的截图
├── kilavuz.html # （可选）浏览器可打印版本
├── kilavuz.docx # （可选）Word版本
└── 00-analiz.md # 工作笔记：屏幕清单 + 样式契约
00-analiz.md不是交付文档，而是可审计的凭证：显示哪个屏幕去了哪个步骤，以及从参考文档中采用了哪个样式决策。始终生成它。
3. 工具映射 / Tool mapping
本技能并非针对特定工具编写。请使用你手头对应的工具：
| 需求 | Claude Code | Cursor | Codex / DeepSeek Harness | 其他 |
|---|---|---|---|---|
| 查看图像 | Read (图像) | Read | read_image | 将图像附加到消息中 |
| 写入文件 | Write / Edit | Write | write / edit | 编辑器 |
| 运行脚本 | Bash | 终端 | pwsh / bash | 终端 |
读取 .docx / .pdf | Bash + python | 终端 | pwsh + python | python |
关键： 必须实际查看图像。不要根据文件名或你之前知道的界面来猜测内容。
始终实际查看图像。永远不要根据文件名推断屏幕内容。
4. 工作流 / Workflow
使用此清单跟踪进度：
- [ ] 1. 收集并验证输入
- [ ] 2. 从参考文档提取样式契约
- [ ] 3. 逐张读取每张截图
- [ ] 4. 将屏幕排列成流程，标记空白
- [ ] 5. 编写手册
- [ ] 6. QA关卡 —— `check_manual.py`
- [ ] 7. 交付（+ 可选的 docx/html）
步骤 1 — 收集并验证输入 / 收集并验证
- 列出截图文件；报告数量和格式。
- 读取参考手册（
.docx→ python-docx,.pdf→ pypdf/pdftotext，纯文本 → 直接读取）。 - 如果存在无法读取或损坏的文件，立即告知，不要静默跳过。
- 确定输出文件夹并创建
images/子文件夹。 - 复制图像： 将要在手册中使用的每个屏幕截图复制到
images/下。保留命名（例如01-giris.png→images/01-giris.png）；如果重命名，QA脚本会通过内容哈希匹配，但为确保顺序，保留名称更安全。不要写入相对于原始文件夹的路径。
列出每张截图，读取参考手册，报告无法读取的文件，创建输出文件夹，然后将每张截图复制到 images/ 中，保留其文件名。永远不要链接回原始的截图文件夹。
步骤 2 — 从参考文档提取样式契约 / 提取样式契约
先测量，再解释：
python <技能目录>/scripts/read_reference.py <示例手册> \
--out 00-analiz-referans.md --json 00-analiz-referans.json
该脚本从PDF/DOCX/MD中提取一个可测量的配置文件：文档元数据、标题层级、编号深度、每页重复的页眉/页脚（文档编号、修订版本）、图表/表格标题模式、字体大小和颜色。将输出传输到 reference/style-contract.md 表格中。
read_reference.py 需要PyMuPDF来读取PDF，需要python-docx来读取DOCX；如果两者都不可用，则向用户请求 .md/.txt 版本（脚本会打印安装命令）。
你不会复制参考手册的内容，而是复制其格式。填充 reference/style-contract.md 文件中的字段，并将其写入 00-analiz.md：
- 标题层级和编号（
1.,1.1,步骤 1,章节） - 步骤句子的语气（祈使句，还是“请点击”，还是“点击”）和长度
- 截图放置：在步骤之前还是之后，是否有标题，是否编号
- 警告/提示框的类型（注意、警告、提示、小心）及其标记格式
- 表格、列表、粗体文本的使用
- 前页部分：封面、版本、日期、目录
- 后页部分：常见问题、故障排除、术语表
- 语气：正式/亲切，用“您”还是“你”
- 术语表（参考文档使用的命名）
- 文档标识： 文档编号、修订版本、日期、公司信息块（在模板模式下完全保留；如果值未知，则保留占位符）
- 编号深度： 如果参考文档使用4个层级，如
6.5.1.1，则新手册也使用相同的深度
提取形式，而非内容：层级、编号、步骤语气、图像放置、标注类型、表格、前/后页内容、语气、术语、文档标识。
步骤 3 — 逐张读取每张截图 / 读取每张截图
对每张图像，根据 reference/screenshot-analysis.md 模式进行记录：
| 字段 | 示例 |
|---|---|
| 文件 | 03-ayarlar.png |
| 屏幕/页面名称 | 设置 |
| 可见的主要组件 | 左侧菜单、保存按钮、语言下拉列表 |
| 执行的操作 | 从“语言”下拉列表中选择中文 |
| 状态 | 之前/之后/中间步骤 |
| 高亮/箭头/框 | 红色框标注在“保存”按钮上 |
| 无法读取/模糊不清 | 字段名称模糊 → [?] |
| 步骤编号（草稿） | 4 |
禁止捏造： 不要编写屏幕上不存在的按钮名称、菜单路径、字段标签或错误信息。如果不确定，请放置 [?] 并添加到“未解决问题”部分。
界面/HMI手册中每个屏幕的描述块。 对每张截图，编写以下五个部分（操作员文档中预期的结构）：
### <屏幕名称>
**目的。** 此屏幕的用途 —— 1-2句话。
**屏幕上的信息。** 显示的数值、指示灯、状态颜色。
**按钮功能。**
| 按钮 | 功能 | 说明 |
|---|---|---|
**操作员使用。** 逐步操作步骤。
**注意。** 如果存在误用风险，则发出警告；如果没有，则不写此行。
使用参考文档的模式添加标题（例如 图 12 – 交流电机页面）。通过编号描述图像中的重要元素（1 – 启动, 2 – 停止），但不要缩小到影响可读性或覆盖图像。
对于UI/HMI手册，使用五部分块描述每个屏幕：目的、显示值、按钮表格、操作步骤、注意事项。仅在提高清晰度时对标注进行编号。
永远不要捏造图像中不可见的按钮标签、菜单路径、字段名称或信息。用 [?] 标记不确定性，并将其列在“未解决问题”下。
步骤 4 — 将屏幕排列成流程 / 排序成流程
- 使用排序信号：文件名编号 → 时间戳 → 屏幕状态（之前/之后）→ 逻辑流程。
- 将屏幕分组为章节（例如 安装、初始设置、日常使用）。
- 标记空白： “从步骤1到步骤3时缺少中间屏幕”等。不要捏造缺失的步骤；向用户请求或写入“未解决问题”部分。
- 每个屏幕精确关联到一个步骤。如果同一个屏幕描述多个步骤，则在单个步骤中使用该图像，并在文本中引用另一个步骤。
按文件名 → 时间戳 → 之前/之后状态排序。分组到章节。标记空白而不是捏造步骤。一个截图恰好映射到一个步骤。
步骤 5 — 编写手册 / 起草手册
获取 templates/manual-template.md 骨架，用步骤2中的样式契约填充。规则：
- 每个步骤 = 一个操作 + 显示该操作的一张截图。
- 步骤文本要简短：1-3句话。如果需要原因/理论，则将其移到单独的“为什么？”备注中。
- 图像路径是相对且可移植的：
。使标题符合参考文档的格式。 - 保持标题和编号与参考文档相同的方案；从屏幕获取内容。
- 严格使用参考文档术语表中的术语——不要捏造同义词。
- 如果参考文档中存在前页部分（标题、版本、目标受众）和后页部分（常见问题、故障排除、术语表），则添加；否则不添加。
- 任何无法从屏幕验证的信息都会被标记：短期不确定性用
[?]，缺失信息则从reference/placeholders.md中使用描述性占位符（[由制造商填写]、[需要验证]…）。 - 在手册末尾添加 “未解决问题 / 未解决的问题” 部分（如果为空，则写“无”）。此部分是QA附录，不是参考文档风格的一部分；用户可以在发布准备时删除它。在交付消息中说明这一点。
- 区分操作员和技术服务信息。 PLC编程、标签名称、伺服参数、软件算法和通信细节不属于提供给操作员的主要部分；如果需要，则在“技术服务/维护人员”标题下打开单独的部分。
一个步骤 = 一个操作 + 一张截图。相对图像路径。镜像参考文档的编号和术语。用 [?] 标记不可验证的声明。
步骤 6 — QA关卡 / QA关卡
从项目根目录运行命令，并给出相对于技能文件夹的脚本路径——脚本和手册位于不同的文件夹：
python <技能目录>/scripts/check_manual.py <输出>/kilavuz.md \
--screenshots <屏幕文件夹> --reference <示例手册.md>
脚本检查：图像路径是否存在、每个屏幕是否至少使用一次（通过名称或内容哈希）、标题/章节编号是否连续、步骤编号是否一致（全局或按章节）、是否有 TODO/XXX/<占位符> 残留、[?] 标记是否在“未解决问题”部分中、以及有多少字段占位符等待填充。
如果存在错误，则修复并重新运行。在通过之前不要交付。
不要将 .docx/.pdf 作为 --reference 传递；先用 read_reference.py 提取配置文件以进行样式比较（脚本会以此作为警告说明）。
运行检查器；修复并重新运行，直到通过。不要交付未通过检查的手册。
步骤 7 — 交付 / 交付
kilavuz.md+images/+00-analiz.md已就绪。- 如果需要：
python <技能目录>/scripts/convert.py <输出>/kilavuz.md --format docx,html（如果--out指向其他文件夹，则图像也会复制到那里；--lang确定HTML语言）。- 对于
.docx，需要 python-docx；如果不可用，脚本会打印安装命令。 .html始终可以生成，并且可以通过浏览器 Ctrl+P → PDF 打印。
- 对于
- 在模板模式下，将文档编号/修订版本放在
.docx页眉中，将页码放在页脚中（参见convert.py --doc-no,--header,--footer）。 - 在交付消息中：多少张截图、多少个步骤、多少个章节、多少个
[?]、多少个字段占位符，以及如果缺少屏幕，则列出清单。
5. 硬性规则 / 硬性规则
- 不查看就不写。 实际查看每张截图；不要从文件名推断内容。
- 禁止捏造。 不要编写屏幕上不存在的标签、菜单、消息、版本或数字。
- 形式来自参考文档，内容来自屏幕。 不要复制参考手册的句子。
- 让不确定性可见。 使用
[?]+ “未解决问题”部分；不要静默猜测。 - 一个截图 = 一个步骤。 没有图像被闲置不用。
- 可移植的路径。 使用
images/...相对路径；不要编写绝对Windows路径。 - 用户的语言。 手册语言是用户要求的语言；不是技能指令的语言。
- 报告缺失的输入。 如果存在无法读取的文件或缺失的中间屏幕，请告知。
- 如果无法查看，则停止。 如果你没有图像查看能力（工具不支持或模型不支持图像），则不要开始编写手册。告知用户在此会话中无法读取图像，并请求一个具有图像处理能力的会话。禁止根据文件名猜测内容。
1 不查看就不写。2 永远不要捏造UI。3 形式来自参考文档，内容来自图像。4 用 [?] 或显式占位符表示不确定性。5 一个截图 = 一个步骤，没有未使用的。6 相对图像路径。7 手册语言 = 要求的语言。8 报告问题。9 如果无法查看，则停止。