内容
# PowerPoint 画布控制器
[中文说明](README.zh-CN.md) · [MIT License](LICENSE)
PowerPoint 画布控制器是一个开源的 Codex 插件和本地 MCP 实现，用于通过 PowerPoint 的原生 COM 对象模型构建可编辑的 Microsoft PowerPoint 幻灯片。它直接绘制到可见的桌面应用程序，保持文本/形状/箭头/图片可编辑，并且从不使用操作系统鼠标或键盘自动化。
> **平台：** Windows + 桌面 Microsoft PowerPoint。基于 Web 的 PowerPoint、WPS Office、LibreOffice、macOS 和 Linux 不是运行时目标，因为此插件依赖于 Windows PowerPoint COM API。
## 功能
| 功能 | 详情 |
| --- | --- |
| 实时编辑 | 创建幻灯片并添加、更新、删除、分组、检查和截图原生 PowerPoint 对象。 |
| 可编辑图元 | 矩形、圆角矩形、椭圆、三角形、菱形、六边形、平行四边形、云形、文本框、线条、连接线和独立图片。 |
| 节奏控制 | `powerpoint_live_draw_sequence` 每次应用一个 COM 编辑；默认延迟为 100 毫秒，可按批次更改。 |
| 质量循环 | 检查几何形状和文本，渲染 PowerPoint 截图，检测文本溢出和幻灯片外对象，然后原地优化。 |
| 输出 | 保存可编辑的 `.pptx`；以精确像素宽度导出幻灯片为 PNG/JPG；导出演示文稿为 PDF。 |
| 安全 | 使用命名目标，默认重用活动演示文稿，需要 `confirm: true` 来清除幻灯片或关闭演示文稿。 |
| 运行时 | 无依赖的 Node.js MCP 服务器 + Windows PowerShell 桥接器；不需要 npm 包安装。 |
## 工作原理
```text
Codex
│ MCP 通过 stdio
▼
Node.js 服务器（实时或文件实用工具）
│ 临时请求 JSON
▼
PowerShell 桥接器
│ 原生 COM 调用
▼
可见的桌面 Microsoft PowerPoint
```
桥接器直接编辑 PowerPoint 的对象模型。它不首先合成 XML，不打开预生成的 文件，也不注入 OS 级输入事件。图片保持为单独的 PowerPoint 图片对象；标签、箭头、面板和其他形状不烘焙到光栅图像中。
## 要求
- Windows 10 或 Windows 11
- 桌面 Microsoft PowerPoint（Microsoft 365 或受支持的永久桌面版本）
- Codex 桌面应用程序或带有插件支持的 Codex CLI
- Node.js 18 或更新版本（推荐 Node.js 22+）
- Windows PowerShell 5.1 或 PowerShell 7+
- Git（如果从存储库安装）
不需要 npm 依赖项。PowerPoint 必须安装在与 MCP 服务器相同的 Windows 机器上。
## 安装
此存储库是插件根目录。它不是存储库级别的市场目录，因此全新安装首先在 Codex 的个人市场中注册克隆文件夹。
### 从 GitHub 全新安装（PowerShell）
以下命令将插件克隆到标准个人插件位置，创建或更新个人市场条目并安装它。现有市场条目被保留；只有此插件的条目被替换。
```powershell
$pluginRoot = Join-Path $HOME "plugins\powerpoint-canvas-controller"
$marketplacePath = Join-Path $HOME ".agents\plugins\marketplace.json"
New-Item -ItemType Directory -Force -Path (Split-Path $pluginRoot -Parent) | Out-Null
if (Test-Path (Join-Path $pluginRoot ".git")) {
git -C $pluginRoot pull --ff-only
} elseif (Test-Path $pluginRoot) {
throw "安装目录存在但不是此 Git 存储库：$pluginRoot"
} else {
git clone https://github.com/wangzian828/powerpoint-canvas-controller.git $pluginRoot
}
New-Item -ItemType Directory -Force -Path (Split-Path $marketplacePath -Parent) | Out-Null
if (Test-Path $marketplacePath) {
$catalog = Get-Content -Raw -LiteralPath $marketplacePath | ConvertFrom-Json
} else {
$catalog = [pscustomobject]@{
name = "personal"
interface = [pscustomobject]@{ displayName = "个人" }
plugins = @()
}
}
$entry = [pscustomobject]@{
name = "powerpoint-canvas-controller"
source = [pscustomobject]@{ source = "local"; path = "./plugins/powerpoint-canvas-controller" }
policy = [pscustomobject]@{ installation = "AVAILABLE"; authentication = "ON_INSTALL" }
category = "生产力"
}
$catalog.plugins = @($catalog.plugins | Where-Object { $_.name -ne $entry.name }) + $entry
$catalog | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $marketplacePath -Encoding utf8
$marketplaceName = $catalog.name
codex plugin add "powerpoint-canvas-controller@$marketplaceName"
```
安装后，重启 Codex 并启动新线程，以便加载技能和两个 MCP 服务器。如果您已经维护标准个人市场条目，则最终安装步骤如下：
```powershell
codex plugin add powerpoint-canvas-controller@personal
```
### 请求 Codex 安装
在具有终端访问权限的 Codex 任务中，您可以使用此请求：
```text
安装 https://github.com/wangzian828/powerpoint-canvas-controller。
克隆到 ~/plugins/powerpoint-canvas-controller，在个人 Codex 市场中注册该本地文件夹，安装 powerpoint-canvas-controller，验证插件，并告诉我何时重启 Codex。安装过程中不要打开 PowerPoint。
```
## 使用
安装后启动新 Codex 线程，提及 **PowerPoint 画布控制器**，并提供幻灯片或参考资料。第一个请求是：
```text
使用 PowerPoint 画布控制器。在活动 PowerPoint 演示文稿中工作，除非没有合适的目标，否则不要打开第二个演示文稿。仅使用 PowerPoint 的原生 COM API；不要控制操作系统鼠标或键盘。以可编辑的文本、形状、箭头、连接线和图片重建此图。按 100 毫秒的步骤逐个绘制逻辑区域，每个区域完成后检查截图，纠正溢出和歪曲的连接线，然后保存可编辑的 PPTX 并导出宽度为 2000 像素的 PNG 预览图。
```
中文提示同样有效：
```text
使用 PowerPoint 画布控制器。优先复用当前活动的 PowerPoint 演示文稿，不要打开第二个文稿，除非没有合适的目标。只能调用 PowerPoint 原生 COM API，不能控制系统鼠标键盘。把这张图重建为可编辑的文字、形状、箭头、连接符和图片；按 100 ms 的步骤逐个绘制逻辑区域，每个区域完成后检查截图，修正溢出和歪曲的连接线，最后保存可编辑 PPTX，并导出宽度为 2000 像素的 PNG 预览图。
```
## 单演示文稿规则
插件设计用于保持实时会话整洁：
1. 在创建任何内容之前检查 `powerpoint_live_status`。
2. 尽可能重用活动演示文稿或明确提供的 `presentation_path`。
3. 仅在没有合适目标的情况下或显式请求新建演示文稿时调用 `powerpoint_live_new_presentation`。
4. 在绘图任务中保持一个命名目标；不要为每个区域或测试用例创建新演示文稿。
5. 捆绑的自测试创建了一个临时演示文稿，重用它并在 `finally` 块中关闭它。
当多个用户演示文稿打开时，请传递完整的演示文稿路径，而不是依赖活动窗口。插件不会故意修改无关的演示文稿，但显式路径是多窗口会话中最安全的选择。
## MCP 服务器和工具
插件通过 [.mcp.json](.mcp.json) 暴露两个_stdio_ MCP 服务器。
### `powerpoint-live`
针对可见 PowerPoint 应用程序的实时操作：
`powerpoint_live_launch` · `powerpoint_live_status` · `powerpoint_live_new_presentation` ·
`powerpoint_live_add_slide` · `powerpoint_live_add_shape` · `powerpoint_live_add_text` ·
`powerpoint_live_add_line` · `powerpoint_live_add_connector` · `powerpoint_live_add_picture` ·
`powerpoint_live_update_shape` · `powerpoint_live_delete_shape` ·
`powerpoint_live_group_shapes` · `powerpoint_live_draw_sequence` · `powerpoint_live_clear` ·
`powerpoint_live_close_presentation` · `powerpoint_live_inspect` ·
`powerpoint_live_screenshot`
`powerpoint_live_draw_sequence` 支持这些操作类型：`shape`、`text`、`line`、
`connector`、`picture`、`update`、`delete` 和 `wait`。
### `powerpoint-file-utils`
文件导向的操作仍然使用 PowerPoint 自己的渲染器和对象模型：
`powerpoint_file_inspect` · `powerpoint_file_validate` · `powerpoint_file_save` ·
`powerpoint_file_export_slide` · `powerpoint_file_export_pdf`
检查和验证以只读方式打开显式命名的文件，默认情况下不保存并关闭它。现有的输出文件需要 `overwrite: true`。请参见 [`skills/control-powerpoint-canvas/references/tool-reference.md`](skills/control-powerpoint-canvas/references/tool-reference.md) 中的完整字段参考。
## 最小批次示例
坐标和大小是 PowerPoint 点（`72 pt = 1 inch`）。常见的 16:9 幻灯片是 `960 × 540` 点，颜色使用 `#RRGGBB`。
```json
{
"step_delay_ms": 100,
"screenshot_after": true,
"operations": [
{
"type": "shape",
"name": "input_card",
"shape_type": "rounded",
"text": "输入",
"x": 80,
"y": 210,
"width": 210,
"height": 90,
"fill_color": "#EEF4FC",
"line_color": "#17345B",
"line_width": 2,
"font_size": 20,
"bold": true
},
{
"type": "shape",
"name": "model_card",
"shape_type": "rounded",
"text": "模型",
"x": 375,
"y": 210,
"width": 210,
"height": 90
},
{
"type": "connector",
"name": "input_to_model",
"source": "input_card",
"target": "model_card",
"connector_type": "straight",
"end_arrow": "triangle"
}
]
}
```
使用原生连接线时，箭头应保持附着，而形状移动时。使用直线时，精确坐标很重要。为每个对象分配稳定的语义名称；后续更新和删除操作通过该名称寻址。
## 推荐的绘图工作流
捆绑的技能遵循此顺序：
1. 读取当前状态和幻灯片尺寸。
2. 建立视觉层次结构和可重用的对象名称。
3. 使用节奏批次 (`step_delay_ms: 100`) 绘制一个逻辑区域。
4. 调用 `powerpoint_live_screenshot` 和 `powerpoint_live_inspect`。
5. 在移动到下一个区域之前，修复重叠、文本平衡、信息密度、幻灯片外几何形状和连接线路由。
6. 在交付前运行 `powerpoint_file_validate`。
7. 使用 `powerpoint_file_save` 保存可编辑的 `.pptx`。
8. 使用 `powerpoint_file_export_slide` 导出 PNG/JPG 预览图；设置 `width_px: 2000` 以获取 2000 像素预览图。使用 `powerpoint_file_export_pdf` 获取 PDF 可交付成果。
避免添加填充微标签仅用于覆盖空白。使用有意义的内容、更大的有用文本、更紧密的间距和显式关系来提高密度。
## 安全性和隐私
- 所有实时编辑都通过 PowerPoint 的原生 COM 对象模型进行。
- 插件从不合成 XML 作为第一步，从不发送 OS 级鼠标或键盘事件。
- `powerpoint_live_clear` 和 `powerpoint_live_close_presentation` 需要 `confirm: true`。
- 关闭演示文稿不会退出 PowerPoint；保存行为是显式的。
- 只读检查和验证默认情况下不保存文件并关闭文件。
- 临时桥接请求文件在本地创建并在每次调用后删除。
- 不包含托管的后端、遥测或插件特定的凭据存储。
- 不要将机密幻灯片、参考图像或导出的演示文稿上传到问题或拉取请求。
## 存储库布局
```text
.
├── .codex-plugin/plugin.json # 插件清单和 UI 元数据
├── .mcp.json # 两个_stdio_ MCP 服务器定义
├── scripts/
│ ├── live-server.mjs # 实时 PowerPoint MCP 服务器
│ ├── file-server.mjs # 文件检查/保存/导出 MCP 服务器
│ ├── mcp-common.mjs # JSONL MCP 和 PowerShell 桥接器帮助程序
│ ├── powerpoint-bridge.ps1 # 原生 PowerPoint COM 实现
│ └── self-test.mjs # 单演示文稿集成测试
├── skills/control-powerpoint-canvas/
│ ├── SKILL.md # 绘图和审查工作流程
│ ├── agents/openai.yaml # 技能 UI 元数据
│ └── references/tool-reference.md # 操作字段和示例
├── LICENSE
└── README.md / README.zh-CN.md
```
## 开发和验证
仅在安装了桌面 PowerPoint 的 Windows 机器上运行自测试。它打开一个临时演示文稿，执行两个 MCP 服务器，保存并导出工件到所选目录，验证结果，并在 `finally` 中关闭测试演示文稿：
```powershell
node .\scripts\self-test.mjs .\test-output
```
生成的 `test-output/` 目录被 Git 忽略。有用的静态检查是：
```powershell
node --check .\scripts\file-server.mjs
node --check .\scripts\live-server.mjs
node --check .\scripts\mcp-common.mjs
node --check .\scripts\self-test.mjs
```
对于插件和技能架构验证，请使用 Codex 插件创建器和技能创建器工具附带的验证程序：
```powershell
$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
$skillCreator = Join-Path $codexHome "skills\.system\skill-creator"
$pluginCreator = Join-Path $codexHome "skills\.system\plugin-creator"
python (Join-Path $skillCreator "scripts\quick_validate.py") `
.\skills\control-powerpoint-canvas
python (Join-Path $pluginCreator "scripts\validate_plugin.py") .
```
## 故障排除
### 插件在 Codex 中不可见
重启 Codex 并启动新线程。确认市场条目指向克隆的文件夹，并且 `codex plugin list` 显示插件已安装并启用。
### 未找到 PowerPoint 或桥接器超时
确认已安装桌面 PowerPoint 并且可以正常启动。关闭模态 Office 对话框，使用完整的 `presentation_path`（当打开多个文档时），并重试 `powerpoint_live_status`。插件无法控制基于 Web 的 PowerPoint 或 WPS Office。
### 文本被剪裁或箭头位置不正确
运行 `powerpoint_live_inspect` 和 `powerpoint_live_screenshot` 以获取受影响的逻辑区域。使用 `powerpoint_live_update_shape` 进行有针对性的几何形状、边距、字体大小或 z-order 更改；使用命名原生连接器代替自由浮动线，当端点应跟随形状。
### 导出失败
检查目标目录是否存在，并且现有文件仅在 `overwrite: true` 时被替换。尝试从桌面 PowerPoint 手动导出相同的幻灯片，以区分 Office 渲染问题和插件问题。
## 贡献
欢迎提出问题和拉取请求。包括 Windows 版本、PowerPoint 版本、Codex 版本、Node.js 版本、确切的工具调用和相关错误文本。请不要提交生成的 `.pptx`、PNG、PDF、机密参考图像或本地测试输出。
## 许可证
MIT © 2026 [wangzian828](https://github.com/wangzian828)
