@topmindspace/topmind-writing-skills 0.7.1

package/topmind-cover/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/README.en.md

@@ -0,0 +1,111 @@
+# topmind-wechat-post · WeChat Article Authoring
+
+**[中文](./README.md)** | English
+
+Full lifecycle for WeChat articles: delivery package, review & rewrite, three quality gates, status sync, WeChat inline typography, and publish checklist.
+
+- Version: **v0.2.0** (same tag as `@topmindspace/topmind-writing-skills@0.7.1`)
+
+## Install
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-wechat-post
+```
+
+## Usage
+
+```bash
+export TOPMIND_WORKSPACE=/path/to/workspace   # recommended; or point the delivery package root with --base
+
+# Create a new delivery package
+python3 scripts/new-article.py --slug demo --title "标题" --direction reverse
+
+# Typography lint + auto-fix
+python3 scripts/lint-wechat.py --input <package>/公众号稿.md --fix
+
+# De-AI-flavor scan (target ≥ 85)
+python3 scripts/scan_ai_flavor.py <package>/公众号稿.md
+
+# Markdown → fully inline HTML (--embed-images is mandatory, or pasted images go missing)
+python3 scripts/md2wechat.py --input <package>/公众号稿.md --out-dir <package> --slug demo --embed-images
+
+# Status sync
+python3 scripts/sync-status.py --set 定稿 <package> --apply
+```
+
+Scripts use Python stdlib only — zero dependencies.
+
+## Minimal example
+
+Input `demo.md`:
+
+    # Title
+
+    Opening hook paragraph.
+
+    ## Chapter One
+
+    Body text with **emphasis**.
+
+    ![diagram](images/a.png)
+
+```bash
+# first drop a real image at images/a.png next to demo.md (missing files land in the
+# checklist as "not embedded" and will be lost on paste)
+mkdir -p images && cp /path/to/your-image.png images/a.png
+python3 scripts/md2wechat.py --input demo.md --out-dir demo --slug demo --embed-images
+```
+
+Output `demo/demo-公众号版.html` (open in a browser → click "复制正文" → paste into the WeChat editor):
+
+```html
+<!-- h2 auto-numbered; closing chapters like "总结" get ∞ -->
+<h2 ...><span ...>1</span>Chapter One</h2>
+<!-- images inlined as base64, pasted along with the text -->
+<img src="data:image/png;base64,iVBORw0KGgo..." ...>
+```
+
+Also generated: `demo/图片上传清单.md` — the upload checklist for images, mermaid diagrams, and reference links.
+
+## md2wechat parameters
+
+| Flag | Description |
+|------|-------------|
+| `--input` / `--out-dir` / `--slug` | Required: input md, output dir, filename slug |
+| `--embed-images` | Inline images as base64 (mandatory, or pasted images go missing) |
+| `--theme` | Theme id / Chinese name / JSON path, or `genre:<topic>` for auto-pick; `--list-themes` shows all |
+| `--link-mode` | Link rendering: `footnote` (default: superscript `[n]` + end-of-article "参考链接") / `inline` (label normal, URL gray: `文字（url）`) / `note` (whole block gray small text: `文字（url）`) |
+| `--asset-root` | Asset root dir, resolves `../assets/`-style image paths in the draft |
+| `--no-toc` | Skip the auto-inserted "本文看点" reading guide |
+| `--signature` / `--author` / `--author-bio` | Closing signature: `auto` (default, skipped if the draft has one) / `on` / `off`, name and bio |
+| `--no-pangu` | Disable automatic CJK/Latin spacing |
+| `--render-mermaid` | Render mermaid to PNG when mmdc is available |
+
+## Three paths
+
+- **forward**: draft → WeChat article (review & rewrite)
+- **reverse**: original topic → WeChat article → optional pushback
+- **curated web**: online curated sources → handled as reverse
+
+## Three quality gates
+
+Facts (first-hand sources) / logic (structural consistency) / copy (de-AI-flavor ≥ 85).
+
+## Related skills
+
+- Cover art → `topmind-cover` (shared X long-form / WeChat cover)
+- X long-form → `topmind-x-article` (Markdown draft → one-click X publish package)
+
+## External dependencies
+
+The following skills live **outside this repo** (usually provided by the user's local workbuddy environment). Missing ones degrade or disable the corresponding capability; all scripts in this repo still work fully:
+
+- `humanizer-zh`: fidelity boundaries for Chinese de-AI-flavor; without it the "de-AI-flavor only, no typesetting" path is unavailable.
+- `qu-aiwei-zh`: Chinese de-AI-flavor scan targeting; `scripts/scan_ai_flavor.py` shares its origin and can substitute when missing.
+
+## Development
+
+```bash
+python3 scripts/package_skill.py --check
+python3 scripts/negative_tests.py
+```

package/topmind-wechat-post/README.md

@@ -0,0 +1,111 @@
+# topmind-wechat-post · 公众号创作技能
+
+[English](./README.en.md) | 中文
+
+公众号文章全生命周期：交付包、审校改写、质量三关、状态同步、微信内联排版与发布清单。
+
+- 版本：**v0.2.0**（与 `@topmindspace/topmind-writing-skills@0.7.1` 同 tag）
+
+## 安装
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-wechat-post
+```
+
+## 用法
+
+```bash
+export TOPMIND_WORKSPACE=/path/to/workspace   # 推荐；或用 --base 指定交付包根
+
+# 新建交付包
+python3 scripts/new-article.py --slug demo --title "标题" --direction reverse
+
+# 排版体检 + 自动修复
+python3 scripts/lint-wechat.py --input <包>/公众号稿.md --fix
+
+# 去 AI 味扫描（目标 ≥85）
+python3 scripts/scan_ai_flavor.py <包>/公众号稿.md
+
+# Markdown → 全内联 HTML（必加 --embed-images，否则粘贴丢图）
+python3 scripts/md2wechat.py --input <包>/公众号稿.md --out-dir <包> --slug demo --embed-images
+
+# 状态同步
+python3 scripts/sync-status.py --set 定稿 <包> --apply
+```
+
+脚本纯 Python 标准库，零依赖。
+
+## 最小示例
+
+输入 `demo.md`：
+
+    # 标题
+
+    开头钩子段落。
+
+    ## 第一章
+
+    正文文字，**重点**加粗。
+
+    ![示意图](images/a.png)
+
+```bash
+# 先在 demo.md 同级放一张真实图片到 images/a.png（缺图会进"未内嵌"清单，粘贴后丢图）
+mkdir -p images && cp /path/to/你的图.png images/a.png
+python3 scripts/md2wechat.py --input demo.md --out-dir demo --slug demo --embed-images
+```
+
+输出 `demo/demo-公众号版.html`（浏览器打开 → 点「复制正文」→ 粘贴到公众号后台）：
+
+```html
+<!-- 二级标题自动编号；"总结"类末章编号为 ∞ -->
+<h2 ...><span ...>1</span>第一章</h2>
+<!-- 图片 base64 内嵌，粘贴即带图 -->
+<img src="data:image/png;base64,iVBORw0KGgo..." ...>
+```
+
+附带 `demo/图片上传清单.md`：图片 / mermaid 图表 / 参考链接的上传与核对清单。
+
+## md2wechat 参数
+
+| 参数 | 说明 |
+|------|------|
+| `--input` / `--out-dir` / `--slug` | 必填：输入 md、输出目录、文件名标识 |
+| `--embed-images` | 图片 base64 内嵌（必加，否则粘贴丢图） |
+| `--theme` | 主题标识 / 中文名 / JSON 路径，或 `genre:题材` 按题材自动选；`--list-themes` 查看全部 |
+| `--link-mode` | 外链形态：`footnote`（默认：正文上标 `[n]` + 文末「参考链接」）/ `inline`（文字正常、URL 灰小字：`文字（url）`）/ `note`（整块灰小字：`文字（url）`） |
+| `--asset-root` | 素材根目录，用于解析稿中 `../assets/` 形式的图片路径 |
+| `--no-toc` | 不自动插入前言导读 |
+| `--signature` / `--author` / `--author-bio` | 尾部签名区：`auto`（默认，有签名则不重复）/ `on` / `off`，署名与简介 |
+| `--no-pangu` | 关闭中英文自动加空格 |
+| `--render-mermaid` | 有 mmdc 时把 mermaid 渲染成 PNG |
+
+## 三条路径
+
+- **forward**：底稿 → 公众号（审校改写）
+- **reverse**：选题原创 → 公众号 → 可选回推
+- **站外拉取**：在线精选站 → 按 reverse 处理
+
+## 质量三关
+
+事实（一手来源）/ 逻辑（结构一致）/ 文字（去 AI 味 ≥85）。
+
+## 相关技能
+
+- 封面配图 → `topmind-cover`（X 长文 / 公众号共用封面）
+- X 长文 → `topmind-x-article`（Markdown 原稿一键转 X 发布包）
+
+## 外部依赖
+
+本技能工作流会路由到以下**仓库外**技能（不含于本仓库，一般随用户侧 workbuddy
+环境提供）。缺失时对应能力降级/不可用，不影响本仓库脚本的全部功能：
+
+- `humanizer-zh`：中文去 AI 味的保真边界；缺失时「只去 AI 味不排版」路径不可用。
+- `qu-aiwei-zh`：中文去 AI 味扫描定位；`scripts/scan_ai_flavor.py` 与其同源，缺失时可用仓库内脚本替代。
+
+## 开发
+
+```bash
+python3 scripts/package_skill.py --check
+python3 scripts/negative_tests.py
+```

package/topmind-wechat-post/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: topmind-wechat-post
+version: 0.2.0
+description: "管一篇公众号文章从选题/底稿到发布的完整生命周期：交付包搭建、审校改写、质量三关（事实/逻辑/去AI味）、状态同步、微信内联排版与发布清单。Use when 写公众号、公众号排版、公众号定稿、发公众号。Do NOT use for 只改错别字、小红书/知乎、纯网页发布。"
+action_category: write
+triggers:
+  - 公众号
+  - 微信排版
+  - 公众号排版
+  - 公众号稿
+  - 排版这篇文章
+  - 定稿
+  - 发公众号
+  - 公众号交付
+  - wechat
+  - mp format
+triggers_cn:
+  - 写公众号文章
+  - 公众号排版定稿
+  - 公众号发布清单
+author: TopMindspace
+license: MIT
+homepage: https://github.com/topmindspace/topmind-writing-skills#readme
+updated: 2026-09-29
+---
+
+# topmind-wechat-post · 公众号创作技能
+
+**公众号专用写作技能**。管一篇公众号文章从选题/底稿到发布清单的完整生命周期。
+
+```
+选题/底稿 → 创作 → 质量三关 → 定稿(状态+目录) → 排版 → 发布清单 →（可选）回推 notes
+```
+
+> 用户明确说公众号 / 微信排版时进本技能；通用长文写作不在本技能范围内。
+
+## 语言铁律
+
+- **默认中文**：标题、正文、配图文案一律用中文写作，这是默认行为，不需要用户每次声明。
+- **英文是例外**：只有用户**明确说**"写英文文章"时才用英文。用户消息里夹杂英文词、
+  给英文参考素材、引用英文原文，都不算"要求写英文"。
+- 引用英文一手素材（官方公告、模型卡、论文标题）时保留英文原文，正文主体仍是中文，
+  必要时在旁给中文翻译。
+
+## 脚本（真源）
+
+| 脚本 | 用途 |
+|------|------|
+| `scripts/new-article.py` | 建交付包（骨架稿 + frontmatter + images/diagrams） |
+| `scripts/sync-status.py` | 状态 ⇄ 目录名 ⇄ 字数（草稿 / 定稿 / 已发布） |
+| `scripts/sync-mapping.py` | 映射一致性（frontmatter + 目录 + 可选 notes + topic 总表） |
+| `scripts/push-to-topstream.py` | 可选回推：公众号稿降级为纯 Markdown notes |
+| `scripts/lint-wechat.py` | 排版体检 + 自动修复（中英文间距、段长、AI 腔…） |
+| `scripts/md2wechat.py` | Markdown → 全内联 HTML；**必加 `--embed-images`** |
+| `scripts/scan_ai_flavor.py` | 中文去 AI 味扫描（与 `qu-aiwei-zh` 同源） |
+
+```bash
+# 路径解析：CLI --base/--workspace → env TOPMIND_WECHAT_BASE / TOPMIND_WORKSPACE / TOPSTREAM_ROOT → 惯例
+export TOPMIND_WORKSPACE=/path/to/workspace   # 推荐
+python3 scripts/new-article.py --slug demo --title "标题" --direction reverse
+python3 scripts/lint-wechat.py --input <包>/公众号稿.md --fix
+python3 scripts/scan_ai_flavor.py <包>/公众号稿.md          # 目标 ≥85
+python3 scripts/md2wechat.py --input <包>/公众号稿.md --out-dir <包> --slug demo \
+  --asset-root <素材根> --embed-images
+python3 scripts/sync-status.py --set 定稿 <包> --apply
+```
+
+细节见 [`references/workflow.md`](references/workflow.md) · [`references/known-pits.md`](references/known-pits.md)。
+
+## 路径默认
+
+| 用途 | 解析 |
+|------|------|
+| 交付包根 | `--base` → `TOPMIND_WECHAT_BASE` → `{ws}/40-创作/2026-公众号` 或 `{ws}/20-专题/2026-公众号` |
+| 工作区 | `TOPMIND_WORKSPACE` |
+| 底稿/回推 | `--topstream` → `TOPSTREAM_ROOT` → 可选；不存在则跳过 notes 校验 |
+| 终稿交付 | 可 `save-output` 拷贝到 role:delivery（`88-交付/`），包仍留在创作类专题 |
+
+## 三条路径
+
+### forward（底稿 → 公众号）
+
+```
+底稿 notes/*.md → 审校改写 → 质量三关 → 定稿 → 排版 → 发布
+```
+
+`new-article.py --direction forward --source-file notes/xxx.md`
+
+### reverse（选题原创）
+
+```
+选题包 → 调研素材 → 多轮改稿 → 三关 → 定稿 → 排版 → 发布 →（可选）push-to-topstream
+```
+
+`new-article.py --direction reverse`（`target_file: pending`）
+
+### 站外拉取（转载整合 / 在线精选站）
+
+源不在本工作区、也不在 topstream `notes/` 时，**仍落 `reverse` + `target_file: pending`**。  
+**不要用 `forward`**：它要求 `source_file` 以 `notes/` 开头且文件真实存在，站外源必然过不了 `sync-mapping.py`。
+
+```bash
+python3 scripts/new-article.py --slug <中文短名> --title "<标题>" --direction reverse
+```
+
+取源坑（RSC 载荷、图片 hash 映射、`md5` 去重、截图裁切）见 `references/workflow.md`「站外拉取取源注意」；差异与口径写进包内 `README.md`。
+
+**回推纪律**：notes 保持纯 Markdown（`:::` 容器 / 徽章 / `==高亮==` 只进公众号稿）；回推**务必带 `--assets`**（否则 GitHub 上 `images/` 死链）。命令串见 `references/workflow.md`「收尾」。
+
+## 交付包与状态
+
+```text
+YYYY-MM-DD-<中文短名>            # 草稿
+YYYY-MM-DD-<中文短名>-released   # 定稿 / 已发布
+├── 公众号稿.md                  # 唯一改稿入口
+├── <slug>-公众号版.html         # 浏览器打开 → 复制正文 → 粘贴后台
+├── 图片上传清单.md
+├── images/  diagrams/
+└── README.md                    # 包说明（可选）
+```
+
+**frontmatter（映射真源）**
+
+```yaml
+status: 草稿            # 草稿 | 定稿 | 已发布
+direction: reverse      # forward | reverse
+source_file: ""         # forward 填 notes/xxx.md
+target_file: pending    # reverse：pending | notes/xxx.md
+word_count: 0           # 纯中文字数，sync-status 维护
+```
+
+**交付铁律**：发布/分享时直接用交付包里的 HTML 原文件原样呈现，
+不临时重新生成版本；`公众号稿.md` 是唯一改稿入口，改稿后重建 HTML 再交付。
+
+状态与目录名**不要手改**：
+
+```bash
+python3 scripts/sync-status.py --set 定稿 <包> --apply
+```
+
+## 质量三关（定稿前必过）
+
+### 关 1 · 事实
+
+- 承重数字回**一手来源**；厂商口径 / 据报道 分开写  
+- 查不到一手来源的传闻**删**  
+- 改稿续写：正文已有数字**回源重核**（上一轮文本最不可信）  
+- 多口径（主轮/复跑）显式拆开；表格从数据源生成，禁止手抄  
+- 外部工具改过的稿：**先核数字再动文字**；「比值对但绝对值错」= 全段重核  
+
+### 关 2 · 逻辑
+
+- 单边结论旁配反方证据  
+- 结构前后一致；同一事实多处同值  
+
+### 关 3 · 文字（去 AI 味）
+
+```bash
+python3 scripts/scan_ai_flavor.py <包>/公众号稿.md   # ≥85（人话）
+```
+
+- 删套话/黑话/工程圈行话；降调段末加粗金句  
+- **满分 ≠ 有人味**：再查「段末金句癖 / 节奏过分整齐 / 没有场景与我 / 报告体标注」  
+- **口语化 ≠ 有人味**：删社交垫词（元叙述、空转过渡、姿态句）  
+- 判据：**这句话删掉之后，读者少知道了什么？**  
+
+详见 [`references/writing-quality.md`](references/writing-quality.md)。
+
+## 排版要点（写稿时）
+
+- 开头 150 字内钩子；单段 ≤110 字；列表项 ≤70 字  
+- 二级标题不手写序号（排版层自动生成）；容器：`::: stat|pull|note|tip|warn|danger|dialogue`  
+- **`::: stat` 内必须是 `数值 | 说明` 管道行**，否则静默丢弃  
+- 评测稿：**图承担数据，正文只解读**；健康密度 **300–450 字/图**  
+- 个股用词红线：禁用 买入/推荐/目标价…；文末投资声明  
+
+更多：[`references/typography-rules.md`](references/typography-rules.md) · [`references/wechat-constraints.md`](references/wechat-constraints.md)。
+
+## 排版与导出（必读）
+
+```bash
+python3 scripts/md2wechat.py \
+  --input <包>/公众号稿.md --out-dir <包> --slug <slug> \
+  --asset-root <素材根> --embed-images \
+  [--theme assets/themes/minimal-ink.json]
+```
+
+1. **永远 `--embed-images`**，否则粘贴丢图（相对路径被序列化成 file://）  
+2. **图片 basename 铁律**：正文引用名 = `images/` 目标名；禁止两套同名图共处  
+3. 合规自检出现 `✗` 改生成器，不要手改 HTML  
+4. **配图位置铁律**（2026-10-01 九月全景教训）：图片必须紧跟它证明的那段文字
+   （最多隔一段）；改稿移动段落时图片行一起搬。构建后必跑：嵌入图数量=文档图数量、
+   嵌入图顺序=文档出现顺序（逐张解码与源文件比对）；每张图前后 6 行做主题关键词
+   邻近检查，不通过则人工核对。
+5. **双版一致性校验**（2026-10-01 九月全景教训 B）：同一选题出 X 版后，
+   必跑 X 内嵌图序列 vs 公众号内嵌图序列的逐字节/逐像素比对（X 去掉封面后应完全一致）。
+   X 侧图片顺序必须用 `--images-from 公众号稿.md` 派生，禁止手工拼 `--images`
+   （曾因文件名排序 ≠ 文档顺序，导致 X 版从第六节起整段配图错位）。
+
+坑清单：[`references/known-pits.md`](references/known-pits.md)。
+
+## 主题
+
+| 文件 | 风格 | 适用 |
+|------|------|------|
+| `assets/themes/minimal-ink.json`（默认） | 黑白灰 + 砖红 | 深度研析 / 观点 / 随笔 |
+| `assets/themes/tech-blue.json` | 科技蓝 | AI/技术 |
+| `assets/themes/newsprint.json` | 报纸衬线 | 人文评论 |
+| `assets/themes/graphite.json` | 石墨克制 | 严肃报告 |
+| `assets/themes/amber-review.json` | 琥珀评测 | 产品评测 |
+
+`md2wechat.py --list-themes` 看全部；`--theme genre:评测` 可按题材自动选。  
+渲染规格见 [`references/element-spec.md`](references/element-spec.md) · 主题映射见 [`references/theme-map.md`](references/theme-map.md)。
+
+**平台红线速查**（详见 [`references/wechat-constraints.md`](references/wechat-constraints.md)）：禁 `div`/`pre`/`h1`/`figure`/`thead`/flex/float/gradient/shadow；表格 `table-layout` 不写 fixed；列数 ≥4 转卡片。
+
+## 与 Desktop「公众号创作」
+
+可视化工作流伴面（若有）：包列表 → 改稿 → 三关 → 预览 → 导出。脚本语义以本技能为准。
+
+## 外部依赖
+
+以下技能**不在本仓库**（一般随用户侧 workbuddy 环境提供）；缺失时对应路由能力不可用，
+本仓库脚本（交付包、排版、发布清单等）功能不受影响：
+
+- `humanizer-zh`：中文去 AI 味的保真边界（「只去 AI 味不排版」路径用）。
+- `qu-aiwei-zh`：中文去 AI 味扫描定位；本仓库 `scan_ai_flavor.py` 与其同源，
+  缺失时可用仓库内脚本替代，扫描定位能力降级。
+
+## When NOT to use
+
+- 只想改几个句子 → 直接编辑  
+- 小红书 / 知乎 / 掘金 → 平台约束不同  
+- 通用长文交付 → 不在本技能范围
+- 封面配图 → `topmind-cover`；X 长文 → `topmind-x-article`
+- 只去 AI 味不排版 → 中文走 `humanizer-zh`（先立保真边界）+ `qu-aiwei-zh`（再扫描定位）；英文走 `humanizer`
+
+## 实战沉淀（2026-10-01 九月全景项目）
+
+- **文字精炼原则**：月度盘点类文章，文字只给"看图能看清的简单结论或事实"，
+  不发散论述。删掉的典型："9 月没发生的那件事可能是最重要的"（评论腔）、
+  "是同一道题的两种解法"（比喻发散）。每段压到 1–2 句，只留时间、主体、数字、来源。
+- **第三方客观素材优先**：官方产品截图 > 官方基准图 > 第三方榜单截图 > 自制图表。
+  自制图只用于时间线、价格对比、总结盘点。9 月项目新增：OpenAI DevDay 官方
+  Codex 四图（CLI/Cloud/Code Review/Security）、DeepSeek Harness 官方图标+
+  第三方实测截图。
+- **模型信息核实**：Muse Spark、Step 5 Preview 等新模型，分数/价格必须回官方模型卡
+  或 Artificial Analysis 原页，不直接采用二手报告数字。榜单文字与榜单截图日期对齐
+  （如 AA 9/28 快照），分数不跨期比较。
+- **frontmatter 状态诚实**：`status: 定稿` 必须等事实/逻辑/文字三关全过才写，
+  构建流水线跑通不等于定稿；`word_count` 用脚本实算，不手填。