yanyan-skill 0.1.0

package/README.en.md

@@ -0,0 +1,180 @@
+# yanyan_skill
+
+[中文](README.md)
+
+yanyan_skill is a reusable Codex skill collection for local content workflows. It currently includes a WeChat Official Account formatting and draft upload assistant.
+
+## Skills
+
+| Skill | Purpose |
+| --- | --- |
+| `yanyan_wechat_upload` | Converts Markdown / HTML / pasted text into WeChat-compatible HTML, generates a local preview, and creates or updates a WeChat article draft only after explicit user confirmation. |
+
+## Install Into Codex
+
+### Option 1: npx
+
+Install directly from GitHub:
+
+```bash
+npx github:yanyansay/yanyan_skill install yanyan_wechat_upload
+```
+
+Install into a project-local `.codex/skills/` directory:
+
+```bash
+npx github:yanyansay/yanyan_skill install yanyan_wechat_upload --target .codex/skills
+```
+
+List installable skills:
+
+```bash
+npx github:yanyansay/yanyan_skill list
+```
+
+If this package is published to npm later, the command can become:
+
+```bash
+npx yanyan-skill install yanyan_wechat_upload
+```
+
+### Option 2: Manual Copy
+
+Copy a skill into your Codex skills directory:
+
+```bash
+mkdir -p ~/.codex/skills
+cp -R skills/yanyan_wechat_upload ~/.codex/skills/
+```
+
+For project-local skills, copy it into `.codex/skills/`:
+
+```bash
+mkdir -p .codex/skills
+cp -R skills/yanyan_wechat_upload .codex/skills/
+```
+
+### Option 3: ClawHub
+
+This repository already uses the `skills/<skill-name>/SKILL.md` structure, so it can be published to ClawHub later.
+
+If maintainers publish the skill to the ClawHub registry, use:
+
+```bash
+clawhub publish skills/yanyan_wechat_upload
+```
+
+After publishing, users can install it with a command like:
+
+```bash
+clawhub install yanyan_wechat_upload
+```
+
+## Initialize Configuration
+
+After installation, type this skill command in a Codex chat:
+
+```text
+yanyan_wechat_upload:init
+```
+
+This is not a terminal command. It is a skill command inside the conversation. Codex will ask for the account name, author, cover strategy, signature strategy, theme color, and keyring service, then write non-sensitive local configuration to:
+
+```text
+~/.config/yanyan_skill/yanyan_wechat_upload/config.json
+```
+
+You can override the path with `YANYAN_WECHAT_UPLOAD_CONFIG=/path/to/config.json`.
+
+Important local config fields:
+
+```json
+{
+  "ACCOUNT_NAME": "Your account name",
+  "AUTHOR_NAME": "Author name",
+  "KEYRING_SERVICE": "yanyan_wechat_upload",
+  "COVER_MODE": "ask-each-run",
+  "DEFAULT_COVER_SOURCE": "RUNTIME_REQUIRED",
+  "SIGNATURE_MODE": "none",
+  "SIGNATURE_VALUE": "none",
+  "THEME_COLOR": "#D97706"
+}
+```
+
+The skill resolves configuration in this order:
+
+1. The JSON file pointed to by `YANYAN_WECHAT_UPLOAD_CONFIG`
+2. `~/.config/yanyan_skill/yanyan_wechat_upload/config.json`
+3. Defaults embedded in `SKILL.md`
+
+Do not commit personal local configuration to this public repository. The repository copy of `SKILL.md` only keeps non-sensitive defaults:
+
+```yaml
+ACCOUNT_NAME: "Your account name"
+AUTHOR_NAME: "Author name"
+KEYRING_SERVICE: "yanyan_wechat_upload"
+
+COVER_MODE: "ask-each-run"
+DEFAULT_COVER_SOURCE: "RUNTIME_REQUIRED"
+
+SIGNATURE_MODE: "none"
+SIGNATURE_VALUE: "none"
+
+THEME_COLOR: "#D97706"
+```
+
+Do not write AppID or AppSecret into `SKILL.md` or `config.json`. Store credentials in a system secret store.
+
+## Configure AppID / AppSecret
+
+AppID / AppSecret must not be written into `SKILL.md` or `config.json`. Store them in a system secret store. macOS example:
+
+```bash
+python3 -m pip install keyring
+keyring set yanyan_wechat_upload app_id
+```
+
+Paste the AppID when prompted. Then run:
+
+```bash
+keyring set yanyan_wechat_upload app_secret
+```
+
+Paste the AppSecret when prompted. Do not send AppSecret in chat, and do not write it into the config file.
+
+You also need to add your current public IP address to the API IP allowlist in the WeChat Official Account admin console.
+
+## Usage
+
+After installation and configuration, say in Codex:
+
+```text
+把这篇 md 发到公众号。/path/to/article.md
+```
+
+Or:
+
+```text
+生成公众号草稿
+```
+
+Then paste the Markdown content.
+
+The upload workflow always generates a local preview first and asks:
+
+```text
+排版预览已完成，请确认是否上传到公众号草稿？
+```
+
+The skill may create or update a WeChat draft only after explicit confirmation.
+
+## Maintenance
+
+- Add a new skill under `skills/<skill-name>/SKILL.md`.
+- Update the repository version first, then copy it into your local Codex skill directory.
+- Do not commit secrets, tokens, temporary upload files, draft payloads, or personal local asset paths.
+- Keep personal defaults in `~/.config/yanyan_skill/.../config.json`, not in the repository.
+
+## Security Boundary
+
+This repository does not contain AppID, AppSecret, or access tokens. The WeChat upload assistant only records how credentials should be read; real credentials must come from Keychain, environment variables, or the current tool's secret manager.

package/README.md

@@ -0,0 +1,180 @@
+# yanyan_skill
+
+[English](README.en.md)
+
+yanyan_skill 是一组可复用的 Codex skills，用来把常见内容工作流沉淀成可安装、可配置、可迭代的本地助手。当前包含微信公众号排版与草稿上传助手。
+
+## 当前 Skills
+
+| Skill | 作用 |
+| --- | --- |
+| `yanyan_wechat_upload` | 将 Markdown / HTML / 粘贴正文整理成微信公众号兼容 HTML，生成本地预览，并在用户确认后创建或更新公众号图文草稿。 |
+
+## 安装到 Codex
+
+### 方式一：npx 安装
+
+可以直接从 GitHub 安装：
+
+```bash
+npx github:yanyansay/yanyan_skill install yanyan_wechat_upload
+```
+
+安装到项目内 `.codex/skills/`：
+
+```bash
+npx github:yanyansay/yanyan_skill install yanyan_wechat_upload --target .codex/skills
+```
+
+查看仓库内可安装的 skills：
+
+```bash
+npx github:yanyansay/yanyan_skill list
+```
+
+如果未来发布到 npm，命令可以简化为：
+
+```bash
+npx yanyan-skill install yanyan_wechat_upload
+```
+
+### 方式二：手动复制
+
+把某个 skill 复制到你的 Codex skills 目录：
+
+```bash
+mkdir -p ~/.codex/skills
+cp -R skills/yanyan_wechat_upload ~/.codex/skills/
+```
+
+如果你在项目内使用 Codex-local skills，也可以复制到项目的 `.codex/skills/`：
+
+```bash
+mkdir -p .codex/skills
+cp -R skills/yanyan_wechat_upload .codex/skills/
+```
+
+### 方式三：ClawHub
+
+这个仓库已经按 `skills/<skill-name>/SKILL.md` 结构维护，适合后续发布到 ClawHub。
+
+如果维护者发布到 ClawHub registry，可以使用：
+
+```bash
+clawhub publish skills/yanyan_wechat_upload
+```
+
+发布成功后，用户才能用类似命令安装：
+
+```bash
+clawhub install yanyan_wechat_upload
+```
+
+## 初始化配置
+
+安装后，在 Codex 对话里输入这个 skill 命令：
+
+```text
+yanyan_wechat_upload:init
+```
+
+这不是终端命令，而是对话里的 skill 命令。Codex 会通过对话收集公众号名称、作者名、封面图策略、签名策略、强调色和 keyring service 名称，然后把非敏感配置写入用户电脑：
+
+```text
+~/.config/yanyan_skill/yanyan_wechat_upload/config.json
+```
+
+也可以通过环境变量指定其他配置文件位置：`YANYAN_WECHAT_UPLOAD_CONFIG=/path/to/config.json`。
+
+本机配置文件里的重点配置项：
+
+```json
+{
+  "ACCOUNT_NAME": "你的公众号名称",
+  "AUTHOR_NAME": "作者名",
+  "KEYRING_SERVICE": "yanyan_wechat_upload",
+  "COVER_MODE": "ask-each-run",
+  "DEFAULT_COVER_SOURCE": "RUNTIME_REQUIRED",
+  "SIGNATURE_MODE": "none",
+  "SIGNATURE_VALUE": "none",
+  "THEME_COLOR": "#D97706"
+}
+```
+
+skill 执行时按这个顺序读取配置：
+
+1. `YANYAN_WECHAT_UPLOAD_CONFIG` 指向的 JSON 文件
+2. `~/.config/yanyan_skill/yanyan_wechat_upload/config.json`
+3. `SKILL.md` 里的默认配置
+
+不要把个人配置提交到公开仓库。仓库里的 `SKILL.md` 只保留非敏感默认值：
+
+```yaml
+ACCOUNT_NAME: "你的公众号名称"
+AUTHOR_NAME: "作者名"
+KEYRING_SERVICE: "yanyan_wechat_upload"
+
+COVER_MODE: "ask-each-run"
+DEFAULT_COVER_SOURCE: "RUNTIME_REQUIRED"
+
+SIGNATURE_MODE: "none"
+SIGNATURE_VALUE: "none"
+
+THEME_COLOR: "#D97706"
+```
+
+不要把 AppID 或 AppSecret 写进 `SKILL.md` 或 `config.json`。凭证应保存到系统安全存储。
+
+## 配置 AppID / AppSecret
+
+AppID / AppSecret 不写入 `SKILL.md`，也不写入 `config.json`。推荐放到系统安全存储。macOS 示例：
+
+```bash
+python3 -m pip install keyring
+keyring set yanyan_wechat_upload app_id
+```
+
+按提示粘贴 AppID。完成后继续运行：
+
+```bash
+keyring set yanyan_wechat_upload app_secret
+```
+
+按提示粘贴 AppSecret。不要把 AppSecret 发到对话里，也不要写进配置文件。
+
+同时需要在微信公众平台后台把当前公网 IP 加入 API IP 白名单。
+
+## 使用方法
+
+安装并配置后，在 Codex 中直接说：
+
+```text
+把这篇 md 发到公众号。/path/to/article.md
+```
+
+或者：
+
+```text
+生成公众号草稿
+```
+
+然后粘贴 Markdown 正文。
+
+上传类流程会先生成本地预览，并停下来询问：
+
+```text
+排版预览已完成，请确认是否上传到公众号草稿？
+```
+
+只有你明确确认后，skill 才能创建或更新公众号草稿。
+
+## 维护方式
+
+- 新增 skill：放到 `skills/<skill-name>/SKILL.md`。
+- 修改已有 skill：先改仓库版本，再复制到本地 Codex skill 目录使用。
+- 不要提交密钥、token、本地临时上传文件、草稿 payload 或个人素材路径。
+- 个人默认配置应写入 `~/.config/yanyan_skill/.../config.json`，不要提交到仓库。
+
+## 安全边界
+
+这个仓库不包含任何 AppID、AppSecret 或 access token。微信公众号上传助手只记录凭证读取方式，真实凭证必须通过 Keychain、环境变量或工具密钥管理读取。

package/bin/yanyan-skill.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const repoRoot = path.resolve(__dirname, "..");
+const skillsRoot = path.join(repoRoot, "skills");
+const defaultTarget = path.join(os.homedir(), ".codex", "skills");
+
+function usage() {
+  console.log(`yanyan-skill
+
+Usage:
+  yanyan-skill list
+  yanyan-skill install <skill-name> [--target <dir>]
+
+Examples:
+  yanyan-skill install yanyan_wechat_upload
+  yanyan-skill install yanyan_wechat_upload --target .codex/skills
+
+After installation, open Codex and run:
+  yanyan_wechat_upload:init
+`);
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function listSkills() {
+  if (!fs.existsSync(skillsRoot)) return [];
+  return fs
+    .readdirSync(skillsRoot)
+    .filter((name) => fs.existsSync(path.join(skillsRoot, name, "SKILL.md")))
+    .sort();
+}
+
+function parseOptions(args) {
+  const options = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--target") {
+      options.target = args[++i];
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { rest, options };
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) fail(`Skill not found: ${src}`);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.rmSync(dest, { recursive: true, force: true });
+  copyTree(src, dest);
+}
+
+function shouldSkip(name) {
+  return name === "__pycache__" || name === ".DS_Store" || name.endsWith(".pyc");
+}
+
+function copyTree(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      if (shouldSkip(entry)) continue;
+      copyTree(path.join(src, entry), path.join(dest, entry));
+    }
+    return;
+  }
+  fs.copyFileSync(src, dest);
+}
+
+function install(skillName, options) {
+  if (!skillName) fail("Missing skill name.");
+  const src = path.join(skillsRoot, skillName);
+  const targetRoot = path.resolve(options.target || defaultTarget);
+  const dest = path.join(targetRoot, skillName);
+  copyDir(src, dest);
+  console.log(`Installed ${skillName} -> ${dest}`);
+  console.log("Next: open Codex and run `yanyan_wechat_upload:init` to configure it through chat.");
+}
+
+const [command, ...args] = process.argv.slice(2);
+const { rest, options } = parseOptions(args);
+
+if (!command || command === "-h" || command === "--help") {
+  usage();
+} else if (command === "list") {
+  for (const skill of listSkills()) console.log(skill);
+} else if (command === "install") {
+  install(rest[0], options);
+} else {
+  usage();
+  fail(`Unknown command: ${command}`);
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "yanyan-skill",
+  "version": "0.1.0",
+  "description": "YanYan Say Codex skill collection installer.",
+  "bin": {
+    "yanyan-skill": "bin/yanyan-skill.js"
+  },
+  "files": [
+    "bin/",
+    "skills/yanyan_wechat_upload/SKILL.md",
+    "README.md",
+    "README.en.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/skills/yanyan_wechat_upload/SKILL.md

@@ -0,0 +1,545 @@
+---
+name: yanyan_wechat_upload
+description: 将中文内容排版成微信公众号兼容 HTML，并在用户确认预览后创建或更新公众号草稿。适用于“上传公众号”“生成公众号草稿”“Markdown 转公众号”“排版公众号文章”“发布到公众号草稿”等请求。必须先做配置检查和 HTML 预览，不得在用户确认前上传。
+---
+
+# WeChat Upload
+
+## 角色
+
+你是用户的微信公众号排版与草稿上传助手。
+
+你的任务是：
+
+- 把用户提供的文章来源整理成微信公众号兼容 HTML
+- 提取或确认标题、摘要、作者、封面图、正文、图片和相关阅读链接
+- 生成本地预览 HTML，让用户先检查排版
+- 只有在用户明确确认后，才创建或更新微信公众号草稿
+- 密钥只从外部安全位置读取，不把 AppSecret 写入文件、日志或对话输出
+- 如果当前环境不能调用微信公众号 API，就只生成预览 HTML 和上传检查清单，不假装已经上传
+
+## Skill Commands
+
+### `yanyan_wechat_upload:init`
+
+当用户输入 `yanyan_wechat_upload:init`，或说“配置公众号上传助手”“初始化公众号上传配置”“修改公众号上传配置”等类似请求时，进入本 skill 的对话式初始化流程。
+
+这个命令不是终端命令。用户是在 Codex 对话里调用它；你作为 agent 负责提问、整理配置、写入用户电脑上的本机配置文件。
+
+初始化流程：
+
+1. 一次性向用户收集以下配置；如果用户跳过某项，使用括号内默认值，不要反复追问：
+   - 公众号名称（默认：`我的公众号`）
+   - 作者名（默认：空）
+   - keyring service 名称（默认：`yanyan_wechat_upload`）
+   - 文章来源支持方式（默认：`paste-md,local-md`）
+   - 封面图处理方式（默认：`ask-each-run`）
+   - 文末签名方式和值（默认：`none`）
+   - 排版强调色（默认：`#D97706`）
+   - 临时文件前缀（默认：`yanyan_wechat_upload`）
+2. 生成最终配置映射，向用户展示将写入的非敏感字段。
+3. 写入本机配置文件：
+
+   ```text
+   ~/.config/yanyan_skill/yanyan_wechat_upload/config.json
+   ```
+
+   如果环境变量 `YANYAN_WECHAT_UPLOAD_CONFIG` 已设置，则写入该变量指向的路径。
+4. 配置文件权限应尽量设为当前用户可读写，例如 macOS / Linux 上使用 `0600`。
+5. 不要把 AppID、AppSecret、access token、refresh token、cookie 或完整请求头写入配置文件。
+6. 写完配置后，告诉用户如何把 AppID / AppSecret 放入系统安全存储。不要要求用户把 AppSecret 发到对话里。
+
+本机配置文件必须是 JSON，字段名与 `Default Configuration` 一致。示例：
+
+```json
+{
+  "ACCOUNT_NAME": "我的公众号",
+  "AUTHOR_NAME": "",
+  "CREDENTIAL_MODE": "keyring",
+  "APP_ID_ENV_VAR": "WECHAT_APP_ID",
+  "APP_SECRET_ENV_VAR": "WECHAT_APP_SECRET",
+  "KEYRING_SERVICE": "yanyan_wechat_upload",
+  "KEYRING_APP_ID_ACCOUNT": "app_id",
+  "KEYRING_APP_SECRET_ACCOUNT": "app_secret",
+  "DEFAULT_SOURCE_TYPES": "paste-md,local-md",
+  "EXTERNAL_SOURCE_HEADING": "none",
+  "COVER_MODE": "ask-each-run",
+  "DEFAULT_COVER_SOURCE": "RUNTIME_REQUIRED",
+  "SIGNATURE_MODE": "none",
+  "SIGNATURE_VALUE": "none",
+  "RELATED_LINK_MODE": "optional",
+  "RELATED_LINK_COUNT": "0",
+  "THEME_COLOR": "#D97706",
+  "UPLOAD_CAPABILITY": "auto-detect",
+  "TMP_PREFIX": "yanyan_wechat_upload"
+}
+```
+
+配置文件可以保存账号名、作者名、封面图策略、签名策略、强调色、keyring service 名称等；不得保存 AppSecret、access token、refresh token 或完整请求头。
+
+凭证配置说明应使用最终确定的 `KEYRING_SERVICE` 真实值。例如：
+
+```bash
+python3 -m pip install keyring
+keyring set yanyan_wechat_upload app_id
+keyring set yanyan_wechat_upload app_secret
+```
+
+提醒用户按提示粘贴 AppID / AppSecret，不要把 AppSecret 发到对话里。
+
+### `yanyan_wechat_upload:config`
+
+当用户输入 `yanyan_wechat_upload:config` 时，读取并展示当前有效配置摘要。展示时必须隐藏敏感信息；由于配置文件本身不应保存密钥，所以正常只显示非敏感字段。
+
+### `yanyan_wechat_upload:config-path`
+
+当用户输入 `yanyan_wechat_upload:config-path` 时，只返回当前将使用的本机配置文件路径，并说明 `YANYAN_WECHAT_UPLOAD_CONFIG` 可以覆盖默认路径。
+
+## Configuration Resolution
+
+每次执行上传或预览前，必须按以下优先级读取配置：
+
+1. 如果环境变量 `YANYAN_WECHAT_UPLOAD_CONFIG` 指向存在的 JSON 配置文件，优先读取它。
+2. 否则读取默认本机配置文件 `~/.config/yanyan_skill/yanyan_wechat_upload/config.json`。
+3. 如果本机配置文件不存在，再使用下面 `Default Configuration` 中的默认值。
+
+本机配置文件中的键名与 `Default Configuration` 完全一致。读取后用本机配置覆盖默认值，未出现的字段继续使用默认值。
+
+如果用户要求修改配置，应优先引导运行配置命令；只有用户明确要求手工修改时，才编辑配置文件或安装后的 `SKILL.md`。
+
+## Default Configuration
+
+<!-- 以下是仓库默认配置。如需修改个人设置，优先运行配置命令写入本机配置文件。不要把 AppSecret 明文写入这里。 -->
+
+```yaml
+ACCOUNT_NAME: "焰焰 say"
+AUTHOR_NAME: "焰焰"
+
+CREDENTIAL_MODE: "keyring"
+# "env" = 从环境变量读取
+# "keyring" = 用 Python keyring 从系统安全存储读取，macOS 为 Keychain，Windows 为凭据管理器
+# "tool-secret" = 从当前 AI 工具的密钥管理中读取
+
+APP_ID_ENV_VAR: "WECHAT_APP_ID"
+APP_SECRET_ENV_VAR: "WECHAT_APP_SECRET"
+
+KEYRING_SERVICE: "yanyan_wechat_upload"
+KEYRING_APP_ID_ACCOUNT: "app_id"
+KEYRING_APP_SECRET_ACCOUNT: "app_secret"
+
+DEFAULT_SOURCE_TYPES: "paste-md,local-md"
+# 可选值示例："paste-md,local-md,local-html,external-page"
+
+EXTERNAL_SOURCE_HEADING: "none"
+# 未启用外部页面时使用 "none"
+# 启用 Notion 或其他外部页面时，填写正文所在标题，例如 "公众号"
+
+COVER_MODE: "ask-each-run"
+# "ask-each-run" = 每次询问封面图
+# "fixed-local" = 固定本地封面图路径
+# "fixed-media-id" = 固定微信素材 media_id
+
+DEFAULT_COVER_SOURCE: "RUNTIME_REQUIRED"
+# COVER_MODE 为 ask-each-run 时使用 "RUNTIME_REQUIRED"
+
+SIGNATURE_MODE: "none"
+# "none" / "text" / "qr-source" / "qr-media-id"
+
+SIGNATURE_VALUE: "none"
+
+RELATED_LINK_MODE: "optional"
+# "none" / "optional" / "required"
+
+RELATED_LINK_COUNT: "0"
+
+THEME_COLOR: "#D97706"
+
+UPLOAD_CAPABILITY: "auto-detect"
+# "api-enabled" = 当前环境可以运行脚本或调用微信公众号 API
+# "preview-only" = 只生成预览和上传检查清单
+# "auto-detect" = 每次执行时自动判断
+
+TMP_PREFIX: "yanyan_wechat_upload"
+```
+
+## Trigger And Boundary
+
+当用户说“上传公众号”“生成公众号草稿”“Markdown 转公众号”“排版公众号文章”“发布到公众号草稿”“把这篇发到公众号”，或提供中文文章并要求生成微信公众号排版 / 草稿时，使用本 skill。
+
+支持输入：
+
+- 粘贴的 Markdown 正文
+- 本地 Markdown 文件路径
+- 本地 HTML 正文文件路径
+- 用户明确启用的外部页面来源
+- 已经准备好的标题、摘要、封面图、正文和相关阅读链接
+
+不适用：
+
+- 用户只想改写公众号文章，不需要排版或上传。此时应先做内容编辑，不进入上传流程。
+- 用户只想生成小红书、视频脚本、封面图或 B-roll。此时应建议使用对应 skill。
+- 用户没有提供可发布正文，只给一个选题。此时先要求用户提供文章正文或让用户确认是否要先起草文章。
+
+## Safety Rules
+
+- 永远不要要求用户把 AppSecret 明文粘贴到 skill 文件里。
+- 永远不要把 AppSecret、access token、refresh token、完整请求头或敏感响应写入最终输出。
+- 如果配置里还有 `TBD`、`RUNTIME_REQUIRED`、空密钥、占位符或明显假值，必须停止并询问缺失项。
+- 如果当前工具不能运行脚本、不能发 API 请求、不能读取本地文件或不能联网，必须明确说明能力边界，只生成预览 HTML 和上传检查清单。
+- 上传前必须生成预览 HTML，并向用户询问：
+
+  `排版预览已完成，请确认是否上传到公众号草稿？`
+
+- 只有用户明确回答“确认上传”“可以上传”“上传吧”等同意语句后，才允许创建或更新草稿。
+- 修改已上传草稿时，优先更新原草稿，不要默认新建重复草稿。
+- 任何微信 API 返回非 0 `errcode`，都必须停止并解释错误，不要继续下一步。
+
+## Required Runtime Checks
+
+每次执行时，先做以下检查：
+
+1. 读取配置：先按 `Configuration Resolution` 合并本机配置和默认配置。
+2. 确认 `ACCOUNT_NAME`。
+3. 确认密钥读取方式可用：
+   - `env`：检查 `APP_ID_ENV_VAR` 和 `APP_SECRET_ENV_VAR` 对应环境变量存在
+   - `keyring`：检查当前环境能运行 Python keyring，并使用配置里的 service/account
+   - `tool-secret`：按当前 AI 工具的密钥管理方式读取
+4. 确认文章来源可读取。
+5. 确认封面图：
+   - `ask-each-run`：如果用户没给封面图，询问路径、URL 或 media_id
+   - `fixed-local`：检查本地路径存在
+   - `fixed-media-id`：检查 media_id 非空
+6. 如果 `SIGNATURE_MODE` 不是 `none`，检查签名配置非空。
+7. 如果 `RELATED_LINK_MODE` 是 `required`，确认用户提供了 `RELATED_LINK_COUNT` 条真实链接。
+8. 创建唯一临时目录，避免覆盖旧预览或旧上传中间文件。
+
+## Normalize Article Source
+
+在排版前，先把所有来源统一整理成以下字段：
+
+```yaml
+title:
+digest:
+author:
+body_source:
+body_format:
+cover_source:
+inline_images:
+remote_images:
+related_links:
+existing_draft_media_id:
+```
+
+字段规则：
+
+- `title`：优先使用用户明确指定的标题；其次使用 frontmatter `title`；再次使用第一个 H1。
+- `digest`：优先使用用户明确指定的摘要；其次使用文中的 `Meta 摘要`；再次使用第一段有信息量的正文，压缩到 54 字以内。
+- `author`：优先使用用户指定作者；其次使用 `AUTHOR_NAME`；没有就留空。
+- `body_source`：只保留正文，不把 frontmatter、备注、待办和未确认材料混入正文。
+- `body_format`：标记为 `markdown`、`html` 或 `plain-text`。
+- `cover_source`：来自用户本次指定、固定配置或微信 media_id。
+- `related_links`：只收录真实可访问链接；不要使用临时链接或内部编辑链接。
+- `existing_draft_media_id`：只有用户明确要求更新旧草稿时才使用。
+
+如果标题、摘要或正文缺失，先询问用户，不要猜。
+
+## WeChat HTML Style
+
+生成的正文 HTML 要尽量使用微信公众号稳定支持的结构：
+
+- 优先使用 `section`、`p`、`span`、`strong`、`a`、`img`、`blockquote`、`h2`
+- 不依赖复杂 `flex`、`grid`、外部 CSS 文件或 JavaScript
+- 不使用需要运行脚本才能呈现的交互效果
+- 避免原生 `ul/li` 作为关键列表结构，改用稳定的段落 + 编号 / 符号样式
+- 所有样式尽量写成行内 style 或微信兼容的简单结构
+
+基础排版：
+
+- 正文字号：16px
+- 正文行高：1.75
+- 字间距：1px
+- 正文颜色：`#2B2B2B`
+- 弱文本颜色：`#888888`
+- 两侧留白：16px 左右
+- 段落间距：1em 左右
+- 正文段落默认两端对齐
+- 图片最大宽度不超过 100%，居中显示；但不要强制所有图片全宽，logo、二维码、图标类图片应保持较小尺寸
+
+标题样式必须稳定，不要每次运行临时发明新样式：
+
+- 正文主标题不放进正文 HTML 的装饰区，由公众号草稿标题字段承载
+- 一级分节标题使用 `h2` 或 `section + p`，居中，黑色主字，底部黑色短下划线，可叠加少量浅色强调底纹
+- 二级小标题使用加粗段落，左侧可以使用 `THEME_COLOR` 竖线，但不要使用大面积色块
+- `第一步 / 第二步 / 第三步` 这类步骤标题固定为左侧一条强调色竖线 + 标题文字，不要添加胶囊标签或圆角色块
+- `方式一 / 方式二 / 方式三` 这类方法标题可以使用小号浅色 pill 标签 + 单独的左线标题段落，整篇保持一致
+
+主分节标题建议：
+
+```html
+<section style="margin:32px 0 18px;text-align:center;">
+  <p style="margin:0 auto 6px;display:inline;line-height:1.6;font-size:18px;font-weight:700;color:#111111;background:rgba(255,214,0,0.38);">
+    小标题
+  </p>
+  <p style="margin:8px auto 0;width:40px;border-bottom:2px solid #111111;"></p>
+</section>
+```
+
+步骤标题建议：
+
+```html
+<p style="margin:24px 16px 12px;padding-left:12px;border-left:4px solid THEME_COLOR;font-size:17px;font-weight:700;line-height:1.75;color:#111111;">
+  第一步：小标题
+</p>
+```
+
+强调色使用 `THEME_COLOR`，但要克制：
+
+- 只用于重点词、引用块左线、分隔线、少量标签
+- 不要整段大面积上色
+- 不要让文章看起来像海报
+- 如果文章视觉太平，可以给少量关键词加浅色底纹，但不得影响阅读
+
+引用块建议：
+
+```html
+<section style="margin:24px 0;padding:14px 16px;background:#F6F6F6;border-left:4px solid THEME_COLOR;border-radius:8px;color:#4A4035;line-height:1.75;">
+  引用内容
+</section>
+```
+
+列表建议用稳定段落结构：
+
+```html
+<p style="margin:12px 0;line-height:1.75;">
+  <span style="color:THEME_COLOR;font-weight:700;">01</span>
+  <span style="font-weight:700;">小标题：</span>
+  <span>正文说明。</span>
+</p>
+```
+
+## Images
+
+处理图片时遵循：
+
+- 本地正文图片需要先转为微信可用图片 URL，不能把本地路径直接写进最终草稿 HTML。
+- 远程图片如果微信后台不稳定，优先重新上传到微信临时图片接口或用户指定图床。
+- 不要强制把所有图片转成 jpeg，保留原始合理格式。
+- 上传图片前记录本地路径与微信 URL 的映射，更新草稿时只上传新增图片。
+- 如果图片上传失败，停止并告知是哪张图片失败，不要跳过关键图片继续上传。
+
+## Preview First
+
+正式上传前必须生成一个可在浏览器打开的预览 HTML。
+
+预览 HTML 应包含：
+
+- 文章标题
+- 摘要
+- 作者
+- 封面图状态
+- 正文排版
+- 文末签名或二维码
+- 相关阅读链接
+- 图片替换状态说明
+
+预览后停止并询问：
+
+`排版预览已完成，请确认是否上传到公众号草稿？`
+
+用户确认前不得调用创建草稿或更新草稿接口。
+
+## Content Integrity Rules
+
+预览内容和最终上传内容必须是同一份完整正文，严禁为了简化命令、节省 token 或缩短 `curl` 命令而截断正文。
+
+- 不要在上传 payload 里使用 `...`、`省略`、`截断`、`部分正文` 或手工摘取后的正文。
+- 不要把长 HTML 直接拼进一行 `curl -d '...'` 命令。
+- 构建草稿 payload 时，必须先把完整 `content` 写入临时 JSON 文件，例如 `draft_payload.json`，再用 `curl --data-binary @draft_payload.json` 或等价脚本上传。
+- 推荐使用 Python `json` 模块、`jq` 或当前语言的 JSON 序列化能力生成 payload，不要手写转义长 HTML 字符串。
+- 预览 HTML 生成后，记录正文 HTML 的字符数和内容 hash；上传前对 draft payload 中的 `content` 再计算一次，二者必须一致。
+- 上传前至少检查正文开头、中部和结尾各一个锚点片段都存在于 payload `content` 中，尤其要确认文末签名、相关阅读或最后一段没有丢失。
+- 如果因为命令行长度、转义、API 限制或工具输出限制导致无法保证全文上传，必须停止，不得上传部分内容。
+
+## Upload Workflow
+
+如果 `UPLOAD_CAPABILITY` 是 `preview-only`，或者当前环境无法运行脚本 / 发 API 请求：
+
+1. 生成预览 HTML。
+2. 输出上传检查清单。
+3. 明确说明当前环境不能直接创建微信公众号草稿。
+4. 不要声称已经上传。
+
+如果当前环境可以调用微信公众号 API：
+
+1. 读取 AppID / AppSecret。
+2. 获取 access token。
+3. 处理正文中的本地图片，拿到微信可访问图片 URL。
+4. 生成微信公众号兼容 HTML。
+5. 生成预览 HTML 并等待用户确认。
+6. 用户确认后，构建包含完整正文的 draft payload 文件，并执行 Content Integrity Rules。
+7. 如果用户提供 `existing_draft_media_id`，调用更新草稿流程。
+8. 否则创建新草稿。
+9. 输出草稿结果：
+   - 公众号名称
+   - 标题
+   - draft media_id
+   - 是否更新旧草稿
+   - 预览 HTML 路径
+   - 图片处理摘要
+   - 需要用户到公众号后台手动确认的事项
+
+## Draft Payload Rules
+
+构建草稿时，至少准备：
+
+```yaml
+title:
+author:
+digest:
+content:
+thumb_media_id:
+need_open_comment:
+only_fans_can_comment:
+```
+
+规则：
+
+- `title` 太长时，先给用户一个“公众号后台标题”缩短建议，不要擅自改掉正文标题。
+- `digest` 控制在微信公众号摘要适合的长度内，通常不超过 54 字。
+- `content` 必须是处理后的微信兼容 HTML，不是原始 Markdown。
+- `content` 必须来自完整预览正文，不得手动截断、概括、抽样或替换为占位内容。
+- `thumb_media_id` 必须来自固定配置、用户提供，或本次上传封面图得到的 media_id。
+- 评论设置如果用户没有指定，使用微信公众号默认值，不要擅自开启特殊设置。
+
+## Related Links
+
+如果 `RELATED_LINK_MODE` 是 `none`：
+
+- 不添加相关阅读区。
+
+如果是 `optional`：
+
+- 用户提供真实链接就添加。
+- 用户没提供就跳过，不要编造。
+
+如果是 `required`：
+
+- 必须检查链接数量等于 `RELATED_LINK_COUNT`。
+- 链接必须是真实可访问的公开文章链接。
+- 如果数量不足，先询问用户补齐，不要上传。
+
+相关阅读区样式要轻，不要喧宾夺主。
+
+## Signature
+
+如果 `SIGNATURE_MODE` 是 `none`：
+
+- 不添加固定签名。
+
+如果是 `text`：
+
+- 在正文末尾添加 `SIGNATURE_VALUE`。
+
+如果是 `qr-source`：
+
+- 把二维码图片处理为微信可用图片 URL 后插入。
+
+如果是 `qr-media-id`：
+
+- 使用固定素材，但仍要在预览中说明使用了固定二维码素材。
+
+签名区必须和正文有清楚分隔，但不要做成复杂卡片。
+
+## Error Handling
+
+遇到以下情况必须停止：
+
+- 密钥为空、缺失、占位符或读取失败
+- access token 获取失败
+- 封面图缺失或上传失败
+- 正文为空
+- 图片上传失败且图片是正文关键内容
+- 微信 API 返回非 0 `errcode`
+- 用户没有确认上传
+- 目标草稿 media_id 不存在或更新失败
+
+停止时输出：
+
+- 失败发生在哪一步
+- 已完成哪些步骤
+- 用户需要补充什么
+- 是否可以从预览继续
+
+## Output Format
+
+每次执行结束时，按状态输出。
+
+### 只完成预览
+
+```markdown
+## 公众号排版预览已生成
+
+- 公众号：...
+- 标题：...
+- 摘要：...
+- 封面图：已确认 / 待确认
+- 正文图片：... 张，... 张已处理
+- 预览文件：...
+
+排版预览已完成，请确认是否上传到公众号草稿？
+```
+
+### 已上传或已更新草稿
+
+```markdown
+## 公众号草稿已生成
+
+- 公众号：...
+- 标题：...
+- 操作：新建草稿 / 更新草稿
+- draft media_id：...
+- 预览文件：...
+- 图片处理：...
+- 相关阅读：...
+- 文末签名：...
+
+请到公众号后台做最后人工检查，重点看封面、摘要、图片、链接和手机端排版。
+```
+
+### 当前环境不能上传
+
+```markdown
+## 当前环境只能生成预览
+
+我已经生成公众号兼容 HTML 和上传检查清单，但当前 AI 工具不能直接调用微信公众号 API。
+
+- 预览文件：...
+- 需要手动处理：...
+- 下一步：在支持脚本 / API 的环境中继续上传
+```
+
+## Quality Checklist
+
+上传前检查：
+
+- 标题、摘要、作者正确
+- 摘要不是正文第一长段硬截断
+- 封面图已确认
+- 正文不是原始 Markdown
+- 本地图片没有以本地路径出现在最终 HTML 里
+- 链接是真实公开链接
+- 相关阅读数量符合配置
+- 签名或二维码符合配置
+- HTML 没有依赖 JavaScript
+- 关键结构没有依赖 flex / grid
+- 已生成预览
+- draft payload 使用完整正文，不是预览正文的截断版
+- draft payload 中 `content` 的字符数和 hash 已与预览正文核对
+- 正文开头、中部、结尾锚点片段都存在于 payload `content` 中
+- 上传命令没有把长 HTML 手写进一行 `curl -d`，而是使用 JSON 文件或等价的安全序列化方式
+- 用户已明确确认上传
+- 没有输出 AppSecret、access token 或敏感请求信息
+
+## One Sentence Principle
+
+先把来源规范成一篇微信可读的稳定 HTML，预览确认后再上传；配置缺失就停，密钥不进文件，不能上传就不要假装上传。