extract-attachments

概述

<extract-attachments>

<objective>

目标:

• 对输入的 DOCX 文件执行附件提取，提取所有嵌入的媒体文件（图片、音频、视频等）、嵌入对象（word/embeddings/）和 OLE 对象（word/oleObjects/），自动检测文件真实类型，支持段落章节上下文定位。
• 不在范围之内做的事:
  • 不支持 DOCX 以外的文档格式（如 .doc、.pdf）
  • 不对提取后的附件内容做语义分析、格式转换或二次编辑（EMF→PNG 转换除外）
  • 不支持 WORD 宏文件（.docm）、加密或密码保护的 DOCX 文件
  • 不合并多个 DOCX 的附件为一个输出目录

</objective>

<process>

流程强制约束（必须遵守）

• Step 执行规则：Step 必须按 Step 1→Step 2 的顺序执行，不得跳过、合并或重排。Step N 的准入条件依赖 Step N-1 的产出物，跳过 Step N-1 将导致 Step N 无法执行。
• 规则优先级：本 SKILL 的强制规则具有最高优先级；references/ 文件仅用于补充业务细节、参数说明和脚本用法，不得覆盖、弱化或绕过本 SKILL 的强制规则；当 references/ 默认行为与本 SKILL 强制规则冲突时，必须以本 SKILL 强制规则为准；不得以 reference 默认行为、经验判断或执行便利性为理由绕过本规则。
• 错误终止命中约定：<error> 用于流程未能按本 SKILL 要求完成的情况。只要当前流程命中 <error> 中定义的任一错误类型 E01、E02、E03 至 E08，必须立即停止当前流程，进入 <error>，并严格使用"错误输出卡片"模板作为唯一最终回复；不得在错误输出卡片前后追加分析、解释、建议、追问或自定义内容；不得继续调用工具、写入文件、补救、重试或执行后续步骤。

执行步骤

Step 1 – 参数收集与确认

• 准入条件：

• 无（流程起始步骤）
• 操作：

• 依据 <input> 章节的规范要求执行本 Step 相关操作
• 仅加载 templates/input.schema.json 获取参数规范；禁止加载任何 reference 文件
• 分析用户输入，收集参数，完成 required 字段收集与校验
• 按 <input> 模板展示参数确认卡片
• 质量门禁：

• 所有操作均已按顺序执行完成
• 所有缺失的 required 字段均已向用户追问且在确认卡片中展示
• <input_path> 为绝对路径且已完成文件存在性检查
• 产出：

• 最终生效参数集
• 参数确认卡片

Step 2 – 工具选择与执行

• 准入条件：

• Step 1 已按顺序完成全部操作，参数确认卡片已展示
• Step 1 完成后必须立即自动进入 Step 2，不得等待用户确认、追问或额外输入。参数确认卡片展示即视为 Step 1 已完成，立即开始执行 Step 2 操作，无需用户回复"继续"、"确认"或任何形式的手动触发。
• 操作：

• 依据 <tools> 章节的规范要求执行本 Step 相关操作
• 加载 references/extract-attachments.md
• 按已加载 reference 文件「依赖项检查」章节执行依赖检查
• 按已加载 reference 文件「参数说明」章节执行工具命令
• 按 reference 文件「质量检查命令」章节执行输出完整性检查
• 按 reference 文件「质量检查命令」章节执行文件类型正确性检查
• 依据 <output> 章节的规范要求生成完成卡片
• 质量门禁：

• Step 2 操作均已按顺序执行完成
• 对应 reference 文件已加载、依赖项检查全部通过
• 业务执行 exit code 0，<output_dir> 目录已就绪
• 输出目录包含有效提取文件、文件类型正确
• 完成卡片与质量检查结果保持一致
• 产出：

• 提取后的附件文件（<output_dir> 目录）
• 段落章节上下文映射结果（extract-attachments-result-{timestamp}.json）
• 完成卡片

</process>

<input>

强制规则（必须遵守）：

• 参数定义依据：具体上下文变量定义见 templates/input.schema.json。通过分析用户输入确定参数取值，required 参数必须完成收集与校验，若缺失则必须追问用户并在确认卡片中展示；optional 参数按 schema 默认值静默处理，无需追问或向用户逐一收集。
• input_path 提取约定：<input_path> 只能由用户原始输入或用户确认内容中清晰标出的完整路径唯一提取而来；不得通过 cwd/pwd、当前工作目录、workspace 路径、环境变量、历史记忆、目录枚举、相似目录搜索或模型猜测补全。无法唯一提取 <input_path> 时，必须立即停止；不得继续读取 schema、reference 等相关文件，不得执行路径拼接、路径规范化、路径检查或目录枚举；最终回复必须且只能输出：无法从输入中确定完整路径，请用双引号、代码块、单独一行或"路径：..."提供完整路径。
• input_path 路径检查约定：Step 1 仅允许对已明确形成的 <input_path> 做一次存在性检查；若检查结果为不存在或不可访问，必须停止并请求用户确认正确路径，不得进入 Step 2，不得输出错误输出卡片，禁止检查父目录、兄弟目录、子目录或相似目录，禁止使用 dir、ls、find 等命令排查路径。
• 相对路径约定：针对于参数中的相对路径，需调用 cwd 命令转换为绝对路径。所有路径参数必须使用已解析的绝对路径并以双引号包裹；不得使用环境变量、~ 或其他路径简写形式。
• 参数确认卡片模板如下：

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  # 参数确认 ✓
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ## 📂 最终输入预览
  | Item | Value |
  | --- | --- |
  | Input Path | [input_path] |
  | Output Dir | [output_dir] |

</input>

<tools>

强制规则（必须遵守）：本节列出的所有规则均为强制执行约束，违反即视为执行失败（触发 <error> 的 E08）。所有结论必须来自真实工具输出或已加载 reference 文件中的明确说明，不得虚构未发生的工具调用、参数、返回值或文件清单。

• 禁止自写逻辑：凡属附件提取、BIN 文件解析、文件类型检测、文件名安全清理、段落上下文定位、质量审查的逻辑，绝对禁止用以下任何方式自行实现：
  • python -c "..." 内联脚本
  • 写入临时 .py/.sh 文件
  • 正则匹配、zipfile/olefile/lxml 标准库调用
  • 拆成多条 exec 组合管道
  • 所有业务逻辑均已沉淀到 scripts/extract_attachments.py 中
  • 遇到任何问题（文件大、嵌入对象多、编码异常、路径超长）都不得绕过脚本自行编写，必须先检查是否正确应用了编码前缀、依赖是否完整。
  • 唯一例外：已加载 reference「依赖项检查」中明确写出的 python -c "import …" 检查命令，以及「质量检查命令」中明确写出的检查命令。
• 文件写入限制：除 业务执行命令序列 产生的文件外，大模型不得写入其他任何文件，除非用户明确要求。
• Python 环境一致性约定：根据当前操作系统执行对应命令：Windows 执行 Write-Output "PYTHON=$env:PYTHON"；Linux/macOS 执行 printf 'PYTHON=%sn' "$PYTHON"，将 <Python解释器> 解析为环境变量 PYTHON 指向的绝对文件路径。执行脚本时，必须始终使用该解释器，不得切换到其他 Python 环境。如若 PYTHON 缺失、为空或不是绝对路径，必须按 <error> 的 E03 处理。禁止退回使用裸 python、python3。
• 命令编码限定：所有 Shell 命令执行前，必须确保 UTF-8 编码。Windows 终端默认代码页为 GBK（CP936），含中文的路径、参数或内联脚本在非 UTF-8 终端中会被错误解码导致乱码。按当前 Shell 选择对应前缀：
  • PowerShell：[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; $env:PYTHONUTF8=1; <命令>
  • CMD：chcp 65001 > nul && set PYTHONUTF8=1 && <命令>
  • Bash（Linux）：PYTHONUTF8=1 <命令>
  • Zsh（macOS）：PYTHONUTF8=1 <命令>
  • 编码前缀是强制性的，不是可选优化项。Windows 终端下不加前缀必然导致含中文路径/内容的乱码。若使用前缀后仍然乱码，检查是否误用了不匹配的 Shell 前缀（如在 PowerShell 环境使用了 CMD/Bash 前缀）。
• 检查类命令执行约定：路径检查、依赖检查、--help 可用性检查等检查类命令必须使用 background=false 前台执行。检查类命令必须设置 timeout=60秒，禁止执行常驻命令，禁止交互式执行。检查失败按 <error> 对应条目处理；<input_path> 路径检查失败按 E02 处理；依赖或可用性检查失败按 E03 处理；检查命令超时按 E05 处理；违反检查边界按 E08 处理。
• 业务命令执行约定：
  • 附件提取（extract_attachments.py）：必须使用 background=true 后台托管运行，不得使用 background=false 前台执行。
    • 启动时设置 yieldMs=2秒、timeout=600秒，并保存 sessionId；一次用户请求只能启动一个业务后台任务，后续 process 操作只能作用于该 sessionId。
    • 启动后仅允许使用 process(action="poll") 轮询状态，每次 timeout=60秒。
    • 仅在任务仍运行且需要查看过程输出时，允许使用 process(action="log") 增量读取日志，每次设置 limit=200 和递增 offset。
    • 状态为 completed 且 exit 0 后，进入质量审查。
    • 状态为 failed、timeout、cancelled，或出现命令失败、结果文件缺失、等待交互、结果不可用等异常时，必须按 <error> 的对应错误类型处理。
    • 禁止使用 submit；禁止启动第二条业务命令、提高 timeout、改写命令、替代执行或自行补救；仅异常时允许 kill 当前 sessionId。
  • 质量审查：前台运行，timeout=60秒。
  • 业务脚本调用限制：业务脚本只能作为完整命令执行一次。禁止单独预运行、调试或重复执行业务脚本。业务脚本失败或结果不符合要求时按 E04 处理，越界补救或重试按 E08 处理。
  • 超时处理约定：前台执行返回 timed out 或超过规定时间上限时，必须按 <error> 的 E05 处理；禁止提高 timeout 重试、启动替代命令或继续执行后续步骤。
• 选择与集成逻辑规则：本 SKILL 领域知识封装在 references/ 文件中，根据操作类型确定加载的 reference 文件路径：

• 所选 reference 文件是对应业务操作、参数映射、依赖检查和命令用法的唯一事实来源。
• 必须严格执行所选 reference 文件声明的操作与参数约束；不得自行补写、简化、替换或重新推导业务参数。
• reference 文件缺失、读取失败、内容截断、能力不匹配或与本 SKILL 强制规则冲突时，必须按 <error> 的 E03 处理。

</tools>

<output>

强制规则（必须遵守）：

• 仅当业务命令成功返回、质量审查通过，且结果与用户意图和 <output> 模板一致时，才允许进入 <output>；否则必须按 <error> 的对应错误类型处理。
• 完成卡片模板如下：

  # 📁 输入内容（最终生效参数）
  | Item | Value |
  | --- | --- |
  | Input Path | {{ input_path }} |
  | Output Dir | {{ output_dir }} |

  # 🧰 工具调用记录
  | Step | Command | Exit Code |
  |------|---------|-----------|
  | ... | ... | ... |

  # 📊 附件提取统计
  | 指标 | 数值 |
  |------|------|
  | 提取附件总数 | {{ total_extracted }} |
  | OLE10Native 解析成功数 | {{ ole10native_count }} |
  | 直接验证成功数 | {{ direct_verify_count }} |
  | EMF 转换成功数 | {{ emf_convert_count }} |
  | 提取失败数 | {{ failed_count }} |

  # ✅ 质量检查
  | 检查项 | 结果 |
  |------|------|
  | 输出目录已创建 | {{ output_dir_check }} |
  | 包含有效提取文件 | {{ files_exist_check }} |
  | 文件类型正确性 | {{ type_check }} |

</output>

<error>

强制规则（必须遵守）：

• 错误回复只能基于当前已获得的信息生成；未知项填写 unknown。禁止为补齐错误内容继续读取文件、调用工具、解析原始结果、检查中间产物、重构展示或推断未发生的事实。
• 错误类型如下，同时命中多条规则时，按照"流程违规 > 业务执行错误 > 质量审查异常 > 环境依赖错误 > 超时错误 > 目标路径错误 > 输入参数错误 > 部分处理异常"的优先级确定最终错误类型：

• E01｜输入参数错误：未能读取 templates/input.schema.json、无法形成最终生效参数集、参数校验失败、关键参数缺失或无法推导。处理方法：立即停止，按错误输出卡片汇报。
• E02｜目标路径错误：<input_path> 不存在、不是 .docx 文件、无法访问，或其他路径检查失败。处理方法：立即停止，请求用户确认正确路径；不得输出错误输出卡片，不得进入 Step 2。
• E03｜环境依赖错误：Python 解释器缺失或无效、olefile/lxml 依赖缺失、业务脚本不存在或不可执行、reference 文件缺失/读取失败/内容截断/能力不匹配/规则冲突。处理方法：立即停止，按错误输出卡片汇报缺失项。
• E04｜业务执行错误：业务脚本返回非零退出状态、输出目录未生成、结果 JSON 文件不可用。处理方法：立即停止，按错误输出卡片汇报。
• E05｜超时错误：工具调用返回 timed out、超过本 SKILL 规定的超时上限，或出现其他不可恢复的超时错误。处理方法：按错误输出卡片汇报；批量模式下可跳过当前文件继续下一文件。
• E06｜部分处理异常：部分 BIN 文件 OLE10Native 解析失败、部分 EMF 转换失败、跳过空文件。处理方法：继续处理其余文件，在完成卡片中记录跳过项；若异常数量过多导致结果不可信，升级为 E04。
• E07｜质量审查异常：质量检查发现输出目录为空、文件类型错误、结果 JSON 文件缺失或格式错误。处理方法：按错误输出卡片汇报，标注具体文件名。
• E08｜流程违规：违反步骤准入、章节边界、依赖检查顺序、命令执行边界、结果读取边界，或在应停止时继续补救、重试、读取、验证、检查、解析、重构结果。处理方法：立即停止，按错误输出卡片汇报。
• 错误展示使用错误输出卡片：

  --------------------------------------------------
  # 执行失败 ✗
  --------------------------------------------------

  ## ❌ 错误信息

  | Item | Value |
  | --- | --- |
  | Error Code | {{ error_code }} |
  | Error Type | {{ error_type }} |
  | Step | {{ step }} |
  | Status | failed |

  ## 📌 失败原因

  {{ reason }}

  ## ⚠️ 影响范围

  {{ impact }}

  ## 🔧 需要处理

  {{ required_action }}

</error>

</extract-attachments>