PPTAgent 双栈架构解析:CLAUDE.md 如何界定 deeppresenter 与 pptagent、代码规范与 AI Agent 协作规则
PPTAgent 双栈架构解析:CLAUDE.md 如何界定 deeppresenter 与 pptagent、代码规范与 AI Agent 协作规则
CLAUDE.md 是 PPTAgent 仓库面向 AI 编码 Agent 与维护者的"工程地图":它界定了仓库的双栈(deeppresenter / pptagent)结构、各功能的"地面真值"入口、工程哲学、代码风格规则,以及 Agent 改动代码时的边界与已知陷阱。读完本文,你能分清每一项能力归属哪一技术栈、哪些声明以源码与 pyproject.toml 为准、改 CLI / 编排 / MCP / 导出时应检查哪些路径,从而避免踩中仓库自身标注的"sharp edges"。
说明:在当前仓库中,
CLAUDE.md是指向 AGENTS.md 的符号链接(CLAUDE.md -> AGENTS.md),二者内容完全一致。本文以该文件为唯一叙述主体;AGENTS.md 中的架构与路径属于文档声明,涉及目录与文件时请以实际 checkout 为准(详见第 7 节)。
文档定位与适用对象
PPTAgent 是一个"agentic PowerPoint generation system"(智能体式演示文稿生成系统)。根据 AGENTS.md 的 Purpose 章节,仓库包含两条紧密相关、但职责不同的代码路径:
deeppresenter/:当前运行时(runtime)、CLI、多智能体循环(multi-agent loop)、MCP 工具接线(tool wiring)以及 HTML-to-PPTX 导出流水线。pptagent/:更早的核心生成与评估库,仍随包一起分发,并且仍然是 MCP server 入口pptagent-mcp的来源。
文档明确给出了一条优先级规则:在改动代码时,除非任务明确涉及旧的 pptagent 生成内部实现或 MCP server,否则应把 deeppresenter 视为主产品面(primary product surface)。
这一文档的定位与面向最终用户的 README.md 不同——它不是安装/使用指南,而是给"要动代码的人(尤其是 AI Agent)"看的工程约束层。文档开头还带有一句元规则:
Do not use plan mode unless user explicitly mentioned(除非用户明确要求,否则不要使用 plan 模式)
也就是说,这份文档同时承担了两类读者对象的职责:对人,它是维护手册;对 AI 编码 Agent(Claude Code 等),它是"项目背景 + 行为约束"的注入文件。
双栈总体结构:deeppresenter 与 pptagent
AGENTS.md 的 High-Level Architecture 章节把两条栈的目录与职责拆开描述。这里完整继承该结构:
deeppresenter/
cli/:基于 Typer 的 CLI,提供onboard、generate、serve、config、clean等子命令。main.py:编排入口。AgentLoop.run()先执行Research,再二选一执行PPTAgent或Design,最后导出产物(artifacts)。agents/:围绕共享Agent基类的智能体包装。research.py:由提示词与附件构建"稿件 / 研究输出"。pptagent.py:从 Markdown 运行面向 PPT 的生成流程。design.py:生成幻灯片 HTML,随后依赖浏览器转换。
tools/:MCP 风格工具服务器,覆盖检索(search)、研究(research)、反思(reflection)、文件转换(file conversion)、任务管理(task management)。utils/:配置加载、常量、日志、MinerU 集成、Web 转换、MCP 客户端支持。html2pptx/:基于 Node 的转换助手,供 HTML 幻灯片流水线调用。test/:集成风格测试,覆盖沙箱工具、浏览器/PDF 转换、图像处理等相关能力。
pptagent/
- 核心演示生成、版面归纳(layout induction)、文档解析、评估,以及模板驱动的 PPT 生产。
mcp_server.py通过 FastMCP 暴露"模板化幻灯片创建"工作流。test/既包含单元测试,也包含标记为llm/parse的测试。
从两条栈的分工可以推断:pptagent/ 沉淀了论文(PPTAgent, EMNLP 2025)时期的核心生成/评估能力与 MCP 服务,而 deeppresenter/ 是承载当前产品形态(DeepPresenter, ACL 2026 相关升级:Deep Research 集成、自由视觉设计、自主资产创建、文生图、带沙箱与 20+ 工具的 Agent 环境)的运行时层。这与 README.md 的 News 章节"2025/12 发布 DeepPresenter 代码库重大升级"的时间线一致。
运行时"地面真值"(Ground Truth)
AGENTS.md 的 Ground Truth 章节给出了一组"以代码为准"的事实声明,用于在文档与实际不一致时裁定谁是权威。逐条继承如下:
| 声明 | 内容 |
|---|---|
| 包元数据与入口 | Python 包元数据和 console entrypoints 位于 pyproject.toml |
| 主 CLI 命令 | pptagent 指向 deeppresenter.cli:main |
| MCP server 命令 | pptagent-mcp 指向 pptagent.mcp_server:main |
| 默认运行时工作区 | 在 ~/.cache/deeppresenter 下创建,除非设置了 DEEPPRESENTER_WORKSPACE_BASE |
| 配置模板 | 位于 deeppresenter/config.yaml.example 与 deeppresenter/mcp.json.example |
该章节同时给出一条重要的元规则:
Do not assume the root
README.mdis fully current. It still references paths likewebui.pythat are not present in this checkout. Prefer the code andpyproject.tomlover prose docs when they conflict.
翻译即:当文字文档与代码冲突时,优先信任代码与 pyproject.toml,而不是 README 等叙述性文档。 这条规则本身就是"地面真值"思想的体现——把文档降格为可被代码推翻的假设。
三大工程哲学
文档把设计取舍提炼为三条带引语的原则,用于约束"什么样的代码该被接受"。
1. Good Taste First(好品味优先)
"Sometimes you can look at a problem differently, restate it, and the special case disappears."
- 倾向于重构代码,使"边界情况"(edge case)退化为"普通情况"。
- 好品味大多是累积的工程判断力。
- 删除特判分支,优于不断堆叠条件分支。
2. Pragmatism Over Theory(务实胜过理论)
"I am a pragmatic bastard."
- 解决本仓库里真实存在的问题,而非假想问题。
- 当更简单的方案可行时,拒绝"理论上优雅但操作上很重"的设计。
- 代码服务于现实,而非纸面架构。
3. Simplicity As A Constraint(把简单当作约束)
"If you need more than 3 levels of indentation, you're screwed and should fix your program."
- 保持函数短小、聚焦。
- 优先使用直接、明显的命名与结构。
- 把不必要的复杂度当作缺陷(defect)看待。
这三条哲学并非口号,而是对后续"代码风格规则"的动机说明:它们共同指向"更少依赖、更少代码、更浅缩进、更少特判"。
代码风格与沟通规范
代码风格规则(Code Style Rules)
AGENTS.md 给出 6 条硬规则:
- 避免过度异常处理。除非存在要处理的具体失败模式,否则不要用防御性包装去隐藏正常控制流。
- 为所有函数和方法添加类型注解(type hints)。
- 技术文档与代码注释使用英文书写。
- 优先使用现代工具链与当前最佳实践:
- 在合适处使用
uv、rg与最新的 Python 特性; - 遵循当前库 API,例如用 Pydantic 的
model_dump()而非遗留写法。
- 在合适处使用
- 更少的依赖、更少的代码优先。
- 让
pyproject.toml聚焦于主产品面deeppresenter。当某个隔离子目录的依赖确实独立且可维护时,放到其本地requirements.txt。
值得注意的是,当前 checkout 提供了可直接印证这套风格的证据:
- .pre-commit-config.yaml 用
astral-sh/ruff-pre-commit(ruff-check --select I --fix、ruff-format)与asottile/pyupgrade --py311-plus把"现代工具 + 类型/语法升级"固化成提交钩子——正好对应第 2、4 条规则;同时含check-yaml、trailing-whitespace、debug-statements等基础检查。 - skills/pptagent/requirements.txt 是一个"本地隔离子目录依赖放在独立 requirements"的实际样例:它把转换器 API 版本锁定为
pptagent==1.1.37,并声明playwright==1.62.0、PyYAML>=6、Pillow>=10、PyMuPDF>=1.24.3、fastmcp>=2.10.0,<2.14.0。这与第 6 条"隔离子目录用本地 requirements"的诉求相吻合。
沟通规范(Communication Rules)
- 用英文思考,用中文回复用户(Think in English, reply to the user in Chinese)。
- 直接、简洁;代码有问题就用技术语言说明为什么。
- 批评要针对实现、设计或假设,绝不针对人。
- 不要为了让对方舒服而稀释技术判断。
AI Agent 协作规则与"高利害"区域
对 AI Agent 而言,AGENTS.md 的 Working Rules For Agents 是最可执行的部分。它把"改哪里"与"检查什么"绑定,以降低双栈带来的误改风险。
通用规则
- 先检查真实入口再编辑。同一概念可能同时存在于
deeppresenter/与pptagent/中。 - 保持改动范围收敛。除非任务明确跨两栈,不要同时重构两套栈。
按改动类型给出的检查清单
| 你要改什么 | 应一并检查 |
|---|---|
| CLI 行为 | deeppresenter/cli/commands.py、deeppresenter/cli/common.py,以及任何配置加载路径 |
| 编排(orchestration) | deeppresenter/main.py 与 deeppresenter/agents/ 下相关 agent 类 |
| MCP 行为 | 先确认改动应落在 deeppresenter/tools/*.py 还是 pptagent/mcp_server.py |
| 导出 / 转换 | 同时看 Python 与 Node 两侧:deeppresenter/utils/webview.py 与 deeppresenter/html2pptx/ |
最后一条通用约束:
- 优先保留现有的配置名与环境变量——它们已被织入 onboarding 与示例配置中(改动会牵一发动全身)。
已知"陷阱"(Known Sharp Edges)与变更策略
AGENTS.md 用 Known Sharp Edges 列出四类风险,并给出 Preferred Change Strategy(推荐变更策略)。这些内容是 Agent 避免"看起来对、实际错"的关键。
已知陷阱
- 仓库含旧布局留下的过时文档:引用或编辑文件前,先确认文件真实存在。
- 双栈语义重叠:
deeppresenter与pptagent都定义了"生成相关概念";改一处不会自动更新另一处。 - 浏览器与 Docker 依赖是常规运行时的一部分,对某些代码路径而言不是可选的开发附加项。
- 部分测试是重集成测试:缺少 Playwright、Docker 镜像或模型凭据时可能失败。
推荐变更策略(四步)
- 先确认行为归属哪一栈。
- 只编辑最小的相关面。
- 跑最小但有意义的测试子集。
- 明确列出你在本地未能验证的依赖。
这四步与前文"务实优先、简单当约束"的哲学一脉相承:先界定归属、再最小化改动、再局部验证、最后诚实暴露未验证点。
文档中的路径清单(File Map)与当前 checkout 对照
AGENTS.md 的 File Map 给出了一份"该看哪些文件"的索引,这里完整保留其声明:
| 文件 | 用途 |
|---|---|
pyproject.toml |
包元数据、依赖、pytest markers、console scripts |
README.md |
面向用户的概览,"部分仍然有效" |
pptagent/README.md |
旧的项目叙事,聚焦原始 PPTAgent 论文/系统 |
pptagent/DOC.md |
遗留文档,有有用的概念背景,但路径与启动流不一定最新 |
deeppresenter/config.yaml.example |
模型/运行时配置 schema |
deeppresenter/mcp.json.example |
MCP 工具定义与预期环境变量 |
需要向读者强调的事实边界(以当前 checkout 为准): 文档描述的是包含 deeppresenter/、pptagent/、根级 pyproject.toml 的完整研究仓库布局。而在本文所述的这份 checkout 中,经目录与文件检索核对,根目录只含 skills/、resource/、README.md、AGENTS.md/CLAUDE.md 等,未包含 deeppresenter/、pptagent/、根级 pyproject.toml 或 deeppresenter/*.example 这些路径;可运行的能力集中在 PPTAgent Skill 目录 skills/pptagent,并通过 skills/pptagent/requirements.txt 以 pptagent==1.1.37 锁定底层包版本。
这正是文档自身"地面真值"原则的最佳示范——它已在文中警告"仓库含过时文档,引用/编辑前先验证文件存在"。因此本文的处理方式是:架构与职责按文档原样继承,路径与入口作为"文档声明"标注,并提示以实际 checkout 校验,而不把两者混为一谈。
可在此 checkout 直接验证的对照点
- 配置 schema 的活体样例:虽然
deeppresenter/config.yaml.example不在本 checkout,但 Skill 侧提供了结构同源的 skills/pptagent/config.example.yaml:
它印证了文档所指的"配置模板 + 环境变量"这一约定:# multimodal uses the host image viewer; text uses the endpoint below. mode: multimodal visual: base_url: "" model: "" api_key_env: VISUAL_API_KEY timeout_seconds: 300 delivery: mode: strict # best-effort only when the user accepts a draftapi_key_env命名承载密钥的环境变量名,mode区分宿主图像查看器(multimodal)与外部端点(text),delivery.mode在strict与best-effort间切换——这与文档"保留配置名与环境变量"的约束一致。 - 依赖隔离的活体样例:skills/pptagent/requirements.txt(见第 5 节)。
小结:如何把 CLAUDE.md 当"导航 + 护栏"用
对要维护或二次开发 PPTAgent 的人(以及被注入该文件的 AI 编码 Agent),AGENTS.md / CLAUDE.md 提供了一套可直接执行的决策框架:
- 先定位归属:是
deeppresenter(当前运行时/CLI/编排/HTML-to-PPTX)还是pptagent(旧核心/评估/MCP server 入口);默认优先deeppresenter。 - 以代码与
pyproject.toml为准:文档声明的入口(pptagent→deeppresenter.cli:main、pptagent-mcp→pptagent.mcp_server:main)与配置模板路径,作为"需校验的地面真值"。 - 按改动类型走检查清单:CLI / 编排 / MCP / 导出各有必查文件,尤其导出要同时看 Python 与 Node 两侧。
- 守住风格与哲学:少依赖、少代码、加类型、注释英文、异常不过度、缩进不超三层;批评对事不对人,判断不稀释。
- 对"陷阱"保持警惕:先验证文件存在,改动收敛到最小面,跑最小测试子集,并诚实列出未验证依赖。
把这份文档当作"项目导航 + 行为护栏",就能在双栈并存、文档与代码可能不一致的仓库里,既改对地方,也少踩已知坑。