ppt-agent

ppt-agent 是 Windows 上的 PowerPoint 实时控制工具。Agent 可以读取当前打开的演示、修改文字与形状、编辑备注和表格单元格，并通过回读与截图检查结果。操作发生在桌面版 PowerPoint 中：编辑自动跟到目标页和形状，浏览器观察台同步显示画面与中文操作流水。

当前状态：开发中的可用核心。 本机已验证真实 PowerPoint 的读取、编辑、保存、实时取景及 MCP 接入。PowerPoint 内加载项和 DSH 状态条仍需安装与端到端验收；详细记录见 交付报告。

功能

Related MCP server: ppt-mcp

快速开始

需要 Windows、Python 3.11+、已安装并可启动的桌面版 Microsoft PowerPoint。本机验收环境为 Python 3.13 与 PowerPoint 16.0。网页版 PowerPoint 不提供本项目使用的 COM 接口。

在 PowerShell 中执行（示例使用 Python 3.13，可以换为自己安装的受支持版本）：

git clone https://github.com/Curlance/ppt-agent.git
cd ppt-agent
py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"

.venv\Scripts\python.exe -m pptd doctor
.venv\Scripts\python.exe -m pptd url --launch

doctor 会检查解释器和 COM，必要时启动守护进程。url --launch 打开带本机令牌的观察台。接着打开自己的演示：

.venv\Scripts\python.exe -m pptd open "C:\path\to\demo.pptx"
.venv\Scripts\python.exe -m pptd call ppt_read_slide -a slide=1
.venv\Scripts\python.exe -m pptd call ppt_shot -a slide=1
.venv\Scripts\python.exe -m pptd call ppt_set_pace -a pace_ms=800

读取结果包含形状序号和 ref。使用返回的标识编辑，并回读检查：

# shape 必须替换为读取结果中的实际形状标识
.venv\Scripts\python.exe -m pptd call ppt_set_text -a slide=1 -a shape=1 -a text="新的标题"
.venv\Scripts\python.exe -m pptd call ppt_read_slide -a slide=1

查看全部工具：.venv\Scripts\python.exe -m pptd tools。需要结束会话时执行 .venv\Scripts\python.exe -m pptd stop，守护进程停止后 PowerPoint 保持打开。

实际界面

以下为真实浏览器渲染截图，画面中的 PPT 是测试自动创建的示例演示。

观察台：当前页实时取景、PowerPoint 状态、工具列表和操作流水。

窄任务窗格页面：实时画面、跟速与停止按钮。此截图是在浏览器中验证的页面，PowerPoint 内旁加载仍待验收。

接入 agent

安装完成后，环境内提供 pptctl 命令；也可以始终用 .venv\Scripts\python.exe -m pptd 调用。

这些入口复用同一个守护进程。操作令牌保存在 %LOCALAPPDATA%\ppt-agent\runtime.json，运行 pptctl url --mcp-token 可查看；配置或截图中不要公开令牌。

完整说明见 接入指南、工具参考 和 OpenAPI。公开指南使用占位路径，可为本机生成配置：

.venv\Scripts\python.exe -m pptd export-api --local-paths --out local-docs

可选集成：

• DSH：pptctl dsh-bundle 生成含本机路径的 bundle，pptctl dsh-status 检查安装与加载状态。

• Agent 技能：skills/ppt-agent 描述读取、编辑、回读和错误恢复流程；pptctl skill-install 默认安装到 DSH 技能目录，其他宿主可用 --out 指定目录。

• PowerPoint 内界面：加载项说明 提供 VBA 浮窗和 Web Add-in 的安装步骤；安装与信任设置需自行完成。

验证与边界

# 常规测试：不启动真实 PowerPoint
.venv\Scripts\python.exe -m pytest -q
.venv\Scripts\python.exe -m pptd export-api --check

# 真机测试：会启动 PowerPoint 并创建临时演示
.venv\Scripts\python.exe -m pytest -m com -q

CI 在 Windows 上检查单元测试、接口文档和打包；CI 环境没有桌面 Office，真机 COM 与 UI 验收在本机单独运行。测试记录与具体覆盖范围见 交付报告。

项目结构

pptd/               守护进程、STA COM、注册表、工具与三种接口
addin/              VBA 源码、Web Add-in 清单与安装说明
skills/ppt-agent/   Agent 的操作与验证规则
docs/api/           自动生成的契约和接入指南
docs/screenshots/   自建示例演示的真实 UI 截图
assets/             Logo 与流程图
tests/              单元测试、真机 COM 和浏览器测试

设计背景 保留早期设计，完成情况以当前 README 和交付报告为准。运行记录、令牌、私钥、本机路径配置、备份与构建产物均不纳入仓库。

许可证

本项目公开源码，采用 PolyForm Noncommercial License 1.0.0。仅授予许可条款规定的非商业用途权限，商业使用须事先取得作者的另行授权。 具体权利与条件以 LICENSE 为准。商业授权请求可通过本仓库的 Issues 联系作者。

Logo 的设计说明和生成提示词见 品牌说明。本项目与 Microsoft 无官方关联。