Imported from lxq-12345/pdfsc (AGENTS.md). Install upstream with npx skills add lxq-12345/pdfsc. Copyright stays with the author.

PDF智转器（pdfsc）— AGENTS.md

最后更新：2026-04-05

一、项目简介

本项目是一个 AI 驱动的 PDF → Markdown 智能转换工具。
中文名：PDF智转器
英文 ID：pdf-smart-converter
CLI 工具名：pdfsc

项目目标：将 PDF 转换为适合知识库 / RAG 使用的高质量 Markdown 文档。

二、执行原则

1. 角色定位

你在本项目中的角色包括：

1. 执行者

   • 按照项目规划执行具体任务
   • 遇到规划未覆盖的情况，暂停并报告
   • 不自行填充决策

2. 技术顾问

   • 回答用户关于项目的技术问题
   • 讨论方案的利弊和可行性
   • 提供基于经验的建议

3. 沟通助手

   • 遇到模糊指令时，先澄清再执行
   • 不猜测用户意图
   • 区分“讨论”与“执行”场景

2. 基本行为要求

• 先理解任务，再执行操作
• 不得擅自降低质量标准
• 不确定内容不得脑补，应显式说明不确定性
• 当指令含糊、上下文不足、或存在两种以上合理解释时，必须先向用户澄清
• 默认保守：不确定是讨论还是执行时，先按讨论处理

3. 讨论与执行判定规则

• 出现“创建”“修改”“删除”“运行”“验证”“生成”等执行动词，且对象明确时，按执行处理
• 动词不明确，例如“继续”“准备”“下一步”“按上次来”，按讨论处理并先澄清
• 若指令同时包含讨论和执行成分，先确认执行对象与范围，再进入执行

三、项目文件管理规范（强制执行）

所有项目相关文件必须保存在项目目录范围内，并纳入可管理、可追溯的仓库结构。

允许的文件保存位置

• plan/：所有规划、计划、方案文档
• mem/：备忘、记录、阶段状态、临时笔记
• docs/：参考文档、技术说明、备份文件
• skills/：技能说明、转换规范、执行规则
• scripts/、tests/ 等其他项目子目录

严格禁止的操作

• 不得引用或依赖项目目录之外的私有工具状态目录作为项目依据
• 不得将项目规划、快照、规则、备忘保存在项目目录之外
• 不得创建随机命名、不可追溯的临时文件
• 不得使用用户目录中的工具内部文件作为项目文档依据

文本文件格式规范

本项目所有文本文件统一使用 LF 作为行结束符。

适用范围包括但不限于：

• Python 源码（.py）
• Markdown 文件（.md）
• 配置与参数文件（.yml、.yaml、.json、.txt）
• Shell 脚本（.sh）
• 测试样本、提示词、报告模板等文本文件

禁止向仓库提交使用 CRLF 作为行结束符的文本文件。
如发现历史遗留文件存在 CRLF，应在不改变语义内容的前提下统一规范化为 LF。

原则说明

1. 项目文件必须可版本控制（git）
2. 团队协作需要共享所有规划和规则文档
3. 删除项目时，应能一并删除全部相关文件
4. 用户必须能看到并管理所有项目相关文档

新建规划或方案文档时

• 保存在 plan/ 目录
• 使用清晰、可读、可追溯的文件名
• 必要时更新 plan/项目规划.md 中的引用
• 纳入 git 版本控制

四、工作方式规范

1. 平台中立原则

不得使用任何会将项目计划、快照、备忘、规则文件写入项目目录之外的工作模式、外部状态目录或临时机制。

2. 模糊指令处理

遇到以下情况必须暂停并请求澄清：

• 动词不明确，例如“继续”“准备”“下一步”
• 目标对象不清晰
• 缺少关键上下文
• 存在两种以上合理执行路径

澄清时应简洁、直接，优先帮助用户快速做出选择。

五、会话与状态管理

1. 启动要求

每次启动会话后，优先于一切具体任务，读取并遵循：

./会话管理协议.md

2. 当前状态来源

本文件不维护动态任务状态。
当前阶段、当前任务、下一步安排，以以下文件为准：

1. ./plan/项目规划.md
2. ./mem/ 目录下日期最新的备忘文件或状态文件

“最新”统一按文件最后修改时间降序取第一；若时间相同，优先选择文件名包含阶段标签的文件。

3. 归档与恢复

归档提醒、快照机制、会话中断恢复流程，统一以 会话管理协议.md 为准。

六、遇到问题时的处理规则

以下情况必须立即暂停，并向用户报告，而不是自行决策：

• 项目规划未涵盖的技术方案选择题
• 多种实现方案利弊无法依据现有文档判断
• 质量标准存在歧义，或不同文档之间有冲突
• 关键规则文件内容不清晰，无法确定执行依据
• 高风险批量改动，可能影响既有质量基线

满足任一条件时，原则上视为高风险批量改动：

• 一次修改达到或超过 5 个文件
• 涉及 2 个及以上核心模块
• 可能影响既有样例的输出结构或质量基线

以下任一情况视为质量歧义并暂停：

• 规范条款之间存在冲突
• 同一条款存在两种以上合理解释，且会影响输出结构
• 历史基线与当前规则结论不一致

处理步骤

1. 优先查阅 plan/项目记忆文档.md 或相关备忘文件，寻找已知解决方案
2. 如果仍无答案，向用户清晰陈述：
   • 问题是什么
   • 当前上下文是什么
   • 可选方案有哪些
   • 各方案的主要影响是什么
3. 等待用户指示，不得自行填充决策

暂停时，反馈内容至少应包含：问题、上下文、可选方案、影响评估。
未收到用户确认，不得继续执行。

不要自行决策，不要降低质量标准。

七、必读文档（按顺序）

启动后请按以下顺序阅读，建立完整认知后再执行任务。

所有文件路径均相对于项目根目录。

1. ./会话管理协议.md

   • 启动检查流程
   • 快照与备忘机制
   • 会话归档与中断恢复

2. ./plan/项目规划.md

3. ./plan/项目技术约定.md

   • 完整技术方案
   • 项目阶段
   • 验收标准
   • 环境准备与版本管理规则

4. ./skills/Markdown转换规范.md

   • Markdown 转换行为规范
   • 输出格式要求
   • 质量审查清单
   • 所有转换任务的直接执行依据

5. ./环境说明.md

   • WSL 与 Windows 的环境分工
   • 关键软链接说明
   • 测试前最小检查
   • 路径与环境约束

6. ./mem/ 目录下最新的备忘文件

   • 最近讨论结论
   • 当前待办
   • 下一步方向

八、环境与测试约束

本项目环境说明与测试约束见：

• ./环境说明.md
• ./plan/项目技术约定.md

执行测试、路径验证、脚本运行、批量处理前，应先阅读这两个文件。
其中对 WSL、Windows、关键软链接和测试前最小检查的说明，属于执行前提。

九、转换与质检要求

1. 转换规范

所有 PDF → Markdown 转换任务，必须遵守：

./skills/Markdown转换规范.md

该文件是转换任务的直接执行依据。

2. 质量底线

转换结果必须满足以下要求：

• 内容与原 PDF 保持基本一致
• 结构层级清晰
• 不漏页、不漏段、不随意补写
• 表格、列表、标题、图片、代码块等结构处理符合规范
• 输出结果适合知识库 / RAG 使用
• 不为了适配单个案例而破坏通用规则

3. 质检要求

完成转换或修改转换逻辑后，应至少检查：

• 内容完整性
• 结构准确性
• 页眉页脚、页码等噪声清理情况
• 表格转换质量
• 图片与图注处理
• 代码块识别与标注
• 是否引入新的格式退化

4. 回归要求

若修改了转换逻辑、转换规范、提示策略或相关脚本：

• 必须回归样例集
• 必须检查是否破坏既有质量基线
• 必须在结果说明中写清本次修改影响范围

最小回归范围如下：

• 至少回归 3 个代表样本：纯文字、图文混排、复杂长文档各 1 个
• 若涉及图片处理逻辑，额外回归 1 个 extract 模式样本
• 若仅影响局部规则且影响范围明确，可在说明中注明采用受影响子集回归，但不得低于上述最低要求

十、关键规则文件修改要求

为避免关键规则文件被覆盖，凡修改以下文件前，必须先创建备份文件并保存到 docs/ 目录：

• AGENTS.md
• 会话管理协议.md
• 其他未显式标注版本标签、但属于规则类或流程类的关键文件

强制要求

1. 修改前先备份，未备份不得修改

2. 备份文件统一保存到 docs/ 目录，不得保存到项目外部目录

3. 备份文件名必须包含备份版本号

4. 推荐命名格式：

   {原文件名去扩展名}_备份_v{主版本}-b{两位序号}.md

5. 同一主版本下多次备份时，序号递增，例如 b01、b02、b03

6. 修改完成后，在回复中明确报告备份文件名和备份版本号

例外说明

• 已有可追溯版本标签且由发布流程自动管理的文件，可按既有流程执行
• 若存在冲突，以“先备份再修改”为优先原则

十一、配置文件反馈与改进

如果发现本文件或其他规则文件存在以下问题：

• 表述不清晰
• 指导不完整
• 存在歧义
• 不同章节之间有逻辑矛盾

处理方式如下：

1. 直接向用户报告问题位置和影响范围
2. 不要擅自修改本文件
3. 提出修改意见，用户确认方可修改，修改记录到项目记忆文档中存档

十二、完成标准

在执行具体任务时，完成不等于“文件已生成”，而应满足以下标准：

• 已按规定阅读必要文档
• 已遵守项目文件管理规范
• 已按 Markdown 转换规范完成输出
• 已完成必要质检
• 如涉及规则或逻辑修改，已完成必要回归
• 已明确记录结果、问题和后续事项