# Ciao

> 人和 Agent 同写一篇，复制进公众号。
> Markdown → 微信公众号成品 HTML。给人用编辑器，给 Agent 用 HTTP API。
> 基址：https://weixin.genedai.md
> 本文件：https://weixin.genedai.md/llms.txt

不要自己拼公众号 HTML，不要走 MCP。用下面的 HTTP 接口。写完把返回的 /d/<id> 链接发给用户，他们在浏览器里打开即可预览、改、复制到公众号。

## 鉴权

写接口默认开放（未设置 UPLOAD_KEY）。若部署时设置了 UPLOAD_KEY，请求头加：

    x-upload-key: <口令>

CORS 已开（Origin *）。浏览器、curl、Codex、Claude Code、Workbody 均可直连。

## 推荐工作流

1. 如有图：POST /api/upload，把返回的 url 写进 Markdown：![图注](url)
2. 创建草稿：POST /api/article（纯文本用 text，已排好用 md）
3. 把返回的 url（https://weixin.genedai.md/d/<id>）发给用户
4. 还要改：PATCH /api/article/<id>

## POST /api/article

创建可分享草稿。JSON。

    { "text": "未排版草稿" }
    { "text": "未排版草稿", "format": false }
    { "md": "已经带标记的正文", "title": "标题", "lead": "导语", "byline": "文丨张三" }

字段：
- text：纯文本。满 80 字且未写 format=false 时走 AI 排版。短稿或 format=false 则原样当正文。要强制排版写 format=true
- md：已排版 Markdown。与 text 二选一；同时有则用 md
- model：可选，指定 Workers AI 模型
- title, lead, byline, cover, coverSource, account, color, fontSize, fin
- 不要自己传 id，服务端会生成。User-Agent 别用 Python-urllib（Cloudflare 可能 403）

返回：{ "url", "id", "model", "updated" }

## GET /api/article/:id

读草稿 JSON：{ v, created, updated, model, state: { title, md, lead, ... }, revs: [{ at, title, chars }] }。revs 是可恢复的上一稿摘要。没有这篇是 404。HEAD 同路径可探活。
加 ?rev=<at> 只读那一版全文 { at, state }，不改当前稿。

## PATCH /api/article/:id  （PUT 同）

改已有草稿。JSON，只传要改的字段（title, account, cover, coverSource, lead, byline, md, color, fontSize, fin）。
md 可以是空字符串（会清空正文）。请带 "baseUpdated": "<上次的 updated>"，不一致返回 409 { error, updated, revs }。不带则最后写入获胜，但会先把当前稿强制推进 history（最多 12 版）。
返回 { url, id, updated, revs }。没有这篇是 404。

服务端按「编辑会话」留快照：距上次写入超过 3 分钟、距上一份快照超过 10 分钟、或正文被大段换掉时，把当前稿推进 history（最多 12 版）。overwrite=true 或不带 baseUpdated 的盲写也会强制留一版（上限仍 12）。GET 只返回摘要 revs: [{ at, title, chars }]，不含全文。
恢复上一稿：PATCH { "restore": "<revs[0].at>", "baseUpdated": "<上次 updated>" }。当前稿会进 history，再 restore 一次等于换回去。

## POST /api/upload

multipart/form-data，字段名 file。png / jpeg / gif / webp，最大 15MB。
返回 { "url": "https://weixin.genedai.md/i/<hash>.jpg", "key", "size" }。
图片也可直接 GET /i/<key>。正文写法：![图注](url)

## POST /api/format

只排版、不落草稿。JSON { "text", "model"? }。返回 { "markdown", "model" }。
一般直接走 POST /api/article 即可。

## 排版语法（只有这些）

行首前缀：
- ## 小标题     主题色左框，全文 2–5 个，短语，8 字内
- ### 次级标题
- > 编者按      灰色整段（背景、采访说明）
- - 列表 / 1. 数字列表
- !! 金句       同一行，全文 1–2 处；不是围栏，不要成对写
- ---           单独一行，分隔

行内：
- **加粗**   ==高亮（主题色底白字，最多 3–5 处）==   ((名词注释))
- *斜体*   ~~删除线~~   `行内代码`
- ![图注](图片url)   [文字](链接)  — mp.weixin 链接可点，外链变文末参考
- 表格：| A | B |  次行 |---|---|

硬性：不增删不改写原文；不要输出大标题（标题走 title 字段）；不要用代码围栏包全文。

## 文内开头图 / 导语 / 署名

这些不是正文 Markdown，是草稿字段：
- cover：文内开头图 URL，每行一张，叠在导语和署名之上。可选。不是公众号后台封面（封面发文时在后台另选）
- coverSource：开头图来源；文末灰字写作「开头图来源」，可留空
- lead：导语，主题色金句
- byline：署名，每行一条，「丨」会着色
- title：仅预览与导出，公众号标题在后台另填


## 同一条链接

`/d/<id>` 就是文档，不是每人一份本地副本。
公开示例（只读）：https://weixin.genedai.md/d/demo  —— PATCH 会 403，要改请 POST /api/article 另开一篇。
- 人在编辑器里改：自动 PATCH 回这一条（先点「生成链接」才会从 `/` 变成 `/d/<id>`）
- Agent：创建用 POST，之后只 PATCH 同一个 id，不要另开一篇
- 冲突：PATCH 请带 `"baseUpdated": "<上次的 updated>"`，不一致返回 409。不带则最后写入获胜（会先把当前稿推进 history，最多 12 版），可能盖掉人刚改、还没写到链接上的内容
- 有链接的人都能改（没有登录）。发给别人前先说清楚

## 给用户的入口

编辑器：https://weixin.genedai.md
本说明：https://weixin.genedai.md/llms.txt
界面「稿件 → 复制 Agent 说明」可复制说明（与本文件等价，并带当前草稿 id）。