# PraxisHub：微信公众号草稿创建能力

这份文档给 AI 助手读取。目标是让 AI 知道什么时候使用托管 API 创建微信公众号文章任务、如何调用、如何验证成功，以及哪些步骤必须留给用户手动确认。

## 能力边界

- 能力 ID：`wechat.create_draft`
- 作用：把 Markdown 文章提交给PraxisHub，通过服务端流程生成公众号预览，并在账号能力准备好后创建微信公众号草稿。
- 默认模式：只创建草稿，不公开发布文章。
- 适用对象：Codex、Claude、本机自动化脚本、团队内部 AI agent。
- 成功结果：返回 `wechat_draft:` 开头的回执，回执后缀通常是微信草稿 `media_id`。

## 首选接口

```bash
curl -X POST https://mt-api.kakacut.cn/platform-kernel/pipeline/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "workspace_id": "cloud-wechat",
    "user_id": "server",
    "pipeline_id": "wechat-markdown-default",
    "article_path": "/opt/praxis-ai/data/articles/example.md",
    "title": "公众号文章标题",
    "run_id": "stable-run-id",
    "metadata": {
      "content_source_url": "https://example.com/source",
      "reviewer": "ai-agent"
    }
  }'
```

## 调用前检查

1. 文章文件必须是托管服务可读取的 Markdown 文件。
2. 使用已配置的 `workspace_id`、`user_id` 和 `pipeline_id`。
3. 如果要让读者在微信里看到原文链接，把它放进请求的 `metadata`。
4. 设置稳定的 `run_id`，方便轮询和排障。

## 验证成功

API 返回任务启动后，不要立刻声称草稿已创建。必须轮询运行状态：

```text
GET https://mt-api.kakacut.cn/api/pipeline/run?id={run_id}&token={api_token}
```

成功条件：

- 整体 run 状态是 `completed`。
- `wechat-draft` 步骤状态是 `completed`。
- 返回的 receipt 以 `wechat_draft:` 开头。

## 自动写入草稿的内容

- 标题
- 摘要
- 作者
- 渲染后的公众号正文 HTML
- 封面或 thumb media
- 原文链接 `content_source_url`
- 留言开关 `need_open_comment`
- 仅粉丝留言 `only_fans_can_comment`

## 仍需用户在微信后台确认

- 最终公开发布或定时发布
- 原创、赞赏、付费、合集、创作来源、广告、平台推荐等微信后台选项
- 微信草稿 API 不支持的其它后台开关

## 常见错误

- `wechat_pipeline_target_missing`：需要使用 `--console-url` 和已配置的 pipeline/preset；开发直连才使用 `--direct-wechat`。
- `wechat_cover_missing`：传入的封面不存在，或服务端未配置 `WECHAT_COVER_PATH`。
- `42001`：微信 access token 过期或刷新失败，等待服务端刷新后重试。
- `40007`：media id 无效，通常与封面上传、thumb media 或凭据不匹配有关。

## 给 AI 的行为要求

- 不要绕过托管服务直接拼 WeChat API 请求。
- 不要把“任务已启动”说成“草稿已创建”。
- 不要承诺最终发布；这里只创建草稿。
- 失败时返回可恢复原因和下一步动作。