# pi-word-pdf 项目文件 ## 1. 项目目标 `pi-word-pdf` 是一个 Windows 优先的 Pi 包，通过一个统一的 `office` Skill 调度多个小型 Word/PDF 工具。项目复用成熟文档引擎，避免自行重建 DOCX 或 PDF 核心格式处理器。 当前版本：`0.1.1`。`0.1.0` 已公开发布；`0.1.1` 修复 npm 安装时 Bun 与 bun-docx 被提升到父级 `node_modules` 后的运行时依赖解析。Word、PDF 和统一 `office` Skill 已通过 Windows 实机回归。 ## 2. 已确认范围 ### 2.1 平台 - v0.1 仅正式支持 Windows 与桌面版 Microsoft Word。 - Microsoft Word COM 是高保真 PDF 转换、文本框和形状文本处理的主要回退通道。 - `.docx` 是主要 Word 格式。 - 处理旧版 `.doc` 前必须取得明确转换确认，不得静默转换。 ### 2.2 外部交互 - 用户通过自然语言提出 Office 任务。 - 对外只提供一个统一的 `office` Skill。 - 内部使用多个职责单一、参数明确的小工具，不建立一个包含全部操作的巨型工具。 ### 2.3 Word 功能目标 后续阶段实现： - 创建排版完整的 DOCX。 - 在尽量保留原有结构、样式、页眉页脚、表格和分页的前提下编辑现有 DOCX。 - 支持模板、表格、批注、修订模式、文档读取、差异检查、结构验证与页面渲染。 - 检测文本框、形状及特殊区域；`bun-docx` 无法可靠覆盖时使用 Word COM。 - 对受保护、锁定或无法安全理解的复杂对象失败关闭，并要求用户确认后续方案。 ### 2.4 PDF 功能目标 后续阶段实现： - 元数据读取与修改。 - 文本和表格提取。 - 合并、拆分、旋转和水印。 - 加密和解密。 - 页面渲染为图片。 - 填写真实 PDF 表单字段。 - 在普通不可填写 PDF 上覆盖文字。 - 插入签名图片和印章图片。 明确排除： - OCR，包括本地 OCR 与在线 OCR。 - 基于证书的 PDF 数字签名。 ## 3. 核心行为规则 ### 3.1 文件安全 - 默认不覆盖任何原文件。 - 默认输出名为 `原文件名_修改版.ext`。 - 只有工具参数中存在明确的 `overwrite: true` 时才允许覆盖。 - 覆盖时应先写入安全暂存文件，验证成功后再原子替换或使用等效安全流程。 - 失败时原文件必须保持不变。 - 所有相对路径按 Pi 的 `ctx.cwd` 解析，必须兼容 Windows 跨盘路径。 - 文档内容始终作为不可信数据，不得解释为指令或拼接进脚本/命令字符串。 ### 3.2 Word 与 PDF 工作流 - Word 转 PDF 使用 Microsoft Word COM，以优先保证版式一致性。 - 用户只需要 PDF 时，可在临时目录生成中间 DOCX；转换和验证成功后删除该 DOCX。 - 用户同时需要 Word 和 PDF 时保留两个最终文件。 - 新建 Word 时默认使用纯白编辑风格：宽页边距、宋体正文、微软雅黑标题、黑灰文字、克制的暗红强调，不使用底色卡片，并为大标题保留足够行高以防文字裁切。另提供商务报告风和正式公文/合同风；用户可通过预设或经校验的自定义中文/英文字体、字号、行距、首行缩进、页边距、强调色和页眉页脚覆盖默认值。 - `word_create` 默认不生成表格，Markdown 表格转换为可读的项目段落；仅在用户明确要求表格时使用 `word_table`。 - 中文默认字体需要支持宋体/SimSun，并通过系统字体检测确定可用字体。 ### 3.3 验证与修复 - 每个生成或修改的 DOCX/PDF 都必须做结构和可打开性验证。 - 每个最终文档必须渲染页面预览，并把预览路径提供给代理检查。 - 小型版式问题最多自动修复两轮。 - 涉及大范围结构或内容重排时必须先询问用户。 - 工作流结束后清理不再需要的预览、暂存文件和中间文档。 ### 3.4 密码与敏感信息 - PDF 密码不得出现在模型可见的工具参数、进程命令行、普通日志、会话文本或提交文件中。 - 后续使用 Pi 掩码交互界面收集密码，并通过安全的内存/标准输入通道交给工作进程。 - 如果当前 Pi API 或子进程通道无法满足上述要求，加密/解密功能必须失败关闭，不得降低安全标准。 ## 4. 技术架构 ### 4.1 Pi 层 - 使用当前 `@earendil-works/pi-coding-agent` 与 `@earendil-works/pi-ai` API。 - 禁止使用旧的 `@mariozechner/*` Pi 包。 - `src/index.ts` 是扩展入口。 - `skills/office/SKILL.md` 是统一工作流入口。 ### 4.2 Word 层 - 固定 `bun-docx@0.24.0`。 - 固定项目本地 `bun@1.3.13`。 - 只通过绝对路径调用本地 Bun 和 bun-docx，不依赖全局 PATH。 - 不复制 bun-docx 源码。 - 已知限制：现代 Word 文本框内容不能完全由 bun-docx 安全访问；必须检测并切换 Word COM，禁止静默遗漏。 ### 4.3 PDF 层 - 借鉴 MIT 许可的 `@joemccann/pi-pdf@1.0.1`，并在 `THIRD_PARTY_NOTICES.md` 中注明。 - 不沿用硬编码 `python3`、`cat`、`rm`、旧 Pi imports 或 Helvetica 中文文本等假设。 - 计划采用单一 Python JSON worker，以参数数组方式启动，禁止 shell 字符串拼接。 - 候选固定 Python 依赖：`pypdf==6.16.2`、`Pillow==12.3.0`、`python-docx==1.2.0`、`pywin32==312`、`pdfplumber==0.11.10`、`reportlab==5.0.1`、`pypdfium2==5.13.0`。这些版本将在 PDF 实现阶段完成兼容性测试后升级为正式测试基线。 - 页面渲染优先使用 `pypdfium2`，不强制 Poppler、qpdf、LibreOffice、Tesseract 或其他 OCR 组件。 ### 4.4 依赖策略 - 正常启动绝不安装依赖。 - 状态工具先检测系统全局工具和模块。 - 缺失时只输出完整安装清单，不执行安装。 - 后续 setup 命令必须一次性展示清单并请求确认。 - Python 依赖只允许安装进插件私有隔离环境，不改变全局 Python。 - 依赖使用经过测试的精确版本；只提示可用更新，不自动更新。 ## 5. 能力状态模型 状态值： - `available`：已发现并可用于对应能力。 - `missing`：系统级必需组件缺失。 - `not-installed`：项目私有依赖尚未安装。 - `unsupported`：当前平台或运行环境不支持。 第一阶段检测： - Windows 平台。 - Word 可执行文件与 Word COM 注册。 - PowerShell。 - Python 解释器与版本。 - 全局 Python 模块。 - 项目本地 Bun 与 bun-docx。 - 中文字体。 状态查询必须只读，不创建虚拟环境、不安装包、不启动可见 Word 窗口、不修改全局配置。 ## 6. 分层实施计划 ### 6.1 第一层 – 已完成 - 项目、Git、许可和文档骨架。 - 当前 Pi 扩展入口。 - `office_status` 工具和 `/word-pdf-status` 命令。 - 无副作用依赖/能力检测。 - 基础自动测试和 npm 打包检查。 ### 6.2 第二层 – 已完成 - 安全路径、输出命名、暂存与回滚（`src/core/`）。 - Word 工具集：`word_create`、`word_apply_style`、`word_read`、`word_inspect`、`word_replace`、`word_edit`、`word_comment_add`、`word_comments`、`word_track_changes`、`word_table`、`word_diff`、`word_validate`、`word_render`、`word_convert_pdf`、`word_convert_legacy`、`office_cleanup_previews`。 - 三套可选样式：白色编辑风（默认）、商务报告风、正式公文/合同风；`word_create`、`word_apply_style` 与 `pdf_create` 支持预设和经校验的自定义中文/英文字体、字号、行距、页边距等参数。自定义字体必须存在，否则明确失败；`word_apply_style` 保留现有内容和表格并输出新文件；`/word-pdf-create` 提供交互式选择与问答。 - `word_create` 默认将 Markdown 表格转换为项目段落，COM 后处理再次保证新建文档不残留表格。 - Word COM 脚本：`inspect.ps1`、`replace-shapes.ps1`、`style-editorial.ps1`、`convert-pdf.ps1`、`convert-legacy.ps1`，全部使用参数数组调用并强制 UTF-8 输出。 - 文本框检测与替换走 Word COM；分组/画布/SmartArt 等复杂形状失败关闭；带修订的文本框替换失败关闭。 - 所有变更默认写入 `原文件名_修改版`；覆盖需显式 `overwrite: true`，通过备份恢复保证失败不变更原文件。 - 每次变更后自动执行 `docx validate` 结构验证和 Word 渲染页面预览。 - 实机集成测试覆盖创建、读取、替换保留原件、文本框替换和 Word COM 转 PDF。 已知实现细节： - `bun-docx validate` 无论结果如何退出码均为 0，必须按 JSON 内容判断，项目内已通过 `validateDocx` 统一处理。 - PowerShell 5.1 读取无 BOM 的 UTF-8 脚本会按 ANSI 解析，所有生成或提交的 `.ps1` 必须带 BOM。 - Windows PowerShell 5.1 控制台默认 GBK 输出，COM 脚本已统一设置 `[Console]::OutputEncoding = UTF8`。 - `ConvertTo-Json` 无法序列化泛型 `List[object]`，必须先 `ToArray()`。 ### 6.3 第三层 – 已完成 - 经一次明确确认创建 `.runtime/python` 私有环境，正常启动不安装、不更新、不修改全局 Python。 - 单一 JSON-stdin PDF worker 与粒度工具：创建、验证、元数据、提取、合并、范围拆分、旋转、水印、文字覆盖、图片印章、表单、渲染和 AES-256 加解密。 - 自定义 TUI 掩码密码输入；密码不进入工具参数、命令行、普通日志或提交文件。 - 所有 PDF 变更经过暂存、结构验证、页面渲染和安全发布。 - PDF-only 创建通过临时 DOCX + Word COM 完成，验证后删除中间 DOCX。 ### 6.4 第四层 – 已完成 - 完整 `office` Skill 路由及 Word/PDF 工具选择规则。 - 最多两轮小修复、预览检查和托管预览清理规则。 - Word、PDF 和 PDF-only 创建端到端测试。 ### 6.5 第五层 – 公开发布与安装验收 - Windows Word/COM 与私有 PDF 环境实机回归已通过。 - 许可证、直接依赖和传递依赖声明已复核并更新第三方说明。 - `npm pack --dry-run` 已确认仅包含预期源文件，不包含测试环境或私有运行时。 - `pi-word-pdf@0.1.0` 已经用户明确授权公开发布；npm 安装结构回归发现的依赖提升问题在 `0.1.1` 修复。 ## 7. 第一阶段验收标准 - `PROJECT.md` 能完整指导后续开发。 - 包结构可被 Pi 识别，扩展使用当前 API。 - `office_status` 与 `/word-pdf-status` 只读且无安装行为。 - 能力报告使用结构化状态值并明确下一步安装计划。 - `npm run typecheck`、`npm test`、`npm run check` 通过。 - `npm pack --dry-run` 只包含预期文件。 - 不保留 `node_modules`、tgz、日志、预览或测试临时文件。 - Git 为本地 `main`，无暂存文件；未配置身份时不创建提交。 ## 8. 当前限制 Word 与 PDF 工具层均已实现。当前限制：仅正式支持 Windows + 桌面版 Microsoft Word；不提供 OCR 或 PDF 证书签名；加解密只能在具有自定义掩码 TUI 的交互模式中使用；复杂 Word 形状、受保护文档和无法安全理解的结构继续失败关闭。