@topmindspace/tms-skills 0.1.19 → 0.2.0

package/topmind-wechat-post/scripts/negative_tests.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""topmind-wechat-post 异常输入测试：各脚本错误路径干净（任一失败 → 退出码 1）。"""
+from __future__ import annotations
+
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS = ROOT / "scripts"
+PY = sys.executable
+fails: list[str] = []
+
+
+def run(script: str, args: list[str]) -> subprocess.CompletedProcess:
+    return subprocess.run([PY, str(SCRIPTS / script), *args], capture_output=True, text=True, timeout=60)
+
+
+def check(name: str, cond: bool, detail: str = "") -> None:
+    print(("  ✓ " if cond else "  ✗ ") + name + (f" — {detail}" if detail and not cond else ""))
+    if not cond:
+        fails.append(name)
+
+
+def main() -> None:
+    print("[negative_tests] topmind-wechat-post")
+    with tempfile.TemporaryDirectory() as td:
+        td = Path(td)
+
+        # 1. lint 空文件不崩溃
+        (td / "empty.md").write_text("", encoding="utf-8")
+        r = run("lint-wechat.py", ["--input", str(td / "empty.md")])
+        check("lint 空文件不崩溃", r.returncode == 0 and "Traceback" not in r.stderr, r.stderr[:100])
+
+        # 2. md2wechat 缺失输入 → 非零干净报错
+        r = run("md2wechat.py", ["--input", str(td / "nope.md"), "--out-dir", str(td), "--slug", "t"])
+        check("md2wechat 缺失输入干净报错", r.returncode != 0 and "Traceback" not in r.stderr, r.stderr[:100])
+
+        # 3. scan 空文件不崩溃
+        r = run("scan_ai_flavor.py", [str(td / "empty.md")])
+        check("scan 空文件不崩溃", r.returncode == 0 and "Traceback" not in r.stderr, r.stderr[:100])
+
+        # 4. new-article --help 正常
+        r = run("new-article.py", ["--help"])
+        check("new-article --help 正常", r.returncode == 0, r.stderr[:100])
+
+        # 5. sync-status 缺失包 → 非零干净报错
+        r = run("sync-status.py", ["--set", "定稿", str(td / "nope-pkg")])
+        check("sync-status 缺失包干净报错", r.returncode != 0 and "Traceback" not in r.stderr, r.stderr[:100])
+
+    if fails:
+        print(f"\n[negative_tests] {len(fails)} 项失败")
+        sys.exit(1)
+    print("\n[negative_tests] 全部通过")
+
+
+if __name__ == "__main__":
+    main()

package/topmind-wechat-post/scripts/new-article.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""new-article.py — 一键创建公众号文章交付包。
+
+创建 <base>/YYYY-MM-DD-<slug>/ 目录，内含：
+  - 公众号稿.md   带 frontmatter 的文章骨架（含写作提示与容器语法示例）
+  - images/       图片目录（可选，从 --images 拷贝）
+  - diagrams/     mermaid 图表目录
+
+Usage:
+    python3 new-article.py --slug gpt-6-review --title "GPT-6 深度评测" \
+        [--base <专题目录>] [--date 2026-09-04] [--images src1 src2 ...]
+
+默认 base = <topmind-workspace>/40-创作/2026-公众号
+"""
+
+import argparse
+import datetime
+import os
+import re
+import shutil
+import sys
+
+def _default_base():
+    """交付包根：CLI --base → env TOPMIND_WECHAT_BASE → env TOPMIND_WORKSPACE 发现 → 惯例路径。"""
+    env = os.environ.get("TOPMIND_WECHAT_BASE") or os.environ.get("TOPMIND_WECHAT_PACKAGE_ROOT")
+    if env:
+        return os.path.abspath(os.path.expanduser(env))
+    ws = os.environ.get("TOPMIND_WORKSPACE")
+    if ws:
+        for rel in (
+            ("40-创作", "2026-公众号"),
+            ("20-专题", "2026-公众号"),
+            ("88-交付", "2026-公众号"),
+        ):
+            p = os.path.join(ws, *rel)
+            if os.path.isdir(p):
+                return p
+        return os.path.join(ws, "40-创作", "2026-公众号")
+    # 惯例：父工作区（可被 CLI 覆盖）
+    return os.path.join(
+        os.path.expanduser("~"), "TopWorkSpace", "topmind-workspace",
+        "40-创作", "2026-公众号")
+
+
+def _default_topstream():
+    env = os.environ.get("TOPSTREAM_ROOT") or os.environ.get("TOPMIND_TOPSTREAM")
+    if env:
+        return os.path.abspath(os.path.expanduser(env))
+    return os.path.join(os.path.expanduser("~"), "TopWorkSpace", "topstream")
+
+DEFAULT_BASE = _default_base()
+
+SKELETON = """---
+title: "{title}"
+category: 40-创作
+topic: 2026-公众号
+source_type: {source_type}
+captured_at: {now}
+status: 草稿
+direction: {direction}
+source_file: {source_file}
+target_file: {target_file}
+word_count: 0
+tags: [公众号, 排版]
+note_role: bundle
+---
+
+# {title}
+
+<!-- 骨架说明（写作时逐条删除）：
+  1. 开头：3 句内给出「反差钩子」——一个具体事实/数字/场景，别写背景铺垫。
+  2. 小标题用 ##（h2），正文段落 ≤ 110 字（约 4 行手机屏）。
+  3. 重点句才加粗，加粗占比 < 20%；关键数据可用 ::: stat 容器。
+  4. 外链会被公众号拦截，直接写 [文字](url)，脚本自动转文末脚注。
+  5. 中英文间距不用管，lint --fix 会自动补。
+  6. 可用容器（::: 类型 然后空行，内容，空行，::: 收尾）：
+       ::: note   补充说明（灰）
+       ::: tip    小技巧（绿）
+       ::: warn   注意事项（橙）
+       ::: danger 常见坑（红）
+       ::: pull   金句 / 核心观点（大字号居中）
+       ::: dialogue  对话（A: B: 交替缩进）
+       ::: stat   数据亮点（大数字）
+       [!新特性] 这样的行内徽章  /  ==高亮重点==
+-->
+
+> 一句话导语：这篇文章解决什么问题、读者能带走什么。
+
+## 为什么值得聊
+
+## 核心内容
+
+### 分论点一
+
+### 分论点二
+
+## 我的看法
+
+::: pull
+把最想让读者记住的一句话放在这里。
+:::
+
+## 小结
+
+---
+
+*本文首发于我的公众号，转载请注明出处。*
+"""
+
+# 目录名按专题规范：中文短名（可含英文/数字/连字符），如 个人免费基建全景、GrokBot多Agent调度
+SLUG_RE = re.compile(r"^[\u4e00-\u9fffA-Za-z0-9][\u4e00-\u9fffA-Za-z0-9-]*$")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--slug", required=True,
+                    help="包名关键词（中文短名，可含英文/数字/连字符），如 个人免费基建全景、GrokBot多Agent调度")
+    ap.add_argument("--title", required=True, help="文章标题")
+    ap.add_argument("--base", default=DEFAULT_BASE)
+    ap.add_argument("--date", default=datetime.date.today().isoformat())
+    ap.add_argument("--direction", default="reverse", choices=("forward", "reverse"),
+                    help="forward=源自 topstream 底稿；reverse=本工作区选题，定稿后回推 topstream")
+    ap.add_argument("--source-file", default="",
+                    help='forward 时填 topstream 的 notes/xxx.md')
+    ap.add_argument("--images", nargs="*", default=[],
+                    help="要拷入 images/ 的源图片路径")
+    args = ap.parse_args()
+
+    if not SLUG_RE.match(args.slug):
+        print("✗ 目录名只允许中文、英文字母、数字、连字符：%s" % args.slug)
+        return 1
+
+    pkg = os.path.join(args.base, "%s-%s" % (args.date, args.slug))
+    if os.path.exists(pkg):
+        print("✗ 目录已存在：%s" % pkg)
+        return 1
+
+    os.makedirs(os.path.join(pkg, "images"), exist_ok=True)
+    os.makedirs(os.path.join(pkg, "diagrams"), exist_ok=True)
+
+    draft = os.path.join(pkg, "公众号稿.md")
+    if args.direction == "forward" and not args.source_file:
+        print("⚠ forward 未给 --source-file，将留空 source_file（回补 notes/xxx.md）")
+    src_file = args.source_file or '""'
+    tgt_file = '""' if args.direction == "forward" else "pending"
+    with open(draft, "w", encoding="utf-8") as fh:
+        fh.write(SKELETON.format(
+            title=args.title,
+            source_type="user-original" if args.direction == "reverse" else "ai-derived",
+            direction=args.direction,
+            source_file=src_file,
+            target_file=tgt_file,
+            now=datetime.datetime.now().astimezone().isoformat(timespec="seconds")))
+
+    copied = 0
+    for src in args.images:
+        if os.path.exists(src):
+            shutil.copy2(src, os.path.join(pkg, "images", os.path.basename(src)))
+            copied += 1
+        else:
+            print("! 跳过不存在的图片：%s" % src)
+
+    print("✓ 交付包已创建：%s" % pkg)
+    print("  稿件骨架 : 公众号稿.md（含容器语法示例，写作时删掉注释）")
+    if copied:
+        print("  图片     : %d 张 → images/" % copied)
+    print("")
+    print("下一步：")
+    print("  1. 写完稿后体检（可加 --fix 自动补中英文间距）：")
+    print("     python3 %s/lint-wechat.py --input '%s' --fix" % (
+        os.path.dirname(os.path.abspath(__file__)), draft))
+    print("  2. 定稿时同步状态与目录名（加 --apply 生效）：")
+    print("     python3 %s/sync-status.py --set 定稿 '%s' --apply" % (
+        os.path.dirname(os.path.abspath(__file__)), os.path.basename(pkg)))
+    print("  3. 生成公众号 HTML：")
+    print("     python3 %s/md2wechat.py --input '%s' --out-dir '%s' --slug %s" % (
+        os.path.dirname(os.path.abspath(__file__)), draft, pkg, args.slug))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/topmind-wechat-post/scripts/package_skill.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""技能分发包打包器（发布前完整性校验 + 发布清单）。
+
+用法:
+    python scripts/package_skill.py            # 校验 → 打包 → 写发布清单
+    python scripts/package_skill.py --check    # 只校验不打包（CI / 提交前自检）
+
+产物:
+    dist/<skill>.zip            分发包（解压目录名 = 技能名）
+    dist/<skill>.manifest.json  发布清单（版本 / 条目 / 大小 / SHA-256）
+
+校验（任一不过 → 退出码 1）:
+    · SKILL.md frontmatter 含 name / description；name 与目录名一致；
+      description ≤ 1024 字符（平台截断阈值）
+    · README.md / package.json 存在；package.json name 与技能名一致
+    · scripts/*.py 全部可编译；references/*.md 非空
+    · SKILL.md 引用的 references/<file> 全部存在
+    · 无 scripts/_* / __pycache__ / .env 等不应进包的文件
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+NAME = ROOT.name
+OUT = ROOT / "dist" / f"{NAME}.zip"
+MANIFEST = ROOT / "dist" / f"{NAME}.manifest.json"
+DESC_LIMIT = 1024
+
+INCLUDE = ["SKILL.md", "README.md", "package.json", "assets/", "references/", "scripts/", "evals/", "agents/"]
+EXCLUDE_RES = [
+    re.compile(r"(^|/)scripts/_"),
+    re.compile(r"(^|/)\.env($|\.)"),
+    re.compile(r"(^|/)__pycache__(/|$)"),
+    re.compile(r"(^|/)node_modules(/|$)"),
+    re.compile(r"(^|/)dist(/|$)"),
+]
+
+errors: list[str] = []
+
+
+def fail(msg: str) -> None:
+    errors.append(msg)
+    print(f"  ✗ {msg}")
+
+
+def ok(msg: str) -> None:
+    print(f"  ✓ {msg}")
+
+
+def read_frontmatter() -> dict:
+    text = (ROOT / "SKILL.md").read_text(encoding="utf-8")
+    m = re.match(r"^---\r?\n([\s\S]*?)\r?\n---", text)
+    if not m:
+        fail("SKILL.md 缺 frontmatter")
+        return {}
+    fm = m.group(1)
+    name = re.search(r"^name:\s*(\S+)\s*$", fm, re.M)
+    desc = ""
+    dm = re.search(r'^description:\s*"([^"]*)"\s*$', fm, re.M)
+    if dm:
+        desc = dm.group(1).strip()
+    else:
+        dm = re.search(r"^description:\s*>\-\s*\n((?:[ \t]+.*\n?)+)", fm, re.M)
+        if dm:
+            desc = " ".join(line.strip() for line in dm.group(1).splitlines() if line.strip())
+    return {"name": name.group(1) if name else "", "description": desc}
+
+
+def check() -> bool:
+    print(f"[check] {NAME}")
+    fm = read_frontmatter()
+    if fm.get("name") != NAME:
+        fail(f"frontmatter name={fm.get('name')!r} 与目录名 {NAME!r} 不一致")
+    else:
+        ok("name 与目录名一致")
+    desc = fm.get("description", "")
+    if not desc:
+        fail("description 为空")
+    elif len(desc) > DESC_LIMIT:
+        fail(f"description {len(desc)} 字符，超过 {DESC_LIMIT}")
+    else:
+        ok(f"description {len(desc)} 字符")
+
+    for f in ("README.md", "package.json"):
+        if not (ROOT / f).is_file():
+            fail(f"缺 {f}")
+        else:
+            ok(f"有 {f}")
+    try:
+        pkg = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+        if pkg.get("name") != NAME:
+            fail(f"package.json name={pkg.get('name')!r} 与技能名不一致")
+        if not re.match(r"^\d+\.\d+\.\d+", str(pkg.get("version", ""))):
+            fail("package.json version 非 semver")
+    except (OSError, json.JSONDecodeError) as e:
+        fail(f"package.json 解析失败: {e}")
+
+    for p in ROOT.rglob("*"):
+        if not p.is_file() or ".git" in p.parts:
+            continue
+        rel = p.relative_to(ROOT).as_posix()
+        for rx in EXCLUDE_RES:
+            if rx.search(rel):
+                fail(f"不应进包的文件: {rel}")
+                break
+    ok("无禁用文件")
+
+    for py in sorted((ROOT / "scripts").glob("*.py")):
+        try:
+            compile(py.read_text(encoding="utf-8"), str(py), "exec")
+        except SyntaxError as e:
+            fail(f"{py.name} 编译失败: {e}")
+    ok("scripts/*.py 编译通过")
+
+    refdir = ROOT / "references"
+    if refdir.is_dir():
+        for md in sorted(refdir.glob("*.md")):
+            if md.stat().st_size == 0:
+                fail(f"references/{md.name} 为空")
+        skill_text = (ROOT / "SKILL.md").read_text(encoding="utf-8")
+        for ref in sorted(set(re.findall(r"references/([\w\-.]+\.md)", skill_text))):
+            if not (refdir / ref).is_file():
+                fail(f"SKILL.md 引用的 references/{ref} 不存在")
+        ok("references 完整性通过")
+
+    if errors:
+        print(f"\n[check] {NAME}: {len(errors)} 项失败")
+        return False
+    print(f"\n[check] {NAME}: 全部通过")
+    return True
+
+
+def package() -> None:
+    if not check():
+        sys.exit(1)
+    (ROOT / "dist").mkdir(exist_ok=True)
+    entries: list[str] = []
+    with zipfile.ZipFile(OUT, "w", zipfile.ZIP_DEFLATED) as z:
+        for p in sorted(ROOT.rglob("*")):
+            if not p.is_file() or ".git" in p.parts:
+                continue
+            rel = p.relative_to(ROOT)
+            rel_posix = rel.as_posix()
+            if any(rx.search(rel_posix) for rx in EXCLUDE_RES):
+                continue
+            if not any(
+                rel_posix == inc.rstrip("/") or rel_posix.startswith(inc)
+                for inc in INCLUDE
+                if inc.endswith("/")
+            ) and rel_posix not in INCLUDE:
+                continue
+            z.write(p, arcname=f"{NAME}/{rel_posix}")
+            entries.append(rel_posix)
+    sha = hashlib.sha256(OUT.read_bytes()).hexdigest()
+    pkg = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+    manifest = {
+        "name": NAME,
+        "version": pkg.get("version"),
+        "built_at": datetime.now(timezone.utc).isoformat(),
+        "files": len(entries),
+        "sha256": sha,
+        "entries": entries,
+    }
+    MANIFEST.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"\n[package] {OUT} ({len(entries)} 文件, sha256={sha[:12]}…)")
+
+
+def main() -> None:
+    if "--check" in sys.argv[1:]:
+        sys.exit(0 if check() else 1)
+    package()
+
+
+if __name__ == "__main__":
+    main()

package/topmind-wechat-post/scripts/push-to-topstream.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""push-to-topstream.py — 反向回推：公众号稿 → topstream/notes 纯 Markdown。
+
+反向链路的最后一公里最容易出错：`::: 容器`、`==高亮==`、`[!徽章]` 等公众号专用语法
+绝不能写进 notes/（仓库原文保持纯 Markdown）。本脚本做「降级转换」并生成 README 索引条目。
+
+降级规则：
+  - 剥离 frontmatter
+  - `:::` 围栏行删除，容器内文本原样保留
+  - `==高亮==` → 去掉 `==`
+  - `[!徽章]` / `[!xxx]` → 整段删除
+  - `[文字](url)` 外链保留（GitHub markdown 支持）
+  - 中英文盘古之白保留（对 notes 同样适用）
+
+Usage:
+    python3 push-to-topstream.py <包目录> [--target notes/xxx.md] [--apply]
+    # 默认 dry-run：打印降级预览 + 语法统计 + README 索引条目，不写盘
+"""
+
+import argparse
+import os
+import re
+import shutil
+import sys
+
+DEFAULT_BASE = os.path.join(
+    os.path.expanduser("~"), "TopWorkSpace", "topmind-workspace",
+    "40-创作", "2026-公众号")
+DEFAULT_TOPSTREAM = os.path.join(os.path.expanduser("~"), "TopWorkSpace", "topstream")
+
+CONTAINER_RE = re.compile(r"^:::\s*\w*\s*$")
+HIGHLIGHT_RE = re.compile(r"==([^=]+)==")
+BADGE_RE = re.compile(r"\[![^\]]*\]")
+
+
+def split_fm(text):
+    if not text.startswith("---\n"):
+        return None, text
+    i = text.find("\n---", 3)
+    if i < 0:
+        return None, text
+    return text[4:i], text[i + 4:].lstrip("\n")
+
+
+def get_field(fm, key, default=""):
+    if not fm:
+        return default
+    m = re.search(r"^%s:\s*(.*)$" % re.escape(key), fm, re.M)
+    if not m:
+        return default
+    v = m.group(1).strip()
+    return v.strip('"').strip("'") if v else default
+
+
+def downgrade(body):
+    """公众号稿正文 → notes 纯 Markdown。返回 (文本, 统计)"""
+    stats = {"container": 0, "highlight": 0, "badge": 0}
+    out = []
+    for line in body.split("\n"):
+        if CONTAINER_RE.match(line.strip()):
+            stats["container"] += 1
+            continue
+        if BADGE_RE.search(line):
+            stats["badge"] += len(BADGE_RE.findall(line))
+            line = BADGE_RE.sub("", line).strip()
+            if not line:
+                continue
+        line, n = HIGHLIGHT_RE.subn(r"\1", line)
+        stats["highlight"] += n
+        out.append(line)
+    return "\n".join(out).strip("\n") + "\n", stats
+
+
+IMG_REF_RE = re.compile(r"(!\[[^\]]*\]\()(images/[^)\s]+)(\))")
+
+
+def push_assets(body_md, pkg_path, topstream, note_target, name_map, dry=False):
+    """把正文引用的本地图片搬进 topstream 并改写为仓库约定路径。
+
+    `notes/xxx.md` 里写 `images/xx.png` 在 GitHub 上是死链——仓库没有 `notes/images/`。
+    仓库既有约定：图放 `assets/images/<note-slug>/`，正文用 `../assets/images/<slug>/xx.png`。
+    返回 (新正文, 搬移明细, 未找到的源图)。
+    """
+    slug = os.path.splitext(os.path.basename(note_target))[0]
+    dst_dir = os.path.join(topstream, "assets", "images", slug)
+    moved, missing = [], []
+
+    def repl(m):
+        src = m.group(2)
+        base = os.path.basename(src)
+        src_path = os.path.join(pkg_path, src)
+        if not os.path.exists(src_path):
+            missing.append(src)
+            return m.group(0)
+        new_name = name_map.get(base, base)
+        if not dry:                      # dry-run 只看映射，不落盘
+            os.makedirs(dst_dir, exist_ok=True)
+            shutil.copy2(src_path, os.path.join(dst_dir, new_name))
+        moved.append((base, new_name))
+        return m.group(1) + "../assets/images/%s/%s" % (slug, new_name) + m.group(3)
+
+    return IMG_REF_RE.sub(repl, body_md), moved, missing
+
+
+def make_readme_entry(title, target, tags):
+    tag_str = " ".join("`%s`" % t for t in tags)
+    return (
+        "- [**%s**](%s)  \n"
+        "  描述：<一句话介绍这篇文章解决了什么问题、读者能带走什么>  \n"
+        "  %s\n" % (title, target, tag_str)
+    )
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("pkg", help="包目录名（相对 base）或绝对路径")
+    ap.add_argument("--base", default=DEFAULT_BASE)
+    ap.add_argument("--topstream", default=DEFAULT_TOPSTREAM)
+    ap.add_argument("--target", help="回推目标 notes/xxx.md（缺省读 frontmatter target_file）")
+    ap.add_argument("--apply", action="store_true", help="实际写盘（默认只预览）")
+    ap.add_argument("--force", action="store_true", help="目标已存在时覆盖")
+    ap.add_argument("--assets", action="store_true",
+                    help="把正文图片搬进 <topstream>/assets/images/<note-slug>/ 并改写引用（GitHub 必需）")
+    ap.add_argument("--asset-slug", default="", help="覆盖资源子目录名（默认取 note 文件名）")
+    ap.add_argument("--asset-names", default="",
+                    help='文件名重命名映射，如 "00-封面.jpg=01-cover.jpg,01-分工.png=02-division-of-labor.png"')
+    args = ap.parse_args()
+
+    pkg_path = args.pkg if os.path.isabs(args.pkg) else os.path.join(args.base, args.pkg)
+    draft = os.path.join(pkg_path, "公众号稿.md")
+    if not os.path.exists(draft):
+        print("✗ 找不到公众号稿：%s" % draft)
+        return 1
+
+    text = open(draft, encoding="utf-8").read()
+    fm, body = split_fm(text)
+    title = get_field(fm, "title") or get_field(fm, "title", "")
+    status = get_field(fm, "status", "草稿")
+    target_file = get_field(fm, "target_file", "")
+    tags = []
+    mt = re.search(r"^tags:\s*\[(.*)\]$", fm or "", re.M)
+    if mt:
+        tags = [t.strip().strip('"').strip("'") for t in mt.group(1).split(",") if t.strip()]
+    tags = [t for t in tags if t not in ("公众号", "排版")]
+
+    target = args.target or (target_file if target_file != "pending" else "")
+    if not target:
+        print("✗ 需要回推目标：--target notes/xxx.md（frontmatter target_file 仍为 pending）")
+        return 1
+    if not target.startswith("notes/"):
+        print("✗ target 应以 notes/ 开头：%s" % target)
+        return 1
+
+    body_md, stats = downgrade(body)
+
+    name_map = {}
+    for pair in args.asset_names.split(","):
+        if "=" in pair:
+            k, v = pair.split("=", 1)
+            name_map[k.strip()] = v.strip()
+
+    if args.assets:
+        if args.asset_slug:
+            target = os.path.join(os.path.dirname(target), args.asset_slug + ".md")
+        body_md, moved, missing = push_assets(
+            body_md, pkg_path, args.topstream, target, name_map,
+            dry=not args.apply)
+    else:
+        moved, missing = [], []
+
+    # 确保有 H1 标题开头
+    if not body_md.lstrip().startswith("# "):
+        body_md = "# %s\n\n%s" % (title, body_md)
+
+    out_path = os.path.join(args.topstream, target)
+
+    print("回推预览：%s" % os.path.basename(pkg_path))
+    print("  标题     : %s" % title)
+    print("  状态     : %s" % status)
+    print("  目标     : %s" % target)
+    print("  降级统计 : 容器 %d · 高亮 %d · 徽章 %d"
+          % (stats["container"], stats["highlight"], stats["badge"]))
+    if status != "定稿":
+        print("  ⚠ status=%s，回推前应先定稿（sync-status.py --set 定稿）" % status)
+    print("")
+    if moved or missing:
+        print("  图片搬运 : %d 张 → assets/images/%s/"
+              % (len(moved), os.path.splitext(os.path.basename(target))[0]))
+        for zh, en in moved:
+            if zh != en:
+                print("             %s → %s" % (zh, en))
+        non_ascii = [en for _, en in moved if not en.isascii()]
+        if non_ascii:
+            print("             ⚠ 文件名含非 ASCII 字符：%s" % "、".join(non_ascii))
+            print("               仓库约定用 ASCII（--asset-names 传映射，如 \"00-封面.jpg=01-cover.jpg\"）")
+        if missing:
+            print("             ✗ 源图缺失（引用仍是 images/，会 404）：%s" % "、".join(missing))
+    elif "images/" in body_md:
+        print("  ⚠ 正文引用了本地图但未加 --assets：GitHub 上 images/ 是死链，请补 --assets")
+    print("")
+    print("—— README 索引条目（复制到 topstream/README.md 的「研析心得」段）——")
+    print(make_readme_entry(title, target, tags))
+
+    if args.apply:
+        os.makedirs(os.path.dirname(out_path), exist_ok=True)
+        if os.path.exists(out_path) and not args.force:
+            print("✗ 目标已存在，加 --force 覆盖：%s" % out_path)
+            return 1
+        with open(out_path, "w", encoding="utf-8") as fh:
+            fh.write(body_md)
+        print("")
+        print("✓ 已写入 %s（%d 字节）" % (out_path, len(body_md.encode("utf-8"))))
+        print("  下一步：把上面的 README 条目插进 topstream/README.md；")
+        print("  （图片已按上面明细落 assets/，正文引用已改写为 ../assets/...）")
+        print("  然后回本包改 frontmatter：target_file 从 pending 改为 %s" % target)
+        print("  （可用：sync-status.py 之外手动改 target_file 字段，或用编辑器）")
+    else:
+        print("")
+        print("[dry-run] 加 --apply 实际写盘。写盘不会自动改 README 与 frontmatter，")
+        print("        这两步由你/agent 手工完成，保证索引不漂移。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())