Back to Details

pdf

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PDF 처리

PDF处理

[PDF 처리 스킬 활성화]
[PDF处理技能激活]

목표

目标

PDF 파일에 대한 모든 작업을 처리함. 텍스트/테이블 추출, PDF 병합/분할, 회전, 워터마크 추가, 신규 PDF 생성, 폼 작성, 암호화/복호화, 이미지 추출, OCR을 통한 스캔 PDF 검색 가능화 등을 포함.
处理PDF文件的所有操作，包括文本/表格提取、PDF合并/拆分、旋转、添加水印、新建PDF、填写表单、加密/解密、提取图片、通过OCR使扫描版PDF可搜索等。

활성화 조건

激活条件

사용자가 
.pdf
파일을 언급하거나 PDF 관련 작업 요청 시 활성화.
当用户提及
.pdf
文件或请求PDF相关操作时激活。

에이전트 호출 규칙

Agent调用规则

에이전트 FQN

Agent FQN

에이전트FQN티어
pdf-handler
claude-skills:pdf-handler:pdf-handler
MEDIUM
AgentFQN等级
pdf-handler
claude-skills:pdf-handler:pdf-handler
MEDIUM

프롬프트 조립 절차

提示组装流程

  1. agents/pdf-handler/
    에서 3파일 로드 (AGENT.md + agentcard.yaml + tools.yaml)
  2. gateway/runtime-mapping.yaml
    참조하여 구체화:
    • 모델 구체화: agentcard.yaml의 
      tier: MEDIUM
      → 
      tier_mapping.default.MEDIUM
      → 
      claude-sonnet-4-5
    • 툴 구체화: tools.yaml의 추상 도구 → 
      tool_mapping
      에서 실제 도구 결정
    • 금지액션 구체화: 
      forbidden_actions: [user_interact, agent_delegate]
      → 
      action_mapping
      에서 
      [AskUserQuestion, Task]
      제외
    • 최종 도구 = (구체화된 도구) - (제외 도구)
  3. 프롬프트 조립: 공통 정적(runtime-mapping) → 에이전트별 정적(3파일) → 동적(작업 지시)
  4. Task(subagent_type="claude-skills:pdf-handler:pdf-handler", model="claude-sonnet-4-5", prompt=조립된 프롬프트)
    호출
  1. 加载
    agents/pdf-handler/
    下的3个文件（AGENT.md + agentcard.yaml + tools.yaml）
  2. 参考
    gateway/runtime-mapping.yaml
    进行具体化：
    • 模型具体化：agentcard.yaml中的
      tier: MEDIUM
      → 
      tier_mapping.default.MEDIUM
      → 
      claude-sonnet-4-5
    • 工具具体化：tools.yaml中的抽象工具 → 在
      tool_mapping
      中确定实际工具
    • 禁止操作具体化：
      forbidden_actions: [user_interact, agent_delegate]
      → 在
      action_mapping
      中排除
      [AskUserQuestion, Task]
    • 最终工具 =（具体化后的工具）-（排除的工具）
  3. 提示组装：公共静态内容(runtime-mapping) → Agent专属静态内容(3个文件) → 动态内容(任务指令)
  4. 调用
    Task(subagent_type="claude-skills:pdf-handler:pdf-handler", model="claude-sonnet-4-5", prompt=组装好的提示)

오케스트레이션 스킬 활용

编排技能应用

워크플로우 Phase추천 스킬적용
Phase 1 (작업 유형 판별)
ulw
매직 키워드		필수
Phase 2-A (PDF 읽기/추출)
ulw
매직 키워드		필수
Phase 2-B (새 PDF 생성)
/oh-my-claudecode:ralph
필수
Phase 2-C (병합/분할)
ulw
매직 키워드		필수
Phase 2-D (폼 작성)
/oh-my-claudecode:ralph
필수
Phase 2-E (이미지 변환)
ulw
매직 키워드		필수
Phase 3 (결과 검증)
ulw
매직 키워드		필수
工作流阶段推荐技能应用要求
Phase 1 (任务类型判别)
ulw
魔法关键字		必填
Phase 2-A (PDF读取/提取)
ulw
魔法关键字		必填
Phase 2-B (新建PDF)
/oh-my-claudecode:ralph
必填
Phase 2-C (合并/拆分)
ulw
魔法关键字		必填
Phase 2-D (表单填写)
/oh-my-claudecode:ralph
必填
Phase 2-E (图片转换)
ulw
魔法关键字		必填
Phase 3 (结果验证)
ulw
魔法关键字		必填

워크플로우

工作流

Phase 1: 작업 유형 판별 (
ulw
활용)

Phase 1: 任务类型判别（使用
ulw
）

사용자 요청을 분석하여 작업 유형을 읽기/생성/편집/폼/변환 중 하나로 분류.
分析用户请求，将任务类型分类为读取/生成/编辑/表单/转换中的一种。

Phase 2-A: PDF 읽기/추출 → Agent: pdf-handler (
ulw
활용)

Phase 2-A: PDF读取/提取 → Agent: pdf-handler（使用
ulw
）

  • TASK: pypdf, pdfplumber를 활용하여 PDF에서 텍스트, 테이블, 메타데이터 추출
  • EXPECTED OUTCOME: 추출된 텍스트/테이블 데이터, 메타데이터
  • MUST DO: pdfplumber로 테이블 추출 시 레이아웃 보존, 스캔 PDF는 OCR 필요 여부 안내
  • MUST NOT DO: 스캔 PDF를 일반 추출로 처리하지 않음 (OCR 필요)
  • CONTEXT: 원본 PDF 경로, 추출 대상(텍스트/테이블/메타데이터), 
    PYTHONPATH=gateway/tools
    환경변수 설정 필수
  • TASK：使用pypdf、pdfplumber从PDF中提取文本、表格、元数据
  • EXPECTED OUTCOME：提取后的文本/表格数据、元数据
  • MUST DO：使用pdfplumber提取表格时保留布局，扫描版PDF需提示是否需要OCR
  • MUST NOT DO：不得将扫描版PDF按普通提取处理（需OCR）
  • CONTEXT：原始PDF路径、提取目标(文本/表格/元数据)，必须设置
    PYTHONPATH=gateway/tools
    环境变量

Phase 2-B: 새 PDF 생성 → Agent: pdf-handler (
/oh-my-claudecode:ralph
활용)

Phase 2-B: 新建PDF → Agent: pdf-handler（使用
/oh-my-claudecode:ralph
）

  • TASK: reportlab를 활용하여 신규 PDF 생성
  • EXPECTED OUTCOME: 유효한 PDF 구조를 가진 신규 PDF 파일
  • MUST DO: Paragraph 객체에서 
    <sub>
    , 
    <super>
    태그 사용 (Unicode 첨자 금지), 여러 페이지 생성 시 Platypus 프레임워크 활용
  • MUST NOT DO: Unicode 첨자/위첨자 문자 (₀₁₂, ⁰¹²) 사용 금지 (검은 박스 렌더링됨)
  • CONTEXT: 콘텐츠 요구사항, 페이지 레이아웃, 
    PYTHONPATH=gateway/tools
    환경변수 설정 필수
  • TASK：使用reportlab新建PDF
  • EXPECTED OUTCOME：具备有效PDF结构的新建PDF文件
  • MUST DO：在Paragraph对象中使用
    <sub>
    、
    <super>
    标签（禁止使用Unicode下标），多页生成时使用Platypus框架
  • MUST NOT DO：禁止使用Unicode下标/上标字符（₀₁₂, ⁰¹²）会渲染为黑框
  • CONTEXT：内容需求、页面布局，必须设置
    PYTHONPATH=gateway/tools
    环境变量

Phase 2-C: 병합/분할 → Agent: pdf-handler (
ulw
활용)

Phase 2-C: 合并/拆分 → Agent: pdf-handler（使用
ulw
）

  • TASK: pypdf + qpdf로 PDF 병합/분할
  • EXPECTED OUTCOME: 병합된 PDF 또는 분할된 PDF 파일들
  • MUST DO: qpdf 활용하여 구조 무결성 보존
  • MUST NOT DO: 메타데이터 손실 금지
  • CONTEXT: 원본 PDF 경로, 병합/분할 범위, 
    PYTHONPATH=gateway/tools
    환경변수 설정 필수
  • TASK：使用pypdf + qpdf进行PDF合并/拆分
  • EXPECTED OUTCOME：合并后的PDF或拆分后的PDF文件
  • MUST DO：使用qpdf保证结构完整性
  • MUST NOT DO：禁止丢失元数据
  • CONTEXT：原始PDF路径、合并/拆分范围，必须设置
    PYTHONPATH=gateway/tools
    环境变量

Phase 2-D: 폼 작성 → Agent: pdf-handler (
/oh-my-claudecode:ralph
활용)

Phase 2-D: 表单填写 → Agent: pdf-handler（使用
/oh-my-claudecode:ralph
）

  • TASK: 전략 판별(필드 방식 vs 주석 오버레이) 후 PDF 폼 작성
  • EXPECTED OUTCOME: 작성 완료된 PDF 폼, 바운딩 박스 검증 통과
  • MUST DO: check_fillable_fields.py로 필드 확인, fill_fillable_fields.py(필드 방식) 또는 fill_pdf_form_with_annotations.py(주석 오버레이) 선택, check_bounding_boxes.py로 좌표 검증
  • MUST NOT DO: 전략 판별 없이 폼 작성 시도 금지, 바운딩 박스 검증 없이 결과 전달 금지
  • CONTEXT: 원본 PDF 경로, 폼 데이터, agents/pdf-handler/references/pdf-forms-guide.md 참조, 
    PYTHONPATH=gateway/tools
    환경변수 설정 필수
스크립트 호출 패턴:
bash
python gateway/tools/pdf/check_fillable_fields.py input.pdf
python gateway/tools/pdf/fill_fillable_fields.py input.pdf output.pdf
PYTHONPATH=gateway/tools python gateway/tools/pdf/fill_pdf_form_with_annotations.py input.pdf output.pdf
  • TASK：先判别策略(字段方式 vs 注释覆盖)再填写PDF表单
  • EXPECTED OUTCOME：填写完成的PDF表单，通过边界框验证
  • MUST DO：使用check_fillable_fields.py检查字段，选择fill_fillable_fields.py(字段方式)或fill_pdf_form_with_annotations.py(注释覆盖)，使用check_bounding_boxes.py验证坐标
  • MUST NOT DO：禁止未判别策略直接尝试填写表单，禁止未验证边界框就交付结果
  • CONTEXT：原始PDF路径、表单数据，参考agents/pdf-handler/references/pdf-forms-guide.md，必须设置
    PYTHONPATH=gateway/tools
    环境变量
脚本调用模式:
bash
python gateway/tools/pdf/check_fillable_fields.py input.pdf
python gateway/tools/pdf/fill_fillable_fields.py input.pdf output.pdf
PYTHONPATH=gateway/tools python gateway/tools/pdf/fill_pdf_form_with_annotations.py input.pdf output.pdf

Phase 2-E: 이미지 변환 → Agent: pdf-handler (
ulw
활용)

Phase 2-E: 图片转换 → Agent: pdf-handler（使用
ulw
）

  • TASK: PDF를 PNG 이미지로 변환
  • EXPECTED OUTCOME: 각 페이지가 PNG 이미지로 변환됨
  • MUST DO: convert_pdf_to_images.py 활용
  • MUST NOT DO: 이미지 품질 저하 금지
  • CONTEXT: 원본 PDF 경로, 출력 디렉토리, 
    PYTHONPATH=gateway/tools
    환경변수 설정 필수
스크립트 호출 패턴:
bash
PYTHONPATH=gateway/tools python gateway/tools/pdf/convert_pdf_to_images.py input.pdf output_dir/
  • TASK：将PDF转换为PNG图片
  • EXPECTED OUTCOME：每页PDF转换为PNG图片
  • MUST DO：使用convert_pdf_to_images.py
  • MUST NOT DO：禁止降低图片质量
  • CONTEXT：原始PDF路径、输出目录，必须设置
    PYTHONPATH=gateway/tools
    环境变量
脚本调用模式:
bash
PYTHONPATH=gateway/tools python gateway/tools/pdf/convert_pdf_to_images.py input.pdf output_dir/

Phase 3: 결과 검증 (
ulw
활용)

Phase 3: 结果验证（使用
ulw
）

  • PDF 읽기 가능 여부 확인 (pypdf)
  • 폼 작성인 경우 check_bounding_boxes.py로 좌표 검증
  • create_validation_image.py로 시각적 검증 이미지 생성
  • 모든 검증 통과 후에만 완료 선언
스크립트 호출 패턴:
bash
python gateway/tools/pdf/check_bounding_boxes.py output.pdf
PYTHONPATH=gateway/tools python gateway/tools/pdf/create_validation_image.py output.pdf validation.png
  • 检查PDF是否可读取（pypdf）
  • 若为表单填写，使用check_bounding_boxes.py验证坐标
  • 使用create_validation_image.py生成视觉验证图片
  • 仅在所有验证通过后才宣告完成
脚本调用模式:
bash
python gateway/tools/pdf/check_bounding_boxes.py output.pdf
PYTHONPATH=gateway/tools python gateway/tools/pdf/create_validation_image.py output.pdf validation.png

완료 조건

完成条件

  • 생성/편집된 PDF가 유효한 PDF 구조를 가짐
  • 폼 작성 시 check_bounding_boxes.py 검증 통과
  • 시각적 검증 이미지(create_validation_image.py)로 확인 가능
  • 사용자 요청의 모든 항목이 반영됨
  • 生成/编辑后的PDF具备有效PDF结构
  • 表单填写时通过check_bounding_boxes.py验证
  • 可通过视觉验证图片(create_validation_image.py)确认
  • 已反映用户请求的所有项

검증 프로토콜

验证协议

  1. PDF 읽기 가능 여부 확인 (pypdf)
  2. 폼 작성인 경우 check_bounding_boxes.py로 좌표 검증
  3. create_validation_image.py로 시각적 검증 이미지 생성
  4. 모든 검증 통과 후에만 완료 선언
  1. 检查PDF是否可读取（pypdf）
  2. 若为表单填写，使用check_bounding_boxes.py验证坐标
  3. 使用create_validation_image.py生成视觉验证图片
  4. 仅在所有验证通过后才宣告完成

상태 정리

状态整理

완료 시 임시 이미지 파일 생성 시 사용자에게 안내. 상태 파일 미사용 (단건 작업).
完成时若生成临时图片文件，需告知用户。不使用状态文件（单任务处理）。

취소

取消

cancelomc
또는 
stopomc
키워드로 즉시 중단.
使用
cancelomc
或
stopomc
关键字立即终止。

재개

恢复

원본 PDF가 보존되어 있으므로 처음부터 재시작 가능.
由于原始PDF已保存，可从开头重新启动。

MUST 규칙

MUST规则

#규칙
1폼 작성 시 반드시 전략 판별 (필드 방식 vs 주석 오버레이) 선행
2시각적 검증 이미지를 생성하여 결과 확인
3모든 Phase에 오케스트레이션 스킬 활용 필수 명시
4에이전트 위임 시 5항목 (TASK, EXPECTED OUTCOME, MUST DO, MUST NOT DO, CONTEXT) 포함
5PDF 커스텀 도구 호출 시 
PYTHONPATH=gateway/tools
환경변수 설정 필수
#规则
1填写表单时必须先判别策略（字段方式 vs 注释覆盖）
2生成视觉验证图片以确认结果
3必须明确所有阶段都需使用编排技能
4委托Agent时需包含5项内容（TASK, EXPECTED OUTCOME, MUST DO, MUST NOT DO, CONTEXT）
5调用PDF自定义工具时必须设置
PYTHONPATH=gateway/tools
环境变量

MUST NOT 규칙

MUST NOT规则

#금지 사항
1폼 전략 판별 없이 직접 폼 작성 시도 금지
2바운딩 박스 검증 없이 폼 결과 전달 금지
3에이전트의 내부 사고 방식이나 단계별 절차를 스킬에서 기술하지 않음
4reportlab 사용 시 Unicode 첨자/위첨자 문자 사용 금지
#禁止事项
1禁止未判别表单策略直接尝试填写表单
2禁止未验证边界框就交付表单结果
3禁止在技能中描述Agent的内部思考方式或分步流程
4使用reportlab时禁止使用Unicode下标/上标字符

검증 체크리스트

验证检查表

  • frontmatter에 name, description 포함
  • 에이전트 호출 규칙 섹션 포함 (pdf-handler FQN, 프롬프트 조립 4단계, 오케스트레이션 활용)
  • 모든 Phase에 스킬 부스팅 명시
  • 완료 조건, 검증 프로토콜, 상태 정리, 취소/재개 섹션 포함
  • MUST 규칙, MUST NOT 규칙 섹션 포함
  • Agent 위임 단계에 5항목 포함
  • 스크립트 호출 패턴에 PYTHONPATH 설정 명시
  • frontmatter包含name、description
  • 包含Agent调用规则章节（pdf-handler FQN、提示组装4步骤、编排技能应用）
  • 所有阶段明确标注技能增强要求
  • 包含完成条件、验证协议、状态整理、取消/恢复章节
  • 包含MUST规则、MUST NOT规则章节
  • Agent委托步骤包含5项内容
  • 脚本调用模式中明确标注PYTHONPATH设置