yuanflow-cli 0.1.33 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "YuanFlow 自媒体 API CLI 与 Skill 安装器。",
   "type": "module",
   "license": "MIT",

package/skills/yuanflow-skill//345/205/254/344/274/227/345/217/267/347/224/237/346/210/220/344/270/216/345/217/221/345/270/203/SKILL.md

@@ -5,7 +5,7 @@ description: 当用户需要公众号文章创作、文章改写、Markdown 排
 
 # 公众号生成与发布
 
-本 Skill 用于把公众号文章从“需求确认、内容生成、排版预览、导出 HTML、推送草稿箱”串成一个可控流程。它可以一次性完成全流程，也可以只做其中一段，例如只写文章、只生成封面建议、只做排版预览或只推送草稿箱。
+本 Skill 用于把公众号文章从“需求确认、内容生成、排版预览、导出 HTML、新增或更新草稿箱草稿”串成一个可控流程。它可以一次性完成全流程，也可以只做其中一段，例如只写文章、只生成封面建议、只做排版预览、只新增草稿或更新已有草稿。
 
 ## 分类
 
@@ -22,7 +22,7 @@ description: 当用户需要公众号文章创作、文章改写、Markdown 排
    - 用户没有要求正文插图时：不要擅自生成插图；只处理文字正文和可选封面。
 5. 排版结果使用 Markdown 还是 HTML。
    - 如果选择 HTML，会把 Markdown 转成微信公众号编辑器可粘贴的内联样式 HTML。
-6. 是否需要推送到微信公众号草稿箱。草稿箱只负责生成草稿，正式发布必须由用户自行在公众号后台确认。
+6. 是否需要写入微信公众号草稿箱，并确认是新增草稿还是更新已有草稿。更新已有草稿时必须先拿到目标草稿的 `media_id`，多图文还要确认更新第几篇，第一篇 `index=0`。草稿箱只负责生成或更新草稿，正式发布必须由用户自行在公众号后台确认。
 
 ## 内容创作流程
 
@@ -63,6 +63,8 @@ Agent 在排版前应做结构化增强，但不能改变事实：
 - 用户要求生成插图：调用 `生图技能` 生成图片，使用工具返回的本地缓存路径插入 Markdown。
 - 用户只要求封面：只生成或使用封面，不在正文里额外插图。
 
+使用生图技能生成公众号封面或正文插图时，不能只凭当前文章主题临时想象一个空泛提示词。必须先查看 `生图技能` 的提示词参考目录，优先根据参考文件的标题、目录或小节名判断有没有适合当前用户需求或间接相近方向的内容，例如知识卡、信息图、海报封面、科技商业插画、人物/场景图、产品图或编辑部视觉；发现相近方向后再进入对应小节阅读参考。不要求每次完整查看所有提示词，也不要机械逐篇浏览。读取后只借鉴其中的构图、镜头、版式、材质、灯光、信息层级、文字约束和负面提示写法，再结合当前公众号主题重写成新的高质量中文提示词；不要原样复制案例，不要带入无关品牌、人物、Logo、水印或英文占位字。若参考库没有完全匹配的方向，也要选择最接近的视觉类型作为结构参考，再生成更具体的画面规划。
+
 生成公众号正文插图时必须遵守中文默认规则：
 
 - 中文公众号文章默认生成中文语境图片。生图提示词必须写明：画面中如出现文字、标签、标题、图表标注，全部使用清晰简体中文。
@@ -70,11 +72,13 @@ Agent 在排版前应做结构化增强，但不能改变事实：
 - 如果文章段落确实需要图中文字，只允许使用与文章一致的简体中文短句，并明确列出具体中文文字。
 - 除非用户明确要求英文或双语，不要在正文插图、封面图或预览图里生成英文。
 
-推送草稿箱时使用 `scripts/wechat_draft.py`：
+写入草稿箱时使用 `scripts/wechat_draft.py`。
+
+新增草稿示例：
 
 ```bash
 python scripts/wechat_draft.py \
-  --credentials-file "D:\公众号token\新建文本文档.txt" \
+  --credentials-file "D:\path\to\wechat-credentials.txt" \
   --input article.md \
   --theme newspaper \
   --cover-image cover.png \
@@ -83,22 +87,36 @@ python scripts/wechat_draft.py \
   --json
 ```
 
+更新已有草稿示例：
+
+```bash
+python scripts/wechat_draft.py \
+  --credentials-file "D:\path\to\wechat-credentials.txt" \
+  --input article.md \
+  --theme newspaper \
+  --draft-media-id MEDIA_ID \
+  --draft-index 0 \
+  --output-dir dist \
+  --update-draft \
+  --json
+```
+
 执行顺序：
 
 1. 读取或生成 Markdown 正文，确保正文里的本地图片路径真实存在。
 2. 先用 `wechat_format.py` 完成主题排版和本地预览。
-3. 如果要推送草稿箱，再用 `wechat_draft.py`：
+3. 如果要新增或更新草稿箱，再用 `wechat_draft.py`：
    - 获取 `access_token`。
    - 上传正文图片到 `/cgi-bin/media/uploadimg`，替换正文图片地址。
-   - 上传封面图到 `/cgi-bin/material/add_material`，取得 `thumb_media_id`。
-   - 调用 `/cgi-bin/draft/add` 创建草稿箱草稿。
-4. 返回草稿 `media_id`、本地 `draft_payload.json`、`wechat.html`、`preview.html` 和图片上传映射。
+   - 新增草稿时必须上传或提供封面图 `thumb_media_id`，再调用 `/cgi-bin/draft/add` 创建草稿箱草稿。
+   - 更新已有草稿时必须提供 `--draft-media-id` 和 `--draft-index`，调用 `/cgi-bin/draft/update` 更新指定图文。更新接口不是局部 patch，需要按接口要求重新提交该篇文章的完整 `articles` 对象；如果只改正文且不换封面，可以不传封面。
+4. 返回草稿 `media_id` 或更新结果、本地 `draft_payload.json`、`wechat.html`、`preview.html` 和图片上传映射。
 
 接口细节需要确认时，读取 `references/wechat-official-api.md`，不要凭记忆改接口路径。
 
 安全要求：
 
-- 真实创建草稿必须显式传入 `--push-draft`，否则只生成本地 HTML 和草稿 payload。
+- 真实新增草稿必须显式传入 `--push-draft`；真实更新草稿必须显式传入 `--update-draft`、`--draft-media-id` 和 `--draft-index`。否则只生成本地 HTML 和草稿 payload。
 - 不要在对话、工作台或日志里输出 AppSecret、access_token。
 - 如果微信接口返回 IP 白名单、权限不足、未认证、额度不足等错误，要把错误原因原样归类说明，不要假装成功。
 
@@ -167,7 +185,7 @@ python scripts/wechat_format.py --input article.md --theme newspaper --output di
 2. `option_grid`：主题卡片和文章预览结果。主题卡片必须带 `intent: select_wechat_theme`、`payload.theme` 和 `instruction`，让用户点击后形成待执行任务。
 3. `preview_frame`：手机样式 HTML 预览。
 4. `editor_panel`：Markdown 或 HTML 源码。
-5. `action_bar`：导出 HTML、推送草稿箱、继续改写等动作。
+5. `action_bar`：导出 HTML、新增草稿、更新已有草稿、继续改写等动作。
 
 ## 公众号凭证
 
@@ -185,6 +203,8 @@ python scripts/wechat_format.py --input article.md --theme newspaper --output di
 
 封面不使用第三方生成接口。需要封面时，使用 YuanFlow 内置生图技能生成。
 
+生成封面前同样必须先查看 `生图技能/references/image-prompt-reference.md` 的标题、目录或小节名，选择与文章定位最接近的封面、海报、知识卡、商业科技视觉或信息图方向作为参考；只需进入相近方向阅读，不需要完整扫完所有提示词。封面提示词要把文章主题、目标读者、视觉主元素、构图层级、比例、中文文字规则和负面约束写清楚，避免只写“生成一张某主题封面图”这类空泛需求。
+
 建议比例：
 
 - 横向封面：2.35:1

package/skills/yuanflow-skill//345/205/254/344/274/227/345/217/267/347/224/237/346/210/220/344/270/216/345/217/221/345/270/203/references/wechat-official-api.md

@@ -61,8 +61,24 @@ JSON：{"articles":[...]}
 - `need_open_comment`
 - `only_fans_can_comment`
 
+5. 更新草稿
+
+```text
+POST https://api.weixin.qq.com/cgi-bin/draft/update?access_token=ACCESS_TOKEN
+JSON：{"media_id":"MEDIA_ID","index":0,"articles":{...}}
+```
+
+核心字段：
+
+- `media_id`：要修改的图文消息草稿 ID
+- `index`：要更新的文章位置，第一篇为 `0`
+- `articles`：新的图文信息对象，不是数组
+
+更新草稿不是局部 patch。调用时应按官方字段重新提交指定 `index` 这一篇文章的完整内容对象。正文内图片仍必须先走 `/cgi-bin/media/uploadimg`，封面如需更新则传 `thumb_media_id`；如果只更新正文且不更换封面，可以不传新的封面。
+
 ## 执行约束
 
 - 真实创建草稿必须显式使用 `--push-draft`。
+- 真实更新草稿必须显式使用 `--update-draft`，并提供 `--draft-media-id` 和 `--draft-index`。
 - 不要输出 AppSecret 或 access_token。
 - 微信返回错误时保留 `errcode/errmsg`，并把错误归因到白名单、凭证、素材、草稿权限或额度。

package/skills/yuanflow-skill//345/205/254/344/274/227/345/217/267/347/224/237/346/210/220/344/270/216/345/217/221/345/270/203/scripts/wechat_draft.py

@@ -18,6 +18,7 @@ WECHAT_TOKEN_URL = "https://api.weixin.qq.com/cgi-bin/token"
 WECHAT_UPLOAD_ARTICLE_IMAGE_URL = "https://api.weixin.qq.com/cgi-bin/media/uploadimg"
 WECHAT_ADD_MATERIAL_URL = "https://api.weixin.qq.com/cgi-bin/material/add_material"
 WECHAT_ADD_DRAFT_URL = "https://api.weixin.qq.com/cgi-bin/draft/add"
+WECHAT_UPDATE_DRAFT_URL = "https://api.weixin.qq.com/cgi-bin/draft/update"
 
 
 class WechatApiError(RuntimeError):
@@ -171,29 +172,31 @@ def _truncate_utf8(value: str, max_bytes: int) -> str:
     return encoded[:max_bytes].decode("utf-8", errors="ignore").rstrip()
 
 
-def build_draft_payload(
+def build_draft_article(
     *,
     title: str,
     author: str,
     digest: str,
     content: str,
-    thumb_media_id: str,
+    thumb_media_id: str = "",
     content_source_url: str = "",
 ) -> dict[str, Any]:
-    return {
-        "articles": [
-            {
-                "title": _truncate_utf8(title, 64),
-                "author": author,
-                "digest": _truncate_utf8(digest, 54),
-                "content": content,
-                "content_source_url": content_source_url,
-                "thumb_media_id": thumb_media_id,
-                "need_open_comment": 0,
-                "only_fans_can_comment": 0,
-            }
-        ]
+    article = {
+        "title": _truncate_utf8(title, 64),
+        "author": author,
+        "digest": _truncate_utf8(digest, 54),
+        "content": content,
+        "content_source_url": content_source_url,
+        "need_open_comment": 0,
+        "only_fans_can_comment": 0,
     }
+    if thumb_media_id:
+        article["thumb_media_id"] = thumb_media_id
+    return article
+
+
+def build_draft_payload(*, article: dict[str, Any]) -> dict[str, Any]:
+    return {"articles": [article]}
 
 
 def add_draft(access_token: str, payload: dict[str, Any]) -> dict[str, Any]:
@@ -207,7 +210,36 @@ def add_draft(access_token: str, payload: dict[str, Any]) -> dict[str, Any]:
     )
 
 
+def update_draft(
+    access_token: str,
+    *,
+    media_id: str,
+    index: int,
+    article: dict[str, Any],
+) -> dict[str, Any]:
+    if not media_id.strip():
+        raise WechatApiError("draft-media-id-missing", "更新草稿必须提供 --draft-media-id。")
+    body = json.dumps(
+        {
+            "media_id": media_id.strip(),
+            "index": index,
+            "articles": article,
+        },
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return _request_json(
+        "POST",
+        WECHAT_UPDATE_DRAFT_URL,
+        params={"access_token": access_token},
+        data=body,
+        headers={"Content-Type": "application/json; charset=utf-8"},
+    )
+
+
 def run(args: argparse.Namespace) -> dict[str, Any]:
+    if args.push_draft and args.update_draft:
+        raise WechatApiError("draft-operation-conflict", "--push-draft 和 --update-draft 不能同时使用。")
+
     input_path = Path(args.input).resolve()
     output_dir = Path(args.output_dir).resolve()
     output_dir.mkdir(parents=True, exist_ok=True)
@@ -222,14 +254,15 @@ def run(args: argparse.Namespace) -> dict[str, Any]:
     access_token_status = "skipped"
 
     credentials = {"app_id": "", "app_secret": ""}
-    if args.push_draft or args.credentials_file or args.app_id or args.app_secret:
+    will_write_draft = bool(args.push_draft or args.update_draft)
+    if will_write_draft or args.credentials_file or args.app_id or args.app_secret:
         credentials = _load_credentials(
             Path(args.credentials_file).resolve() if args.credentials_file else None,
             args.app_id,
             args.app_secret,
         )
 
-    if args.push_draft:
+    if will_write_draft:
         access_token = get_access_token(credentials["app_id"], credentials["app_secret"])
         access_token_status = "ok"
         markdown, image_uploads = upload_and_replace_markdown_images(markdown, input_path.parent, access_token)
@@ -245,10 +278,8 @@ def run(args: argparse.Namespace) -> dict[str, Any]:
     uploaded_markdown_path.write_text(markdown, encoding="utf-8")
 
     cover_media_id = args.thumb_media_id.strip()
-    if args.push_draft and not cover_media_id:
+    if will_write_draft and not cover_media_id and args.cover_image:
         cover_image = Path(args.cover_image).resolve() if args.cover_image else None
-        if not cover_image:
-            raise WechatApiError("cover-image-required", "推送草稿箱必须提供 --cover-image 或 --thumb-media-id。")
         if not cover_image.exists() or not cover_image.is_file():
             raise WechatApiError("cover-image-not-found", f"封面图片不存在：{cover_image}")
         try:
@@ -261,8 +292,11 @@ def run(args: argparse.Namespace) -> dict[str, Any]:
         cover_upload = {"source": str(cover_image), "media_id": cover_media_id}
 
     draft_payload: dict[str, Any] | None = None
-    if cover_media_id:
-        draft_payload = build_draft_payload(
+    draft_article: dict[str, Any] | None = None
+    if args.push_draft and not cover_media_id:
+        raise WechatApiError("cover-image-required", "新增草稿必须提供 --cover-image 或 --thumb-media-id。")
+    if cover_media_id or args.update_draft:
+        draft_article = build_draft_article(
             title=title,
             author=author,
             digest=args.digest.strip() or _plain_text_digest(markdown),
@@ -270,6 +304,9 @@ def run(args: argparse.Namespace) -> dict[str, Any]:
             content_source_url=args.content_source_url.strip(),
             thumb_media_id=cover_media_id,
         )
+        draft_payload = build_draft_payload(
+            article=draft_article,
+        )
         draft_payload_path = output_dir / "draft_payload.json"
         draft_payload_path.write_text(json.dumps(draft_payload, ensure_ascii=False, indent=2), encoding="utf-8")
     else:
@@ -279,10 +316,20 @@ def run(args: argparse.Namespace) -> dict[str, Any]:
         if not draft_payload:
             raise WechatApiError("draft-payload-missing", "草稿 payload 未生成。")
         draft_result = add_draft(access_token, draft_payload)
+    elif args.update_draft:
+        if not draft_article:
+            raise WechatApiError("draft-payload-missing", "草稿更新 payload 未生成。")
+        draft_result = update_draft(
+            access_token,
+            media_id=args.draft_media_id,
+            index=args.draft_index,
+            article=draft_article,
+        )
 
     result = {
         "ok": True,
-        "pushed": bool(args.push_draft),
+        "pushed": will_write_draft,
+        "operation": "update" if args.update_draft else ("add" if args.push_draft else "preview"),
         "title": title,
         "theme": args.theme,
         "account": {
@@ -323,6 +370,9 @@ def main() -> int:
     parser.add_argument("--app-id", default="", help="微信公众号 AppID")
     parser.add_argument("--app-secret", default="", help="微信公众号 AppSecret")
     parser.add_argument("--push-draft", action="store_true", help="显式创建草稿箱草稿；不传则只生成本地文件和 payload")
+    parser.add_argument("--update-draft", action="store_true", help="显式更新已有草稿；需同时提供 --draft-media-id")
+    parser.add_argument("--draft-media-id", default="", help="要更新的已有草稿 media_id")
+    parser.add_argument("--draft-index", type=int, default=0, help="要更新的图文位置，第一篇为 0")
     parser.add_argument("--json", action="store_true", help="输出 JSON")
     args = parser.parse_args()