yuanflow-cli 0.1.27 → 0.1.29

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.27",
-  "description": "YuanFlow 自媒体 API CLI 与 Skill 安装器。",
+  "version": "0.1.29",
+  "description": "YuanFlow 自媒体 API CLI 与 Skill 安装器。",
   "type": "module",
   "license": "MIT",
   "private": false,
@@ -71,5 +71,3 @@
     "douyin"
   ]
 }
-
-

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

@@ -0,0 +1,136 @@
+---
+name: 公众号生成与发布
+description: 当用户需要公众号文章创作、文章改写、Markdown 排版、主题预览、HTML 导出或推送到微信公众号草稿箱时使用。
+---
+
+# 公众号生成与发布
+
+本 Skill 用于把公众号文章从“需求确认、内容生成、排版预览、导出 HTML、推送草稿箱”串成一个可控流程。它可以一次性完成全流程，也可以只做其中一段，例如只写文章、只生成封面建议、只做排版预览或只推送草稿箱。
+
+## 分类
+
+自媒体技能区
+
+## 开始前必须确认
+
+1. 用户是在已有文章上处理，还是完全重新创作。
+2. 用户本轮要做完整流程，还是只做写作、排版、封面建议、导出或草稿箱推送中的一部分。
+3. 排版结果使用 Markdown 还是 HTML。
+   - 如果选择 HTML，会把 Markdown 转成微信公众号编辑器可粘贴的内联样式 HTML。
+4. 是否需要推送到微信公众号草稿箱。草稿箱只负责生成草稿，正式发布必须由用户自行在公众号后台确认。
+
+## 内容创作流程
+
+### 已有文章处理
+
+1. 读取用户提供的原文、素材或 Markdown。
+2. 判断是否需要改写、润色、补结构、提炼标题、生成摘要或只做排版。
+3. 保留用户原文中的事实、数字、引用和语气约束，不擅自新增未证实的信息。
+
+### 完全重新创作
+
+1. 先明确主题、读者、账号定位、文章目的和期望风格。
+2. 使用 `自媒体知识库` 查询公众号创作相关知识点，根据主题构造 `domain` 和 `content_goal`。
+3. 结合知识库结果输出文章结构、标题候选和正文。
+4. 用户确认正文后再进入排版、导出或草稿箱流程。
+
+## AI 内容增强
+
+Agent 在排版前应做结构化增强，但不能改变事实：
+
+- 连续对话内容转成 `dialogue` 容器。
+- 连续图片转成 `gallery` 容器。
+- 金句、关键引用、核心观点转成 `callout` 容器。
+- 步骤、时间线、对比、清单转成对应结构容器。
+- 外部链接转脚注，避免微信编辑器粘贴后结构混乱。
+
+## 确定性排版脚本
+
+当前 Skill 内置 `scripts/wechat_format.py`，用于把 Markdown 转成微信可粘贴的内联样式 HTML。
+
+### 主题选择强制闸门
+
+当用户要求进入排版、预览、导出 HTML 或全流程时，Agent 必须先进入 `theme_select` 主题选择态。
+
+除非用户在本轮已明确指定某个主题 ID，否则不得直接执行 `wechat_format.py --theme ... --output ...`。正确顺序是：
+
+1. 文章正文确认或生成后，先写入 Markdown 源文件。
+2. 执行主题画廊命令，基于正文生成 20 个核心主题预览：
+
+```bash
+python scripts/wechat_format.py --input article.md --theme-gallery --gallery-limit 20 --json
+```
+
+3. 使用 `content_workbench_update` 写入右侧 `内容创作` 工作台：
+   - `status`: `collecting`
+   - `activeStep`: `theme_select`
+   - `steps`: 必须包含 `主题选择`
+   - `views`: 至少包含脚本返回的 `option_grid` 主题卡片；可以同时附带 `editor_panel` 显示 Markdown 摘要。
+4. 明确告诉用户：请在右侧工作台选择一个主题，然后发送输入框上方出现的待执行任务。
+5. 只有拿到用户选择的主题后，才执行：
+
+```bash
+python scripts/wechat_format.py --input article.md --theme <selected_theme> --output dist/wechat.html --preview dist/preview.html --json
+```
+
+主题选择不是装饰步骤，是排版导出前的执行闸门。用户说“完整执行”也不能跳过，除非用户同时明确指定主题。
+
+执行方式示例：
+
+```bash
+python scripts/wechat_format.py --input article.md --theme newspaper --output dist/wechat.html --json
+```
+
+常用参数：
+
+- `--input`：Markdown 文件路径。
+- `--theme`：主题名，默认 `wechat-native`。主题来自 `themes/*.json`。
+- `--output`：输出 HTML 文件路径。
+- `--json`：同时输出结构化执行结果，便于 Agent 写入右侧工作台。
+- `--list-themes`：输出所有主题元数据。
+- `--theme-gallery`：基于文章生成可写入工作台 `option_grid` 的主题画廊 JSON。
+- `--gallery-limit`：主题画廊数量，默认 20。
+
+## 工作台展示
+
+当右侧工作台存在 `内容创作` Tab 时，应使用 `content_workbench_update` 写入工作台，而不是写入数据面板。
+
+推荐写入结构：
+
+- `appId`: `wechat_official_account`
+- `title`: `公众号生成与发布`
+- `status`: `started` / `collecting` / `completed` / `failed`
+- `views`: 可组合使用 `stepper`、`option_grid`、`preview_frame`、`editor_panel`、`asset_gallery`、`action_bar`、`status_timeline`、`result_card`
+
+典型展示：
+
+1. `stepper`：需求确认、内容创作、主题选择、预览、导出、草稿箱。
+2. `option_grid`：主题卡片和文章预览结果。主题卡片必须带 `intent: select_wechat_theme`、`payload.theme` 和 `instruction`，让用户点击后形成待执行任务。
+3. `preview_frame`：手机样式 HTML 预览。
+4. `editor_panel`：Markdown 或 HTML 源码。
+5. `action_bar`：导出 HTML、推送草稿箱、继续改写等动作。
+
+## 公众号凭证
+
+如果用户首次要求推送草稿箱，需要配置微信公众号官方接口凭证：
+
+- 官方入口：https://developers.weixin.qq.com/platform
+- 必需信息：AppID、AppSecret
+- 凭证由 YuanFlow Runtime 保存到用户数据目录的本地 secrets/config 中，Skill 不自行写入凭证文件，也不把密钥打印到对话里。
+
+如果当前环境没有可用的受控凭证保存工具，应提示用户先在程序设置或 Runtime 受控入口配置凭证，再继续草稿箱流程。
+
+## 封面
+
+封面不使用第三方生成接口。需要封面时，使用 YuanFlow 内置生图技能生成。
+
+建议比例：
+
+- 横向封面：2.35:1
+- 方图辅助：1:1
+
+## 输出要求
+
+- 默认先给用户可确认的阶段性结果，不要一次性跳过用户选择。
+- HTML 结果要适合复制到微信公众号编辑器。
+- 草稿箱流程完成后只说明“已生成草稿箱草稿”，不要声称已发布。

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_format.py

@@ -0,0 +1,391 @@
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+THEMES_DIR = ROOT / "themes"
+CORE_THEME_IDS = [
+    "wechat-native",
+    "newspaper",
+    "magazine",
+    "sspai",
+    "github",
+    "chinese",
+    "ink",
+    "bauhaus",
+    "bytedance",
+    "sports",
+    "midnight",
+    "coffee-house",
+    "terracotta",
+    "mint-fresh",
+    "lavender-dream",
+    "fresh-card",
+    "ocean-card",
+    "warm-card",
+    "focus-gold",
+    "sunset-amber",
+]
+
+
+def _style(style_map: dict[str, Any]) -> str:
+    parts: list[str] = []
+    for key, value in style_map.items():
+        css_key = key.replace("_", "-")
+        parts.append(f"{css_key}:{value}")
+    return ";".join(parts)
+
+
+def _load_theme(theme_name: str) -> dict[str, Any]:
+    safe_name = re.sub(r"[^a-zA-Z0-9_-]", "", theme_name or "wechat-native")
+    path = THEMES_DIR / f"{safe_name}.json"
+    if not path.exists():
+        path = THEMES_DIR / "wechat-native.json"
+    if not path.exists():
+        return {"name": "YuanFlow", "styles": {}}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _theme_id_from_path(path: Path) -> str:
+    return path.stem
+
+
+def _load_theme_by_id(theme_id: str) -> dict[str, Any]:
+    path = THEMES_DIR / f"{theme_id}.json"
+    if not path.exists():
+        return {"name": theme_id, "description": "", "styles": {}, "colors": {}}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def list_themes(*, core_only: bool = False, limit: int | None = None) -> list[dict[str, Any]]:
+    if core_only:
+        theme_ids = [theme_id for theme_id in CORE_THEME_IDS if (THEMES_DIR / f"{theme_id}.json").exists()]
+    else:
+        theme_ids = sorted(_theme_id_from_path(path) for path in THEMES_DIR.glob("*.json"))
+    if limit and limit > 0:
+        theme_ids = theme_ids[:limit]
+
+    items: list[dict[str, Any]] = []
+    for theme_id in theme_ids:
+        theme = _load_theme_by_id(theme_id)
+        colors = theme.get("colors") if isinstance(theme.get("colors"), dict) else {}
+        items.append(
+            {
+                "id": theme_id,
+                "name": theme.get("name") or theme_id,
+                "description": theme.get("description") or "",
+                "accent": colors.get("accent") or colors.get("primary") or "#1d4ed8",
+                "background": colors.get("background") or "#ffffff",
+            }
+        )
+    return items
+
+
+def _gallery_markdown_sample(markdown: str) -> str:
+    content = markdown.strip()
+    if len(content) <= 1200:
+        return content
+    return f"{content[:1200].rstrip()}\n\n> 预览仅截取正文开头，完整排版会使用全文。"
+
+
+def build_theme_gallery(markdown: str, title: str, *, limit: int = 20) -> dict[str, Any]:
+    sample = _gallery_markdown_sample(markdown)
+    themes = []
+    for theme_meta in list_themes(core_only=True, limit=limit):
+        theme_id = theme_meta["id"]
+        theme = _load_theme_by_id(theme_id)
+        preview_body = markdown_to_wechat_html(sample, theme)
+        preview_html = build_preview(preview_body, f"{theme_meta['name']} · 主题预览")
+        themes.append(
+            {
+                "id": theme_id,
+                "label": theme_meta["name"],
+                "title": theme_meta["name"],
+                "summary": theme_meta["description"],
+                "description": theme_meta["description"],
+                "accent": theme_meta["accent"],
+                "background": theme_meta["background"],
+                "previewHtml": preview_html,
+                "intent": "select_wechat_theme",
+                "payload": {
+                    "theme": theme_id,
+                    "themeName": theme_meta["name"],
+                    "title": title,
+                },
+                "instruction": (
+                    f"选择公众号主题「{theme_meta['name']}」（theme={theme_id}），"
+                    "继续执行排版并导出 HTML。"
+                ),
+            }
+        )
+    return {
+        "ok": True,
+        "title": title,
+        "themes": themes,
+        "views": [
+            {
+                "id": "wechat-theme-gallery",
+                "type": "option_grid",
+                "title": "选择公众号排版主题",
+                "summary": "点击一个主题卡片后，发送输入框上方的待执行任务，Agent 才能继续排版导出。",
+                "items": themes,
+            }
+        ],
+    }
+
+
+def _paragraph(text: str, styles: dict[str, Any]) -> str:
+    return f'<p style="{_style(styles.get("p", {}))}">{html.escape(text)}</p>'
+
+
+def _render_list(items: list[str], ordered: bool, styles: dict[str, Any]) -> str:
+    tag = "ol" if ordered else "ul"
+    li_style = _style(styles.get("li", styles.get("p", {})))
+    rendered = "".join(f'<li style="{li_style}">{html.escape(item)}</li>' for item in items)
+    return f'<{tag} style="{_style(styles.get(tag, {}))}">{rendered}</{tag}>'
+
+
+def _render_image(line: str, styles: dict[str, Any]) -> str | None:
+    match = re.match(r"!\[([^\]]*)\]\(([^)]+)\)", line.strip())
+    if not match:
+        return None
+    alt, src = match.groups()
+    img_style = _style(
+        styles.get(
+            "img",
+            {
+                "max_width": "100%",
+                "border_radius": "8px",
+                "display": "block",
+                "margin": "16px auto",
+            },
+        )
+    )
+    return f'<img src="{html.escape(src)}" alt="{html.escape(alt)}" style="{img_style}" />'
+
+
+def _flush_paragraph(buffer: list[str], output: list[str], styles: dict[str, Any]) -> None:
+    if not buffer:
+        return
+    output.append(_paragraph(" ".join(buffer).strip(), styles))
+    buffer.clear()
+
+
+def markdown_to_wechat_html(markdown: str, theme: dict[str, Any]) -> str:
+    styles = theme.get("styles") if isinstance(theme.get("styles"), dict) else {}
+    wrapper_style = _style(
+        styles.get(
+            "wrapper",
+            {
+                "background_color": "#ffffff",
+                "padding": "16px",
+                "font_family": "-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif",
+            },
+        )
+    )
+    output: list[str] = [f'<section data-yuanflow="wechat-article" style="{wrapper_style}">']
+    lines = markdown.splitlines()
+    if lines and lines[0].strip() == "---":
+        for index, line in enumerate(lines[1:], start=1):
+            if line.strip() == "---":
+                lines = lines[index + 1 :]
+                break
+    paragraph_buffer: list[str] = []
+    unordered: list[str] = []
+    ordered: list[str] = []
+    in_code = False
+    code_lines: list[str] = []
+
+    def flush_lists() -> None:
+        if unordered:
+            output.append(_render_list(unordered, False, styles))
+            unordered.clear()
+        if ordered:
+            output.append(_render_list(ordered, True, styles))
+            ordered.clear()
+
+    for raw_line in lines:
+        line = raw_line.rstrip()
+        stripped = line.strip()
+
+        if stripped.startswith("```"):
+            _flush_paragraph(paragraph_buffer, output, styles)
+            flush_lists()
+            if in_code:
+                code_style = _style(styles.get("code_block", styles.get("pre", {})))
+                output.append(
+                    f'<pre style="{code_style}"><code>{html.escape(chr(10).join(code_lines))}</code></pre>'
+                )
+                code_lines.clear()
+                in_code = False
+            else:
+                in_code = True
+            continue
+
+        if in_code:
+            code_lines.append(line)
+            continue
+
+        if not stripped:
+            _flush_paragraph(paragraph_buffer, output, styles)
+            flush_lists()
+            continue
+
+        image_html = _render_image(stripped, styles)
+        if image_html:
+            _flush_paragraph(paragraph_buffer, output, styles)
+            flush_lists()
+            output.append(image_html)
+            continue
+
+        heading = re.match(r"^(#{1,3})\s+(.+)$", stripped)
+        if heading:
+            _flush_paragraph(paragraph_buffer, output, styles)
+            flush_lists()
+            level = len(heading.group(1))
+            tag = f"h{level}"
+            text = html.escape(heading.group(2).strip())
+            output.append(f'<{tag} style="{_style(styles.get(tag, {}))}">{text}</{tag}>')
+            continue
+
+        quote = re.match(r"^>\s?(.+)$", stripped)
+        if quote:
+            _flush_paragraph(paragraph_buffer, output, styles)
+            flush_lists()
+            output.append(
+                f'<blockquote style="{_style(styles.get("blockquote", {}))}">{html.escape(quote.group(1))}</blockquote>'
+            )
+            continue
+
+        ordered_match = re.match(r"^\d+\.\s+(.+)$", stripped)
+        if ordered_match:
+            _flush_paragraph(paragraph_buffer, output, styles)
+            if unordered:
+                output.append(_render_list(unordered, False, styles))
+                unordered.clear()
+            ordered.append(ordered_match.group(1))
+            continue
+
+        unordered_match = re.match(r"^[-*]\s+(.+)$", stripped)
+        if unordered_match:
+            _flush_paragraph(paragraph_buffer, output, styles)
+            if ordered:
+                output.append(_render_list(ordered, True, styles))
+                ordered.clear()
+            unordered.append(unordered_match.group(1))
+            continue
+
+        flush_lists()
+        paragraph_buffer.append(stripped)
+
+    _flush_paragraph(paragraph_buffer, output, styles)
+    flush_lists()
+    output.append("</section>")
+    return "\n".join(output)
+
+
+def build_preview(html_body: str, title: str) -> str:
+    escaped_title = html.escape(title or "公众号预览")
+    return f"""<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>{escaped_title}</title>
+  <style>
+    body {{ margin: 0; background: #f4f6f8; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }}
+    .phone {{ width: min(430px, 100%); min-height: 100vh; margin: 0 auto; background: #fff; box-shadow: 0 12px 32px rgba(15, 23, 42, .12); }}
+    .bar {{ padding: 14px 18px; border-bottom: 1px solid #eef2f7; font-weight: 700; }}
+    .content {{ padding: 14px 18px 28px; }}
+  </style>
+</head>
+<body>
+  <main class="phone">
+    <div class="bar">{escaped_title}</div>
+    <div class="content">{html_body}</div>
+  </main>
+</body>
+</html>"""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="YuanFlow 微信公众号 Markdown 排版工具")
+    parser.add_argument("--input", default="", help="Markdown 输入文件")
+    parser.add_argument("--theme", default="wechat-native", help="主题名称")
+    parser.add_argument("--output", default="", help="HTML 输出文件")
+    parser.add_argument("--title", default="公众号生成与发布", help="预览标题")
+    parser.add_argument("--preview", default="", help="可选预览 HTML 输出文件")
+    parser.add_argument("--list-themes", action="store_true", help="输出可用主题列表")
+    parser.add_argument("--theme-gallery", action="store_true", help="基于文章生成主题选择画廊 JSON")
+    parser.add_argument("--gallery-limit", type=int, default=20, help="主题画廊数量，默认 20")
+    parser.add_argument("--json", action="store_true", help="输出 JSON 执行结果")
+    args = parser.parse_args()
+
+    if args.list_themes:
+        payload = {"ok": True, "themes": list_themes()}
+        print(json.dumps(payload, ensure_ascii=False))
+        return 0
+
+    if not args.input:
+        raise SystemExit("--input is required unless --list-themes is used")
+
+    input_path = Path(args.input).resolve()
+    markdown = input_path.read_text(encoding="utf-8")
+
+    if args.theme_gallery:
+        payload = build_theme_gallery(markdown, args.title, limit=args.gallery_limit)
+        if args.output:
+            output_path = Path(args.output).resolve()
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+            payload["output"] = str(output_path)
+        if args.json or not args.output:
+            print(json.dumps(payload, ensure_ascii=False))
+        return 0
+
+    if not args.output:
+        raise SystemExit("--output is required for HTML export")
+
+    output_path = Path(args.output).resolve()
+    theme = _load_theme(args.theme)
+    html_body = markdown_to_wechat_html(markdown, theme)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(html_body, encoding="utf-8")
+
+    preview_path = Path(args.preview).resolve() if args.preview else output_path.with_name("preview.html")
+    preview_path.write_text(build_preview(html_body, args.title), encoding="utf-8")
+
+    result = {
+        "ok": True,
+        "theme": args.theme,
+        "themeName": theme.get("name") or args.theme,
+        "output": str(output_path),
+        "preview": str(preview_path),
+        "views": [
+            {
+                "id": "preview",
+                "type": "preview_frame",
+                "title": "公众号手机预览",
+                "html": preview_path.read_text(encoding="utf-8"),
+            },
+            {
+                "id": "html",
+                "type": "editor_panel",
+                "title": "微信内联 HTML",
+                "content": html_body,
+            },
+        ],
+    }
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())