# AnPPT Agent

AnPPT 是托管的 PPT 生成网站。你只调用元能力：生图、复刻、改图、导出。不要在本地做 PPT，不要另开扣费账户。任何消耗和生成都必须：Agent 报价确认 + 用户在网站点确认，两道都过才能执行。

文档: https://ppt.an520.xin/agents
JSON 目录: https://ppt.an520.xin/api/agent/catalog
MCP: https://ppt.an520.xin/api/agent/mcp
HTTP 调技能: POST https://ppt.an520.xin/api/agent/skills/{name}  （JSON 参数，与 MCP tools/call 相同）

## 鉴权

钥匙在网站账号里创建。扣费=该账号钱包，价与网页相同。Bearer 只允许 /api/agent/* 与钱包估价，不要带 Cookie，也不要直打网站生图路由。PPT 只在 AnPPT 服务器生成。生成/转可编辑必须先 propose_job，再等用户在 /agents 确认。

```
Authorization: Bearer anppt_live_…
```

## 扣费与生成确认（强制）

1. Agent 调用 `propose_job`（`agentConfirmed=true`），写出这一步要生成什么、扣多少星。
2. 用户打开网站 `/agents` 点确认（`confirm_job` 只接受登录 Cookie，API Key 不能代替）。
3. `list_jobs` 看到 status=ready 后，才带 `proposalId` 调用 `generate_page` / `convert_editable` 等。
4. 一页一轮。用户没点头禁止生成下一页，禁止一次跑完全书。

MCP 配置示例：

```json
{
  "mcpServers": {
    "anppt": {
      "url": "https://ppt.an520.xin/api/agent/mcp",
      "headers": {
        "Authorization": "Bearer anppt_live_YOUR_KEY"
      }
    }
  }
}
```

## 工作流

### 逐页图生图（用户确认每一页）

1. 只拆当页：原文 + 当页全部原图 upload_asset。不要把整份 PPT 的图一次喂进。
2. 锁画风：用户认可的第一页当风格底；内容页锁顶栏/底栏，中间可换；少字页跟封面完成度。
3. propose_job skill=generate_page，agentConfirmed=true，summary 写页码、文案要点、原图清单、10🌟。停住。
4. 用户在网站 /agents 点确认后，带 proposalId 调用 generate_page（同一 projectId）。mode=replicate 时 imagePath=锁图。
5. get_project 把图给用户看。点头才下一页；失败只重跑当页。禁止一次生成全书。
6. 全书完成后 propose_job convert_editable（20🌟/页），用户再确认才转可编辑，然后按页 refine_page 微调也要再确认。

### 一张一张生成（无原稿）

1. quote_credits action=deck_page_generate pages=1
2. propose_job → 用户确认 → generate_page（同一 projectId）
3. get_project 确认图片后再报价下一页
4. 全书完成后用户确认再 export_image 或 convert_editable

### 复刻 / 美化别人的 PPT

1. upload_asset 每页壳图
2. plan_beautify（免费，不需确认）
3. 对每一页：propose_job generate_page mode=replicate → 用户确认 → 生成
4. 全书完成后用户确认再转可编辑

### 整套文档生成 PPT

1. create_deck（pages 或 sourceText），outline/structure 免费
2. run_deck generate-slide 必须先 propose_job，用户确认一页做一页；禁止 action=generate 一次跑完全书
3. get_deck 等到该页成功
4. 用户确认后再 convert_editable

## 技能

### get_wallet — 查钱包

读取当前 API Key 所属 AnPPT 账号的星星余额。所有生成/改图/转可编辑都扣这只钱包，没有单独的 Agent 账户。先查余额再开贵操作。

- 价格: 不单独计价
- HTTP: `GET https://ppt.an520.xin/api/credits/balance`
- MCP tool: `get_wallet`

### quote_credits — 估价

按官网标准价估算星星，不扣费。action 只能是：deck_page_generate（生图/复刻成图 10🌟/页）、deck_page_refine（改图 5🌟/页）、export_editable（转可编辑 20🌟/页）、export_editable_text（轻量文字档 5🌟/页）、export_image（图片版 PPTX，0）、outline（大纲，0）。pages 为页数。402 之前先 quote。

- 价格: 不单独计价
- HTTP: `POST https://ppt.an520.xin/api/credits/estimate`
- MCP tool: `quote_credits`

### upload_asset — 上传素材

把图片或 PDF 存到该用户名下，返回 path。后续 generate_page.imagePath、plan_beautify.imagePaths、create_deck 的文件都用这个 path。MCP 传 name/mime/base64；不要传外链。单文件 ≤30MB，每用户每小时最多 60 次。

- 价格: 不单独计价
- HTTP: `POST https://ppt.an520.xin/api/assets/upload`
- MCP tool: `upload_asset`

### generate_page — 生成一页图

在 AnPPT 服务器生成一张 16:9 幻灯片图，扣 10🌟，失败退星。禁止直接调用。必须：① propose_job（skill=generate_page，agentConfirmed=true，summary 写清这一页文案/原图/星星）② 等用户在网站 /agents 点确认 ③ 再带 proposalId 调用本技能。一页一轮，用户点头才翻下一页。普通页：title+content，可带 stylePackId。复刻：mode=replicate 且 imagePath=已锁定的壳/风格图，content=当页大纲。同一套 PPT 复用 projectId。不要把整份 PPT 的图一次喂进；只要当页原图。不要在本地画 PPT。

- 价格: 10🌟
- 必须先报价并等用户确认
- HTTP: `POST https://ppt.an520.xin/api/single-page/generate`
- MCP tool: `generate_page`

### refine_page — 改一页图

对已生成页做图生图修改，扣 5🌟/次，失败退星。禁止直接调用：先 propose_job，等用户确认后再带 proposalId。editInstruction 用中文写清改什么、什么保持不变。需要已有 pageId。

- 价格: 5🌟
- 必须先报价并等用户确认
- HTTP: `POST https://ppt.an520.xin/api/single-page/refine`
- MCP tool: `refine_page`

### get_project — 读单页项目

读取单页/美化项目的页面、状态、图片 URL。generate_page 后用它核对 status 与 imageUrl。

- 价格: 不单独计价
- HTTP: `GET https://ppt.an520.xin/api/single-page/project`
- MCP tool: `get_project`

### plan_beautify — 复刻拆文案

PPT 美化元能力的规划步：按壳页图+主题/材料，拆出与页数一致的新文案（免费 LLM，不扣星）。先 upload_asset 得到 imagePaths，再对本工具。返回的 slides[].title/content 再逐页交给 generate_page（mode=replicate，同一 imagePath）。不要把复刻走成普通文生图。

- 价格: 不单独计价
- 调用需功能开关 ppt_replicate（说明书可匿名读，执行仍 404）
- HTTP: `POST https://ppt.an520.xin/api/tools/replicate/plan`
- MCP tool: `plan_beautify`

### create_deck — 创建整套 PPT

在网站上建一套 deck（不是本地文件）。有现成逐页文案时传 pages[{title,rawText}]，状态直接 outlined。只有长文档时传 sourceText+targetPageCount（1–40），状态 parsed，接着 run_deck outline。stylePackId 可选。解析/大纲不扣星。

- 价格: 不单独计价
- HTTP: `POST https://ppt.an520.xin/api/deck/paged-copy-v2`
- MCP tool: `create_deck`

### run_deck — 推进整套 PPT

对已有 deckId 执行工作台动作。免费：outline / structure / confirm-structure。生成必须一页一轮：只允许 generate-slide / refine-slide 等单页动作，且必须先 propose_job 再等用户确认。禁止 action=generate 或 retry-failed 一次跑完全书。生成 10🌟/页，改图 5🌟，失败退星。

- 价格: 10🌟
- 必须先报价并等用户确认
- HTTP: `POST https://ppt.an520.xin/api/deck/{deckId}`
- MCP tool: `run_deck`

### get_deck — 读整套 PPT

读取 deck 状态、每页 genStatus/imageUrl、活跃 job。generating 时隔几秒再拉，不要重复 generate。

- 价格: 不单独计价
- HTTP: `GET https://ppt.an520.xin/api/deck/{deckId}`
- MCP tool: `get_deck`

### export_image — 导出图片版 PPTX

把已生成页打成 16:9 整页图片 PPTX，免费但仍算生成，必须先 propose_job 再等用户确认。deck 传 deckId；单页/美化项目传 projectId。没有成功页会 409。

- 价格: 0🌟
- 必须先报价并等用户确认
- HTTP: `POST https://ppt.an520.xin/api/deck/{id}/export-image`
- MCP tool: `export_image`

### convert_editable — 转可编辑 PPTX

把页图交给网站转成元素级可编辑 PPTX，20🌟/页，失败退星。禁止直接调用：先 propose_job，等用户在 /agents 确认后再带 proposalId。只接受已生成项目的 deckId 或 projectId；不要把 PDF/图片 base64 放进确认单（文件转换请用网站「文件转可编辑」）。页数由服务器按实页计价，不能少报。返回 exportId 后 get_export 轮询。不要反复 force。

- 价格: 20🌟
- 必须先报价并等用户确认
- HTTP: `POST https://ppt.an520.xin/api/editable-conversions`
- MCP tool: `convert_editable`

### propose_job — 报价并请用户确认

任何消耗或生成的第一步。Agent 先 quote，再本工具：skill=要执行的技能名，args=稍后真正调用时的参数，summary=给人看的一句话（页码、文案要点、扣多少星），agentConfirmed=true 表示你已核对。不扣费。转可编辑的页数由服务器按项目实页计算，不能少报。返回 proposalId 与 credits。然后停下来，让用户打开网站 /agents 点确认（API Key 不能代替用户）。用户确认前禁止 generate_page / convert_editable。一页一轮。

- 价格: 不单独计价
- HTTP: `POST https://ppt.an520.xin/api/agent/skills/propose_job`
- MCP tool: `propose_job`

### list_jobs — 待确认列表

列出该账号尚未完成的确认单。pending_user=等用户点头；ready=用户已确认，可以带 proposalId 执行。外部 Agent 应轮询本工具，不要催用户以外的渠道扣费。

- 价格: 不单独计价
- HTTP: `POST https://ppt.an520.xin/api/agent/skills/list_jobs`
- MCP tool: `list_jobs`

### confirm_job — 用户确认扣费

只有网站登录用户（Cookie）能调用。API Key / MCP 调用会 403。用户在 /agents 点确认时走这里。需要 proposalId 且 userConfirmed=true。

- 价格: 不单独计价
- HTTP: `POST https://ppt.an520.xin/api/agent/skills/confirm_job`
- MCP tool: `confirm_job`

### cancel_job — 取消确认单

取消尚未执行的确认单。已消耗的不能取消。

- 价格: 不单独计价
- HTTP: `POST https://ppt.an520.xin/api/agent/skills/cancel_job`
- MCP tool: `cancel_job`

### get_export — 导出任务

按 exportId 读取转可编辑/图片版导出进度与下载 url。processing 就轮询，不要重开转换。

- 价格: 不单独计价
- HTTP: `GET https://ppt.an520.xin/api/pptx-exports/{exportId}`
- MCP tool: `get_export`