PPTAgent 双栈架构解析:CLAUDE.md 如何界定 deeppresenter 与 pptagent、代码规范与 AI Agent 协作规则

原创2026-10-12 11:41:201,686 阅读
文章标签:AI 技能AI 应用MCP 服务媒体生成

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.md is fully current. It still references paths like webui.py that are not present in this checkout. Prefer the code and pyproject.toml over 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 条硬规则:

  1. 避免过度异常处理。除非存在要处理的具体失败模式,否则不要用防御性包装去隐藏正常控制流。
  2. 为所有函数和方法添加类型注解(type hints)。
  3. 技术文档与代码注释使用英文书写。
  4. 优先使用现代工具链与当前最佳实践:
    • 在合适处使用 uv、rg 与最新的 Python 特性;
    • 遵循当前库 API,例如用 Pydantic 的 model_dump() 而非遗留写法。
  5. 更少的依赖、更少的代码优先。
  6. 让 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 避免"看起来对、实际错"的关键。

已知陷阱

  1. 仓库含旧布局留下的过时文档:引用或编辑文件前,先确认文件真实存在。
  2. 双栈语义重叠:deeppresenter 与 pptagent 都定义了"生成相关概念";改一处不会自动更新另一处。
  3. 浏览器与 Docker 依赖是常规运行时的一部分,对某些代码路径而言不是可选的开发附加项。
  4. 部分测试是重集成测试:缺少 Playwright、Docker 镜像或模型凭据时可能失败。

推荐变更策略(四步)

  1. 先确认行为归属哪一栈。
  2. 只编辑最小的相关面。
  3. 跑最小但有意义的测试子集。
  4. 明确列出你在本地未能验证的依赖。

这四步与前文"务实优先、简单当约束"的哲学一脉相承:先界定归属、再最小化改动、再局部验证、最后诚实暴露未验证点。

文档中的路径清单(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 draft
    
    它印证了文档所指的"配置模板 + 环境变量"这一约定:api_key_env 命名承载密钥的环境变量名,mode 区分宿主图像查看器(multimodal)与外部端点(text),delivery.mode 在 strict 与 best-effort 间切换——这与文档"保留配置名与环境变量"的约束一致。
  • 依赖隔离的活体样例:skills/pptagent/requirements.txt(见第 5 节)。

小结:如何把 CLAUDE.md 当"导航 + 护栏"用

对要维护或二次开发 PPTAgent 的人(以及被注入该文件的 AI 编码 Agent),AGENTS.md / CLAUDE.md 提供了一套可直接执行的决策框架:

  1. 先定位归属:是 deeppresenter(当前运行时/CLI/编排/HTML-to-PPTX)还是 pptagent(旧核心/评估/MCP server 入口);默认优先 deeppresenter。
  2. 以代码与 pyproject.toml 为准:文档声明的入口(pptagent→deeppresenter.cli:main、pptagent-mcp→pptagent.mcp_server:main)与配置模板路径,作为"需校验的地面真值"。
  3. 按改动类型走检查清单:CLI / 编排 / MCP / 导出各有必查文件,尤其导出要同时看 Python 与 Node 两侧。
  4. 守住风格与哲学:少依赖、少代码、加类型、注释英文、异常不过度、缩进不超三层;批评对事不对人,判断不稀释。
  5. 对"陷阱"保持警惕:先验证文件存在,改动收敛到最小面,跑最小测试子集,并诚实列出未验证依赖。

把这份文档当作"项目导航 + 行为护栏",就能在双栈并存、文档与代码可能不一致的仓库里,既改对地方,也少踩已知坑。

登录后查看全文
PPTAgent